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:

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

• ui.channel.page.on('navigate', handler)
  Registers a handler that's called whenever a user navigates to another page in the Channel Manager. Returns a function that deregisters the handler again. 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: