GOM Form Element Definition

Defining a Form Element by Implementing an Interface

Interface: de.espirit.firstspirit.access.store.templatestore.gom.GomFormElement
FirstSpirit API documentation: GomFormElement

The GOM form element definition class must implement the interface GomFormElement, which identifies the specified GOM element to act as an editor component in a form. However, as input components used in FirstSpirit should support a number of common features such as language-dependent labels and attributes which define the layout of the form element's gadget representation in form views, it is recommended to extend an abstract class AbstractGomFormElement (see below) which already implements much of this common, useful functionality.

Supporting search relevancy On an input component level, FirstSpirit supports the GOM XML attribute searchRelevancy which defines the weight of an input component's content in the search index. The abstract class AbstractGomFormElement (see below) already implements this functionality. Form element classes which implement the interface GomFormElement directly should also implement the interface GomSearchRelevancy in order to add support for this attribute. This interface defines getter and setter methods (#getSearchRelevancy and #setSearchRelevancy, respectively) which operate on a field of type Relevancy. For further information about search relevancy settings, see Search and Global search (→Documentation FirstSpirit SiteArchitect).

Supporting definition of indexing behavior regarding associations On an input component level, FirstSpirit supports the GOM XML attribute indexTreatment which defines to which depth elements (such as datasets, which in turn may contain associations to further elements) referenced by association by the input component will be indexed. Input component implementations provided by FirstSpirit that may contain associations already support this attribute. GOM form element classes for custom input components that perform Value Processing and that are designed to contain associations to other FirstSpirit elements - regardless of whether these form element classes extend the abstract class AbstractGomFormElement (see below) or implement the interface GomFormElement directly - should also implement the interface GomIndexTreatment in order to add support for this attribute. This interface defines getter and setter methods (#getIndexTreatment and #setIndexTreatment, respectively) which operate on a field of type Treatment. Additionally, the Value Engineer implementation of the custom input component should provide an implementation of the aspect interface ReferenceAwareValueIndexSupporting, which enables the input component for use with FirstSpirit's functionality for both full-text indexing and reference indexing. The GOM XML attribute indexTreatment defines indexing behavior pertaining to associations for a single input component defined in a template; in order to define indexing behavior pertaining to associations on a server-wide level (i.e. for all input components that support indexing of associations), specify the FirstSpirit server configuration parameter indexing.relationshipPathLengthToFollow as described in Search and Server (→Documentation for Administrators).

Defining a Form Element by Extending an Abstract Class (Recommended)

Abstract class: de.espirit.firstspirit.access.store.templatestore.gom.AbstractGomFormElement
FirstSpirit API documentation: AbstractGomFormElement

The abstract class AbstractGomFormElement, which is provided in the FirstSpirit API as well, already implements GomFormElement as well as much common functionality expected of input components (such as attributes of the XML tag specifying default values (attribute preset), handling of empty values (attribute allowEmpty), and setting the component to display at full form width (attribute hFill)) and specifying language-dependent component labels (XML block <LANGINFOS />).

Extending AbstractGomFormElement, the form element class' only mandatory task is to set and provide its XML tag:

public class CustomInputComponent extends AbstractGomFormElement {

    public static final String TAG = "CUSTOM_INPUT_COMPONENT";

    protected String getDefaultTag() {
        return TAG;
    }
}

The tag returned by getDefaultTag() must match the component name provided in the FSM Component Definition.

The input component may be used in template form definitions as follows:

<CMS_MODULE>
    <CUSTOM_INPUT_COMPONENT name="myCustomInputComponent">
        <LANGINFOS>
            <LANGINFO lang="*" label="Custom Input Component" />
        </LANGINFOS>
    </CUSTOM_INPUT_COMPONENT>
</CMS_MODULE>

Both the attribute name as well as the XML block <LANGINFOS /> including its inner tags are specified by the abstract class AbstractGomFormElement. See the pages XML Tag Attributes and Additional XML Tags for information about adding custom attributes and child tags.