Version 8.2 (2013-03-18)	SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT

In the example introducing the ROWTABLEAREA2 control, the header of the grid was built by arranging certain LABEL controls, where the LABEL controls where rendered as headers:

<rowtablearea2 griddataprop="lines" rowcount="10" withborder="true" width="100%">
    <tr>
        ...
        <label name="First Name" asheadline="true">
        </label>
        ...
    </tr>
    <repeat>
...
...
...

It is also possible to use the GRIDCOLHEADER control in order to define the header of a grid. The advantages are:

• GRIDCOLHEADER controls are automatically rendered in "header style".

• GRIDCOLHEADER controls allow to sort the grid content.

• GRIDCOLHEADER controls allow to resize a grid.

• GRIDCOLHEADER controls allow to change the sequence of columns - if used together with the FLEXLINE control.

This document covers the following topics:

• Flexible Column Sizing

• Flexible Column Sorting

• Flexible Column Sequence

• GRIDCOLHEADER Properties

• Smart Selection of Rows - SELECTOR Control

• SELECTOR Properties

Flexible Column Sizing

Let us have a look on the following grid definition:

<rowarea name="Grid Col Header Example">
    <rowtablearea2 griddataprop="lines" rowcount="10" width="100%" withborder="true"
                   hscroll="true" firstrowcolwidths="true">
        <tr>
            <gridcolheader name=" " width="30">
            </gridcolheader>
            <gridcolheader name="First Name" width="150">
            </gridcolheader>
            <gridcolheader name="Last Name" width="150">
            </gridcolheader>
            <hdist>
            </hdist>
        </tr>
        <repeat>
            <str valueprop="selected">
                <checkbox valueprop="selected" flush="screen" width="100%" align="center">
                </checkbox>
                <field valueprop="firstName" width="100%" noborder="true"
                       transparentbackground="true">
                </field>
                <field valueprop="lastName" width="100%" noborder="true"
                       transparentbackground="true">
                </field>
                <hdist>
                </hdist>
            </str>
        </repeat>
    </rowtablearea2>
</rowarea>

You see:

• The ROWTABLEAREA2 definition was set to always follow the column widths of the first row. The first row of the grid is the row containing the GRIDCOLHEADER controls, this means that this row defines the column sizing for the whole grid.

• The header row of the grid is built out of GRIDCOLHEADER controls, each one specifying a name and a width.

• The header row is closed with an horizontal distance.This is quite important: if your column widths do not horizontally fill the grid, then the remaining space is typically equally distributed among the columns. Even if GRIDCOLHEADER specifies a certain width, this may still be overridden by the browser. A horizontal distance control (HDIST) at the end makes the browser assign the remaining space to the distance control, not to the GRIDCOLHEADER controls.

When the user moves the mouse over the border of the header columns, then the cursor will change and the user can change the width of the columns:

Your adapter gets notified by a certain event if the user changes the width of the columns. Have a look at the adapter code:

// This class is a generated one.

import com.softwareag.cis.server.Adapter;
import com.softwareag.cis.server.util.GRIDCOLHEADERInfo;
import com.softwareag.cis.server.util.GRIDCollection;
import com.softwareag.cis.server.util.IGRIDCOLHEADERChangeListener;
import com.softwareag.cis.server.util.ISSSARRAYInfo;

public class FlexibleColumnSizingAdapter
    extends Adapter
    implements IGRIDCOLHEADERChangeListener
{
    // class >LinesItem<
    public class LinesItem
    {
        // property >firstName<
        String m_lastName;
        public String getLastName() { return m_firstName; }
        public void setLastName(String value) { m_firstName = value; }

        String m_firstName;
        public String getFirstName() { return m_firstName; }
        public void setFirstName(String value) { m_firstName = value; }

        // property >selected<
        boolean m_selected;
        public boolean getSelected() { return m_selected; }
        public void setSelected(boolean value) { m_selected = value; }
    }

    // property >lines<
    GRIDCollection m_lines = new GRIDCollection();
    public GRIDCollection getLines() { return m_lines; }

    /** initialisation - called when creating this instance*/
    public void init()
    {
        for ( int i=0; i<20; i++)
        {
            LinesItem line = new LinesItem();
            line.setFirstName("First Name " +i);
            line.setLastName("Last Name " + i);
            m_lines.add(line);
        }
        m_lines.addGridColHeaderChangeListener(this);

    }

//  ------------------------------------------------------------------------
//  interface IGRIDCOLHEADERChangeListener
//  ------------------------------------------------------------------------
    public void reactOnContextMenuRequest(ISSSARRAYInfo collection,
            GRIDCOLHEADERInfo colInfo)
    {  }

    public void reactOnMove(ISSSARRAYInfo collection, GRIDCOLHEADERInfo[] colInfo)
    {  }

    public void reactOnResize(ISSSARRAYInfo collection,
            GRIDCOLHEADERInfo[] colInfos)
    {
        String colWidths = "";
        for (int i=0; i<colInfos.length; i++)
        {
            colWidths += colInfos[i].getWidth();
            colWidths += " ";
        }
        outputMessage(MT_SUCCESS,colWidths);
    }
}

