Use the Open UI Extension Client Library

Overview

This page explains how to use the Bloomreach Open UI Extension JavaScript Client Library to develop a custom UI extension.

Purpose

The Open UI Extension Client Library enables communication between your custom UI extension and the CMS UI. It abstracts the details of window.postMessage and provides a stable public API for extension development.

For detailed type information, refer to the TypeScript API reference for the Open UI Extension Library.

Installation

Install the client library using npm:

npm install @bloomreach/ui-extension
copy

You can use the library in two ways:

• As a JavaScript module:

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

• As a standalone ES5 script:

  <script src="https://unpkg.com/@bloomreach/[email protected]/dist/ui-extension.min.js"></script>
  

  This approach creates a global object: window.UiExtension.

Registering the Extension

Before your extension can interact with the CMS, you must register it. Call the register() method on the UiExtension object:

UiExtension.register().then((ui) => {
  // your code goes here ...
});
copy

The register() method registers your extension with the CMS application. It returns a Promise that resolves to a ui object. Use the ui object to access CMS information and interact with the CMS UI.

API Reference

Static Properties

The ui object provides the following properties:

Property	Description	Example value
ui.baseUrl	URL of the CMS hosting the extension.	"https://cms.example.com"
ui.extension.config	Value of the 'frontend:config' property.	"{ apiKey: '1234' }"
ui.locale	Locale selected by the CMS user on the login page.	"nl"
ui.styling*	User interface styling for the extension. For page tools, always "material" (AngularJS Material).	"material"
ui.timeZone	Time zone selected by the CMS user on the login page.	"Europe/Amsterdam"
ui.user.id	Username of the CMS user.	"admin"
ui.user.firstName	First name of the CMS user.	"Suzanna"
ui.user.lastName	Last name of the CMS user.	"Doe"
ui.user.displayName	First and last name of the CMS user, or username if both are blank.	"Suzanna Doe" or "admin"
ui.version	CMS version.	"13.2.0"

*ui.styling is available since version 13.2.0.

Extension-Specific Properties, Functions, and Events

The ui object includes additional properties, functions, and events specific to the extension type. Refer to the following pages for details:

• Page Tools
• Document Field Extensions
• Dialogs