Class TableTag

  • All Implemented Interfaces:
    Composite, ConditionalTag, ScrollSizeSupport, org.apache.commons.jelly.Tag

    public class TableTag
    extends InputComponentTag
    implements Composite, ScrollSizeSupport

    A tag that creates a table component.

    Tables certainly belong to the most complex GUI elements. With this tag and some auxiliary tags that can be placed in the body of this tag such tables can be created and initialized. Though tables can be used for editing data they are no typical input components because they do not store their data in a form bean using a ComponentHandler. Instead they are initialized with a model, which is simply a collection of Java beans. For each element in this collection a row will be displayed in the table. (The column's are derived from the table's column definition; see below.) So tables can be directly used for visualizing collections of data or manipulating single records.

    This tag is used like a normal component tag: simply place it in a builder script at the desired position according to the current layout. With the tag's attributes the model (i.e. the collection with the data objects) is specified. The exact structure of the table is specified by nested tags.

    For each column to be displayed in the table a <column></column> tag (implemented by the TableColumnTag class) must be placed in the body of the table tag. This tag determines the column's header and the name of the property of the model objects that is to be displayed in this column. Further, a Transformer can be specified for formatting the data, and - in case of an editable column - a validator. These attributes are analogous to standard input components. More information can be found in the documentation of the ColumnTag.

    Table tags are input component tags, which means that for each table a component handler will be created. This is a specialized handler that can be used to access specific table functionality. Per default this handler will not be added to the form's fields, but with setting the noField attribute to false this behavior can be changed.

    The following table lists the attributes supported by the TableTag tag handler class:

    Attribute Description Optional
    model Here the name of a bean must be provided that serves as the data model for the table. This bean must be a collection. If it implements the java.util.List interface, it is directly used. Otherwise it is copied into a new list because direct access to the elements by index is needed. The collection can contain arbitrary Java beans whose properties will be accessed using reflection. The bean is looked up in the current bean context. No
    editable This boolean property determines whether the table is read-only or can be edited. Here only the default value is set; it is possible to override this value for specific columns. If this attribute is not provided, false is assumed as the default value. Yes
    selectionBackground With this property the background color for selected cells can be set. If ommitted, the default color will be used. Yes
    selectionForeground With this property the foreground color for selected cells can be set. If ommitted, the default color will be used. Yes
    multiSelection This boolean property indicates whether the created table should support multi-selection, i.e. multiple rows can be selected at the same time. If the attribute is missing, false is the default value. Yes
    scrollWidth Here the preferred width of the scroll pane enclosing the table can be specified as a number with unit (e.g. "1.5cm"). If specified, the scroll pane will have exactly this preferred width. Otherwise, the width is determined by the preferred width of the table. yes
    scrollHeight Here the preferred height of the scroll pane enclosing the table can be specified as a number with unit (e.g. "10dlu"). If specified, the scroll pane will have exactly this preferred height. Otherwise, the height is determined by the preferred height of the table. yes
    var If this attribute is set, the table tag will store a reference to itself in the Jelly context under the name specified here. This is especially useful for testing purposes. The variable created by this meachanism can be used for instance to query the internally created form objects. Yes

    There are some further objects that can be associated with a table and are defined by nested tags:

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

      • TableTag

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

      • getSelectionBackground

        public String getSelectionBackground()
        Returns the selection background color as a string.
        Returns:
        the selection background color (can be null)
      • setSelectionBackground

        public void setSelectionBackground​(String selectionBackground)
        Set method for the selectionBackground attribute.
        Parameters:
        selectionBackground - the value of the attribute
      • getSelectionForeground

        public String getSelectionForeground()
        Returns the selection foreground color as a string.
        Returns:
        the selection foreground color (can be null)
      • setSelectionForeground

        public void setSelectionForeground​(String selectionForeground)
        Set method for the selectionForeground attribute.
        Parameters:
        selectionForeground - the attribute's value
      • getScrollWidth

        public String getScrollWidth()
        Returns the preferred scroll width as a string.
        Returns:
        the preferred scroll width specification (can be null)
      • setScrollWidth

        public void setScrollWidth​(String scrollWidth)
        Set method of the scrollWidth attribute.
        Parameters:
        scrollWidth - the attribute's value
      • getScrollHeight

        public String getScrollHeight()
        Returns the preferred scroll height as a string.
        Returns:
        the preferred scroll height specification (can be null)
      • setScrollHeight

        public void setScrollHeight​(String scrollHeight)
        Set method of the scrollHeight attribute.
        Parameters:
        scrollHeight - the attribute's value
      • getSelectionBackgroundColor

        public Color getSelectionBackgroundColor()
        Returns the selection background color as Color object. This is the value set by the setSelectionBackground() method transformed into a Color representation.
        Returns:
        the selection background color
      • getSelectionForegroundColor

        public Color getSelectionForegroundColor()
        Returns the selection foreground color as Color object. This is the value set by the setSelectionForeground() method transformed into a Color representation.
        Returns:
        the selection foreground color
      • setModel

        public void setModel​(String s)
        Set method for the model attribute.
        Parameters:
        s - the value of the attribute
      • setEditable

        public void setEditable​(boolean f)
        Set method of the editable attribute.
        Parameters:
        f - the value of the attribute
      • isMultiSelection

        public boolean isMultiSelection()
        Returns a flag whether multi-selection is enabled for this table.
        Returns:
        the multi selection flag
      • setMultiSelection

        public void setMultiSelection​(boolean multiSelection)
        Set method for the multiSelection attribute.
        Parameters:
        multiSelection - the attribute's value
      • setVar

        public void setVar​(String s)
        Set method of the var attribute.
        Parameters:
        s - the value of the attribute
      • isTableEditable

        public boolean isTableEditable()
        Returns a flag whether the table is editable. Note that this flag does not control the editable state of the full table, it only defines the default state for columns. A column can override this flag.
        Returns:
        a flag whether the table is editable
      • isColumnEditable

        public boolean isColumnEditable​(TableColumnTag colTag)
        Returns a flag whether the specified column is editable. This method should be used to find out whether the column can be edited or not. It also takes the table's default settings into account.
        Parameters:
        colTag - the tag representing the column to test
        Returns:
        a flag whether this column can be edited
      • getEditorSelectionHandler

        public TableSelectionHandler getEditorSelectionHandler()
        Returns the selection handler for editor components.
        Returns:
        the editor selection handler
      • setEditorSelectionHandler

        public void setEditorSelectionHandler​(TableSelectionHandler editorSelectionHandler)
        Sets the selection handler for editor components. This method will be invoked by tags in the body to set a concrete implementation of the TableSelectionHandler interface.
        Parameters:
        editorSelectionHandler - the selection handler for editor components
      • getEditorValidationHandler

        public TableEditorValidationHandler getEditorValidationHandler()
        Returns the editor validation handler.
        Returns:
        the editor validation handler
      • setEditorValidationHandler

        public void setEditorValidationHandler​(TableEditorValidationHandler editorValidationHandler)
        Sets the editor validation handler. This method will be called by nested tags to set a concrete implementation of the TableEditorValidationHandler interface.
        Parameters:
        editorValidationHandler - the editor validation handler
      • getRendererSelectionHandler

        public TableSelectionHandler getRendererSelectionHandler()
        Returns the selection handler for renderer components. This method never returns null. If no handler was set, a dummy handler is returned.
        Returns:
        the renderer selection handler
      • setRendererSelectionHandler

        public void setRendererSelectionHandler​(TableSelectionHandler rendererSelectionHandler)
        Sets the selection handler for renderer components. This method will be invoked by tags in the body to set a concrete implementation of the TableSelectionHandler interface.
        Parameters:
        rendererSelectionHandler - the selection handler for renderer components
      • getValidationErrorTitle

        public String getValidationErrorTitle()
        Returns the title of the message box that is displayed if validation fails.
        Returns:
        the message box title
      • setValidationErrorCaption

        public void setValidationErrorCaption​(String validationErrorTitle)
        Sets the title of the message box that is displayed if validation fails. This property can be evaluated by the current TableEditorValidationHandler. This object is triggered whenever validation of user input in a custom editor fails. In this case typically a message box with the validation error message(s) is displayed. With this property the caption of this message box is specified. It is typically set by a nested TableEditorValidationHandlerTag tag handler.
        Parameters:
        validationErrorTitle - the caption of a validation error message box
      • getColumns

        public Collection<TableColumnTag> getColumns()
        Returns a collection with the column tags defined for this table. With this method all information about the existing columns can be obtained.
        Returns:
        a collection with the tags representing the columns of this table
      • getColumn

        public TableColumnTag getColumn​(int index)
        Returns the tag for the column with the given index.
        Parameters:
        index - the column index (0-based)
        Returns:
        the column with this index
      • getColumnCount

        public int getColumnCount()
        Returns the number of columns of this table.
        Returns:
        the number of columns of the represented table
      • getRowRenderForm

        public Form getRowRenderForm()
        Returns the form with the renderers defined for this table. All components defined in <colrenderer> tags for columns of this table will be collected into a Form object. For columns that do not define their own renderers default FieldHandler objects will be added to this form. So this form object contains a complete representation of the data of a single row. Platform specific implementations can make use of this object when the table is to be displayed.
        Returns:
        a form containing the components for rendering a row
      • getRowEditForm

        public Form getRowEditForm()
        Returns the form with the editors defined for this table. This method is analogous to getRowRenderForm(), but the returned Form object contains the defined editor components (plus the default FieldHandler objects to be used for columns that do not have their own editor).
        Returns:
        a form containing the components for rendering a row
        See Also:
        getRowRenderForm()
      • getTableModel

        public Collection<?> getTableModel()
        Returns the model of this table. This is a collection with arbitrary beans, which is fetched from the Jelly context.
        Returns:
        the collection that acts as the table's model
      • getTableFormController

        public TableFormController getTableFormController()
        Returns an initialized TableFormController object associated with this tag.
        Returns:
        a TableFormController
        Since:
        1.3
      • addColumn

        public void addColumn​(TableColumnTag colTag)
        Adds a tag representing a column to this table tag. This method will be called by nested tags.
        Parameters:
        colTag - the column tag to be added
      • getColumnWidthController

        public TableColumnWidthController getColumnWidthController()
                                                            throws FormBuilderException
        Returns the TableColumnWidthController for the columns defined for this table. This method can be called after execution of this tag. It creates the TableColumnWidthController object on demand and initializes with all columns defined for this table.
        Returns:
        the TableColumnWidthController for this table
        Throws:
        FormBuilderException - if the controller cannot be created
      • addComponent

        public void addComponent​(Object comp,
                                 Object constraints)
        Adds an element to this container. This tag implements the Composite interface so that the components created by the columns defined in its body get automatically added and do not mess up the hosting container tag. This makes it also possible to verify that only TableColumnTag tags are placed in the body - these tags create component handlers that do not have a component.
        Specified by:
        addComponent in interface Composite
        Parameters:
        comp - the component to be added
        constraints - a constraints object
      • getContainer

        public Object getContainer()
        Returns an object representing the container. This method from the Composite interface is not supported by this tag.
        Specified by:
        getContainer in interface Composite
        Returns:
        the container object
      • setLayout

        public void setLayout​(Object layout)
        Sets a layout object for this container. This method from the Composite interface is not supported by this tag.
        Specified by:
        setLayout in interface Composite
        Parameters:
        layout - the layout to be set
      • processBeforeBody

        protected void processBeforeBody()
                                  throws org.apache.commons.jelly.JellyTagException,
                                         FormBuilderException
        Processes this tag before the body is executed. This implementation checks for some required attributes and performs some initialization.
        Overrides:
        processBeforeBody in class InputComponentTag
        Throws:
        org.apache.commons.jelly.JellyTagException - if a jelly related problem occurs
        FormBuilderException - if the tag is incorrectly used
        InjectionException - if the model bean cannot be resolved
      • process

        protected void process()
                        throws FormBuilderException,
                               org.apache.commons.jelly.JellyTagException
        Processes this tag. This implementation performs additional validity checks regarding the definitions of the table's columns.
        Overrides:
        process in class InputComponentTag
        Throws:
        FormBuilderException - if an error occurs
        org.apache.commons.jelly.JellyTagException - if the tag is used incorrectly
      • resolveModel

        protected Object resolveModel​(String modelName)
        Obtains the model for the table. This implementation tries to resolve the model bean from the current bean context.
        Parameters:
        modelName - the name of the model
        Returns:
        the bean serving as table model
        Throws:
        InjectionException - if the model bean cannot be resolved