The interface IGRIDCOLHEADERChangeListener passes all events inside the GRIDCOLHEADER controls to the adapter code. You register the interface by using the GRIDCollection's addColHeaderChangeListener method.

In addition, you can set the widths of the columns by your adapter, e.g. you may store column widths inside your application in order to save the user's column settings and later on reapply the width information.

Flexible Column Sorting

The GRIDCOLHEADER allows to bind to a property which is used for sorting. The XML definition of the previous example was extended to demonstrate this:

<rowarea name="Grid Col Header Example">
    <rowtablearea2 griddataprop="lines" rowcount="10" width="100%" withborder="true"
                   hscroll="true" firstrowcolwidths="true">
        <tr>
            <gridcolheader name=" " width="30" propref="selected">
            </gridcolheader>
            <gridcolheader name="First Name" width="150" propref="firstName">
            </gridcolheader>
            <gridcolheader name="Last Name" width="150" propref="lastName">
            </gridcolheader>
            <hdist>
            </hdist>
        </tr>
        <repeat>
            <str valueprop="selected">
                <checkbox valueprop="selected" flush="screen" width="100%" align="center">
                </checkbox>
                <field valueprop="firstName" width="100%" noborder="true"
                       transparentbackground="true">
                </field>
                <field valueprop="lastName" width="100%" noborder="true"
                       transparentbackground="true">
                </field>
                <hdist>
                </hdist>
            </str>
        </repeat>
    </rowtablearea2>
</rowarea>

Each GRIDCOLHEADER control now points to the property that is referenced in the subsequent FIELD/CHECKBOX definition. The control now displays small sort icons. The user can sort the information by choosing the icon. Sorting is done implicitly on the server side, i.e. the order of items inside the collection is changed without any programming effort.

The automated sorting is a feature of the GRID collection object. The sorting is data type aware, i.e. if a property is a string property, then lexical sorting is performed; if it is, for example, an integer or float property, then numeric sorting is performed.

Flexible Column Sequence

Let us have a look at the following grid definition:

<rowtablearea2 griddataprop="lines" rowcount="20" width="100%"
               withborder="true" hscroll="true" firstrowcolwidths="true">
   <tr>
     <label width="25" asheadline="true">
     </label>
     <flexline infoprop="gridheaderline">
     </flexline>
     <hdist>
     </hdist>
   </tr>
   <repeat>
      <str valueprop="selected">
         <selector valueprop="selected">
         </selector>
         <flexline infoprop="/flexInfo">
         </flexline>
         <hdist>
         </hdist>
      </str>
  </repeat>
</rowtablearea2>

You see:

• The ROWTABLEAREA2 definition is set to always follow the column widths of the first row (FIRSTROWCOLWIDTH is set to "true"). The first row of the grid is the row containing the header FLEXLINE control. This means that this row defines the column sizing for the whole grid.

• The header row of the grid is built using a FLEXLINE control. At runtime, we pass GRIDCOLHEADER controls, where each GRIDCOLHEADER control specifies a name and a width.

• The header row is closed with a horizontal distance.This is important: if your column widths do not horizontally fill the grid, then the remaining space is typically equally distributed among the columns. Even if GRIDCOLHEADER specifies a certain width, this may still be overridden by the browser. A horizontal distance control (HDIST) at the end makes the browser assign the remaining space to the distance control, not to the GRIDCOLHEADER controls.

The user can change the sequence of the columns by moving a column header to the position of another header. Example:

Your adapter gets notified by a certain event if the user changes the width of the columns. Have a look at the adapter code:

// This class is a generated one.
package com.softwareag.cis.test40;

import java.util.Hashtable;

import com.softwareag.cis.server.Adapter;
import com.softwareag.cis.server.IDynamicAccess;
import com.softwareag.cis.server.util.FLEXLINEInfo;
import com.softwareag.cis.server.util.GRIDCOLHEADERInfo;
import com.softwareag.cis.server.util.GRIDCollection;
import com.softwareag.cis.server.util.IGRIDCOLHEADERChangeListener;
import com.softwareag.cis.server.util.ISSSARRAYInfo;
import com.softwareag.cis.server.util.MENUNODEInfo;
import com.softwareag.cis.server.util.SelectableLine;
import com.softwareag.cis.server.util.TREECollection;

