Develop a Document Field Extension

Overview

This page describes how to develop a document field extension using the Open UI extension library in Bloomreach Content.

Purpose

A Document Field Extension acts as a field within a document type. It appears in the document editing template like any other field and allows users to set a String property on the document. Content editors configure the field caption and hint. The extension runs in an iframe and provides a custom UI for setting the String value.

Communication between the extension and the Bloomreach Content editor uses the Open UI Extension client library.

API Reference

Functions

• ui.document.get()

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

  Property	Description	Example value
  id	UUID of the document handle node
  displayName	Display name of the document	"My Document"
  locale	Locale of the document	"en"
  mode	Editor mode: "view", "edit", or "compare"	"view"
  urlName	URL name of the document	"my-document"
  variant.id	UUID of the document variant node

• ui.document.field.getValue()

  Returns a promise that resolves with the current string value of a field. The extension is responsible for interpreting the string (for example, parsing JSON if needed).

  By default, the method returns the value of the Open UI field itself.

  Optionally, you can pass a string array as a path to access a specific field or nested subfield within the document. For multi-valued fields, use zero-based indices to access a specific value.

  Examples:

  • ui.document.field.getValue();
  • ui.document.field.getValue('myproject:title');
  • ui.document.field.getValue('myproject:mymultiple', 1);
  • ui.document.field.getValue('myproject:mycompound', 'myproject:name');
  • ui.document.field.getValue('myproject:mymultiplecompound', 1, 'myproject:name');

  Hint: Starting with v14.7, you can use "." to reference the current compound field when accessing other fields within the same compound. You can also omit the compound field index for convenience. For example:

  • ui.document.field.getValue('.', 'myproject:name');
    This is equivalent to ui.document.field.getValue('myproject:mycompound', 'myproject:name'); if the current compound field is named myproject:mycompound.
  • ui.document.field.getValue('.', 'myproject:name');
    This is equivalent to ui.document.field.getValue('myproject:mymultiplecompound', 1, 'myproject:name'); if the current compound field is myproject:mymultiplecompound and located at the second position. The zero-based index is detected automatically.

  Note: Since v14.7, the API call is the same for both single and multi-valued compound fields. The backend resolves the current compound field details automatically. This simplifies implementation, especially when the extension cannot easily determine the compound field name or index.

• ui.document.field.setValue()

  Sets the string value of the field. Returns a promise that resolves when the value is set. The value can be up to 100,000 characters. Larger strings are ignored, and the promise is rejected.

  The promise resolves when the value reaches the editor. It does not indicate whether validation has passed. For example, a required field check may still cause the field to be marked invalid after setting the value.

• ui.document.field.getComparedValue()

  Available only when the document editor is in "compare" mode. Returns a promise that resolves with the string value of the field being compared.

  By default, returns the value of the Open UI field itself.

  You can also pass a string array as a path to access a specific field or nested subfield. For multi-valued fields, use zero-based indices.

  Hint: As with ui.document.field.getValue(), starting with v14.7 you can use "." to refer to the current compound field and omit the index for convenience.

• ui.document.field.setHeight()

  Sets the height of the iframe containing the document field extension. Accepts a value in pixels (10–2000). Use 'auto' to automatically adjust the iframe height to its content, removing scrollbars. If the content size changes, the iframe height updates automatically. Use 'initial' to reset the iframe to its initial configured height.

• ui.document.open()

  Info: Available since v14.2.1

  Opens a document by UUID in the content perspective. Returns a promise that resolves when the document is opened.

  Property	Description	Example value
  id	UUID of the document handle node	"c580ac64-3874-4717-a6d9-e5ad72080abe"

• ui.document.navigate()

  Info: Available since v14.2.1

  Navigates to a document path in the content perspective. Returns a promise that resolves when the document is opened.

  Property	Description	Example value
  path	Absolute JCR path of the document handle node	"/content/documents/myproject/content/sample-document"

Dialog Support

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

Example Implementation

Hint: This example uses plain HTML and JavaScript for simplicity. You can use any JavaScript framework (such as Angular, Vue, or React) to develop your extension.

This "Hello World" example renders a button and sets the field value to "Hello Button" when clicked.

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>
copy

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;
}
copy