Develop a Page Tool - BloomReach Experience - Open Source CMS

Develop a Page Tool

This feature is available since version 13.0.0

Introduction

Goal

Develop a channel manager page tool using the Open UI extension library.

Background

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 the BloomReach Open UI Extension JavaScript client library.

For a step-by-step example, follow the Develop a Custom Page Tool Tutorial!

Code Example

See Open UI Extension Client Library for general information and instructions on how to include the client library in your extension.

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.

API

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.

Dialog

A Page Tool can also open a dialog to interact with the user. Since version 13.2.0.

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.path * The URL of the page relative to the mount path of the channel. "/news/mypage.html" or an empty string for the home page
page.channel.id The identifier of the channel the page is part of. "example-preview"
page.channel.contextPath * The context path of the site application. "/site" or "/"
page.channel.mountPath * The mount path of the channel. "/subsite", "/europe/nl" or an empty string for the root mount
page.sitemapItem.id The UUID of the matched sitemap item. "7ebbe380-0846-408d-9ec1-ed2604bc398d"

* Available since version 13.2.0.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?