Template Composer Annotations - 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.

30-11-2015

Template Composer Annotations

HST Component class annotations

The following annotations can be used on an HST component Java class. 

@ParametersInfo

Specifies the interface that defines the parameters of the annotated HST component. For example:

MyHstComponent.java 

@ParametersInfo(type = MyComponentParamsInfo.class)
public class MyComponent extends BaseHstComponent {
   ...
}

Parameters info class annotations

The following annotations can be used on an Parameters Info interface that defines the parameters of an HST component.

@FieldGroupList

Specifies a list of @FieldGroup annotations that together contain all component parameters. The order of the field groups determines the order in which they are rendered in the component's properties window in the template composer.

@FieldGroup

Specifies a list of component properties to render in the 'Channel Settings' box. Each property is referenced by its name. The order of the names determines the order in which the properties are rendered in the component's properties box in the template composer. For example:

MyComponentParamsInfo.java 

@FieldGroupList({
    @FieldGroup(titleKey = "address", value = { "street", "city" }),
    @FieldGroup(titleKey = "layout", value = { "size" })
})
public interface MyComponentParamsInfo {

    @Parameter(name = "street")
    String getStreet();

    @Parameter(name = "city")
    String getCity();

    @Parameter(name = "size", defaultValue="medium")
    @DropDownList({"small", "medium", "large"})
    String getSize();
}

Each group may have a title whose translation is looked up in a resource bundle (i.e. one or more localized .properties files) with the same name and in the same package as the interface. For example:

MyComponentParamsInfo.properties

address=Address Information
street=Street
city=City
layout=Layout Settings
size=Size
size/small=Small
size/medium=Medium
size/large=Large

The resource bundle contains the translations for the groups and parameters.

Parameters info method annotations

The following annotations can be used for getter methods of Parameters Info interfaces of HST components.

@Parameter

Specifies the name of the parameter, an optional default value, and whether it's required or not. Options:

  • name

    The name of the parameter that will be stored in the hst:parameternames property. Must be unique per component.

  • required

    Whether this parameter is required or not. The template composer only save a component's parameters when all required parameters have been filled in. Default: false.

  • displayName

    The string shown to the user as the label for the parameter field in the component's properties panel in the template composer. Default: the same value as name. Alternatively, resource bundles can be used to have different display names per CMS language (see the @FieldGroup annotation above).

 

If no other annotations are used, the widget in the CMS UI to edit the parameter depends on the return type of the annotated method:

Method Return Type

CMS UI Widget

java.lang.String

Text field that accepts an alpha-numeric value for the parameter

short, int, long, java.lang.Short, java.lang.Integer, java.lang.Long

Text field that accepts only numeric values

boolean, java.lang.Boolean

Checkbox that sets 'true' or 'false' in the parameter value

java.util.Date

Date picker widget

@DropDownList

 

Used for a getter that returns a String value from fixed set of values. The display name of each value can be localized. The resource bundle key for each value is parameterName/value (e.g. "size/small=Small" for the value 'small' of the parameter 'size').

@JcrPath

Used for a getter that returns a path to a document as String value. The path can be set by picking a document. The path can be either absolute or relative, depending on the isRelative option. The CMS UI will display the name or the last path element of the document, and a button that opens a document picker. Options:

  • isRelative

    Whether the stored path is relative to the canonical content root path of the channel in which this annotation is used. The default is 'false', i.e. the stored path is absolute.

  • pickerConfiguration

    The root path of the CMS configuration to use for the picker, relative to /hippo:configuration/hippo:frontend/cms. Default value: "cms-pickers/documents".

    To pick only images, use the value "cms-pickers/images".
    To pick only documents, use the value "cms-pickers/documents-only".
  • pickerInitialPath

    The initial path to use in the picker if nothing has been selected yet. Use the path to a folder to initially open the picker in that folder. Use the path to the handle of a document to preselect that document. Use an empty string to use the default initial path of the picker. Default value: "" (empty string).

  • pickerRemembersLastVisited

    Whether the picker remembers the last visited path. Default: true.

  • pickerSelectableNodeTypes

    Types of nodes to be able to select in the picker. Default: empty list, resulting in the default behavior of the picker.

@Color

Used for a getter that returns a hexidecimal color value as a String. The CMS UI will display a color picker with a textfield that allows you to either pick a color from the color picker or to type in a hex color value.

@DocumentLink

Used for a getter method that returns the path to a document as a String value. The CMS UI will display a combo box with the list of documents of the type specified using the docType parameter. When the allowCreation parameter is set, the user can also create a document of the type specified by docType. Options:

  • docType

    The primary node type of the document, used in displaying the combobox with the list of documents.

  • allowCreation

    When set to true, the document combobox will also display a link to create a new document from the Template Composer.

  • docLocation

    When allowCreation is set to true, the Template Composer will use the path specified in this parameter as the location of the document to be created. The path is relative to the channel's content root. For example, if you set docLocation to common/textpages, and the channel's content root is /content/documents/yourchannel, the document will be created under /content/documents/yourchannel/common/textpages. The name of the document will be provided by the user via a prompt window.

 

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?