Docs

Everything You Need to Know

Pubsub

API

Pubsub System

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

Subscribe

$.subscribe(topic, callback)

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

$.subscribe('my-topic', (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 $.subscribe(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.

Publish

$.publish(topic, data)

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

Unsubscribe

$.unsubscribe(topic)

Using this method, you can unsubscribe a top, or turn it off. Unsubscribing a topic completely eliminates that topic. This means any subscriptions or mediators listening for it will not do anything if you attempt to publish that topic afterwards. If you don't want to completely eliminate a subscribed topic, you can turn it off at the mediator level using the off method. Check out the mediator documentation below for more details.

Mediator API

const myMtor = $.subscribe(topic, callback)

$.subscribe returns a subscriber object. When you store it in a variable, it's called a mediator. The setup is the same as a generic subscriber describe earlier. It takes two arguments: a topic and a callback to execute when the topic is broadcast. Since a publication can also include data, the mediator can do something with the data, such as transforming it or passing it to a view for rendering.

const myMtor = $.subscribe('my-topic', (myData) => myView.render(myData))

When you capture a subscriber 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.

const myMtor = $.subscribe('my-topic', (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 publications using the $.removeTopic method. This will stop all mediators and all subscribers that use that topic from running. In contrast, myMtor.off() only affects that mediator.