event

Agents, Widgets and Applications are loosely coupled in a Dashboard plugin, but it is still very easy to communicate between your them, as well as with the Dashboard and even with other plugins.

How to use

import { Plugin } from'@root'

const events = Plugin.event('my-custom-event-uuid')

Event instance

event instance has custom methods to be called to communicate:

property	type
send	function
on	function
ready	function
off	function

send

We will start in your agent class. Let's say that you want to send an event to your application based on if your api is up and running.

We would then write the following code:

import { Plugin } from'@root'

class Agent extends Plugin.Agent {
    ...
    const eventPayload = {
        status: true
    }
    
    // you can access events methods from any Base-Components when you extend yours with
    this.send({
        name: 'pluginName:apiStatus',
        userData: eventPayload
    })
      
    //  Or create your own events instance
    this.events = Plugin.event('my-events-instance-uuid')
    this.events.send({
        name: 'pluginName:apiStatus',
        userData: eventPayload
    })
    ...
}

As default all events are broadcasted, to everyone listening to the event name. If you want to target a specific type of plugin or even an instance of an app, widget or agent you can send an extended event. For example when you want to respond to a previous event.

Target a plugin

events.send({
	name: 'pluginName:apiStatus', // Name of the event
	target: 'com.naviga.dashboard-plugin-bundle', // The bundle id of the target type
	userData: {
		status: true
	}
})

Target an event instance

events.send({
	name: 'pluginName:apiStatus', // Name of the event
	targetUUID: EVENT_INSTANCE_UUID, // The UUID of the target type (more info in **on**)
	userData: {
		status: true
	}
})

We call the dispatch send function with the event payload and the event name.

Best practice here for event names is to use your plugin name, followed by : and then what type of event name: 'pluginName:apiStatus'

on

To listen to this event inside your application class simply write

events.on('pluginName:apiStatus', userData => {
    console.log("Api is up and running: ", userData.status)
})

What is happening here is that we subscribe to the "pluginName:apiStatus" event.

And we then asynchronously receive the data in the userData object.

Dashboard will set reserved properties in userData object that you can't override with your own values which they are:

property	value
_sender	a custom object for events instance details
UUID	the events instance uuid that the send methods has been fired from

the UUID can be used to answer back to the current events instance who just end the message

events.on('pluginName:apiStatus', userData => {
    console.log("Api is up and running: ", userData.status)
    
    events.send({
        name: 'pluginName:apiStatusResponse',
        targetUUID: userData.UUID,
        userData: {
            // custom data or empty object
        }
    })
})

ready

Plugins can be loaded, installed and activated in different order so if a plugin have dependency to another plugin we can use events.ready() to know when it's ready to communicate with.

For example if one plugin talks to an API and another plugin wants to use that data. We do this by listening to the bundle id of the target plugin.

If the target plugin is already loaded the callback will fire instantly.

events.ready('com.naviga.dashboard-APIPlugin', () => {
    events.send({
        name: 'apiPlugin:search',
        userDate: {
            query: 'dashboard'
        }
    })
})

off

When a component is unmounted from the DOM it is necessary to unregister the events dispatcher, otherwise callbacks can be called when your component is not mounted and this can cause your plugin to try to modify unmounted node elements.

In other words, hell breaks loose.

import { Plugin } from '@root'

import {
    useRef,
    useEffect,
    Component
} from 'react'

const Application = prop() => {
    const events = (Plugin.event('event-uniq-id'))
    
    useEffect(() => {
        return () => {
            events.off()
        }
    }, [events])
}

class Application extends Component {
    constructor(props) {
        super(props)
        
        this.events = Plugin.event('event-uniq-id')
    }
    
    componentWillunmout() {
        this.events.off()
    }
}