UI extensions in CMS (SaaS)

11 min

UI extensions add your own tools and pages to the Optimizely Content Management System (SaaS) interface. Editors can work with external data, run custom checks, or use richer input fields without leaving CMS. For example, an extension can show analytics for the open page or replace a plain text field with a color picker.

Each extension is part of an app that you build and install in Optimizely Connect Platform (OCP) for your CMS instance. CMS displays the extensions that the app provides and connects them to the content that editors work with.

Extension types

An extension displays in one of three places in CMS.

Type	Where it displays	How you open it	Tied to the open content
Sidebar	A panel next to the content you are editing. Editors can resize it from 350 to 600 pixels.	Select the extension icon in the editing view.	Yes
Extensions view	A full page in CMS.	Select Extensions in the CMS navigation menu, and then select the extension.	No
Property editor	Replaces the standard input field for one property.	Opens when you edit content that uses the property.	Yes, and to the property value

Use a sidebar for tools that help with the open content item, such as a checklist or an assistant. Use an Extensions view for standalone tools, such as dashboards or reports. Use a property editor when a field needs a richer input, such as a color picker or a map. An app can provide extensions of more than one type.

Prerequisites

An OCP app that contains UI extensions and is installed for your CMS instance. See Add an extension to CMS.

Edit access in CMS. Every user who can edit content can use every installed extension. CMS has no per-extension access control.

Administrator access in CMS to assign property editors and to open the Extensions Diagnostics page.

Add an extension to CMS

CMS does not have its own install step for extensions. When you install an app with extensions for your CMS instance, CMS lists the app's extensions automatically.

Build an OCP app that contains your extensions, or use one that your developers built. See Build your own extension.

Install the app in OCP for your CMS instance. Each CMS instance has its own installation, settings, and credentials. See Installation scope in the OCP documentation.

Enter the app settings in OCP if the app has a settings form.

Go to Settings > Tools > Extensions Diagnostics in the CMS (SaaS) UI and confirm that the app and its extensions are listed.

CMS can take a few minutes to display a recently installed or updated app. To load the latest list immediately, select Refresh on the Extensions Diagnostics page, and then reload the CMS page.

When you uninstall an app in OCP, its extensions disappear from CMS. Properties that used one of its property editors return to the standard editor. CMS keeps the property values.

Assign a custom property editor

Property editor extensions replace the standard input field for a property of a content type. You need administrator access.

Go to Settings > Content Types in CMS.

Select the content type and go to Properties for that content type.

Click the property you want to change.

Select the extension in Editor. The list shows only extensions that support the property's type. To return to the standard editor, select Default.

Click Save.

A property editor extension supports one of the following property types:

Text property – String, Long string, or XHTML string. See Text property.

Number property – Integer or Floating point number. See Number property.

If Editor does not display, or the extension is missing from the list, no installed extension supports the property's type.

Use an extension

Use extensions to work with external tools and data without leaving CMS. Sidebars and Extensions views open from the CMS UI, and property editors open in the fields you edit.

Open a sidebar extension

Open a content item in the editing view. The editing view displays an icon for each sidebar extension.

Hover over an icon to see the extension name.

Select the icon to open the extension panel. The panel shows the extension name and works with the content item you have open.

Drag the edge of the panel to resize it.

Select the extension icon again or select Close to close the panel.

One sidebar panel is open at a time. Selecting another icon replaces the open panel.

Open an Extensions view

Select Extensions in the CMS navigation menu. The page lists the extensions that open as a full page. If no installed app provides one, the page displays No extensions are available.

Select an extension to open it as a full page.

Select Back to list to return to the list.

Use a property editor

When an administrator assigns a property editor extension to a property, the extension replaces the standard field in the editing view. You enter and change the value in the extension, and CMS saves it with the content item as usual. If the content item is read-only for you, CMS tells the extension that the field is read-only.

Check extensions with Extensions Diagnostics

