Develop a Page Tool

Overview

This page explains how to develop a page tool for Bloomreach Content using the Open UI extension library.

When to Use

Create a page tool when you need to display information about the current page in Experience Manager or interact with page-level data through a custom UI extension.

Prerequisites

Familiarity with JavaScript
Access to the Open UI Extension JavaScript client library
Experience Manager version 13.1 or higher (some features require 13.2.0)

Implementation Steps

1. Include the Open UI Extension Client Library

Refer to Open UI Extension Client Library for instructions on adding the client library to your extension.

2. Register the Extension and Access Page Data

The following example demonstrates how to register your extension and display analytics for the current page:

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);
});

UiExtension.register() registers the extension with Experience Manager and returns a Promise that resolves to the ui object.
Use the ui object to access CMS information and interact with the UI.
ui.channel.page.get() retrieves properties of the current page.
ui.channel.page.on('navigate', showAnalytics) registers a handler to update analytics when the user navigates to a different page.

For a step-by-step tutorial, see Develop a Custom Page Tool Tutorial.

API Reference

Functions

ui.channel.refresh(): Refreshes the metadata of the current channel, such as change status and sitemap. The Experience Manager UI updates to reflect the refreshed metadata.
ui.channel.page.get(): Returns a Promise that resolves with the current page's properties.
ui.channel.page.refresh(): Refreshes the page currently displayed in Experience Manager.

Dialog Support

Page tools can open a dialog to interact with users. Dialog support is available since version 13.2.0.

Events

You can register event handlers using the on method. Each on method returns a function that deregisters the handler.

Available events:

ui.channel.on('changes.publish', handler): Invokes the handler when a user publishes changes in the current channel. Available since version 13.1.
ui.channel.on('changes.discard', handler): Invokes the handler when a user discards changes in the current channel. Available since version 13.1.
ui.channel.page.on('navigate', handler): Invokes the handler when a user navigates to a different page in Experience Manager. The handler receives the current page's properties as an argument.

Page Properties

The channel.page.get() function and the channel.page.on('navigate') event handler provide a page object with the following properties:

Property	Description	Example value
`page.id`	UUID of the `hst:component` root node of the page hierarchy.	"446cdf18-23cd-48b3-89f8-964e6865be0c"
`page.url`	Public URL of the page.	"http://www.example.com/news"
`page.path` *	URL of the page relative to the channel's mount path.	"/news/mypage.html" or ""
`page.channel.id`	Identifier of the channel the page belongs to.	"example-preview"
`page.channel.contextPath` *	Context path of the site application.	"/site" or "/"
`page.channel.mountPath` *	Mount path of the channel.	"/subsite", "/europe/nl", or ""
`page.siteMapItem.id`	UUID of the matched sitemap item.	"7ebbe380-0846-408d-9ec1-ed2604bc398d"

* Available since version 13.2.0.

Verification

After registering your extension, verify that it displays or updates information based on the current page in Experience Manager.
Use the browser console to confirm that event handlers are triggered as expected.