Define Configuration Parameters for Dynamic Components

Introduction

Goal

Define configuration parameters for Dynamic Components, to relay parameters to frontend components via the Delivery API and to enable the Channel Editor UI to render configuration dialogs.

Background

A delivery tier component can be configured through parameters stored in the component’s configuration node in the repository. As a component developer, you can define these parameters using parameter configuration metadata stored under the component's catalog definition.

Defining parameters in this way allows for new components to be created by configuring the generic component base classes, which can support many common use cases without needing custom Java code.

Components can then be added to a page template (from the catalog) and configured by end users using the Channel Editor, using the Channel Editor UI to render the component’s configuration editor.

Catalog Structure

Dynamic components are configured using the hst:componentdefintion type as nodes in the component catalog. This catalog is defined in the HST configuration for a channel, using a structure similar to this example:

/hst:hst:
  /hst:configurations:
    /example:
      /hst:catalog:
        /onehippo-essentials-package:
          jcr:primaryType: hst:containeritempackage
          /DynamicBanner:
            jcr:primaryType: hst:componentdefinition
            ...
            /document:
              jcr:primaryType: hst:dynamicparameter
              ...
              /hst:fieldconfig:
                jcr:primaryType: hst:jcrpath
                ...

Directly within a catalog are hst:containeritempackage nodes that organize components into groups. Within the grouping nodes are the component definitions, and within the component definitions are dynamic parameter definitions. For some complex parameter types, specialized configuration is provided within an additional hst:fieldconfig node.

The 3 layers of component definition, dynamic parameter, and field config directly replaces the hst:containeritem nodes that were previously used in the catalog, the Java @ParametersInfo annotation, and the detailed configuration of parameters within a Java parameters interface. For developers that are already familiar with developing HST Components, the details of the configuration options should be recognizable from previous experience.

JCR Types

The dynamic components feature uses specific JCR node types to store the component configuration data. These are explained in more detail below.

[hst:fieldconfig] abstract

[hst:jcrpath] > hst:fieldconfig
- hst:pickerconfiguration (string)
- hst:pickerinitialpath (string)
- hst:pickerrememberslastvisited (boolean)
- hst:pickerselectablenodetypes (string) multiple
- hst:relative (boolean)
- hst:pickerrootpath (String)

[hst:dropdown] > hst:fieldconfig
- hst:value (string) multiple
- hst:valuelistprovider (string)
- hst:sourceid (string)

[hst:dynamicparameter]
- hst:required (boolean)
- hst:valuetype (string)
- hst:defaultvalue (string)
- hst:displayname (string)
- hst:hideinchannelmanager (boolean)
+ hst:fieldconfig (hst:fieldconfig)

[hst:componentdefinition]
- hst:componentclassname (string)
- hst:ctype (string)
- hst:xtype (string)
- hst:iconpath (string)
- hst:label (string)
- hst:fieldgroups (string) multiple
//Should be used only for field group parameters
- * (string) multiple
+ * (hst:dynamicparameter)

[hst:containeritemcomponent] > hst:abstractcomponent orderable
//A reference to a catalog item
- hst:componentdefinition (string)
- hst:xtype (string)
// the label of the hst:containeritemcomponent
- hst:label (string)
// icon path relative to the sites webapp
- hst:iconpath (string)
- hst:componentfiltertag (string)
+ * (hst:abstractcomponent)

Instructions

Example: A Dynamic Banner Component

As a simple example, here's the required configuration for a simple banner component that renders the data from a single Banner document. This is equivalent to the standard Document Component that is provided by Essentials, but uses the Base Dynamic Component instead. We will use this example to explore the options for each level of the configuration structure.

/DynamicBanner:
  jcr:primaryType: hst:componentdefinition
  hst:componentclassname: org.hippoecm.hst.component.support.bean.dynamic.BaseHstDynamicComponent
  hst:ctype: Banner
  hst:label: Banner
  /document:
    jcr:primaryType: hst:dynamicparameter
    hst:valuetype: text
    /hst:fieldconfig:
      jcr:primaryType: hst:jcrpath
      hst:pickerconfiguration: cms-pickers/documents-only
      hst:pickerinitialpath: banners
      hst:relative: true

Create a Component Definition

The component definition is the starting point for creating a new dynamic component. The JCR node 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

• hst:componentclassname: This property should specify one of the available dynamic component base classes. In this case, we are using the main Base Dynamic Component class.
• hst:ctype: This property is used as a code-level unique identifier for use by the frontend application to select an appropriate frontend component implementation.
• hst: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 template.

Optional Properties

• hst:xtype: This property defines the rendering template type as explained in the Channel Editor Containers page
• hst:iconpath: This property stores the file path of the icon which is used in the component listing UI in the Experience Manager. The path is relative to the root of the site application, such as images/essentials/catalog-component-icons/mycatalog.png.
• hst:fieldgroups: This multiple-value string property contains a list of field groups 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 hst:dynamicparameter node within the hst:componentdefinition.

Required Properties

• hst:valuetype: The data type of the value stored for this parameter. Valid options are: text, 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 text.

Optional Properties

