Dynamic Components

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.

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>