HstComponent ParametersInfo annotation - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 10. There's an updated version available that covers our most recent release.

13-05-2015

HstComponent ParametersInfo annotation

The ParametersInfo annotations are mandatory for HST components that must be usable in the Template Composer. For HST components that do not need to work in the Template Composer, it is still strongly recommended to use the ParametersInfo annotation, as you can write cleaner code.

The ParametersInfo annotation couples an interface to an HST component. The coupled interface provides strong typed read access to the configured parameters of the HST component.

For example, consider an HST component called Search with two parameters: the document type to search for (docType), and the number of items to show on a page (pageSize). The available parameters are specified in an interface SearchInfo.

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

  @Parameter(name = "docType",
             defaultValue = "myhippoproject:basedocument",
             displayName = "Document Type")
  String getDocType();
}
@ParametersInfo(type = SearchInfo.class)
public class Search extends BaseHstComponent {
  @Override
  public void doBeforeRender(HstRequest request,
                             HstResponse response) throws HstComponentException {
     SearchInfo info = getComponentParametersInfo(request);
     String docType = info.getDocType();
     int pageSize = info.getPageSize();
     // search for documents of type 'docType' and get 'pageSize' results
  }
}

In the code above, note the following crucial parts:

  1. The Search component is glued to the SearchInfo interface via the annotation @ParametersInfo(type = SearchInfo.class) . The Template Composer needs this annotation to display the parameters 'pageSize' and 'docType'.

  2. All methods in the SearchInfo interface have the @Parameter annotation. This annotation glues the hst:parameternames from the component configuration to a getter method.

  3. The @Parameter annotation can contain a defaultValue element, which is the value when the parameter is not present in the component configuration.

  4. You do not create an implementation class of the SearchInfo interface. The HST returns a proxied instance of this interface through getComponentParametersInfo(request).

Besides the @Parameter annotation, the methods of a ParametersInfo interface can also contain several other annotations. These annotations can be used to, for example, render different widgets in the CMS UI to edit the value of the parameter (e.g. via a color picker).

For more information, see the javadocs of org.hippoecm.hst.core.parameters.Parameter and org.hippoecm.hst.core.parameters.ParametersInfo.

Adding I18N translations for the @Parameter properties in the CMS template composer / channel manager

Just as for the additional channel info, you might want the popup dialog for component properties in the CMS to be internationalized. You can easily achieve this by adding a resource bundle in the same package as the parameter info interface above and with the same name (but ending on .properties) below the resources in your site project. The same rules for translating the properties apply as for  additional channel info. When having a DropDownList annotation, you can use the parameter name followed by a slash and then the parameter value again as the key (e.g., 'myDropDownList/option1=Option 1'). 

So, assume for the SearchInfo interface above would be located at org.example.components, then your resource bundles should be located as follows: 

+ site
    + src
        + main
            + java
            |   +org.example.components.SearchInfo
            + resources
                +org.example.components
                    - SearchInfo.properties
                    - SearchInfo_fr.properties
                    - SearchInfo_de.propertis
                    - SearchInfo_it.properties
                    - SearchInfo_nl.properties

i18n resource bundles for the English (default) bundle should contain something like:

pageSize=Page Size
docType=Document Type

Super interface resource bundles support

If you interface extends another interface, then if that interface has resource bundles, they will also work for the sub interface. The resource bundles for the sub interface can override the super interface bundles by redefining the i18n key. Note that multiple inheritance and super interfaces of super interfaces also correctly inherit i18n resource bundles. For the bundle inheritance scanning of super interface, a breadth first super interface bundle scanning is done.

 

Ordering and grouping component parameters

The parameters of a component can be visually ordered and grouped in the template composer by adding @FieldGroupList and @FieldGroup annotations to the ParametersInfo interface. For example:

SearchInfo.java

@FieldGroupList({
    @FieldGroup(
        titleKey = "group.constraints",
        value = { "docType", "tags" }
    ),
    @FieldGroup(
        titleKey = "group.display",
        value = { "pageSize" }
    )
})
public interface SearchInfo {

SearchInfo.properties

group.constraints=Search Constraints
group.display=Display Properties

This example specifies the order of three parameters (" docType", " tags", and " pageSize") and splits them into two groups titled "Search Contraints" and "Display Properties".

@FieldGroupList and @FieldGroup

The @FieldGroupList annotation specifies a list of one or more field groups. Each @FieldGroup annotation contains a list of parameter names. A field group can optionally have a translated title. The title's key is looked up in the resource bundle of the interface. The component properties box in the template composer will show the titles in bold above each group.

All parameters that are not included in any field group will be listed after all parameters that are included in a field group. The order of all the 'ungrouped' parameters is undetermined.

Note that the @FieldGroupList and @FieldGroup annotations can also be used for channel properties.

Inheritance

ParametersInfo interfaces can extend each other. Field groups of super interfaces are merged with the field groups of the sub-interface. Parameters of field groups with the same title key are merged into one group.

A field group can include parameter names from super interfaces, and thereby re-order and re-group these parameters at will. Each parameter is only included once, so including a parameter from a super interface in the field group of a sub-interface will 'override' its position. Like inherited resource bundles, inherited field groups and parameters are scanned breadth-first.

 

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?