Define Configuration Parameters for Components - Bloomreach Experience - Headless Digital Experience Platform

Define Configuration Parameters for Components

Introduction

Goal

Define configuration parameters for components, to relay parameters to frontend components via the Delivery API's Pages endpoint and to enable the Experience manager app to render configuration dialogs.

Background

A page component instance can be configured through parameters stored in the component’s configuration. As a component developer, you can define these parameters using parameter configuration metadata stored in the component's definition in a component group.

Defining parameters in this way allows for new components to be created by configuring the generic base components, which can support many common use cases.

Components can then be added to a page and configured by site editors using the Experience manager app.

Component Group Structure

Components are configured as objects in a component group. This component group is defined in the site configuration for a channel using the CatalogGroup schema:

{
    "name": "sample",
    "hidden": false,
    "system": false
}

Within the component groups are the component definitions (using the ComponentDefinition schema), and within the component definitions are dynamic parameter definitions (using the ParameterType schema). For some complex parameter types, specialized configuration is provided within an additional config property (using the ParameterConfigType schema).

[
    {
        "id": "sample/banner",
        "extends": "base/component",
        ...
        "parameters": [
            {
                "name": "document",
                ...
                "config": {
                   "type": "contentpath",
                   ...
                }
            },
            ...
        ]
    },
    ...
]

Instructions

Example: A Dynamic Banner Component

As an example, here's the required configuration for a simple banner component that renders the data from a single Banner document. We will use this example to explore the options for each level of the configuration structure.

{
  "id": "sample/banner",
  "extends": "base/component",
  "hidden": false,
  "system": false,
  "xtype": null,
  "ctype": "Banner",
  "contentType"; null,
  "label": "Banner",
  "icon": null,
  "parameters": [
      {
        "name": "document",
        "valueType": "string",
        "required": true,
        "hidden": false,
        "overlay": false,
        "defaultValue": "",
        "displayName": null,
        "system": false,
        "config": {
          "pickerConfiguration": "cms-pickers/documents-only",
          "pickerInitialPath": "banners",
          "pickerRememberLastVisited": true,
          "pickerSelectableNodeTypes": [
            "brxsaas:banner"
          ],
          "relative": true,
          "pickerRootPath": null,
          "type": "contentpath"
        }
      }
  ],
  "fieldGroups": []
}

Create a Component Definition

The component definition is the starting point for creating a new project-specific component. The component name here is not significant, but it is a good practice to choose a name that is similar to what is visible in the Experience manager UI for ease of maintenance.

Required Properties

  • extends: This property should specify one of the available base components. In this case, we are using the main base component.
  • ctype: This property is used as a code-level unique identifier for use by the frontend application to select an appropriate frontend component implementation.
  • label: This property provides the label string that is used in the component listing UI in the Experience manager to display the component for use in a page layout.

Optional Properties

  • contentType: This property defines the content type for a page-specific component where the content shares its lifecycle with its containing component instance and page. The content type must be an existing document compound type. The value of contentType must include the namespace prefix, e.g. brxsaas:titleandtext.
  • xtype: deprecated
  • icon: This property stores the icon which is used in the component listing UI in the Experience manager. The icon data is stored as a base64 encoded string.
  • fieldgroups: This multiple-value property contains a list of field group objects to organize the parameters of this component into groups within the editor UI. Field groups will be created in the order specified by this property.

Add Component Parameters

A component can have an arbitrary number of parameters of different data types. Some parameters may be intended for developer use, merely to pass data to a reusable frontend component implementation and modify its behavior. Other parameters could be intended for editing by an Experience manager user via the component editor UI. In both cases, add a new object within the parameters property.

Required Properties

  • valueType: The data type of the value stored for this parameter. Valid options are: string, integer, decimal, boolean, or datetime. In case the value type is not defined, a warn message is logged and the value type is set as string.

Optional Properties

  • displayName: If this property is present, its value is used in the UI as the label for this parameter. If this property is not present, parameter name is set as label. 
  • hidden: If present and true, this parameter should NOT be displayed in the component editor UI. If this property is not present, it is assumed to be false, and the parameter will be editable in the UI.
  • defaultValue: If hidden is false, this value will be the initial value displayed in the component editor UI for a new component instance. If hidden is true, this value will be used in case this parameter is not specified by a developer when creating a new component instance in a page template.
  • required: This determines the validation rules within the component editor for a component instance. Parameters with this property set to true will display an error in the editor if no value is specified.

(Optional) Configure a Content Selector or Drop Down Field Editor UI

For component parameters that are editable in the component editor UI (as specified with "hidden": false), a developer can also control the editing experience within that UI by adding a config property within a parameter object. This is currently supported only for parameters with valueType string. The default editing experience for a parameter of this type is a text field. There are two additional options with distinct config types: a content picker (contentpath) or a drop-down box with a configurable list of options (dropdown).

Content Picker Properties

  • pickerConfiguration: This property selects from a pre-configured content picker dialog. The most common value is 'cms-pickers/documents' to select a document.
  • pickerRootPath: This property determines the highest ancestor path to which a user may navigate using the picker dialog. Use this property to constrain the options available in the UI.
  • pickerInitialPath: This property determines the starting directory for the picker dialog for this component parameter. Use this property as a convenience to users in case there is a strong likelihood that a certain path is most likely to be used.
  • pickerRememberLastVisited: If set to true, this property will cause the picker dialog to store the most recently displayed directory for this picker dialog and reopen in that location on next use.
  • pickerSelectableNodeTypes: It determines types of nodes to be able to select in the picker. Default: empty list, resulting in the default behavior of the picker.
  • relative: If true, the stored value for this parameter will be a content path relative to the canonical content root path of the channel. If false, the stored value will be an absolute content path.

Drop Down Properties

  • value: A developer can use this multiple value property to configure a static list of valid options for this parameter.
  • valueListProvider: deprecated
  • sourceId: A developer can use this property to specify the resource bundle ID of a Resource Bundle Document in which the dropdown values are managed.

Override Existing Component Parameters Defined on Base Components

The component parameters that are defined on base components can be overridden by defining a component parameter with the same name and the same type as the existing component parameter. This allows developers to change values of the properties of component parameters defined on base components without updating the parameter values on every component instance in pages, such as defaultValue, required, displayName, and hidden.

 

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?