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 Parameter schema). For some complex parameter types, specialized configuration is provided within an additional config property (using the ParameterConfig 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",
          "enableUpload": false
        }
      }
  ],
  "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 field group type. The value of contentType may optionally include the namespace prefix; this is only required in case the type is in a namespace other than brxsaas, e.g. mynamespace: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 calendar. In case the value type is not defined, a warning 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, the 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.

👍

Share content between channels

If you set relative to false and pickerRootPath to /content/documents, the picker will allow users to pick from all channels instead of only within the current channel, allowing content to be shared between channels. See the Share content between channels tutorial for an example.

(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.
• enableUpload: This property must always be false unless the property pickerConfiguration has value 'cms-pickers/images' . In that case, this property determines how the picker for this field behaves in the Experience manager, specifically whether uploads of images are allowed when the dialog for picking an image is shown. Set to true to enable uploads, false otherwise. Defaults tofalse.

Drop down properties

• value: A developer can use this multiple value property to configure a static list of valid options for this parameter.
• structuredValues: A developer can also configure a static list of key and labels with this parameter. This parameter expects an array of key-label values. The value and structuredValues parameters are both optional, but one of them should be set in the payload. Setting both of them is not allowed.
• 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. In case the labels are configured in structuredValues parameter, it is not allowed to set this parameter.

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.