#Events

In addition to your Addon contacting the MercuryCMS for information, your Addon can also be notified by MercuryCMS of specific Events. You can then react to these Events.

To subscribe to the Event System, simply provide an eventPath key to whichever process(es) you would like to be notified in your Addon's manifest.

{
  "name": "demo",
  "displayName": "Demo",
  ...
  "processes": {
    "main": {
      "type": "node",
      "main": "/index.js",
      "ports": 1,
      "interface": true,
      "eventPath": "/api/events"
    }
  }
}

When an Event occurs, MercuryCMS will make a POST request containing JSON data to your Addon's specified process(es) (using the first assigned port number for each). Your Addon will be expected to receive, handle, and respond to this request in a timely manner.

Depending on the Event, responses can be as simple as a 200 status code with no body, or you can return JSON objects with data.

#Example Responses

Here is an example setup for an Event response with and without using static-cms-addon.

import cms from 'static-cms-addon'

let settings = {
  apiUrl: 'https://example.com',
}

let app = cms.createServer()

app.on('buildStarted', e => {
  e.send({
    buildObjects: {
      apiUrl: settings.apiUrl,
    }
  })
})

app.listenToEvents('/api/events')
app.listen(cms.getPort())

import express from 'express'
import formidable from 'express-formidable'

let addonPort = process.argv[process.argv.indexOf('--ports') + 1].split(',')[0]

let settings = {
  apiUrl: 'https://example.com',
}

let app = express()
app.use(formidable())

app.post('/api/events', (req, res) => {

  // handle buildStarted event
  if (req.fields.event.type == 'buildStarted') {
    res.send({
      buildObjects: {
        apiUrl: settings.apiUrl,
      }
    })
    return
  }

  // return a simple 200 status code if the event is unrecognized
  res.send()

})

app.listen(addonPort)

app.on() will return the callback passed in. You can then pass that to app.off('buildStarted', callback) to stop listening to that Event Type. app.on() can also be called multiple times to have multiple listeners.

#Event Types

This is a list of all of the Event Types that MercuryCMS will send your Addon. These will only be sent to processes that have defined an eventPath in their manifest. New Event Types will be added over time, so it's important to always return a 200 when receiving any Event.

When using the static-cms-addon Helper Package, calling app.listenToEvents() on the server instance will automatically do this for you if your callback functions don't exist, or fail to call e.send(). Note that your callback functions may be async and it will await before automatically sending. You can call e.wait() to prevent it automatically sending a 200 in the scenario where you may queue some task and have the queue handle calling e.send(), though you should avoid taking a long time to respond as MercuryCMS requires a response before it can continue its processes.