Class ComponentHandlerTag

  • All Implemented Interfaces:
    ConditionalTag, PropertySupport, org.apache.commons.jelly.DynaTag, org.apache.commons.jelly.impl.BeanSource, org.apache.commons.jelly.Tag

    public class ComponentHandlerTag
    extends UseBeanBaseTag

    A tag handler class that allows constructing custom ComponentHandler objects.

    This tag can be placed in the body of a FieldTag to define the ComponentHandler that should be used by the input component to be constructed. The class of the new component handler must be specified in the class attribute. An instance of this class is created, initialized (which can be done by using other attributes representing properties of the newly created object), and finally passed to the enclosing FieldTag instance. This tag will then construct a suitable FieldHandler object and ensure that the represented component is added to the current Form object and to the enclosing GUI container element.

    With this tag handler class two common use cases can be addressed:

    • Components not supported by the form builder library (e.g. custom controls) can be added to both the resulting Form object and the generated GUI. For this purpose a suitable implementation of the ComponentHandler interface must be provided, which wraps the component to be added. The name of the implementation class must then be specified as the value of this tag's class attribute.
    • Sometimes the default data provided by the supported GUI components is not sufficient. A typical example is a group of radio buttons: Each radio button has a boolean data object that tells whether this button is the selected one. Instead of storing a boolean value for each radio button that belongs to the group in the form's bean it is probably better to use a different storage format, e.g. storing only the index of the selected button as an int or using some kind of mapping to other values. This can be achieved by first defining the components that should be manipulated (in this example the radio buttons) in the usual way in the Jelly script, but setting their noField attribute to true. This ensures that they are not added as concrete data fields to the constructed Form object. Then an implementation of the CompositeComponentHandler interface must be created and specified in this tag's class attribute. In this tag's body an arbitrary number of ReferenceTag elements can be placed defining the components that should be wrapped by the new composite component handler. The components specified this way will be retrieved and added to the composite component handler. Then this composite handler will be added to the Form object as a complex data member. It can then perform an arbitrary transformation from the containing components' native data format to another format.
    • This tag of course supports all attributes already defined in its base class. If references are used to define components that are to be added to a composite component handler, these references are resolved at the very end of the builder process, thus ensuring that the referred components have already been created.

    Version:
    $Id: ComponentHandlerTag.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    See Also:
    ReferenceTag
    • Constructor Detail

      • ComponentHandlerTag

        public ComponentHandlerTag()
    • Method Detail

      • addComponentReference

        public void addComponentReference​(String ref)
        Adds a reference to another component to this tag. The reference will be resolved, and the corresponding component handler will be added to the newly created component handler (which must be a composite handler).
        Parameters:
        ref - the name of the referenced component
      • addGroupReference

        public void addGroupReference​(String ref)
        Adds a reference to a component group to this tag. The component handlers of all components contained in this group will be fetched and added to the newly created component handler (which must be a composite handler).
        Parameters:
        ref - the name of the referenced group
      • addReference

        protected void addReference​(net.sf.jguiraffe.gui.builder.components.tags.ComponentHandlerTag.Reference ref)
        Adds a reference to the internal list.
        Parameters:
        ref - the new reference
      • passResults

        protected boolean passResults​(Object bean)
                               throws org.apache.commons.jelly.JellyTagException
        Passes the results of this tag to its target tag. This implementation checks whether the parent tag of this tag is of type FieldTag. If this is the case, the newly created bean instance is added as a component handler. If references to other components or groups are defined, the corresponding reference objects are scheduled for resolving (the new bean must then implement the CompositeComponentHandler interface).
        Overrides:
        passResults in class UseBeanBaseTag
        Parameters:
        bean - the newly created bean
        Returns:
        a flag whether the bean could be passed to the target
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs
      • addComponentToCompositeHandler

        protected static <S> void addComponentToCompositeHandler​(ComponentBuilderData builderData,
                                                                 CompositeComponentHandler<?,​S> handler,
                                                                 String compName)
                                                          throws FormBuilderException
        Helper method for adding the ComponentHandler of a component to a CompositeComponentHandler. This method tries to obtain the component handler for the component with the specified name from the builder data object. Then it adds this handler to the complex handler. Note that it cannot be verified that the child ComponentHandler is actually of the expected data type. Therefore it is not possible to exclude that a ClassCastException might be thrown.
        Type Parameters:
        S - the type of the child ComponentHandler
        Parameters:
        builderData - the builder data object
        handler - the CompositeComponentHandler
        compName - the name of the component to add
        Throws:
        FormBuilderException - if the component cannot be found
      • addGroupToCompositeHandler

        protected static void addGroupToCompositeHandler​(ComponentBuilderData builderData,
                                                         CompositeComponentHandler<?,​?> handler,
                                                         ComponentGroup group)
                                                  throws FormBuilderException
        Helper method for adding the ComponentHandler objects for all components in the specified group to a CompositeComponentHandler. This method iterates over all components in the specified group and calls #addComponentToCompositeHandler() for each.
        Parameters:
        builderData - the builder data object
        handler - the CompositeComponentHandler
        group - the ComponentGroup
        Throws:
        FormBuilderException - if a component cannot be resolved