Class FormControllerTag

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

    public class FormControllerTag
    extends WindowControllerTag

    A specialized tag handler implementation for creating form controllers.

    This tag handler class is pretty similar to WindowControllerTag, but provides some additional functionality specific to form controllers. The main difference is that it deals with objects of class (or derived from) FormController. Such objects are able to fully control the life-cycle of a form without requiring further intervention by the developer.

    This tag creates or obtains a FormController object and performs the necessary initialization steps. Especially the mandatory helper objects are set as follows:

    • The ComponentBuilderData object is set from the current Jelly context.
    • The WindowBuilderData object is set from the current Jelly context.
    • If no FormValidationTrigger trigger was set, the default FormValidationTrigger is obtained from the current BeanContext, and the corresponding property is initialized with this object.
    • If the formBeanName attribute is specified, a bean with this name is obtained from the current BeanContext and set as the form bean in the current WindowBuilderData object.

    For the objects that must be initialized from the current BeanContext constants are defined by this class. The default bean definition file shipped with the framework contains default definitions for all these objects. These can be overridden by applications so that all controllers created by an application make use of application-specific objects.

    Usage of this tag is very similar to the WindowControllerTag. Typically the controller is created as a bean using the full power of the dependency injection framework to set associated objects. Then this tag can be placed inside the body of a window tag for connecting the controller bean with the window. This could look as in the following example:

     <!-- A command to be executed when OK is pressed -->
     <di:bean name="okCommand" singleton="false"
       beanClass="...">
     </di:bean>
     <!-- Define the bean for the controller -->
     <di:bean name="controller" singleton="false"
       beanClass="com.mypackage.MyController">
       <di:setProperty property="okCommand" refName="okCommand"/>
       <!-- Set further properties if required -->
     </di:bean>
     <!-- The frame definition including the controller -->
     <w:frame title="Testwindow">
       <!-- Define the GUI here -->
          ...
       <w:formController beanName="controller"/>
     </w:frame>
     

    In this example a controller bean is defined, which is initialized with an "OK command" (i.e. a command to be executed when the OK button is pressed). Note that the singleton attribute of the bean definition is set to false; controllers should not be reused for multiple forms. Alternatively it is possible to create and initialize the controller directly using the formController tag. However, the <di:bean> tag is much more powerful when it comes to property initialization and dependency resolving.

    Version:
    $Id: FormControllerTag.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Field Detail

      • BEAN_FIELD_MARKER

        public static final String BEAN_FIELD_MARKER
        Constant for the name of the field marker bean.
        See Also:
        Constant Field Values
      • BEAN_VALIDATION_TRIGGER

        public static final String BEAN_VALIDATION_TRIGGER
        Constant for the name of the validation trigger bean.
        See Also:
        Constant Field Values
    • Constructor Detail

      • FormControllerTag

        public FormControllerTag()
        Creates a new instance of FormControllerTag.
    • Method Detail

      • addValidationListener

        public void addValidationListener​(FormControllerValidationListener l)
        Adds a FormControllerValidationListener. This listener will be added to the form controller bean when it is initialized. This method is intended to be called by tags in the body of this tag.
        Parameters:
        l - the listener to be added
      • addFieldStatusListener

        public void addFieldStatusListener​(FormControllerFieldStatusListener l)
        Adds a FormControllerFieldStatusListener. This listener will be added to the form controller bean when it is initialized. This method is intended to be called by tags in the body of this tag.
        Parameters:
        l - the listener to be added
      • addFormListener

        public void addFormListener​(FormControllerFormListener l)
        Adds a FormControllerFormListener. This listener will be added to the form controller bean when it is initialized. This method is intended to be called by tags in the body of this tag.
        Parameters:
        l - the listener to be added
      • passResults

        protected boolean passResults​(Object bean)
                               throws org.apache.commons.jelly.JellyTagException
        Passes the bean to the owning component. This implementation expects that the passed in bean is derived from the FormController class. It performs some specific initializations, e.g. it sets the required data objects (the component builder data and the window builder data) and checks, which helper objects have to be set. Helper objects like the validation trigger can be directly set at the controller bean when it is created. In this case they won't be touched by this method. Objects that have not yet been initialized are obtained from the current bean context and passed to the controller.
        Overrides:
        passResults in class WindowControllerTag
        Parameters:
        bean - the bean
        Returns:
        a flag whether the bean could be passed to its owner
        Throws:
        org.apache.commons.jelly.JellyTagException - in case of an error