Datagrid tutorial

Introduction

The Struts-Layout datagrid framework allow to easily display a list of objects and modify them. The datagrid features are:

  • lines editing,
  • addition of new lines without server request,
  • single / multiple line selection,
  • modification of the state of the selected lines
  • association of a css class to each possible state
  • initialization of the selected lines and states with the datagrid Java API
  • Java API enabling to get the modified lines, the added lines, the removed lines and the lines with a specific state
  • Works with any object class (BeanUtils is used)

Creating a datagrid

Here are the required steps to create a datagrid:

  • A Struts form bean must be defined
  • A property of type fr.improve.struts.taglib.layout.datagrid.Datagrid must be added to the Struts form
  • A Struts Action must be created to define the datagrid. The action must be associated with the previous form, and the form must be putted in the session scope
  • The Struts action must initialize the datagrid form property to a new Datagrid object
  • The object list and type must be set to the Datagrid object
  • The jsp file displaying the datagrid must use the defined Struts form bean
  • The tag <layout:datagrid> must be used to display the datagrid. This tag must be nested in a <layout:from> or a <html:form> tag
  • The tag <layout:datagridColumn> must be used to specify the different columns of the datagrid. This tag must be nested in the <layout:datagrid> tag

Creating the Struts form bean

The Struts form bean must contain a Datagrid object :

 1package com.foo.datagrid;
 2
 3import org.apache.struts.action.ActionForm;
 4import fr.improve.struts.taglib.layout.datagrid.Datagrid;
 5
 6public class DatagridForm extends ActionForm {
 7    private Datagrid datagrid;
 8
 9    public void setDatagrid(Datagrid in_datagrid) {
10        datagrid = in_datagrid;
11    }
12    public Datagrid getDatagrid() {
13        return datagrid;
14    }
15}

Creating the Struts action displaying the data

The action which will display the datagrid should create a new Datagrid, and initialize the form. Here is an exemple:

 1package com.foo.datagrid;
 2
 3import javax.servlet.http.HttpServletRequest;
 4import javax.servlet.http.HttpServletResponse;
 5
 6import org.apache.struts.action.ActionForm;
 7import org.apache.struts.action.ActionForward;
 8import org.apache.struts.action.ActionMapping;
 9
10import org.apache.struts.actions.DispatchAction;
11
12import fr.improve.struts.taglib.layout.datagrid.Datagrid;
13
14public class DatagridAction extends DispatchAction {
15
16    public ActionForward display(ActionMapping in_mapping, ActionForm in_form, HttpServletRequest in_request, HttpServletResponse in_reponse) {    
17        DatagridForm lc_form = (DatagridForm) in_form;
18
19        // Get an object list.
20        List aList = getAListFromSomewhere();
21
22        // Create a datagrid.
23        Datagrid lc_datagrid = Datagrid.getInstance();
24
25        // Set the bean class for new objects. We suppose SomeBean is the class of the object in the List aList.
26        lc_datagrid.setDataClass(SomeBean.class);
27
28        // Set the data
29        lc_datagrid.setData(aList);
30
31        // Initialize the form
32        lc_form.setDatagrid(lc_datagrid);
33
34        // Forward to the jsp.
35        return in_mapping.findForward("jsp");
36    }
37
38    ...
39
40}

Declaring the form and the action in struts-config.xml

Next step is to declare the from and the action in struts-config. Here is how to do this:

 1<struts-config>
 2    ...
 3    <form-beans>
 4        <form-bean name="datagridForm" type="com.foo.datagrid.DataGridForm"/>
 5        ...
 6    </form-beans>
 7
 8    <action-mappings>
 9        <action path="/datagrid" 
10                name="datagridForm" 
11                type="com.foo.datagrid.DatagridAction" 
12                validate="false" 
13                parameter="reqCode" 
14                scope="session">
15            <forward name="jsp" path="/datagrid.jsp"/>
16        </action>
17        ...
18    </action-mappings>
19    ...
20</struts-config>            

Displaying the datagrid

In the following jsp, the datagrid, datagridColumn and form tags are used to display the datagrid.

The attribute "property" of the datagrid tag specify the name of the form bean property holding the datagrid object.

The beans in the datagrid have two properties "fournisseur" and "voyageur".

 1<%@ taglib uri="/WEB-INF/struts-layout.tld" prefix="layout" %>
 2<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %>
 3<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %>
 4
 5<layout:html>
 6    <layout:form action="/datagrid"  reqCode="update" styleClass="PANEL">
 7    <layout:row>
 8        <layout:datagrid property="datagrid" selectionAllowed="true" multipleSelectionAllowed="false" model="datagrid">
 9            <layout:datagridColumn title="Fournisseur" property="fournisseur"/>
10            <layout:datagridColumn title="Voyageur" property="voyageur"/>            
11        </layout:datagrid>
12
13        <layout:column>
14            <layout:submit reqCode="update" >Save</layout:submit>
15        </layout:column>
16    </layout:row>
17    </layout:form>
18</layout:html>

Note that the configured struts-layout collection renderer must implement the fr.improve.struts.taglib.layout.util.IDatagridRenderer interface. Struts-Layout comes with a default implementation : fr.improve.struts.taglib.layout.util.BasicDatagrid that can be used by adding model="datagrid" to the <layout:datagrid> tag.

Adding new item

To enable the user to add new items in the datagrid, a button calling the StrutsLayout.addDatagridLine js function must be added. This function requires the name of the form bean property holding the datagrid as first parameter.

1...
2<layout:column>
3    <layout:button onclick="StrutsLayout.addDatagridLine('datagrid')">Add</layout:button>
4    <layout:submit reqCode="update" >Save</layout:submit>    
5</layout:column>
6...        

Modifying item state

To enable the user to change the state of the selected items, a button calling the StrutsLayout.setDatagirdLineState js function must be added. This function requires two parameters:

  • the name of the form bean property holding the datagrid
  • the new state name
1...
2<layout:column>
3    <layout:button onclick="StrutsLayout.addDatagridLine('datagrid')">Add</layout:button>
4    <layout:button onclick="StrutsLayout.setDatagridLineState('datagrid', 'removed')">Remove</layout:button>
5    <layout:submit reqCode="update" >Save</layout:submit>    
6</layout:column>
7...

Getting the updated data

When the form is submitted, the data in the datagrid are updated, and it is possible to get the modified, added and removed data by using the Datagrid API:

 1...
 2public class DatagridAction extends DispatchAction {
 3    ...
 4
 5    public ActionForward update(ActionMapping in_mapping, ActionForm in_form, HttpServletRequest in_request, HttpServletResponse in_reponse) {
 6        // Cast the form.
 7        DatagridForm lc_form = (DatagridForm) in_form;
 8
 9        // Get the datagrid object.
10        Datagrid lc_datagrid = lc_form.getDatagrid();
11
12        // Get the modified objects.
13        Collection lc_modifiedObjects = lc_datagrid.getModifiedData();
14
15        // Get the removed objects.
16        Collection lc_removedObjects = lc_datagrid.getDeletedData();
17
18        // Get the added objects.
19        Collection lc_addedObjects = lc_datagrid.getAddedData();
20
21        // Get the selected objects.
22        Collection lc_selectedObjects = lc_datagrid.getSelectedData();
23
24        // Do something.
25        ...
26    }    
27
28}