UI extension client library

Introduction

Goal

Use the Bloomreach UI extension JavaScript client library to develop your own custom integrations.

Background

Communication between a custom integration and the Content SaaS UI is handled by a JavaScript library provided by Bloomreach. The library hides the complexity of the window.postMessage communication with the Content SaaS UI and provides a stable public API.

Include client library

The client library is available as an NPM package:

npm install @bloomreach/ui-extension-saas

The library can be used in two ways.

As a JavaScript module:

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

Or as a standalone ES5 script:

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

📘
There may be a more recent version of the ui-extension-saas package, check https://www.npmjs.com/package/@bloomreach/ui-extension-saas for the most up to date information.

The latter creates a global object window.UiExtension.

Register extension

The UiExtension object needs to be registered first:

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

The code snippet above registers the extension with the Content SaaS application, so the latter 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 Content SaaS environment and interact with the Content SaaS UI.

API

Static properties

The ui object contains the following properties:

Property	Description	Example value
`ui.baseUrl`	The URL of the Content SaaS environment that hosts the custom integration.	"https://cms.example.com"
`ui.extension.config`	The value of the custom integration's Configuration field.	"{ apiKey: '1234' }"
`ui.locale`	The locale of the Content SaaS user as selected on the login page.	"nl"
`ui.styling`	The styling of the user interface in which the extension is shown. For page tools this is always "material" for AngularJS Material.	"material"
`ui.timeZone`	The time zone of the Content SaaS user as selected on the login page.	"Europe/Amsterdam"
`ui.user.id`	The username of the Content SaaS user.	"admin"
`ui.user.firstName`	The first name of the Content SaaS user.	"Suzanna"
`ui.user.lastName`	The last name of the Content SaaS user.	"Doe"
`ui.user.displayName`	Concatenation of the first and last name of the Content SaaS user, or the username if both are blank.	"Suzanna Doe" or "admin"
`ui.version`	The version of the Content SaaS environment.

Extension-specific properties, functions, and events

The ui object provides several other properties, functions, and events which are specific to a type of extension and are described on the relevant pages: