Docs

Everything You Need to Know

Pubsub

Use

Using ChocolateChip-UI's pubsub system, its easy to set up mediators. Just provide a topic for the mediator to use and a callback to execute. Then assign the resulting subscriber to a variable:

var barMtor = $.subscribe('foo-topic', (data) => {
  console.log('1. Bar here.')
  console.log(data)
})
var bazMtor = $.subscribe('foo-topic', (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 publish it. Publish the topic with any data you want the mediators to receive. You do this using the $.publish(topic, data?) method:

// Send to both mediators:
$.publish('foo-topic', 'Sent from the publisher.')

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

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.')

Plain Pubsub

You do not have to make a mediator to use ChocolateChip-UI's pubsub. You can simply subscribe to a topic and leave it at that.

$.subscribe('foo-topic', (data) => {
  console.log('1. Bar here.')
  console.log(data)
})
$.subscribe('foo-topic', (data) => {
  console.log('2. Baz here.')
  console.log(data)
})
$.publish('foo-topic', 'This is new stuff')

The above subscribers will return the same result as the previous mediator examples. The difference is you have no object reference. If you want to run only one, you can't, if you want to stop only one, you can't. You can only unsubscribe all from the topic.

Publishing

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

// Define a subscriber:
$.subscribe('my-topic', (msg) => {
  if (msg) {
    console.log('The message is: ' + msg)
  }
})

You can register multiple callbacks on the same topic:

// Define a subscriber:
$.subscribe('my-topic', (msg) => {
  if (msg) {
    console.log('The message is: ' + msg)
  }
})
$.subscribe('my-topic', (msg) => {
  if (msg) {
    console.log('This is another callback running: ' + msg)
  }
})
$.subscribe('my-topic', (msg) => {
  if (msg) {
    console.log('This is a third callback running: ' + msg)
  }
})

To activate a subscriber we use $.publish(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.

// Publish to the topic "baz-topic":
$.publish("baz-topic", "Publishing to the topic 'baz-topic'.")

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

You can stop a subscriber by eliminating its topic with $.removeTopic(topic):

// Stop a subscriber from 
// responding to publications:
$.removeTopic('baz-topic')
// The following will now not do anything:
$.publish("baz-topic", "Publishing to the topic 'baz-topic'.")