• hst:displayname: If a label is not defined with the localization and this property is present, the label on UI is set with this property. If this property is not present, parameter name is set as label. 
• hst:hideinchannelmanager: 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.
• hst:defaultvalue: If hideinchannelmanager is false, this value will be the initial value displayed in the component editor UI for a new component instance. If hideinchannelmanager 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.
• hst: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 hst:hideinchannelmanager: false), a developer can also control the editing experience within that UI by adding an hst:fieldconfig node within the hst:dynamicparameter node. This is currently supported only for parameters with hst:valuetype 'text'. The default editing experience for a parameter of this type is a text field. There are two additional options with distinct fieldconfig node types: a content picker (hst:jcrpath) or a drop-down box with a configurable list of options (hst:dropdown).

Content Picker Properties

• hst:pickerconfiguration: This property selects from a pre-configured content picker dialog. The most common value is 'cms-pickers/documents' to select a document.
• hst: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.
• hst: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.
• hst:pickerrememberslastvisited: 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.
• hst: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.
• hst:relative: If true, the stored value for this parameter will be a JCR path relative to the canonical content root path of the channel. If false, the stored value will be an absolute JCR path.

Drop Down Properties

• hst:value: A developer can use this multiple value property to configure a static list of valid options for this parameter.
• hst:valuelistprovider: If the list of valid options should be configured by an administrator via the Experience Manager administration UI, a developer can configure a dymanic value list provider that generates a list of values using another data source. We recommend org.hippoecm.hst.platform.configuration.components.ResourceBundleListProvider, which uses a Resource Bundle Document to supply the list of options. This is also assumed as the default value if hst:sourceid is specified but hst:valuelistprovider is not. Note that the proper value for this property should be the key of a ValueListProvider instance registered with the ValueListProviderService, for more information about how to do it, check the third option.
• hst:sourceid: This property specifies a parameter to control the behavior of the hst:valuelistprovider. In the case of ResourceBundleListProvider, this value should be the resource bundle ID corresponding to a Resource Bundle Document.

Localization

Component parameters can be localized by defining repository based resource bundles in a similar way to the localization of parameters defined by parameters interface. The only difference is defining the resource bundle with the catalog name (defined with hst:containeritempackage node type) and the component name (defined with hst:componentdefintion node type) instead of the parameter interface package and the name. The resource bundle is bootstrapped under the hippo:configuration/hippo:translations/hippo:hst/componentparameters/ node.

For example, if we have a component catalog item with the following structure

/onehippo-essentials-package::
   jcr:primaryType: hst:containeritempackage
   /DynamicBanner:
     jcr:primaryType: hst:containeritemcomponent
     hst:componentclassname: org.hippoecm.hst.component.support.bean.dynamic.BaseHstDynamicComponent
     hst:label: Banner
     /document:
       jcr:primaryType: hst:dynamicparameter
       hst:valueType: integer
     /time:
       jcr:primaryType: hst:dynamicparameter
       hst:valueType: datetime  
     /size:
       jcr:primaryType: hst:dynamicparameter
       /hst:fieldconfig:
         jcr:primaryType: hst:dropdown
         hst:value: [small, large]

Then the sample bootstrapped configuration which has translations is as follows:

definitions:
  config:
/hippo:configuration/hippo:translations/hippo:hst/componentparameters/onehippo-essentials-package:
      jcr:primaryType: hipposys:resourcebundles
      /DynamicBanner:
        jcr:primaryType: hipposys:resourcebundles
        /en:
          jcr:primaryType: hipposys:resourcebundle
          document: Document
          time: Activation Time
          size: Size 
          size#small: Small
          size#large: Large

The localization of group definitions works the same as the component parameters.

Static values defined in Drop Down properties can be localized by adding the parameter name as a prefix to the static value item with the number sign(#) separator. In the above example, there is a “size” dynamic parameter which is a dropdown field with static values [small, large].

Override Existing Component Parameters Defined on Base Classes

The component parameters that are defined on dynamic base classes, can be overridden by defining a component parameter with the same name and the same type with the existing component parameter. This allows developers to change values of the properties of component parameters defined on base classes without updating the parameter values on every component instance in pages, such as hst:defaultvalue, hst:required, hst:displayname and hst:hideinchannelmanager.

As an example, you create a catalog item that uses Dynamic Query Component and the component is always supposed to fetch only specific document types and the page size is supposed to be 20 by default. The sample configuration is as follows:

/onehippo-essentials-package::
   jcr:primaryType: hst:containeritempackage
   /DynamicDocumentList:
     jcr:primaryType: hst:containeritemcomponent
     hst:componentclassname: org.hippoecm.hst.component.support.bean.dynamic.DocumentQueryDynamicComponent
     hst:label: DocumentList 
     /documentTypes:
       jcr:primaryType: hst:dynamicparameter
       hst:valueType: text
       hst:defaultvalue: example:doctypeforquery
     /pageSize:
       jcr:primaryType: hst:dynamicparameter
       hst:valueType: integer
       hst:defaultvalue: 20     

Types of the parameters are matched as described below:

Component Value type	Method Return Type
text	java.lang.String
integer	short, int, long, java.lang.Short, java.lang.Integer, java.lang.Long
decimal	double, float, java.lang.Double, java.lang.Float
boolean	boolean, java.lang.Boolean
datetime	java.util.Date, java.util.Calendar