Docs

Everything You Need to Know

Tutorials

Mediators - Event Bus

Mediators are just specialized subscribers using ChocolateChip-UI's' pubsub system. Mediators let you write decoupled code. Mediators work best when they deal with one task. Mediators let you handle unidirectional flow. There are two directions for data flow in a ChocolateChip-UI applications: from a component, from a state. Mediators capture the flow coming from these two sources and channel it into four possible directions: a state, a component, 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 component
    • to state
    • to local data store
    • to server
  • from component
    • to component
    • to local data store
    • to server
  • from server
    • to state
    • to component
    • to local data store

Mediators work by listening for a topic. These are custom events that you can fire using ChocolateChip-UI's pubsub system. When you publish 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 publish 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 publication to see if its the type they need.

To create a mediator, you use the $.subscribe 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 = $.subscribe('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 = $.subscribe('my-topic', function(data) {
  // Check if data is object:
  if ($.type(data) === 'object') {
    // render a view with the data:
    peopleComponent.render(data)
  }
})

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

// Publish a string to my-topic:
$.publish('my-topic', 'This is the message.')

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

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

When you send a publication, any mediators listening to that topic will execute. In the above example for myMtor, 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 publication or not.

Directly Running a Mediator

Besides publishing 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'
})