Define a Component’s Configuration Parameters

Introduction

Goal

Define a delivery tier component’s configuration parameters in order to increase your component class’ readability and robustness, and to enable the Channel Editor UI to render the component’s configuration dialog.

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.

The use the @ParametersInfo annotation and 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, the use of the @ParametersInfo annotation and interface is required and enables the Channel Editor UI to render the component’s configuration dialog.

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
  }
}