/**
 * Adapter class for Demo "/cisdemos/35_gridheader.xml/"
 * */
public class GridColHeadersAdapter
    extends Adapter
    implements IGRIDCOLHEADERChangeListener
{
    // -------------------------------------------------------------------------
    // members
    // -------------------------------------------------------------------------

    private GRIDCOLHEADERInfo[] m_gridColHeaderInfos;
    private int s_cellCounter = 1000;
    private String m_columnSortTooltip;
    private String[] m_proprefs = new String[]
    {
           "aaa",
           "bbb",
           "ccc",
           "ddd"
    };
    private String[] m_widths = new String[]
    {
          "25%",
          "25%",
          "25%",
          "25%"
    };
    private String[] m_titles = new String[]
    {
         "AAA",
         "BBB",
         "CCC",
         "DDD"
    };

    // -------------------------------------------------------------------------
    // inner classes
    // -------------------------------------------------------------------------

    /** Represents one line within the grid. The column values of the grid
     * line is kept dynamically (interface IDynamicAccess) - there are
     * no explicit Getter and Setter methods. The definition of the column
     * are kept dynamically, too (FLEXLINEInfo).
     */
    public class Line extends SelectableLine implements IDynamicAccess
    {
        Hashtable m_propertyValues = new Hashtable();


        /** Constructs a grid line that visualizes a person.*/
        public Line(String[] propRefs, String[] widths)
        {
            for (int i = 0; i < propRefs.length; i++)
                m_propertyValues.put(propRefs[i], ""+s_cellCounter--);

            rebuildContentLine(propRefs, widths);
        }

        public void rebuildContentLine(String[] propRefs,
                                       String[] width)
        {
            m_flexInfo.clear();
            for (int i = 0; i < propRefs.length; i++)
                m_flexInfo.addField(GridColHeadersAdapter.this,"valueprop;"+propRefs[i]+";" +
                                    "width;"+width[i]+";" +
                                    "noborder;true;" +
                                     "transparentbackground;true;");
        }

        /** Dynamic person properties */
        public String[] findDynamicAccessProperties()
        {
            return m_proprefs;
        }

        /** Java Datatype */
        public Class getClassForProperty(String property)
        {
            return null; // ==> String
        }
        public Object getPropertyValue(String propertyName)
        {
            return m_propertyValues.get(propertyName);
        }
        public void setPropertyValue(String propertyName, Object value)
        {
            if (value == null) value = "";
            m_propertyValues.put(propertyName, value);
        }
        public void invokeMethod(String methodName)
        {
            // nothing to do
        }
    }

    // -------------------------------------------------------------------------
    // property access
    // -------------------------------------------------------------------------

    // property >gridheaderline<
    FLEXLINEInfo m_gridheaderline = new FLEXLINEInfo();
    public FLEXLINEInfo getGridheaderline() { return m_gridheaderline; }
    public void setGridheaderline(FLEXLINEInfo value) { m_gridheaderline = value; }

    // property >flexInfo<
    FLEXLINEInfo m_flexInfo = new FLEXLINEInfo();
    public FLEXLINEInfo getFlexInfo() { return m_flexInfo; }

    // property >lines<
    GRIDCollection m_lines = new GRIDCollection();
    public GRIDCollection getLines() { return m_lines; }

    // -------------------------------------------------------------------------
    // public methods
    // -------------------------------------------------------------------------

    /** Is called on page load*/
    public void init()
    {
        m_lines.registerGridColHeaderChangeListener(this);
        m_gridColHeaderInfos = new GRIDCOLHEADERInfo[m_proprefs.length];
        for (int i = 0; i < m_proprefs.length; i++)
            m_gridColHeaderInfos[i] =  new GRIDCOLHEADERInfo(i,m_proprefs[i],m_widths[i]);
        for (int i = 0; i < 50; i++)
            m_lines.add(new Line(m_proprefs,m_widths ));
        rearrangeGridColumns(m_gridColHeaderInfos);
    }

    /** Is called when user re-orders columns by drag and drop */
    public void reactOnMove(ISSSARRAYInfo collection, GRIDCOLHEADERInfo[] colInfo)
    {
        rearrangeGridColumns(colInfo);

        // output info
        String info = replaceLiteral("release40","gridcolhead.columnorder");
        for (int i = 0; i < colInfo.length; i++)
        {
            info += replaceLiteral("release40","gridcolhead.column")+colInfo[i].getPropref().toUpperCase();
            if (i != (colInfo.length-1))
                info += ", ";
        }
        outputMessage(MT_SUCCESS, info);
    }

    /** Is called when user re-orders columns by drag and drop */
    public void reactOnResize(ISSSARRAYInfo collection, GRIDCOLHEADERInfo[] colInfo)
    {
        rearrangeGridColumns(colInfo);

        // output info
        String info = replaceLiteral("release40","gridcolhead.columnwidth");
        for (int i = 0; i < colInfo.length; i++)
        {
            info += replaceLiteral("release40","gridcolhead.column")+colInfo[i].getPropref().toUpperCase()+" ("+colInfo[i].getWidth()+")";
            if (i != (colInfo.length-1))
                info += ", ";
        }
        outputMessage(MT_SUCCESS, info);
    }

    /** */
    public void reactOnContextMenuRequest(ISSSARRAYInfo collection, GRIDCOLHEADERInfo colInfo)
    {
    }

    // -------------------------------------------------------------------------
    // private helpers
    // -------------------------------------------------------------------------

    private void rearrangeGridColumns(GRIDCOLHEADERInfo[] colInfo)
    {
        m_gridColHeaderInfos = colInfo;

        // HEADER
        m_gridheaderline.clear();
        for (int i = 0; i < colInfo.length; i++)
            m_gridheaderline.addGridColHeader(this,
                                              m_lines,
                                              "name;"+findTitleForPropRef(colInfo[i].getPropref())+";" +
                                              "width;"+colInfo[i].getWidth()+";" +
                                              "propref;"+colInfo[i].getPropref()+";"+
                                              "sorttitle;"+m_columnSortTooltip);


        // CONTENT
        String[] columns = new String[colInfo.length];
        for (int i = 0; i < columns.length; i++)
            columns[i] = colInfo[i].getPropref();


        String[] witdhs = new String[colInfo.length];
        for (int i = 0; i < columns.length; i++)
            witdhs[i] = colInfo[i].getWidth();

        for (int i=0; i<m_lines.size(); i++)
        {
            Line l = (Line)m_lines.get(i);
            l.rebuildContentLine(columns, witdhs);
        }
    }

    private String findTitleForPropRef(String propRef)
    {
        for (int i = 0; i < m_proprefs.length; i++)
        {
            if (m_proprefs[i].equals(propRef))
                return m_titles[i];
        }
        return ""; // should not happen
    }
}

