#Screens and Server

Your Addon is an ongoing process that communicates with MercuryCMS via calls to HTTP endpoints. You can use the Addon System API to talk to MercuryCMS and MercuryCMS will also make requests to your Addon to inform it of events such as the Build completing or to ask for the Addon to provide your Addon's interface Screens. Your interface Screens are also able to communicate with your Addon directly.

When MercuryCMS launches your Addon's process, it passes it the following arguments.

Here are some examples of how to get this information that you can adapt to use in any language. Note that these values cannot be hardcoded into your Addon. MercuryCMS could be running on any port other than 3001, your Addon's ID is assigned at installation, and its assigned communication ports are assigned randomly every time the Addon is started.

// static-cms-addon
import cms from 'static-cms-addon'
let addonPorts = cms.getPorts() // [49153, 49154]
let addonPort = cms.getPort() // 49153, useful for most processes that only have a single port assigned
let cmsPort = cms.getCmsPort() // 3001
let addonId = cms.getAddonId() // 639b8f837f5fb8a39404280a
let cmsUrl = cms.getUrl() // http://localhost:3001

// js
let addonPorts = process.argv[process.argv.indexOf('--ports') + 1].split(',') // [49153, 49154]
let addonPort = process.argv[process.argv.indexOf('--ports') + 1].split(',')[0] // 49153, useful for most processes that only have a single port assigned
let cmsPort = process.argv[process.argv.indexOf('--cms-port') + 1] // 3001
let addonId = process.argv[process.argv.indexOf('--addon-id') + 1] // 639b8f837f5fb8a39404280a
let cmsUrl = `http://localhost:${cmsPort}` // http://localhost:3001

#Starting your Addon Server

You can use whatever software or packages you want to run your server. static-cms-addon comes with a built-in Express server that makes it easy to get started quickly. This built-in server is compatible with all Express middleware and packages, has built-in error handling (will send 500 codes if a Promise rejection is encountered or an Error is thrown), has express.static middleware available at cms.static, and has Express Formidable installed so you have access to req.fields and req.files.

let app = cms.createServer()

app.use(cms.static('public'))

app.get('/settings', (req, res) => {
  let settings = await cms.database.findOne('settings')
  res.send(settings)
})

app.listen(cms.getPort())

#Screens

When the user navigates to any route that begins with /addons/{{ addonName }}/ in MercuryCMS, that request will be proxied to whichever process defined in your addon.json manifest has designated itself as the interface process. For example, if you want to have a page called /addons/{{ addonName }}/api-keys, you would create a server that listens for GET /api-keys.

Whatever <title> you set on the page will be used for the page title. You can also use JavaScript to update your <title> and MercuryCMS will detect the changes.

#API

As mentioned above, routes that begin in /addons/{{ addonName }} in MercuryCMS will be routed to your addon. This applies to all traffic which means you can allow your interface screens to make requests to your own Addon. If you include <script src="/api/addon/script.js"></script> into your HTML page, you can use cms.getUrl() to get your Addon's API URL. For example, if your Addon name was demo, it would return https://staging.example.mercurycms.app/addons/demo.

#/api/addon/script.js

Including <script src="/api/addon/script.js"></script> gives your Addon's Screen access to a cms object that provides a few useful functions. It also automatically applies dark mode based on the user's preferences.

#/api/addon/style.css

Including <link rel="stylesheet" href="/api/addon/style.css"> in your Addon's Screen will add the same CSS MercuryCMS uses to build its interface. Documentation for this will be provided soon.