ChocolateChip-UI - Documentation

Docs

Everything You Need to Know

Mediators

Use

Setting up mediators is very simple. You just need to provide a topic for the mediator to use and a callback to execute:

var barMtor = $.on('foo-topic',function(data) {
  console.log('1. Bar here.')
  console.log(data);
});
var bazMtor = $.on('foo-topic',function(data){
  console.log('2. Baz here.');
  console.log(data);
});

Notice that we've created both mediators to use the same topic. This means that when anything sends that topic, both mediators will react. Of course, mediators do not need to share the same topic. Define mediators with topics according to what makes sense for your use case.

Once you have a mediator defined, you can execute it using its run method:

FooMtor.run('This is Godzilla!');
// results:
// 1. Foo here.
// This is Godzilla!

Even though both mediators are listening to the same topic, running one mediator will not invoke the other mediator. If you want all mediators using the same topic to respond, you need to use ChocolateChip-UI's dispatcher. Just dispatch the topic with any data you want the mediators to receive. You do this using the $.send(topic, data?) method:

// Send to both mediators:
$.send('foo-topic', 'Sent from the dispatcher.');

// Result:
// 1. Foo here.
// Sent from the dispatcher.
// 2. Bar here.
// Sent from the dispatcher.

As you can see, using mediators gives you more flexibility in how you notify your system about changes that need to be propagated to different areas.

You can find out what topic a mediator is using by examining its topic property:

// Get barMtor's topic:
var topic = barMtor.getTopic();
// topic is "foo-topic"

Controlling Your Mediators

Like regular events, you can delete a mediator. You do this by executing the off method on the mediator:

// Turn barMtor off:
barMtor.off();
// Turn bazMtor off:
bazMtor.off();

// barMtor will not run now:
barMtor.run('Is this working now?');
// bazMtor will not run now:
bazMtor.run('Hey, at least this one works.');

Dispatchers

You can use the ChocolateChip-UI's dispatch system to create generic mediators using its pubsub methods. To do so you use the $.on() method as you did for mediators, but you don't capture it in a variable.

// Define a dispatch receiver:
$.on('my-topic', function(msg) {
  if (msg) {
    console.log('The message is: ' + msg);
  }
});

You can register multiple callbacks on the same topic:

// Define a dispatch receiver:
$.on('my-topic', function(msg) {
  if (msg) {
    console.log('The message is: ' + msg);
  }
});
$.on('my-topic', function(msg) {
  if (msg) {
    console.log('This is another callback running: ' + msg);
  }
});
$.on('my-topic', function(msg) {
  if (msg) {
    console.log('This is a third callback running: ' + msg);
  }
});

To activate a dispatch receiver we use $.send(topic, data). This will run all callbacks registered to a topic, passing them the provided data. So, in the above example with three callbacks, all three will execute. Be aware that the order that callbacks get executed varies by how the host browser reads the topics object. So it's best not to build any dependency on the execution order of receiver callbacks.

// Send a dispatch to the topic "baz-topic":
$.send("baz-topic", "Dispatching to the topic 'baz-topic'.");

Since mediators are listening to topics the same as generic dispatch receivers, you can target all mediators listening to a topic at the same time by using $.send(topic, data).

You can stop dispatch receiver by eliminating its topic with $.removeTopic(topic):

// Stop a dispatch receiver from 
// responding to dispatches:
$.removeTopic('baz-topic');
// The following will now not do anything:
$.send("baz-topic", "Dispatching to the topic 'baz-topic'.");