The Property Editor Contract and Property Sheet

To work smoothly in Experience Builder, the component that you create for your custom property editor must satisfy the property editor contract. This contract determines the input value that the editor component has access to and how the editor component persists this value in the overall component's property sheet. The property sheet, a collection of all the property editors for a given Experience Builder component, injects the relevant information into each property editor in the component.

The property editor contract exposes these public properties for the custom property editor component to access.

  • label
  • description
  • required
  • value
  • errors
  • schema

Here's a detailed look at the contract that describes the type of data for each of the public properties.

When a user enters a value into a property editor, the property sheet expects the editor to throw a single CustomEvent called valuechange to send the value to Experience Builder. This code sample shows an interface for the object payload that's expected for the valuechange event. Think of this interface as the output of the property editor.

After the event fires, the property sheet validates the entered value against the property editor's property type schema and persists the value to the component on the canvas in Experience Builder. If any errors occur during the validation process, they're injected back into the editor via the errors property of the property editor. (See General Guidelines for Creating a Custom Property Editor for more information to avoid common mistakes when you create a property editor component.)

In the Custom Article component example, the default editor for the textAlignment property, which is type=String, is a combobox. To replace that with a button group where users can visually click to select the alignment, create a custom Lightning web component to act as the property editor. In the Custom Article component example, this custom property editor component is called alignmentCPE. (Download the sample components to follow along.)

The component class of alignmentCPE must follow the property editor contract. This code snippet shows a basic editor component class for the property editor. Notice how the public properties of the component—value, label, schema, and errors—follow the property editor contract. Also notice how the editor is firing the valuechange event when users click a new alignment option.

Supported @salesforce Modules

You can use these @salesforce modules in a custom property editor to enhance the editor component.

See Also