Class TableColumnTag

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

    public class TableColumnTag
    extends FieldTag

    A tag handler class for defining columns of a table component.

    The tag represented by this handler class can be placed in the body of a TableTag. It defines the content of one of the table's columns. Its header text and its width can also be specified.

    In the most simple case a property from the beans that form the table's model is directly output. In this case only the name attribute needs to be set. The table implementation will then fetch this property from the model bean for the current row and display it without further modifications. It is recommended to set the columnClass attribute to the fully qualified name of the value class; then a suitable cell renderer can automatically be chosen (e.g. for rendering boolean values as checkboxes etc.).

    If additional formatting is required (e.g. for adapting number or date values to the locale of the current user), a write transformer can be specified. This transformer will be invoked before the value is displayed.

    To satisfy even more complex requirements a <colrenderer> tag (implemented by the ColumnRendererTag class can be placed in the body of this tag. This tag can be used to define an arbitrary component (even a container with an arbitrary number of child components) that will be used for painting the cells in this row. This is especially useful if a column in a table should contain a complete (sub) form.

    For editable columns similar variants are possible. In the simplest scenario only the property name (and eventually the column class) is specified. The table will then use an appropriate default cell editor for editing values in this column. If formatting and validating is involved, corresponding transformers and validators can be specified using nested tags. This happens in an analogous way as for standard input components. The most complex scenario is again to use a nested tag (an <coleditor> tag in this case) for defining a complete (sub) form as editor for this column.

    The following table lists all attributes supported by this tag:

    Attribute Description Optional
    name This attribute defines the name of the property (of the beans that belong to the model) that is to be displayed in this column. The property will be read using reflection from the model beans. This attribute is mandatory even if specific forms are defined for both the column renderer and the column editor. No
    columnClass Here the class of the data to be displayed in this column can be specified. If no specific renderer and/or editor is defined for this column, the class will be used to determine a suitable default renderer or editor class. There are multiple ways of defining the column class using this attribute:
    • An instance of ColumnClass or the name of a constant defined in this class can be specified. In this case a logic type for the column is set. It will be interpreted and transformed according to the UI toolkit in use. This is the most portable way of defining the column class.
    • A Java class or the fully-qualified name of a class can be specified. This class is passed to the underlying UI toolkit (which of course should be able to deal with it).
    • If the column class is not specified, the most generic default renderer is used for this column.
    Yes
    width Defines the absolute width of this table. The value specified here can be a NumberWithUnit. Yes
    percentWidth Using this attribute a relative width of this column in percent can be specified. If columns with a percent width are used, the algorithm to determine the widths of columns is as follows:
    • First columns with a fixed width are set. The remaining space is calculated (i.e. the width of the table minus the sum of the widths of the columns with a fixed width).
    • For all columns that do not have a fixed width the percent values are determined: If a percent value is already set, it is used. For all other columns the percent width is set to a value so that the percent values sum up to 100 percent. (If this is not possible because the values specified sum up to a number greater than 100, an exception is thrown when creating the table.)
    • The remaining space is distributed to the columns based on their percent value.
    Using this algorithm it is possible to mix columns with fix and with relative sizes.
    Yes
    header With this attribute the header text for this column can directly be specified. Yes
    headerres Specifies the header text for this column using a resource ID. Yes
    resgrp Here are resource group for resolving the header text can be specified. This attribute is only evaluated if the headerres attribute is set. If no specific resource group is provided, the default group will be used. Yes
    editable This boolean attribute determines whether this column can be edited. If it is undefined, the value of the enclosing <table> tag's editable attribute is used. Yes

    In the body of this tag the <colrenderer> and <coleditor> tags can appear. Other content is not allowed.

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

      • TableColumnTag

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

      • setHeader

        public void setHeader​(String s)
        Set method for the header attribute.
        Parameters:
        s - the attribute's value
      • setHeaderres

        public void setHeaderres​(String s)
        Set method for the headerres attribute.
        Parameters:
        s - the attribute's value
      • setResgrp

        public void setResgrp​(String s)
        Set method for the resgrp attribute.
        Parameters:
        s - the attribute's value
      • setWidth

        public void setWidth​(String s)
        Set method for the width attribute.
        Parameters:
        s - the attribute's value
      • setPercentWidth

        public void setPercentWidth​(int percentWidth)
        Set method of the percentWidth attribute.
        Parameters:
        percentWidth - the attribute's value
      • setEditable

        public void setEditable​(boolean f)
        Set method for the editable attribute.
        Parameters:
        f - the attribute's value
      • setColumnClass

        public void setColumnClass​(Object o)
        Set method for the columnClass attribute.
        Parameters:
        o - the attribute's value
      • getRenderFields

        public Set<String> getRenderFields()
        Returns a set with the names of the fields of the render form that are used for rendering this column. It is possible to define a renderer for a column (by using a nested ColumnRendererTag tag, which can consist of an arbitrary number of components. If this is done for this column, this method returns the names of the components used in this renderer. This information could be used for instance by a platform specific implementation to decide, which fields needs to be updated before the column can be painted. If no specific renderer is defined for this column, an empty set will be returned here.
        Returns:
        a set with the names of the fields used by the renderer for this column
      • getEditFields

        public Set<String> getEditFields()
        Returns a set with the names of the fields of the editor form that are used for editing this column. This method is analogous to getRenderFields(), but addresses a column specific editor.
        Returns:
        a set with the names of the fields used by the editor for this column
        See Also:
        getRenderFields()
      • getColumnWidth

        public NumberWithUnit getColumnWidth()
        Returns the width of this column as a NumberWithUnit object.
        Returns:
        the width of this column
      • getPercentWidth

        public int getPercentWidth()
        Returns the percent width of this column. A return value of 0 means that no percent width is specified.
        Returns:
        the percent width of this column
      • getHeaderText

        public TextData getHeaderText()
        Returns a TextData object defining the header text of this column.
        Returns:
        a data object for this column's header
      • getLogicDataClass

        public ColumnClass getLogicDataClass()
        Returns the logic data class of this column if available. It is possible to define the type of the data to be displayed in this column in the toolkit-independent way by passing the value of a constant of the ColumnClass enumeration to the setColumnClass(Object) method. If this was done, the logic column class can be queried with this method. It has to be interpreted and converted depending on the currently used UI toolkit. If null is returned, no logic column class was set, and getDataClass() should be used instead to obtain the "real" column class.
        Returns:
        the logic column class (can be null)
      • getDataClass

        public Class<?> getDataClass()
        Returns the class of the data to be displayed in this column. If undefined, the generic base class java.lang.Object will be returned.
        Returns:
        the data class for this column
      • getRendererComponent

        public Object getRendererComponent()
        Returns the component to be used for rendering this column. If a specific column renderer has been set using a nested ColumnRendererTag tag, this component is returned here. Otherwise the return value is null.
        Returns:
        the renderer component for this column
      • getEditorComponent

        public Object getEditorComponent()
        Returns the component to be used for editing this column. If a specific column editor has been set using a nested ColumnEditorTag tag, this component is returned here. Otherwise the return value is null.
        Returns:
        the editor component for this column
      • getTableTag

        protected TableTag getTableTag()
        Returns a reference to the hosting table tag.
        Returns:
        the table tag this column tag belongs to
      • insertField

        protected void insertField​(FieldHandler fieldHandler)
        Inserts the field handler to the form that is automatically constructed during the build process. This implementation checks both the table's renderer and editor form whether a field handler for this column's property has already been added. Only if this is not the case, the default field handler for this column will be added. Further the table tag will be informed about the new column.
        Overrides:
        insertField in class InputComponentTag
        Parameters:
        fieldHandler - the field handler to be added
      • processBeforeBody

        protected void processBeforeBody()
                                  throws org.apache.commons.jelly.JellyTagException,
                                         FormBuilderException
        Performs processing before the tag's body is evaluated. This implementation will perform some checks of the set attributes.
        Overrides:
        processBeforeBody in class InputComponentTag
        Throws:
        org.apache.commons.jelly.JellyTagException - if the tag is incorrectly used
        FormBuilderException - if an error occurs
      • initRenderFields

        protected void initRenderFields​(Set<String> fields)
        Sets the names of the fields used in the specific renderer for this column. This method will be called by nested tags.
        Parameters:
        fields - the set with the field names
      • initEditFields

        protected void initEditFields​(Set<String> fields)
        Sets the names of the fields used in the specific editor for this column. This method will be called by nested tags.
        Parameters:
        fields - the set with the field names
      • initRendererComponent

        protected void initRendererComponent​(Object rendererComponent)
        Sets the renderer component to be used for this column. This method will be called by nested tags.
        Parameters:
        rendererComponent - the renderer component to be used for this column
      • initEditorComponent

        protected void initEditorComponent​(Object editorComponent)
        Sets the editor component to be used for this column. This method will be called by nested tags.
        Parameters:
        editorComponent - the editor component to be used for this column