In order for plugins to be able to communicate to the parent app and other plugins, and for the parent app to be able to communicate to the plugins, there needs to be a messaging system in place. The DAaaS frontend makes use of browser CustomEvents as the common API for these seperate apps to communicate with one another.

• scigateway:api:plugin_rerender: the parent app requests that the plugin rerender itself e.g. the sidebar has been opened/closed and so the plugin needs to recalculate
• scigateway:api:send_themeoptions: the parent app is sending the theme object (which can be passed to a MUI theme provider). This message is sent when a plugin registers a route (normally as part of the initial loading process) or when the user modifies either their dark mode or contrast mode preference. As mentioned, this theme object is a MUI theme and can be passed to a theme provider, but if you aren't using MUI - you can access the dark mode preference via theme.palette.mode (dark if darkmode and light otherwise) and the contrast preference via theme.colours.type (contrast if high contrast and default otherwise).

• scigateway:api:register_route: used to register a link in the sidebar menu, it takes a payload of

  {
    section: string;      // what section of the menu you want the link to be in
    link: string;         // route the link should link to 
    plugin: string;       // name of plugin
    displayName: string;  // text of the link
    order: number;        // how high up in the section should your link be - ascending order
    helpText?: string;    // (optional) help text renders a tooltip in the site tour for this link
  }
  

• scigateway:api:notification: used to trigger a notification in the parent app, it takes a payload of

  {
    message: string;   // message you would like to display in your notification
    severity: string;  // one of "success", "warning" or "error" - details the type of notification. errors and warning generate popup notifications
  } 
  

• scigateway:api:invalidate_token: used to invalidate the session token of the parent app. This will consequently redirect the user to the login page to refresh their tokens

In brief, in order to send an message, one needs to dispatch a custom event on the document like so

document.dispatchEvent(
    new CustomEvent('my-custom-event', { detail: "my-detail"})
);

The initial argument is a string representing the name of the event. In our use case, all events are named daaas-frontend and instead any information about the event itself is contained in the event detail. Because the parent app makes use of Redux, the event detail must follow the contract of an action: it contains a type describing the type of action and any data is contained in a property named payload. So, events sent should look like so:

document.dispatchEvent(
    new CustomEvent('scigateway', { detail: { type: "scigateway:api:event", payload: {data1: "x", data2: "y"} } })
);

For information on how actions should be named, see ADR decision 6.

In order to be able to listen for events, you should add an event listener that listens to daaas-frontend events and perform some check on what the type of the event is and perform the relevant action needed when a message of that typ is recieved. e.g.

document.addEventListener('scigateway', e => {
  const action = (e as CustomEvent).detail;
  if (action.type === 'scigateway:api:plugin_rerender') {
    render();
  }
});

If your plugin makes use of Redux, it may be of use to look at how the parent application handles converting Redux actions to browser events in src/state/middleware/daaas.middleware.tsx. In brief, the middleware watches for any actions that contain a broadcast property and if it is true then it automatically dispatches a CustomEvent. It also attaches a listener for daaas-frontend and handles any messages it expects to recieve from plugins and dispatches matching Redux actions for them.