Make component configuration for your Experience Builder users more convenient and intuitive: create custom property editors and types for your custom Lightning Web Components. Gone are the days when configuring a component was limited to basic text boxes and dropdowns. This blog post will show you how to make your Lightning Web Components visually interactive and easy to configure.
Creating a custom property editor
With custom property editors, you can create any type of UI field for configuring a property value in Experience Builder. For instance, instead of a text field where your users would type in a date, your component property panel can offer a date selector with a pop-up calendar where users can click to select a date.
A custom property editor is really just a Lightning Web Component. Creating one is just like creating any other Lightning Web Component, with just a few extra details. Let’s take a look at how to create one. We’ll use text alignment as an example.
Scenario: Say that you’re working with a custom Lightning Web Component named MyCustomComponent . For the textAlignment property, instead of the default String editor, you envision having a button group where users can adjust alignment with one click.
To create this button group, you can create a Lightning Web Component that acts as a custom property editor for the textAlignment property of the String type. We’ll name this new custom editor alignmentCPE.
To create this custom property editor, follow these basic steps.
Step 1: Create a Component Class
For the alignmentCPE component to act as a custom property editor, it must adhere to the property editor contract. The contract requires your custom property editor component to include certain public properties in its element class: label, description, required, value, errors, and schema. See our guide for more information about the property editor contract. Here’s a basic class snippet for creating a component class.
Step 2: Create the Component UI
Next, let’s craft a user-friendly UI for your property editor using the same HTML and CSS that you would use for other Lightning Web Components.
Here’s a code snippet for the alignmentCPE component.
Step 3: Update the XML Configuration
Finally, ensure that the js-meta.xml file of your component recognizes alignmentCPE as a property editor.
Sometimes you want to go further than creating one custom property editor. For example, you may have multiple properties on your custom Lightning Web Component, and you may want these properties to be grouped in a specific way, such as in tabs or in accordion sections. Or, you may have multiple properties that you want to reuse in different Lightning Web Components.
In these cases, you can create a custom property type. With a custom property type, you can group properties in tabs or accordions. You can put multiple properties in a custom property type and reuse this custom property type without having to re-create each of these properties for each component. You can even add more validation rules to certain properties. For example, for a URL field, you can specify which protocols to allow (for example, https, http).
Now let’s shift our focus to custom property types.
Creating a custom property type
A custom property type is defined using a new metadata type called ExperiencePropertyTypeBundle.
To create a custom property type, follow these steps.
Scenario: Say that you’re working with your custom Lightning Web Component, MyCustomComponent . You want to create a complex property type, layoutAndBorderStyle, that includes sub-properties for borderStyle, borderWeight, borderRadius, layoutHeight, and layoutWidth. You also want to organize these properties on tabs named Borders and Size.
To create this complex type, follow these sub-steps.
Step 1. Structure the ExperiencePropertyTypeBundle
First, let’s set up the folder for the new metadata type. Create an experiencePropertyTypeBundles folder to describe layoutAndBorderStyleType, our custom property type.
Step 2. Define the schema: schema.json
A schema.json file is integral to defining the structure, type, and validation of a property. By adhering to the JSON Schema specifications, you ensure that the property values that you set for your component align with the necessary structure and format, maintaining data integrity and component functionality.
See our guide for a full list of keywords that you can specify in a schema.json file. Unless otherwise noted, the keywords follow the JSON Schema specification.
Here’s the schema JSON for our sample complex property type, layoutAndBorderStyleType:
In the schema.json file, you specify a lightning:type for each property in your complex property type. Salesforce offers several Lightning property types out of the box that act as the basic types. See our guide for the full list of Lightning types. Each Lightning property type includes a default property editor, so if you do use one of these property types, you don’t have to create a property editor yourself.
For example, here’s the default property editor for the Lightning type lightning__dateTimeType.
Step 3. Define the design: design.json
This optional step covers what to do when you want to create a custom property editor for your custom property type. While schema.json defines a property type structure, the optional design.json file allows you to override the property editors for a property and lay out the property as you wish, such as in a vertical layout, on tabs, or in accordion sections.
See our guide for the full list of keywords that you can specify in a design.json file. Unless otherwise noted, the keywords follow the JSON Schema specification.
Here’s an example of a design.json file for laying out properties on tabs for layoutAndBorderStyleType.
Linking custom property editors and types to a Lightning Web Component
After you create a custom property editor or custom property type, the final step is to link them to your Lightning Web Component. Here’s an example of an XML configuration that integrates our custom property editor, alignmentCPE, and our custom property type, layoutAndBorderStyle.
This example shows how to use a custom property editor and custom property type together, but you can choose to use either independently, depending on your component’s needs.
Dive into custom property editors and types today!
Ready to elevate your Experience Builder component configuration? Here are some resources to get you started.
- Custom Property Types and Property Editors Guide: A comprehensive resource for creation through deployment
- Video demonstrations from product experts
- Quick Start Guide: Custom Property Editors and Types: A step-by-step walkthrough
- Code samples: Ready-to-use sample components
Don’t wait—harness the power of custom property editors and types to offer a seamless and intuitive experience to your users!
About the authors
Sudheer Kumar Reddy Gowrigari is an Engineering Manager on the Salesforce Platform team leading the content builder and builder framework areas. Outside work, he loves playing cricket, diving into books, and watching movies.
Trey Washington is a Software Engineer on the Salesforce Platform team, working on low-code builders and builder framework. He enjoys spending his free time hiking or biking in the outdoors.