Dynamic Components

This feature is available since Bloomreach Experience Manager 14.3.0

Introduction

For projects that are built with a JavaScript or TypeScript frontend application rather than Freemarker templates for the view, the Java controller aspect frequently implements similar patterns of behavior. In Bloomreach Experience Manager version 14.3.0 and higher, a new form of dynamically-configurable component base class has been implemented, allowing for many of these use cases to be handled without custom Java code.

Rather than using Java code and a compile, package, & deploy cycle, dynamic components are built within a running Bloomreach Experience Manager instance by editing the component configuration using the JCR Console. Several new component base classes are provided for use in building a wide array of project-specific components for different use cases.

In addition, a more general change has been made in the behavior of the component catalog in the Experience Manager GUI, which emphasizes consistent behavior of dynamic components across different pages by reusing the configuration stored in the component catalog, rather than copying it for each component instance on a page.

Dynamic Components are available in Bloomreach Experience Manager version 14.3.0 or later. In addition, frontend applications must make use of the Delivery API version 1.0 or later for full functionality.
An HST component can be configured to use a dynamic component as the Java class, via custom configuration, though this isn't the intended primary usage of dynamic components. The output of dynamic components is set on the request as model, so it is available both in Delivery API and in Freemarker templates.

Configuring a new Dynamic Component

The Dynamic Components feature places a new emphasis on the component catalog as the central location for configuring new component types for use within a project. To create a project-specific component, first create the catalog and package nodes as described in the component catalog configuration docs. Then create a new JCR node with primary type hst:componentdefinition. This will describe a single new component for use in your project.

Select a Base Class

The initial release includes 3 base classes for use in building new components: the Base Dynamic Component, Dynamic Query Component, and Dynamic Menu Component. A brief description is included below, with full details described in separate pages for each base class.

  • Base Dynamic Component

    As the name indicates, this class includes the most basic dynamic behaviors. This includes dynamic lookup of any content linked via a JcrPath type of component parameter and serializing all parameters via the Delivery API. This base class is useful for a broad set of use cases, including basic document rendering use cases, banners, carousels, etc. This is likely to be the most frequently-used base class within a project.

  • Dynamic Query Component

    This base class is intended for use cases where a set of documents should be loaded via a query and provided to the frontend component as a list. This is appropriate for implementing components like a news list, a blog list, or similar listing pages that may have optional sorting and limiting aspects. Since this is an extension of the Base Dynamic Component, it includes that functionality.

  • Dynamic Menu Component

    This is a simple component with the specific purpose of rendering the contents of a site menu for use in a frontend component. This is also an extension of the Base Dynamic Component.

Configure Component Parameters

Components can be configured with parameters that have values set either by developers in the configuration data or by CMS users in the Experience Manager GUI. For dynamic components, metadata about component parameters is stored within sub-nodes of the component catalog item, and this metadata is used to generate the appropriate dialogs within the Experience Manager. There is essentially a direct mapping between the parameter metadata that was configurable via the @ParametersInfo annotation in Java code and the new dynamic components config. Please refer to this page for details about the available parameter types and their config options.

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.

/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

New JCR Types

Please refer to the page Define Configuration Parameters for Dynamic Components for details of the JCR Types used in configuring Dynamic Components.

Using Dynamic Components with Freemarker Templates

Dynamic components are primarily intended to be used with the Delivery API. However, it's possible to use them with Freemarker frontend templates. The output of dynamic components is set on the request as model, so it is available in Freemarker templates.

Documents, returned by fields with a primary type of hst:jcrpath, are natively available to Freemarker templates.

In order to expose fields of other types, the following snippet can be added to the Freemarker template for the component:

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

This will expose the field values under the cparam object so they can be accessed using standard object notation, for example:

<p>alignment: ${cparam.alignment!'not found'}</p> <p>text color: ${cparam.textColor!'not found'}</p>
Note: dynamic components do not support advanced Freemarker-targeted features such as async/ESI/SSI, standalone and resource template.
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?