Class EventRegistrationTag

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

    public class EventRegistrationTag
    extends UseBeanBaseTag

    A tag handler class for registering an event listener at a single or multiple components.

    This tag handler class has a similar purpose as EventListenerTag. However, it uses a different approach for connecting an event listener with a component. While EventListenerTag and its sub classes allow connecting actions to standard component events (e.g. action or change events), this class operates on plain event listener implementations. It can also be used for working with non-standard event listeners, i.e. event listener interfaces defined in the net.sf.jguiraffe.gui.builder.components.model package that do not extend the FormEventListener interface or even 3rd party or custom event listener interfaces.

    This tag handler class extends UseBeanBaseTag and thus allows the definition of a bean class in multiple ways. The bean specified using the tag's attributes must implement the appropriate event listener interface. With the mandatory type attribute the event listener type must be specified. This can be either one of the standard types (ACTION, CHANGE, or FOCUS) or a non-standard event listener type. In the latter case the type name is derived from the name of the method for adding event listeners. As an example take the TreeHandler interface that defines the addExpansionListener() method for registering an event listener to be notified when a node of the tree is expanded or collapsed. The corresponding event type is Expansion, i.e. the string between add and Listener.

    The component(s) the event listener should be registered at can be specified in multiple ways:

    • This tag can be placed in the body of a tag defining a component. Then it registers the listener at the component handler of this component.
    • The name of a single component can be specified in the component attribute. The listener will be registered at this component's ComponentHandler.
    • Event handlers may also be registered at arbitrary beans accessible through the current BeanContext. To do this the targetBean attribute must be specified. The tag obtains this bean from the context and calls the appropriate add() method for adding the handler. Note that if the tag is used in this way really all beans of the current bean context can be accessed, e.g. the platform-specific components or the current window.
    • It is also possible to register a listener at all components that support the specified event type. In this case the multiple attribute must be set to true, and no component name or bean name must be specified. (The additional multiple attribute was introduced to provide a better error diagnosis: If the component attribute is omitted accidently, an exception is thrown rather than silently registering the listener at all components.)

    The following table lists the attributes supported by this tag handler class. Of course, all attributes defined by the UseBeanBaseTag class for specifying the bean are also supported.

    Attribute Meaning Optional
    component The name of the component the event listener is to be registered at. Yes
    targetBean With this attribute an arbitrary object available in the current BeanContext can be selected to which the event listener is added. This is a more generic form than using the component attribute. The bean specified here does not need to implement the ComponentHandler interface; as the event listener is added through reflection, it can be an arbitrary object defining an appropriate addXXXListener() method. Note: This attribute should not be used for registering standard event handlers (ACTION, FOCUS, and CHANGE ). Yes
    multiple If this attribute is specified (with an arbitrary value), the event listener will be registered at all compatible components. In this case the component attribute must be empty. Yes
    eventType Determines the type of the event listener. The bean specified by this tag must implement a compatible event listener interface. No
    ignoreFail With this attribute error handling can be controlled. Per default, the tag causes an error if no event listener can be registered. This can have various reasons, e.g. the name of the component is wrong, there is a typo in the event listener type, or there is no compatible component supporting the listener type. In most cases it is preferable to throw an exception in such a situation instead of ignoring the problem silently. There may be use cases though, where it is considered normal behavior that no fitting component for registering an event listener can be found. In this cases the ignoreFail attribute should be set - it can have an arbitrary value. If it is present, the tag will not throw an exception if the registration of the event listener is not possible. Yes

    The following fragment shows an example how this tag can be used for registering a listener for tree expansion events:

     <f:tree name="myTree" model="treeModel">
     </f:tree>
     <!-- The event listener bean -->
     <di:bean name="treeListener"
       beanClass="com.mypackage.MyTreeListenerClass">
     </di:bean>
     <!-- Register the event listener -->
     <a:eventListener component="myTree" eventType="Expansion"
       beanName="treeListener"/>
     

    Note that it does not matter where in the builder script the event registration tags are placed as the actual registration is performed after all components have been created.

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

      • EventRegistrationTag

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

      • passResults

        protected boolean passResults​(Object bean)
                               throws org.apache.commons.jelly.JellyTagException
        Performs the registration of the event listener. The actual registration is done by a callback object at the very end of the builder script. This ensures that all components have already been created.
        Overrides:
        passResults in class UseBeanBaseTag
        Parameters:
        bean - the bean object
        Returns:
        a flag whether the event listener could be registered
        Throws:
        org.apache.commons.jelly.JellyTagException - if an error occurs