The Extensions Diagnostics page shows which apps and extensions are available in your CMS instance. Use it to confirm an installation, check an extension's status, or gather details for support. The page is read-only and available to administrators.

Go to Settings > Extensions Diagnostics. The page displays the following information:

Latest SDK version – The most recent SDK version that CMS supports. Compare it with the version your extensions use.

Service address and Instance ID – The connection details CMS uses to load extensions for this instance. Include them when you contact Optimizely Support.

Apps, Extensions, and Functions – The number of installed apps, the extensions they provide, and the back-end functions those extensions can call.

Apps table – Each installed app with its name, ID, version, and functions.

Extensions table – Each extension with its name, ID, type, SDK version, app, and status. Active means the extension works normally. Deprecated means it uses an outdated SDK version and needs an update from its developer. Use the search field and the All apps filter to find an extension.

Refresh – Loads the latest list of apps and extensions. Select it after you install, update, or uninstall an app.

When UI extensions are not available for your instance, the page displays Extensions are turned off in this environment. Contact Optimizely Support.

Extension limits

Extensions run in an isolated frame inside CMS. The frame protects CMS and your content from extension code, and it limits what an extension can do:

Browser storage – Local storage, session storage, and cookies are not available. Store data in your app's back end instead.

Forms – Extensions cannot submit HTML forms. Send data from code to your app's back end instead.

New windows – Extensions cannot open popups, new tabs, or new windows, and cannot redirect the CMS page. An extension can ask CMS to open a content item.

Dialogs and downloads – Extensions cannot open browser dialogs, such as alert or confirm, or start file downloads.

Device features – The clipboard, full screen, camera, microphone, and location are not available.

Network – Extensions can call services and load scripts, styles, images, and fonts over HTTPS only.

Plan features around these limits. For example, a copy-to-clipboard button or a full-screen mode does not work inside an extension. For the full list of technical limits, see Sandbox and runtime limits in the OCP documentation.

Build your own extension

Developers build extensions as React web interfaces with the Optimizely CMS Extensibility SDK (@optimizely/cms-extensibility-sdk). The npm page lists the latest version and the full API reference. The SDK connects your extension to CMS and lets it do the following:

Read the content item – Read the content item the editor has open, and react when the editor switches to another item.

Open a different item – Ask CMS to open a different content item.

Read and update the property value – Read and update the value of the property a property editor is assigned to.

Call back-end functions – Call functions in your app's back end, where secrets and credentials stay safe.

Signal readiness – Tell CMS when the extension is ready.

You package extensions in an OCP app. In the app manifest, you choose where each extension displays with the sidebar, view, or property-editor key. A property editor also declares the property type it supports. The OCP CMS UI extensions guide covers the app setup:

Manifest – Declare extensions and property types.

Call the backend – Add back-end functions for secrets, storage, and server-side work.

Local testing – Try extensions before you deploy.

For a look that matches CMS, build your interface with Optimizely Axiom, the design system CMS uses.

Troubleshoot UI extensions

Use the following table to find the cause of a common extension problem and the fix that gets the extension working again.

Symptom	Cause	Solution
An installed or updated extension does not display in CMS.	CMS has not loaded the latest list of extensions yet.	Select Refresh on the Extensions Diagnostics page, and then reload the CMS page.
The Extensions menu or the sidebar icons are missing.	UI extensions are not turned on, or no installed app provides that extension type.	Open Extensions Diagnostics and check the message and the Extensions table.
A sidebar panel or Extensions view stays blank.	The extension did not start, or it uses a blocked feature.	Check the extension's status in Extensions Diagnostics, and send its name and ID to the app developer.
A property shows the standard field instead of the custom editor.	The app was uninstalled or updated.	Confirm the extension is listed in Extensions Diagnostics, and select it again in the property's Editor setting.
An extension is missing from a property's Editor list.	The extension does not support the property's type.	Check the supported types in Assign a custom property editor.
An extension shows a warning icon or the Deprecated status.	The extension uses an outdated SDK version.	Ask the app developer to update the extension to the latest SDK version.