Jaffa Logo
Home Contact Us FAQs Site Map
Source Forge: Homepage Bugs @ Sourceforge Mailing Lists @ Sourceforge Task Manager @ Sourceforge CVS @ Sourceforge
Jaffa Site
Jaffa Runtime
Jaffa RAD
How To / Use the UserGrid Widget

In Browser

Main UserGrid

Settings Menu


This document explains the basics of how to put a UserGrid widget in a JSP. It also covers adding the code to the FormBean and Action classes, and the configuration parameters that the UserGrid requires.


This example is based on the Jaffa Presentation architecture using JSP's, FormBeans and Action classes. For more information on these topics please see design/overview/presentation


The examples in this document are based on the sample 'UserGrid' component in the HttpUnitTest application in the Jaffa Project.

For an overview of the User Grid widget see design/overview/widgets/user grid

The User Grid Widget is a fully configurable version of the Grid Widget. The widget is based on a single outer tag (UserGrid) and an inner-tag (UserGridColumn) for each of the columns. The UserGrid tag is part of the 'Portlet' Widget tag library. The UserGrid tag, like all other Widgets in this library need to be defined within the scope of a 'Form' tag.

1. The UserGrid Tag

<%@ page language="java" %>
<%@ taglib uri="/WEB-INF/jaffa-portlet.tld" prefix="Portlet" %>
   <Portlet:Form action="/userGrid">
      <Portlet:UserGrid field="sample1" detail="true" userGridId="fred">

The above example shows the following

  • Include the Portlet tag library
  • It is standard to use the <Portlet:Header> tag in the html <head> block
  • Use a <Portlet:Form> tag to tie the JSP to the form bean (via the struts-config.xml file)
  • Use the <Portlet:UserGrid> tag to define the User Grid Widget
  • It is standard to include the <Portlet:RaiseErrors> tag near the end of the JSP
  • It is standard to include the <Portlet:Footer> tag as the end of the html <body> tag

The attributes of the UserGrid tag are as follows

  • field - This is the name of the field in the FormBean that contains the model for the UserGrid widget. The UserGrid widget uses the same Widget Model as the normal Grid widget. This attribute is mandatory.
  • detail - This is a boolean value (true/false) that indicates if the grid should support a 'deatil' event. If 'true' this widget will fire a 'Clicked' event on the Action class. This attribute is optional, the default is false.
  • userGridId - This is the system wide unique name for this user grid. This name will be used for reading and writing default and user layout settings. If two widgets use the same name, they will share the same settings, this may be desirable if the same data is being displayed on different JSPs. This attribute is mandatory.

Defining the Columns

The order of the columns in the JSP is only important if there is no user or default column layout defined. Only in this case does the UserGrid render the columns in the order they are in the JSP. Normally either the user or default grid layout will dictate the column ordering.

A column can contain any regular HTML as well as other Portlet Widgets. The widgets that are supported inside a UserGrid column are Text, Editbox, Button, Dropdown, DateTime, Checkbox, Image and RadioButton. See the relevant How To guides for these other widgets.

An example of some columns

    <Portlet:UserGridColumn label="EditBox-es" dataType="CaseInsensitiveString">
        <ul><li><Portlet:EditBox field="field1" validate="true"/>
        <li><Portlet:EditBox field="field2"/></ul>
    <Portlet:UserGridColumn label="Another instance of an EditBox">
        <Portlet:EditBox field="field2" validate="true"/>
    <Portlet:UserGridColumn label="HTML Text">
        <I>Plain Text</I>
    <Portlet:UserGridColumn label="Button">
        <Portlet:Button field="butt1" label="label for text button" text="true" detail="true"/>

The attributes of the UserGridColumn tag are as follows

  • label - This is the text to be displayed in the column heading. This attribute is mandatory.
  • dataType - This defines the type of data in the column. Possible values are String, CaseInsensitiveString, Number and Date. This attribute is optional. If no value is specified, then this column will not support sorting.

Tying the JSP, FormBean and Action together

The following sections are needed in the struts-config.xml. These are extracts from the HttpUnitTest project

  • In <form-beans>
          <form-bean name="gridForm"
  • In <global-forwards>
    <forward name="gridForm" path="/widgets/tests/grid.jsp"/>
  • In <action-mappings>
          <action path="/grid"

