ChocolateChip-UI - Documentation

Docs

Everything You Need to Know

Mediators

API

Dispatch System

ChocolateChip-UI's dispatch system has two modes: anonymous and mediator. Both use $.on() for setup. When you save the setup to a variable, that is called a mediator. It offers a saved reference to the dispatch object and several methods that affect only that instance of the dispatch object. Otherwise, you can create generic dispatch objects using $.send(topic, data). Using $.send(topic, data) will also activate any mediators listening to that topic.

Dispatch API

$.on(topic, callback)

You do not have to capture data in the dispatch receiver's callback. Also, you should use guards to check if their is any data accompanying a topic dispatch, because it is possible to send a dispatch without data.

$.on('my-topic', function(msg) {
  if (msg) {
    // Use the message that was sent:
    console.log('The message is: ' + msg);
    // Otherwise, let 'em know no message was sent:
  } else {
    console.log('Hey, no message was sent!');
  }
});

You can use $.on(topic, callback) to regeister multiple callbacks on the same topic. When you send to that topic, all handles will be executed. You can use some conditional logic in the callbacks to decide if you want to react to that broadcast or not. You might do that by testing the type of data sent, or any boolean value accessible by the callback.

send

$.send(topic, data)

You use $.send(topic, data) to execute a dispatch receiver's callback. If your broadcast might sometimes not have data, make sure to test in the dispatch receiver's callback for data before trying to use it.

getTopics

$.getTopics()

This method returns an object of all currently registered topics and their callbacks. Each topic has an array that can hold multiple callbacks that will get executed when the topic is triggered. This means that instead of having a hugely complicated callback to handle every conceivable thing you need to do with a topic, you can instead separate things out into their own callbacks, all listening to the same topic.

removeTopic

$.removeTopic(topic)

Mediator API

$.on(topic, callback)

This is a factory that returns a dispatch object. When this object is stored in a variable, it's called a mediator. The setup is the same as a generic dispatch receiver describe earlier. It takes two arguments: a topic and a callback to execute when the topic is broadcast. Since a dispatch can also include data, the mediator can do something with the data, such as transforming it or passing it to a view for rendering.

var MyMtor = $.on('my-topic', function(myData) {
  myView.render(myData);
});

When you capture a dispatch receiver as a mediator, you get several addition methods that affect that instance of the object:

run

run()

This method is used to execute a mediator. It takes one argument, data to pass to the mediator's callback.

var MyMtor = $.on('my-topic', function(message) {
  console.log(message);
});
MyMtor.run('This is a message');

off

off()

This method allows you to destory a method. This is will delete the callback that the mediator uses. Other mediators using the same topic will continue to function.

// Stop the mediator immediately:
MyMtor.off();

// Nothing happens:
MyMtor.run('This is another message');

You can also stop a mediator from responding to dispatches using the $.removeTopic method. This will stop all mediators and all dispatch receivers that use that topic from running. In contrast, MyMtor.off() only affects that mediator.

getTopic

getTopic()

This returns the topic the mediator is listening to.

var topic = MyMtor.getTopic();
console.log(topic);