Start page / Plug-In Development / Universal Extensions / Input Components / GOM Form Element / Additional XML Tags
Additional XML Tags
A GOM form element may specify additional XML tags which may be inserted within their respective parent block in a GOM form definition. This allows flexible, complex form definition analogous to that of FirstSpirit-provided input components such as FS_BUTTON, which makes use of child XML tags and blocks such as <DROPTYPES />.
Specifying Simple XML Tags
Abstract class: de.espirit.firstspirit.access.store.templatestore.gom.AbstractGomElement
FirstSpirit API documentation: AbstractGomElement
A simple XML tag consists of its tag name as well as optional attributes and further child tags.
In the following example, the main component tag, <CUSTOM_INPUT_COMPONENT />, has a simple child tag named <PARAMETER /> possessing attributes key and value:
<CMS_MODULE>
<CUSTOM_INPUT_COMPONENT name="myCustomInputComponent">
<PARAMETER key="param01" value="47" />
<LANGINFOS>
<LANGINFO lang="*" label="Custom Input Component" />
</LANGINFOS>
</CUSTOM_INPUT_COMPONENT>
</CMS_MODULE>
The child tag <PARAMETER /> is added to the class which specifies the tag <CUSTOM_INPUT_COMPONENT /> by providing getter and setter methods in the latter class, analogous to specifying XML tag attributes. In this case, the getter and setter methods operate on objects of a type implementing the interface GomElement or extending the abstract class AbstractGomElement.
Defining a Class Specifying the GOM Element
The GOM element (the child tag) is specified by a class which extends the abstract class AbstractGomElement. This class may again specify XML attributes as well as additional XML tags.
public class ParameterElement extends AbstractGomElement {
// Publicly available tag name, accessed later in the "Lists of XML Tags" example.
// This should follow the name of the getter method in the including class (see below).
public static final String TAG = "PARAMETER";
private String _key = "";
private String _value = "";
@GomDoc(description = "The parameter's key", since="1.0.0")
@Mandatory
@NotNull
public String getKey() {
return _key;
}
public void setKey(@NotNull final String key) {
_key = key;
}
@GomDoc(description = "The parameter's value", since="1.0.0")
@Mandatory
@NotNull
public String getValue() {
return _value;
}
public void setValue(@NotNull final String value) {
_value = value;
}
public void validate() throws IllegalStateException {
if (_key.isEmpty() || _value.isEmpty()) {
throw new IllegalStateException("Both attributes 'key' and 'value' must contain text.");
}
}
}Getter and Setter Methods in the Including Class
The getter and setter methods follow the same requirements as outlined in the section on specifying XML attributes. However, these methods operate on objects of the type which specifies the additional XML tag.
Following the example on the page GOM Form Definition, the main tag <CUSTOM_INPUT_COMPONENT /> (specified by the class CustomInputComponent) may make the child XML tag <PARAMETER /> (specified by the class ParameterElement) available with the following getter and setter methods:
public class CustomInputComponent extends AbstractGomFormElement {
...
private ParameterElement _parameterElement;
@GomDoc(description = "Provide the current parameter object", since="1.0.0")
@Nullable
public ParameterElement getParameter() {
return _parameterElement;
}
public void setParameter(@Nullable final ParameterElement parameterElement) {
_parameterElement = parameterElement;
}
} |
The name of the getter method defines the name of the XML tag used in form definitions in templates. Naming the getter method getParameter results in the XML tag name PARAMETER. The default tag name (shown as the field TAG in the code example for the class ParameterElement) should follow the XML tag name specified by the name of the getter method. |
Specifying Lists of XML Tags
Interface: de.espirit.firstspirit.access.store.templatestore.gom.GomList
FirstSpirit API documentation: GomList<T extends GomElement>
FirstSpirit also provides means to specify lists of XML tags. Such a list may contain none, one or several XML tags specified by the same class, and this class may specify either a simple XML tag or yet another list of XML tags.
In this section, we will use the simple XML tag <PARAMETER /> as defined above and wrap it with a list element represented by the tag <PARAMETERS />. This enables us to specify several parameters.
<CMS_MODULE>
<CUSTOM_INPUT_COMPONENT name="myCustomInputComponent">
<PARAMETERS>
<PARAMETER key="param01" value="17" />
<PARAMETER key="param02" value="42" />
<PARAMETER key="param03" value="47" />
</PARAMETERS>
<LANGINFOS>
<LANGINFO lang="*" label="Custom Input Component" />
</LANGINFOS>
</CUSTOM_INPUT_COMPONENT>
</CMS_MODULE>
As with simple XML tags, the element representing the tag is specified by a class, this time implementing the interface GomList<T> as well as extending a List<T> implementation such as ArrayList<T>, where T represents the class extending GomElement upon which the list's inner elements are based.
Unlike with simple XML tags, a list element only requires implementation of a getter method in the using XML tag's class.
Defining a Class Specifying the List of GOM Elements
The GOM element specifying the list of GOM elements is defined by a class which
- implements the interface GomList<T extends GomElement> and
- extends a List<T> implementation such as ArrayList<T>.
public class ParameterList extends ArrayList<ParameterElement> implements GomList<ParameterElement> {
public static final String DEFAULT_TAG = "PARAMETERS";
private String _tag;
private GomIncludeConfiguration _configuration;
private Map<String, Class<? extends GomElement>> _mappings;
public ParameterList() {
setGomElementTag(DEFAULT_TAG);
}
@Override
public String getGomElementTag() {
return _tag;
}
@Override
public void setGomElementTag(final String tag) {
_tag = tag;
}
// Return a map which pairs XML tag names with GomElement implementations. This allows
// FirstSpirit to identify the correct object type for child tags of an XML tag based on ParameterList.
@Override
public Map<String, Class<? extends GomElement>> getGomElementMappings() {
if (_mappings == null) {
_mappings = new HashMap<String, Class<? extends GomElement>>();
_mappings.put(ParameterElement.TAG, ParameterElement.class);
}
return _mappings;
}
@Override
public GomIncludeConfiguration getIncludeConfiguration() {
return _configuration;
}
@Override
public void setIncludeConfiguration(final GomIncludeConfiguration configuration) {
_configuration = configuration;
}
@Override
public boolean hasRepresentation() {
return false;
}
@Override
public void validate() throws IllegalStateException {
}
}Note that each allowed child tag name must be mapped to a class which implements the interface GomElement. This allows FirstSpirit to instantiate the correct objects, especially in GomList implementations which allow a multitude of different child tags. Towards this end, the method Map<String, Class<? extends GomElement>> getGomElementMappings() returns a list which provides key-value pairs of child element tag names and their associated GomElement implementations.
Getter Method in the Including Class
The getter method follows the same requirements as outlined in the section on specifying XML attributes.
|
In the case of a list of XML tags, the getter method must always provide a non-null object. If no inner elements are available, it is expected that an empty list object is returned. |
public class CustomInputComponent extends AbstractGomFormElement {
...
private ParameterList _parameterList;
@GomDoc(description = "Provide a list of parameter elements", since="1.0.0")
@NotNull
public ParameterList getParameters() {
if (_parameterList == null) {
_parameterList = new ParameterList();
}
return _parameterList;
}
}