Inline editable components

Making a component inline editable allows content editors to change the component’s content directly in the Page Builder preview column, with said changes presenting in real-time and in WYSIWYG fashion.

Inline editable components also present distinctly. Such components show a dotted line under the component field or, in the case of the * FormattedText field, a dotted rectangle surrounding the field.

The following component properties can be configured to be inline editable:

Make a component inline editable

Making a component inline editable requires

  1. adding the ui-metadata property to the manifest.json file with an appropriate name-value pair; and

  2. editing the Common JS file to specify the mapping between the variables passed to the main function and the property defined in the manifest.json file.

Add the ui-metadata property to manifest.json

The ui-metadata property is an optional property. It informs the interaction behavior of the component in the Visual Page Builder interface.

Adding this property to a component’s manifest.json file constitutes a non-breaking change. It does not effect the component’s behavior on Standard pages.

The specific ui-metadata property and name-value pair required is as follows:

"ui:metadata": {
    "inlineEditable": true
}

An example of adding the ui-metadata property to a string property is as follows:

"author": {
    "type": "string",
    "title": "Author",
    "ui:metadata": {
        "inlineEditable": true
    }
}

An example of adding the ui-metadata property to a SquizImage proerty (also known as an inline action) is as follows:

"image": {
    "type": "SquizImage",
    "title": "Image",
    "ui:metadata": {
        "inlineEditable": true
}

Specify the mapping in the Common JS file

To make a component inline editable, specify the mapping between the variables passed to the main function and the property defined in manifest.json.

This is done by adding a data-sq-field="<property-name-here>" property to the HTML element that wraps the property field.

For example:

<div data-sq-field="author">
    ${author}
</div>

More completely, consider the following JavaScript example:

export default {
    async main({ quote, author, foregroundColor, backgroundColor }) {
        return `<div>
    <blockquote>
    <div style="color:${foregroundColor}; background-color:${backgroundColor}">
    ${quote}
    </div>
    <p>
    <em>— ${author}</em>
    </p>
    </blockquote>
    </div>`;
    }
}

As set out here, the author and quote fields are not editable inline.

To make these fields inline editable, add data-sq-field="<property-name-here>" properties to the appropriate wrapping HTML elements. For example:

export default {
    async main({ quote, author, foregroundColor, backgroundColor }) {
        return `<div>
    <blockquote>
    <div data-sq-field="quote" style="color:${foregroundColor}; background-color:${backgroundColor}">
    ${quote}
    </div>
    <p>
    <em>— <span data-sq-field="author">${author}</span></em>
    </p>
    </blockquote>
    </div>`;
    }
}

In this example

  1. the data-sq-field="quote" property was added to the <div></div> tag that wraps the ${quote} field; and

  2. a <span></span> tag was wrapped around the ${author} field and the data-sq-field="author" property was added to the <span></span> tag.

    The <span></span> tag was added because only the ${author} field should be end-user editable.

    If the data-sq-field="author" property was added to the already extant <em></em> tag, this tag would be added to the editable field. In this case, this was not a desirable outcome.

    When adding the `data-sq-field="<property-name-here>" to a wrapping HTML element, best practice is to only enable editing of the component field.

specify the mapping of an array in the Common JS file

When enabling inline editing of array objects, the data-sq-field="<property-name-here>" property must reference the entry index.

For example:

<div data-sq-field="stats[${index}].value">
    ${item.value}
</div>

This allows for the editing of each item in the array.

For a more complete example of a component that makes use of arrays, see the example Accordion component service in the SquizLabs DXP component library.

Inline editing of complex component behaviors require added wrapper elements

Components that allow for complex behaviors — for example event handlers in FormattedText fields — do not work in the Page Builder preview column unless

  1. a further wrapper HTML element is added; and

  2. the event handler is attached to the added wrapper element.

For example the following will not work as expected:

<div data-sq-field="quote">   <!-- event handlers attached here will not work -->
  ${quote}
</div>

For this component to work as expected in Page Builder, add a further wrapper element and attach the event handler to this added element:

<div class="wrapper">   <!-- attach event handlers to this div -->
	<div data-sq-field="quote">
  	${quote}
	</div>
</div>