Use Open UI Dialogs

Overview

This page explains how to open and use dialogs from within an Open UI extension in Bloomreach Content.

When to Use

Use Open UI dialogs when you need to prompt the user for additional input or selection as part of a Page Tool or Document Field Extension. Dialogs cannot be configured as standalone extensions. They must be triggered from an existing Page Tool or Document Field Extension.

For example, use a dialog to let users select a value from a list, or to provide a custom input interface for a document field.

API Reference

The Open UI extension client library provides methods for working with dialogs. When a dialog is opened, Bloomreach Content displays it in an iframe with a header bar containing a title and a close button.

Methods

ui.dialog.open(options)

Opens a modal dialog. The options object defines properties such as title, size, and the URL of the dialog extension. See Dialog Options for details. Returns a promise. The promise resolves or rejects depending on how the dialog is closed. If a dialog is already open, the promise is rejected with error code DialogExists to prevent nested dialogs.
ui.dialog.options()

Returns a promise that resolves with the options object of the currently open dialog. Use this method in the dialog extension to access values passed from the parent extension (for example, the current field value). If no dialog is open, the promise is rejected with error code IncompatibleParent.
ui.dialog.close(value)

Closes the open dialog and resolves the promise returned by ui.dialog.open() with the provided value. If no dialog is open, the promise is rejected with error code IncompatibleParent.
ui.dialog.cancel()

Closes the open dialog and rejects the promise returned by ui.dialog.open() with error code DialogCanceled. If no dialog is open, the promise is rejected with error code IncompatibleParent.

Dialog Options

The following options are available when opening a dialog:

Option	Description
`value` (Transferable, optional)	A value to be processed by the dialog extension. For example, pass the current field value so the dialog can preselect it. The value must be transferable to allow cross-iframe communication.
`size` (DialogSize, optional)	The dialog size. Accepts `'small'`, `'medium'`, or `'large'`. Default is `'medium'`.
`title` (string, required)	The dialog's title text.
`url` (string, required)	The URL to load in the dialog iframe. Can be absolute or relative to the extension's URL.

Implementation Example

Note: The following example uses plain HTML and JavaScript. You can use any JavaScript framework (such as Angular, Vue, or React) to build your extension.

This example demonstrates how to add a dialog to a Document Field Extension. Instead of setting the field value directly, the extension opens a dialog when the user clicks a button. The dialog allows the user to enter a new value, which is then set as the field value.

Parent Extension (`index.html`)

The HTML renders a button and loads the required scripts:

<!doctype html>
<html>
  <head>
    <title>Document Field Extension Example</title>

    <script type="text/javascript" src="https://unpkg.com/@bloomreach/[email protected]/dist/ui-extension.min.js"></script>
    <script type="text/javascript" src="index.js"></script>
  </head>
  <body>
    <p>Value: <span id="fieldValue"></span></p>
    <button id="openDialogButton">Open Dialog</button>
  </body>
</html>

Parent Extension Script (`index.js`)

This script registers the extension, displays the current field value, and sets up the button to open the dialog. When the dialog returns a value, the script updates the field.

document.addEventListener('DOMContentLoaded', async () => {
  try {
    const ui = await UiExtension.register();
    const brDocument = await ui.document.get();
    const value = await ui.document.field.getValue();
    
    showFieldValue(value);
    initDialogButton(ui, brDocument.mode);
    
  } catch (error) {
    console.error('Failed to register extension:', error.message);
    console.error('- error code:', error.code);
  }
});

function initDialogButton(ui, mode) {
  const buttonElement = document.querySelector('#openDialogButton');
  if (mode !== 'edit') {
    buttonElement.style.display = 'none';
    return;
  }

  buttonElement.style.display = 'block';
  buttonElement.addEventListener('click', async () => {
    try {
      const curvalue = await ui.document.field.getValue();
      const dialogOptions = {
        title: 'Dialog',
        url: './dialog.html',
        size: 'small',
        value: curvalue,
      };    
      const response = await ui.dialog.open(dialogOptions);
      await ui.document.field.setValue(response);
      showFieldValue(response);
    } catch (error) {
      if (error.code === 'DialogCanceled') {
        return;
      }

      console.error('Error after open dialog: ', error.code, error.message);
    }
  });
}

function showFieldValue(value) {
  document.querySelector('#fieldValue').innerHTML = value;
}

Dialog Extension (`dialog.html`)

The dialog HTML renders a form for entering a new value and loads the required scripts:

<!doctype html>
<html>
  <head>
    <title>Dialog Example</title>

    <script type="text/javascript" src="https://unpkg.com/@bloomreach/[email protected]/dist/ui-extension.min.js"></script>
  </head>
  <body>
    <p>Current value: <span id="currentValue"></span></p>
    <p>New value: <input id="newValue" type="text"/></p>
    <button id="setFieldValueButton">Set Field Value</button>
    <script type="text/javascript" src="dialog.js"></script>
  </body>
</html>

Dialog Script (`dialog.js`)

This script registers the dialog extension, retrieves the current value from the dialog options, and handles setting the new value.

let ui;
(async () => {
  try {
    ui = await UiExtension.register();
    const options = await ui.dialog.options();
    document.querySelector('#currentValue').innerHTML = options.value;
  
  } catch(error) {
    console.error('Failed to register extension:', error.message);
    console.error('- error code:', error.code);
  }
})();

const buttonElement = document.querySelector('#setFieldValueButton');
buttonElement.addEventListener('click', async () => {
  if (ui == null) {
    console.log("UI Extension not properly registered");
    return;
  }

  const newValue = document.querySelector('#newValue').value;
  ui.dialog.close(newValue);            
});

Verification

To verify the dialog integration:

Open the extension in Bloomreach Content.
Click the "Open Dialog" button.
Enter a new value in the dialog and click "Set Field Value".
Confirm that the field value updates in the parent extension.