Define Configuration Parameters for Delivery Tier Components or REST Services
Overview
This page explains how to define configuration parameters for delivery tier components or REST services in Bloomreach Content. Defining parameters in this way improves code readability and robustness, and enables the Channel Editor UI to display a configuration editor for your components.
This guidance applies to backend services implemented in custom Java code. Starting with version 14.3.0, you can use Headless Dynamic Components to cover many use cases through configuration alone. For those options, see Define Configuration Parameters for Dynamic Components.
When to Use
Define configuration parameters in an interface when you:
- Need strongly typed access to component configuration in Java code
- Want to expose parameters for editing in the Channel Editor UI
- Are developing components that can be added to page templates by end users
- Are implementing JAX-RS REST services that require configurable parameters
Defining parameters in an interface is required for components that are configurable in the Channel Editor. It is strongly recommended for all components to ensure type safety and maintainable code.
Prerequisites
- A Bloomreach Content project with custom Java components
- Familiarity with Java annotations and interfaces
- Access to the
siteweb application source code
Implementation Steps
1. Define a ParametersInfo Interface
Create a Java interface that declares a getter method for each configuration parameter. Annotate each getter with @org.hippoecm.hst.core.parameters.Parameter, specifying at least the name attribute.
You can also add additional annotations to control how the Experience Manager UI renders the configuration editor, such as widget types or grouping directives. For details, see Annotate Channel or Component Configuration Parameters with UI Directives.
Package this interface in your site web application.
Example:
site/components/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 = "myproject:basedocument", displayName = "Document Type") String getDocumentType(); }
2. Associate the Interface with the Component Class
Annotate your component class with @org.hippoecm.hst.core.parameters.ParametersInfo, setting the type attribute to the fully qualified class name of your parameters interface.
Example:
site/components/src/main/java/org/example/components/Search.java
@ParametersInfo(type = SearchInfo.class) public class Search extends BaseHstComponent { }
Alternatively, you can set the hst:parametersinfoclassname JCR property on the component configuration node to the fully qualified class name of the interface. If both the annotation and the JCR property are present, the JCR property takes precedence.
3. Access Configuration Parameters in the Component Class
Within your component class, use getComponentParametersInfo(HstRequest) to retrieve a proxied instance of your parameters interface. This provides strongly typed access to the configured values.
Example:
site/components/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(); // Use 'documentType' and 'pageSize' as needed } }
Verification
- Open the Channel Editor and add your component to a page template.
- Confirm that the configuration editor displays the parameters defined in your interface.
- Change parameter values and verify that your component receives the updated values at runtime.