Extending TowTruck

This page documents some of the ways you can customize the TowTruck experience on your site. Especially how you can extend TowTruck to synchronize parts of your application that require special treatment.

We Haven't Done This Yet

Yeah, we're still working on it. We're using the extending label to categorize tickets related to this. What follows is what we have done, and will continue to be expanded as we handle issues. If you have a use case you'd like us to address, please open a new issue and describe it.

TowTruck.reinitialize()

You can run this to try to reinitialize anything TowTruck initializes on page load. In particular you can use it if there are new textareas or code editors that should be sync'd, but were added dynamically to the page. E.g.:

$("#form").append("<textarea>");
TowTruck.reinitialize();

(We hope with #70 that this will no longer be necessary.)

TowTruck events

The TowTruck object is an event emitter. It uses the style of TowTruck.on("event", handler). The available events:

• TowTruck.on("ready", function () {}): emitted when TowTruck is fully started up.
• TowTruck.on("close", function () {}): emitted when TowTruck is closed. This is not emitted when the page simply closes or navigates elsewhere. It is only closed when TowTruck is specifically stopped.

Configuring events

Like other configuration, you may not wish to set up these callbacks before towtruck.js is loaded. You can do that with the "on" configuration parameter, like:

TowTruckConfig_on = {
  ready: function () {}
};

Or if you want to set things separately you can do:

TowTruckConfig_on_ready = function () {};

Deferring Initialization

TowTruck starts up automatically as soon as it can, especially when continuing a session. Sometimes this is problematic, like an application that bootstraps all of its UI after page load. To defer this initialization, define a function TowTruckConfig_callToStart like:

TowTruckConfig_callToStart = function (callback) {
  MyApp.onload = callback;
};

In this example when MyApp.onload() is called, TowTruck will start to initialize itself. Note that calling TowTruck.reinitialize() might be sufficient for your application's needs if it does a lot of setup after the page loads.

Getting At The Innards

You can still get at TowTruck, even if you can't rely on the internals not to change underneath you. (You would be well recommended to deploy your own copy of the client if you do this stuff.)

Most of the TowTruck features are implemented as individual modules, so it should be possible to introduce your own module to do many of the same things. The most important thing is the session module, and sending and receiving messages.

To get the session module (or any module) you can run this after TowTruck starts:

var session = TowTruck.require("session");

This assumes that the module has already been loaded... but that assumption would be correct once TowTruck has started.

Then there are two interesting methods:

session.send({type: "my-custom-type", attr: value});
session.hub.on("my-custom-type", function (msg) {
  alert(msg.value);
});

I.e., session.send() and session.hub.on(). As you can see the messages are dispatched based on msg.type. These messages are broadcasted to all other participants. Note that the messages are always sent, even if the other person is at a different URL. To check if an incoming message comes from a person on the same page as you, check msg.sameUrl (msg.url shows the actual URL of the other person).