Bloomreach

Bloomreach Documentation version

This article covers a Bloomreach Experience Manager version 13. There's an updated version available that covers our most recent release.

Extend / Open UI Extensions / Document Fields / Develop a Document Field Extension

Develop a Document Field Extension

This feature is available since Bloomreach Experience Manager 13.2.0

Introduction

Goal

Develop a document field extension using the Open UI extension library.

Background

A Document Field Extension functions as a field in a document type. It appears in a document editing template just as any other field and can be used to set a String property in the document. The Bloomreach Experience Manager content editors provide the field caption and hint. The extension is shown in an iframe and provides the UI to set the String value.

The communication between the Bloomreach Experience Manager editor and the extension is done using the Open UI Extension client library.

API

Functions

  • ui.document.get()

    Returns a promise that resolves with information about the current document. The resolved object has the following properties:

    Property   Description Example value
    id The UUID of the document handle node.  
    displayName The display name of the document. "My Document"
    locale The locale of the document. "en"
    mode The mode of the editor that shows the extension. Either "view", "edit" or "compare". "view"
    urlName The URL name of the document. "my-document"
    variant.id The UUID of the document variant node.  
  • ui.document.field.getValue()

    Returns a promise that resolves with the current string value of the field. It's up to the extension to interpret the string, e.g. parse it as JSON.

  • ui.document.field.setValue()

Updates the string value of the field. Returns a promise that resolves when the value has been set. The string can contain at most 100K characters to avoid the storage of unreasonable amounts of data (e.g. when an extension gets compromised). Larger strings will be ignored and return a rejected promise.

Note that validation of the set value is not reflected in the returned promise. A resolved promise just means the value reached the surrounding editor. Any client-side validation (e.g. the 'required' check) may still trigger the field to become invalid.

  • ui.document.field.getComparedValue()

Only available when the "mode" of the document is "compare". Returns a promise that resolves with the string value of the field value to compare.

  • ui.document.field.setHeight()

Sets the height of the iframe that surrounds the document field extension to the given number of pixels. Valid values are from 10 to 2000. When calling the function with the value 'auto', the iframe is set to the height of the iframe. This gives the option to show the iframe without scrollbars. When the size of the iframe content changes, the height of the iframe is automatically adjusted. When calling the function with the value 'initial', the iframe is set to the initial height from the extension configuration.

Dialog

A Document Field Extension can open a dialog to interact with the user.

Code Example

For simplicity, this is a plain HTML/JavaScript example. Extensions can be developed using your JS framework and tools of choice, e.g. Angular, Vue, React, etc.

This "Hello World" example of a document field extension renders a button and sets the field value to "Hello Button" when the user clicks the button.

The HTML for the extension renders the button and loads the client library and the script for the extension:

index.html

<!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="setFieldValue">Set Field Value</button>
  </body>
</html>

The script registers the extension, shows the field value, enables the button, and adds an event listener to the button to set the field value when the user clicks the button:

index.js

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);
    initSetFieldValueButton(ui, brDocument.mode);
    
  } catch (error) {
    console.error('Failed to register extension:', error.message);
    console.error('- error code:', error.code);
  }
});

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

  buttonElement.style.display = 'block';
  buttonElement.addEventListener('click', async () => {
    try {
      var value = 'Hello Button'; 
      ui.document.field.setValue(value);
      showFieldValue(value);
    } catch (error) {
      console.error('Error: ', error.code, error.message);
    }
  });
}

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

 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?