Event bus

FicusJS provides a function for creating a fast, lightweight publish/subscribe event bus.

For communication between components without triggering a re-render, the event bus object provides a topic-based publish/subscribe API.

The event bus will be created as a singleton - this ensures only one instance exists.

Example

Import the createEventBus function into your Javascript main file:

main.js

import { createEventBus } from 'https://unpkg.com/ficusjs?module'

Create a new event bus instance:

main.js

const eventBus = createEventBus()

createEventBus function

Once you have created your events instance using createEventBus, simply pass it to each component:

import { createComponent, withEventBus } from 'https://unpkg.com/ficusjs?module'

// A new component
createComponent(
  'my-component',
  withEventBus(eventBus, {
    /* pass component creation options here */
  })
)

getEventBus function

The getEventBus function is a quick way to retrieve the events instance. If the event bus has not yet been created, getEventBus will create a new instance automatically.

// import the function
import { createComponent, getEventBus, withEventBus } from 'https://unpkg.com/ficusjs?module'

// use it within a component
createComponent(
  'my-component',
  withEventBus(getEventBus(), {
    /* pass component creation options here */
  })
)

Subscribe

To be notified when a particular event will be published, use the subscribe method to register a callback function. This method returns a function which can be invoked later for unsubscription.

const unsubscribe = eventBus.subscribe('myTopic', data => {
  // handle the event with the data passed
})

// Unsubscribe later
unsubscribe()

Publish

When you want to notify subscribers, you need to publish an event:

eventBus.publish('myTopic', data)

Usage in components

Once you have created your events instance, the withEventBus function extends a component and makes working with an event bus easier in component methods.

Subscriptions based on lifecycle hooks will be automatically handled within the component. You need to provide the initial topic subscription (use the created or mounted lifecycle hook) and then once established, subscriptions will be handled automatically when the component fires the removed or updated lifecycle hook.

See extending components for more on the withEventBus function.

import { createComponent, createEventBus, withEventBus } from 'https://unpkg.com/ficusjs?module'
import { html, renderer } from 'https://unpkg.com/ficusjs-renderers@latest/dist/lit-html.js'

const eventBus = createEventBus()

// A new component
createComponent(
  'my-component',
  withEventBus(eventBus, {
    renderer,
    handleEvent (data) {
      /* handle event here */
    },
    mounted () {
      this.events.subscribe('my-event', this.handleEvent)
    },
    render () {
      /* handle render here */
    }
  })
)