Define Configuration Parameters for Delivery Tier Components or REST Services

Introduction

Goal

Define configuration parameters for delivery tier components or REST services in order to increase your code's readability and robustness, 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 in an interface and couple that interface to your component class through a @ParametersInfo annotation. Alternatively, since Bloomreach Experience Manager 12.1, you can optionally set the hst:parametersinfoclassname JCR string property to a FQCN (fully qualified class name) of the interface in a component configuration node instead of using @ParametersInfo annotation. If both @ParametersInfo annotation and hst:parametersinfoclassname property is used, then the interface configured by hst:parametersinfoclassname property will be used.

Defining parameters in an interface is strongly recommended for all components because it provides strongly typed access to the configured parameters and increases the robustness and readability of component code.

For components that can be added to a page template (from the catalog) and configured by end users using the Channel Editor, defining parameters in an interface is required and enables the Channel Editor UI to render the component’s configuration dialog.

You can also define parameters in an interface for JAX-RS REST Services. See RESTful JAX-RS Component Support for details.

Instructions

Define a ParametersInfo Interface

Define an interface.

Within the interface, define a getter method for each configuration parameter.

Annotate each getter method with @org.hippoecm.hst.core.parameters.Parameter and specify at least the name attribute.

Optionally, annotate the parameter getter methods with directives to control which widgets are rendered by the Channel Manager UI to edit the parameters.

Optionally, annotate the interface with grouping directives to control the order in which the Channel Manager UI renders the widgets.

Package the interface with the site web application.

Example interface:

site/src/main/java/org/example/components/info/SearchInfo.java

public interface SearchInfo {
  @Parameter(name = "pageSize",
             defaultValue = "10",
             displayName = "Page Size")
  int getPageSize();

  @Parameter(name = "documentType",
             defaultValue = "myhippoproject:basedocument",
             displayName = "Document Type")
  String getDocumentType();
}

Couple the Interface to the Component Class

Couple the interface to the component class by annotating the class with @org.hippoecm.hst.core.parameters.ParametersInfo, with the value of the type attribute set to the fully qualified name of the interface.

Example component class:

site/src/main/java/org/example/components/Search.java

@ParametersInfo(type = SearchInfo.class)
public class Search extends BaseHstComponent {

}

Access a Component's Configuration Parameters from the Component Class

The delivery tier will create a proxied instance of the interface which provides strongly types access to the configuration parameters. The proxied instance can be accessed from within the component class through org.hippoecm.hst.component.support.bean.BaseHstComponent.getComponentParametersInfo(HstRequest).

Example:

site/src/main/java/org/example/components/Search.java

@ParametersInfo(type = SearchInfo.class)
public class Search extends BaseHstComponent { 

  @Override
  public void doBeforeRender(HstRequest request,
                             HstResponse response) throws HstComponentException {
     SearchInfo info = getComponentParametersInfo(request);
     String documentType = info.getDocumentType();
     int pageSize = info.getPageSize();

     // search for documents of type 'documentType' and get 'pageSize' results
  }
}