Dynamic Components

Info: Dynamic Components are available starting from brXM 14.3.0.

Overview

Dynamic Components allow you to configure component behavior directly in the JCR, without writing or deploying custom Java code. This feature is designed for projects that use a JavaScript or TypeScript frontend application instead of Freemarker templates for rendering views.

With Dynamic Components, you define and manage component configuration within a running Bloomreach Content instance using the JCR Console. This approach eliminates the need for a compile, package, and deploy cycle when creating or updating components. Several base classes are available to support a range of use cases.

The component catalog in the Experience Manager GUI now reuses configuration stored in the catalog for all instances of a dynamic component, ensuring consistent behavior across pages.

Dynamic Components require brXM 14.3.0 or later. Your frontend application must use Delivery API version 1.0 or later to access all features.

Info: You can configure an HST component to use a dynamic component as its Java class through custom configuration. However, this is not the primary intended use. Dynamic components set their output as a model on the request, making it available both through the Delivery API and in Freemarker templates.

Configuring a Dynamic Component

To define a new dynamic component, use the component catalog as the central location for configuration.

Create the catalog and package nodes as described in the component catalog configuration documentation.
Add a new JCR node with the primary type hst:componentdefinition. This node defines a new component for your project.

Selecting a Base Class

Three base classes are available for building dynamic components. Each supports different use cases:

Base Dynamic Component
Provides basic dynamic behavior, including dynamic lookup of content linked via a JcrPath parameter and serialization of all parameters through the Delivery API. Use this base class for general cases such as document rendering, banners, and carousels.
Dynamic Query Component
Use this class when you need to load a set of documents using a query and provide them to the frontend as a list. Typical use cases include news lists, blog lists, or other listings that require sorting or limiting. This class extends the Base Dynamic Component.
Dynamic Menu Component
This class renders the contents of a site menu for use in a frontend component. It also extends the Base Dynamic Component.

Refer to the documentation for each base class for implementation details.

Configuring Component Parameters

You can define parameters for dynamic components that are set either by developers in the configuration or by CMS users in the Experience Manager GUI. Parameter metadata is stored in sub-nodes of the component catalog item. This metadata is used to generate dialogs in the Experience Manager.

The parameter metadata structure for dynamic components closely matches the configuration previously defined using the @ParametersInfo annotation in Java. For details on available parameter types and configuration options, see Define Configuration Parameters for Dynamic Components.

The following configuration defines a simple banner component that renders data from a single Banner document. This example uses the Base Dynamic Component and is functionally similar to the standard Document Component provided by Essentials.

/Dynamic Banner:
  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

JCR Types for Dynamic Components

For information about the JCR types used in dynamic component configuration, see Define Configuration Parameters for Dynamic Components.

Using Dynamic Components with Freemarker Templates

Dynamic Components are primarily designed for use with the Delivery API. However, you can also use them with Freemarker templates. The output of a dynamic component is set as a model on the request, making it accessible in Freemarker.

Documents referenced by fields with the primary type hst:jcrpath are directly available in Freemarker templates.

To expose other parameter fields, add the following snippet to your Freemarker template:

<#assign cparam = .vars["org.hippoecm.hst.utils.ParameterUtils.parametersInfo"].getResidualParameterValues() />

You can then access parameter values using the cparam object. For example:

<p>alignment: ${cparam.alignment!'not found'}</p> <p>text color: ${cparam.textColor!'not found'}</p>

Info: Dynamic components do not support advanced Freemarker-specific features such as async/ESI/SSI, standalone, or resource template.