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
- 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:
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" |