Setting Up UserGrid Properties

There are two configuration entries used by the UserGrid. This are in the framework.properties file in the package org.jaffa.config

These settings control the location of where the Default and User based configuration files for grid layout will be located.

Extract from framework.properties

# The root User location to find the usergrid xml files
# The root Default location to find the usergrid xml files

There will be one xml file used to display the user grid. The name of this file will be UGW_<user-grid-id>.xml. If there is a user based configuration this file will be located in path defined by '' with an additional directory based on the user id. For example if the userGridId='sample1' and the current user is 'Jonny' then this will look for the file 'c:\temp\user_grid\Jonny\UGW_sample1.xml'. If this file can't be located the default one will be used. In this example this will be 'c:\temp\user_grid\DEFAULT\UGW_sample1.xml'.

If either of the above two values are not specified in the properties file the directory returned by System.getProperty("user.home").

The XML Configuration File

The structure of the XML (as defined by the DTD) is...

<!ELEMENT user-grid-settings (grid-width?, user-grid-column-settings*)>
<!ELEMENT grid-width (#PCDATA)>
<!ELEMENT user-grid-column-settings (name, width?)>
<!ELEMENT width (#PCDATA)>

If the user has resized any of the columns then there will be a calculated value for <grid-width>. The order of the <user-grid-column-settings> tags dictate the column ordering. As the <width> tag is also optional, if omitted the browser will automatically size the field based on the overall table width and the widths of the other columns.

Here is an example XML file

<?xml version="1.0" encoding="UTF-8"?>

The FormBean

This is an extract of the code in the form bean needed to support the JSP described above. The code that populates any meaningful content into the GridModel has been removed. This full code can be found in the HttpUnitTest code

package org.jaffa.presentation.portlet.widgets.tests;
import org.jaffa.presentation.portlet.FormBase;
import org.jaffa.presentation.portlet.widgets.model.WidgetModel;
import org.jaffa.presentation.portlet.widgets.model.GridModel;
import org.jaffa.presentation.portlet.widgets.model.GridModelRow;
import org.jaffa.presentation.portlet.widgets.controller.GridController;
public class GridForm extends FormBase {
    public static final String NAME = "gridForm"
    private GridModel w_sample1 = null;
    // **** gridModel cached ****
    public WidgetModel getSample1WM() {
        if (w_sample1 == null) {
            w_sample1 = (GridModel) getWidgetCache().getModel("sample1");
            if (w_sample1 == null) {
                w_sample1 = createNewModel();
                getWidgetCache().addModel("sample1", w_sample1);
        return w_sample1;
    public void setSample1WV(String value) {
        GridController.updateModel(value, (GridModel) getSample1WM(), this);
    private GridModel createNewModel() {
        GridModel model = new GridModel();
        GridModelRow row = model.newRow();
        return model;

The Action class

This is an extract from the action class that will handle the 'row detail' event.

package org.jaffa.presentation.portlet.widgets.tests;
import org.jaffa.presentation.portlet.ActionBase;
import java.io.IOException;
import javax.servlet.ServletException;
import org.jaffa.presentation.portlet.FormKey;
import org.jaffa.presentation.portlet.session.UserSession;
public class GridAction extends ActionBase {
    public FormKey do_Sample1_Clicked(String rowNum)
    throws IOException, ServletException {
        System.out.println("Executing the method 'do_Model1_Clicked'"
            + " with rowNum=" + rowNum);
        // just return to the same screen
        return UserSession.getUserSession(request).getCurrentFormKey();


  • When defining the xml file locations in the framework.properties it is best to use a URL with the file:/// protocol. Although the custom webroot:/// and classpath:/// protocols are supported, if the final url constructed does is not based on the file:/// protocol then it will be possible to read the XML files, but not to write them.

    If on the other had you want to provide default files, and disable users saving there modified versions, you could achieve this if the framework.widgets.usergrid.user.url property is set to a read-only directory.

  • Both the Web Container Based Security and Custom Security Authentication options in Jaffa populate UserSession object and therefore support this widget, since it obtains the 'user id' from the UserSession. It is assumed that this widget will only be used on JSP's within the context of an authenticated session as unauthenticated UserSession have a null userId.

File: usingTheUserGrid.html, Last Modified: Tue Jul 1 2003 at 6:31:24pm. This site has been built using PPWIZARD