Develop a Page Tool

A page tool typically displays information about the current page shown in the Channel Manager. Communication between the page tool and the Channel Manager is handled by a JavaScript library provided by BloomReach. The library hides the complexity of the window.postMessage communication with the CMS and provides a stable public API.

Client library

The client library is available as an NPM package:

npm install @bloomreach/ui-extension

The library can be used in two ways.

As a JavaScript module:

import UiExtension from '@bloomreach/ui-extension';

Or as a standalone ES5 script:

<script src="ui-extension.min.js"></script>

The latter creates a global object window.UiExtension.

Code example

The following code example shows analytics for the current page in the Channel Manager:

UiExtension.register().then((ui) => {
  console.log(`Hi ${ui.user.displayName}`);

  function showAnalytics(page) {
    // show analytics for page
  }

  ui.channel.page.get().then(showAnalytics);
  ui.channel.page.on('navigate', showAnalytics);
});

The code first registers the extension with the CMS, so the CMS knows the extension is ready for communication. The register() method returns a Promise that resolves with a ui object. The ui object can be used to access information about the CMS and interact with the CMS UI.

Static properties

The ui object contains the following properties:

Property	Description	Example value
ui.baseUrl	The URL of the CMS that hosts the extension.	"https://cms.example.com"
ui.extension.config	The value of the 'frontend:config' property.	"{ apiKey: '1234' }"
ui.locale	The locale of the CMS user as selected on the login page.	"nl"
ui.timeZone	The time zone of the CMS user as selected on the login page.	"Europe/Amsterdam"
ui.user.id	The username of the CMS user.	"admin"
ui.user.firstName	The first name of the CMS user.	"Suzanna"
ui.user.lastName	The last name of the CMS user.	"Doe"
ui.user.displayName	Concatenation of the first and last name of the CMS user, or the username if both are blank.	"Suzanna Doe" or "admin"
ui.version	The version of the CMS.	"13.0.0"

Functions

• ui.channel.refresh()
  Refreshes the metadata of the currently shown channel (e.g. whether it has changes, the sitemap, etc.). The Channel Manager UI will be updated to reflect the channel’s refreshed metadata.
• ui.channel.page.get()
  Returns a Promise that resolves with properties of the current page (see below).
• ui.channel.page.refresh()
  Refreshes the page currently shown in the Channel Manager.

Events

Several UI objects have an 'on' method that registers an event handler. The 'on' methods return a function which can be used to deregister the handler. The following events are available:

• ui.channel.on('changes.publish', handler)
  Registers a handler that's called whenever a user publishes changes in the current channel. Available since version 13.1.

• ui.channel.on('changes.discard', handler)
  Registers a handler that's called whenever a user discards changes in the current channel. Available since version 13.1.

• ui.channel.page.on('navigate', handler)
  Registers a handler that's called whenever a user navigates to another page in the Channel Manager. The handler gets properties of the current page (see below) as an argument.

Page properties

A 'page' object with the following properties is returned by channel.page.get() and passed to the channel.page.on('navigate') handler:

Property	Description	Example value
page.id	The UUID of the hst:component root node of the page hierarchy.	"446cdf18-23cd-48b3-89f8-964e6865be0c"
page.url	The public URL of the page.	"http://www.example.com/news"
page.channel.id	The identifier of the channel the page is part of.	"example-preview"
page.sitemapItem.id	The UUID of the matched sitemap item.	"7ebbe380-0846-408d-9ec1-ed2604bc398d"