Docs

Everything You Need to Know

Mediators

Intro

Truck Engine

Mediators are what binds the different parts of Truck together. Model, Views, remote domains and local data persistence do not know about each other. Only the mediators know about these. Truck's mediators handle the flow from one to the other. The following picture illustrates the role mediators play in Truck's architecture:

From this image you can see that the remove server can send a push notification to a mediator. A model can notify a mediator that it has changed. A view can notify a mediator about a user interaction. And a mediator can interact with the remote server, the model, the view and the local data layer.

This architecture supports the following work flows:

  • View => Mediator => Model
  • View => Mediator => Remote Domain
  • View => Mediator => Local Domain
  • Model => Mediator => View
  • Model => Mediator => Remote Domain
  • Model => Mediator => Local Domain
  • Remote Domain => Mediator => View
  • Remote Domain => Mediator => Model
  • Remote Domain => Mediator => Local Domain
  • Mediator => Remote Domain, => View

You can also directly run a mediator for the following work flows:

  • Mediator => Model
  • Mediator => View
  • Mediator => Local Domain
  • Mediator => Remote Domain
  • Mediator => Remote Domain, => View
  • Mediator => Remote Domain, => Model
  • Mediator => Remote Domain, => Local Domain
  • Mediator => Local Domain, => View
  • Mediator => Local Domain, => Model
  • Mediator => Local Domain, => Remote Domain

Dividing task up into individual mediators makes it easier to test. But too much decoupling can make it difficult to find the breaking point when a workflow fails. It's a good practice to include logging in your mediators during development so you can see how they are working together.

Truck's Mediators are an evented bus system. Mediators can respond to events, or as they are called in Truck, handles. For example, when a model changes, it announces that change using a handle. If a mediator is listening for that handle, it can respond. This gets useful when the handle comes with data. The mediator can then take that data and do something with it. When you define the callback for a mediator, it gets passed the data used by the mediator:

// Access passed data in the callback using `data`:
var FooMtor = $.Mediator('FooMtor', function(data) {
  console.log('What we got: ' + data);
});
// Execute the mediator:
FooMtor.run('Something for you here.');
// Result: "What we got: Something for you here."

You can also define a mediator that is executed like any other function. For example:

var FooMtor = $.Mediator('FooMtor', function() {
  console.log('This is FooMtor running1');
});
// Execute the mediator:
FooMtor.run();

Mediators have a number of builtin features that would require extra coding to do in an ordinary method. Besides running a mediator, you can stop it with stop(). This will prevent if from responding to any handles that might get published. You can also provide a number for the stop method, which tells the mediator to only run that many times and then stop.

// Stop the mediator immediately:
FooMtor.stop();
// Stop the mediator after 5 runs:
FooMtor.stop(5);

After some time, you might want to start a stopped mediator. You do that with start(). Using start means the mediator will immediately start responding to its handle when it is published.

// Restart the mediator immediately:
FooMtor.start();

By default, mediators keep track of how many times they have run. You can get that number by examining its count property. This allows you to monitor the activity of mediators. You can reset a mediators count with resetCount(), or you can stop the count altogether with stopCount(). This will stop the count at the current number. If for some reason you don't need a mediator and want to get rid of it, you can kill it literally with kill(). Killing is fatal for a mediator. After being killed, you cannot revive a mediator.

// Get the current number of times
// the mediator has run:
FooMtor.count;
// Rest the mediator's count to 0:
FooMtor.resetCount();
// Stop the mediator from counting its runs:
barMtor.stopCount();

Note:

Mediators are actually part of Truck's dispatch system. They are just dispatch receivers assigned to a variable. If you define a mediator but do not assign it to a variable, it becomes an annonymous receiver that only responds to dispatches. To learn more about the dispatch system, please read this section.