Define Configuration Parameters for Dynamic Components

Info: Available in brXM 14.3.0 and later.

Overview

This page describes how to define configuration parameters for Dynamic Components. These parameters are exposed to frontend components through the Delivery API and enable the Channel Editor UI to render configuration dialogs for end users.

When to Use

Use this approach when you need to:

Pass configuration parameters from the backend to frontend components via the Delivery API.
Allow end users to configure components in the Channel Editor UI.
Create new components by configuring generic component base classes, reducing the need for custom Java code.

Catalog Structure

Dynamic components are configured as hst:componentdefinition nodes within the component catalog. The catalog structure in the HST configuration for a channel typically follows this pattern:

/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
                ...

hst:containeritempackage nodes group related components.
Each component is defined as an hst:componentdefinition node.
Dynamic parameter definitions are nested within the component definitions.
For complex parameter types, use an additional hst:fieldconfig node for specialized configuration.

This structure replaces the previous use of hst:containeritem nodes, the Java @ParametersInfo annotation, and Java parameters interfaces. Developers familiar with HST Components will recognize many configuration options.

JCR Node Types

Dynamic component configuration uses specific JCR node types. The following table summarizes the relevant types and their properties:

[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)

Implementation Steps

1. Create a Component Definition

Define a new dynamic component by adding an hst:componentdefinition node. The node name is not significant, but use a name that matches the label shown in the Experience Manager UI for clarity.

Required Properties

hst:componentclassname: Specify the fully qualified class name of a supported dynamic component base class, such as org.hippoecm.hst.component.support.bean.dynamic.BaseHstDynamicComponent.
hst:ctype: Provide a unique identifier used by frontend applications to select the corresponding frontend component.
hst:label: Set the label shown in the Experience Manager component listing UI.

Optional Properties

hst:xtype: Defines the rendering template type. See Channel Editor Containers for details.
hst:iconpath: Path to the icon displayed in the Experience Manager UI, relative to the site application's root (e.g., images/essentials/catalog-component-icons/mycatalog.png).
hst:fieldgroups: List of field group names to organize parameters in the editor UI. Field groups are created in the order specified.

Example

/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

2. Add Component Parameters

Add one or more hst:dynamicparameter nodes within the component definition to define configurable parameters.

Required Properties

hst:valuetype: Specifies the data type for the parameter. Valid values: text, integer, decimal, boolean, or datetime. If not set, the system logs a warning and defaults to text.

Optional Properties

hst:displayname: Sets the label in the UI if no localization is defined. If omitted, the parameter name is used.
hst:hideinchannelmanager: If true, the parameter is hidden in the component editor UI. Defaults to false.
hst:defaultvalue: If hst:hideinchannelmanager is false, this value is shown as the initial value for new component instances. If true, this value is used when the parameter is not specified by a developer.
hst:required: If true, the editor UI enforces that a value is provided for this parameter.

3. (Optional) Configure Field Editor UI

For parameters that are editable in the UI (hst:hideinchannelmanager: false) and have hst:valuetype: text, you can customize the editing experience by adding an hst:fieldconfig node. Supported field editor types:

Content Picker (hst:jcrpath)
Drop-down List (hst:dropdown)

Content Picker Properties

hst:pickerconfiguration: Selects a pre-configured content picker dialog (e.g., cms-pickers/documents).
hst:pickerrootpath: Sets the highest ancestor path accessible in the picker.
hst:pickerinitialpath: Sets the default starting directory in the picker.
hst:pickerrememberslastvisited: If true, the picker remembers the last visited directory.
hst:pickerselectablenodetypes: Specifies node types selectable in the picker. Defaults to an empty list.
hst:relative: If true, stores a JCR path relative to the channel's content root. If false, stores an absolute JCR path.

Drop-down Properties

hst:value: List of static options for the drop-down.
hst:valuelistprovider: Specifies a dynamic value list provider. For example, use org.hippoecm.hst.platform.configuration.components.ResourceBundleListProvider to source options from a Resource Bundle Document. If hst:sourceid is set but hst:valuelistprovider is not, this provider is used by default.
hst:sourceid: Parameter for the value list provider. For ResourceBundleListProvider, set this to the resource bundle ID.

For more information on configuring value list providers, see Annotate Channel or Component Configuration.

Localization

To localize component parameters, define repository-based resource bundles under the catalog and component names. Resource bundles are stored at /hippo:configuration/hippo:translations/hippo:hst/componentparameters/.

For example, given the following catalog 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]

Define the translations 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

Localize group definitions the same way as component parameters.
For drop-down static values, use the format parameterName#value for translation keys.

Overriding Base Class Component Parameters

You can override parameters defined on dynamic base classes by defining a parameter with the same name and type in your component definition. This allows you to change properties such as hst:defaultvalue, hst:required, hst:displayname, and hst:hideinchannelmanager without modifying every component instance.

Example

Suppose you use the Dynamic Query Component and want to restrict the component to specific document types and set the default page size to 20:

/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

Parameter types must match as follows:

Component Value Type	Java 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`

Verification

After defining or updating component parameters, verify that the Channel Editor UI displays the configuration options as expected.
Confirm that parameters are delivered to frontend components via the Delivery API.
For localized parameters, check that the correct translations appear in the UI.

Define Configuration Parameters for Dynamic Components

Overview

When to Use

Catalog Structure

JCR Node Types

Implementation Steps

1. Create a Component Definition

Required Properties

Optional Properties

Example

2. Add Component Parameters

Required Properties

Optional Properties

3. (Optional) Configure Field Editor UI

Content Picker Properties

Drop-down Properties

Localization

Overriding Base Class Component Parameters

Example

Verification

Related Topics