The interface IGRIDCOLHEADERChangeListener passes all events inside the GRIDCOLHEADER controls to the adapter code. You register the interface by using the GRIDCollection's addColHeaderChangeListener method.

In addition, you can set the sequence of the columns by your adapter, e.g. you may store the column sequence inside your application in order to save the user's column settings and later on reapply the width information.

GRIDCOLHEADER Properties

Smart Selection of Rows - SELECTOR Control

By using the SELECTOR control in combination with the STR control, you can build nice looking grids in which the user can select rows - without effort on the programming side. Have a look at the following screen:

The SELECTOR control is typically is used in the leftmost column. The user can select the control with the mouse or keyboard. In case of using the control for multiple selections, the user can select mulitple rows using a combination of CTRL and click or SHIFT and click.

The SELECTOR control references a boolan property inside a row object that is representing the selection state. The XML layout definition looks as follows:

<rowtablearea2 griddataprop="lines" rowcount="10" width="100%" withborder="true"
               hscroll="true" firstrowcolwidths="true">
     <tr>
         <gridcolheader name=" " width="30" propref="selected">
         </gridcolheader>
         <gridcolheader name="First Name" width="150" propref="firstName">
         </gridcolheader>
         <gridcolheader name="Last Name" width="150" propref="lastName">
         </gridcolheader>
         <hdist>
         </hdist>
     </tr>
     <repeat>
         <str valueprop="selected">
             <selector valueprop="selected" width="30" withlinenum="false"
                       singleselect="false">
             </selector>
             <field valueprop="firstName" width="100%" noborder="true"
                    transparentbackground="true">
             </field>
             <field valueprop="lastName" width="100%" noborder="true"
                    transparentbackground="true">
             </field>
             <hdist>
             </hdist>
         </str>
     </repeat>
</rowtablearea2>

You see the following:

• STR and SELECTOR are referencing the same property selected so that selections done by the SELECTOR control are automatically reflected in the selections of the row.

• SELECTOR is switched to allow multiple selections.

• By using the property withlinenum, you specify that inside the selector no line number is output. Instead, the SELECTOR is left empty if not selected, or it displays an icon if selected.

The selector simplifies programming of the grid selection a lot. When clicking the selector control, it automatically manages the referenced selection property of all rows that are managed inside the corresponding grid collection.

SELECTOR Properties

www.softwareag.com

Copyright © 2005-2013 Software AG, Darmstadt, Germany.

SEARCH   CONTENTS   |   PDF BOOKS   |   HOME   UP   PREV   NEXT