Create a Custom Attribute Editor

Learning Objectives

After completing this unit, you’ll be able to:

• Explain why you create a custom attribute editor.
  
• Describe how the HTML iframe works with a custom attribute editor.
  
• Compare a breakout custom attribute editor and a trigger custom attribute editor.
  
• Identify why you use a breakout custom attribute editor.
  

Recognize When to Use Custom Attribute Editors

When you create a component type for Page Designer, you define attributes that a merchandiser sets when building storefront pages. The type value that you assign to each attribute in the component’s meta definition file determines the UI control that appears in the visual editor. For example, a file picker for images, a checkbox for Booleans, a dropdown for enums.

Page Designer includes several preconfigured type options: Boolean, category, enum, file, image, integer, markup, page, product, string, text, and url. Sometimes none of them fit the job. For example, if you want the merchandiser to select a store location on a map, place a favorite icon on a product tile, or pick a background color from a specific brand palette, then custom attribute editors can implement these specialized UI requirements.

A custom attribute editor doesn’t conflict with the platform code for Page Designer, and you can create more than one custom attribute editor for a single component type.

Understand How a Custom Attribute Editor Works

A custom attribute editor uses a meta definition file, a script file, and JavaScript and CSS resources to implement an editor that operates within a self-contained environment on the client side.

In the component type’s meta definition file, you define the attribute’s type as custom and include an editor_definition element with the custom editor ID and optional configuration information.

You include the custom attribute editor meta definition file and script file, along with JavaScript and CSS resources, in a custom cartridge assigned to the Business Manager site.

On the client side, a host component that contains an HTML <iframe> element wraps each custom attribute editor. The iframe encapsulates the editor’s code and styling, creating a sandbox environment so different custom attribute editors on the same page don’t interfere with each other.

The host and the editor communicate on a dedicated messaging channel using subscribe and emit methods. These methods send predefined events with serializable payloads between the host and the editor.

For more on the messaging channel, see Channel Messaging API documentation.

Create a Custom Attribute Editor

Here’s how you can add a custom attribute editor.

1. In the component type’s meta definition file, set the type of the attribute to custom. Include an editor_definition element with the custom attribute editor’s ID and any configuration.
   
2. Create a meta definition JSON file for the custom attribute editor. This file references the JavaScript and CSS resources. Save it in {your_bm_cartridge}/cartridge/experience/editors or a subdirectory. Use only alphanumeric or underscore characters in file and subdirectory names.
   
3. Create a script file with the same name as the meta definition file but with a .js extension. Save it in the same directory. Every custom attribute editor requires a script file—if you don’t use the init function, include an empty script file.
   
4. Place the client-side JavaScript files and CSS resources in the static/default directory of the same cartridge.
   
5. Add the cartridge to the cartridge path for the Business Manager site. Without this step, the custom attribute editor doesn’t appear in the visual editor.
   

Add a Custom Attribute to the Meta Definition File

Here’s an example of a banner component meta definition file that adds a custom attribute named backgroundColor. The editor_definition element references the custom attribute editor by its ID and passes a set of brand colors as configuration options.

{
  "name": "Main Banner",
  "description": "Image banner with a configurable brand background color.",
  "group": "commerce_assets",
  "attribute_definition_groups": [
    {
      "id": "bannerStyle",
      "name": "Banner Style",
      "attribute_definitions": [
        {
          "id": "backgroundColor",
          "name": "Background Color",
          "type": "custom",
          "required": true,
          "editor_definition": {
            "type": "com.example.colorpicker",
            "configuration": {
              "colors": ["#002D62", "#FFFFFF", "#F5F0EB", "#E31837"]
            }
          }
        }
      ]
    }
  ],
  "region_definitions": []
}

The custom attribute editor meta definition file goes in your BM cartridge under cartridge/experience/editors. It lists the JavaScript and CSS resources that the editor requires. Page Designer resolves relative URLs to the /static/default directory of the cartridge.

{
  "name": "Color Picker",
  "description": "A custom color picker for brand palette selection.",
  "resources": {
    "scripts": [
      "/experience/editors/com/example/colorpicker.js"
    ],
    "styles": [
      "/experience/editors/com/example/colorpicker.css"
    ]
  }
}

The script file, colorpicker.js, lives next to colorpicker.json. Use the init function to add server-side logic or other resources. If server-side initialization isn’t required, include an empty script file.

Distinguish Breakout and Trigger Custom Attribute Editors

The right pane of the Page Designer visual editor has limited space. When you want to give merchandisers a large selection of options, a breakout editor opens in a modal window.

A trigger editor appears in the navigation pane with a Select button. When the merchandiser selects, a breakout editor opens in a modal that presents the full set of choices.

Here’s how you can create a trigger custom attribute editor.

1. Define the attribute as type custom in the component meta definition file.
   
2. Create a meta definition JSON file and a script file for the trigger editor.
   
3. In the script file, use PageMgr.getCustomEditor to instantiate the breakout editor.
   
4. Add the breakout editor as a dependency using editor.dependencies.put().
   

The breakout editor requires its own meta definition file and script file.

Handle Events in Breakout and Trigger Editors

To open the breakout editor’s modal, use a callback on event emission. A callback ties directly to one breakout process, making it straightforward to track multiple open editors.

The trigger editor and breakout editor communicate through client-side script files.

• The trigger editor script opens and closes the breakout editor and emits sfcc:value to Page Designer.
  
• The breakout editor script implements the editor logic and emits sfcc:valid and sfcc:value to the trigger editor.
  

When the breakout editor emits sfcc:valid, Page Designer evaluates the response. If the value is valid, the Apply button activates. If invalid, the Apply button disables and an error message appears.

Use Prebuilt Editors in Custom Attribute Editors

Page Designer provides prebuilt attribute editors that you can use as building blocks when creating custom attribute editors. These prebuilt editors open in a separate breakout modal window.

Use these prebuilt editors to create custom attribute editors faster and more efficiently.

Wrap It Up

In this unit, you learned why and when to create custom attribute editors for Page Designer components. You explored how the HTML iframe sandbox keeps editors isolated from each other, how to configure the cartridge correctly, and how breakout and trigger editors give merchandisers the space to work with a large set of choices. You also learned about prebuilt editors that you can use as building blocks in your custom attribute editors.

Resources

• Salesforce Developers: Create a Breakout Custom Attribute Editor That Displays in a Modal Window
• Salesforce Developers: Page Designer Meta Definition Files