Docs

Everything You Need to Know

Tutorials

Mediators

One Ring to Rule Them All

Mediators let you write decoupled code. Mediators work best when they deal with one task. Mediators let you handle unidirectional flow. There are three directions for data flow in a ChocolateChip-UI applications: from a view, from a model or from a remote server/local data store. Mediators capture the flow coming from these three sources and channel it into four possible directions: a model, a view, a local data store or a remote server.

Go with the Flow

When building a ChocolateChip-UI app, there are a certain number of flows that you need to manage. They are:

  • from view
    • to model
    • to local data store
    • to server
  • from model
    • to view
    • to local data store
    • to server
  • from server
    • to model
    • to view
    • to local data store

Mediators work by listening for a topic. These are custom events that you can fire using ChocolateChip-UI's dispatch system. When you dispatch a topic, you can also send some accompanying data. You can have multiple mediators listening to the same topic. Each mediator could be doing something totally different with the topic. That's up to you to decide how to divide up the work flow. You can dispatch different types of data with the same topic. Then different mediators can check the data type, if it matchs what they're looking for, they can handle it. Offloading the handling of different data types to specific mediators helps keep data processing granular and easier to troubleshoot. Say we have a topic "my-update" and we have three mediators. Each mediators can only handle one of three types of data: strings, arrays or objects. The mediators check the data they receive with the dispatch to see if its the type they need.

To create a mediator, you use the $.on method. This takes two arguments, a topic, which is the mediator listens to, and a callback. If data is passed to the mediator, it will be available as the argument of the callback:

// Create mediator:
var myMtor = $.on('my-topic', function(data) {
  // Check the type of data:
  if ($.type(data) === 'string') {
    console.log('We got the following string: ' + data);
  }
});

// Create another mediator to handle objects:
var peopleMtor = $.on('my-topic', function(data) {
  // Check if data is object:
  if ($.type(data) === 'object') {
    // render a view with the data:
    peopleView.render(data);
  }
});

We can dispatch a topic using ChocolateChip-UI's $.dispatch method. This takes two arguments, the topic to dispatch, and any optional data you want to send:

// Dispatch a string to my-topic:
$.send('my-topic', 'This is the message.');

// Dispatch an object to my-topic:
$.send('my-topic', {firstName: 'Ben', lastName: 'Carson', age: 35};

// With the above dispatches, myMtor responds to the first and peopleMtor to the second.

When you send a dispatch, any mediators listening to that topic will execute. In the above example for yyMtor, because we are doing type checking, it will only procede if the data passed is a string. You can use any kind of checks you need to limit whether a mediator handles a dispatch or not.

Directly Running a Mediator

Besides dispatching a topic to a mediator, you can directly execute them. You do this with their run method. When you run a mediator, you don't need to pass a topic. Instead, you pass it whatever data you want to send:

// Run myMtor:
myMtor.run('Directly running the mediator.');

// Run peopleMtor:
peopleMtor.run({
  firstName: 'Phil',
  lastName: 'Mackee',
  age: 38,
  job: 'electrician'
});