Developing an application with the JWL DataGrid using Rational Application Developer

Document options Document options requiring JavaScript are not displayed Discuss Sample code My developerWorks needs you! Connect to your technical community Rate this page Help us improve this content

Level: Introductory

Susan Gallagher (susan.gallagher@ie.ibm.com), Software Engineer, IBM

17 Jan 2006

This article describes the DataGrid component of the JWL (JSF Widget Library) that is available in Rational Application Developer v6.0.0.1. You can use this component and complementary rapid application development tools to build a Web application that allows the user to display and manipulate tabular data. This article explains how to create a rich, interactive, responsive Web application using the DataGrid component.

Introduction

IBM® Faces Client Components are part of the JWL (JavaServer Faces™ Widget Library). They allow you to build a Web application with rich components to display complex arrangements of data. The resulting application is zero footprint, using only HTML, CSS, and JavaScript™. The IBM Faces Client Components are an extension of JavaServer Faces (JSF, JSR 127). The IBM® Rational® Application Developer V6.0.0.1 (IRAD) tooling allows rapid application development with these components using drag and drop operations. Faces Client Components use separate data and components. The application's data is not streamed in place with the markup for the components. A separate set of data and components is defined. The data is streamed as a formal structure to the browser. The data model and instance data can then be updated at runtime on the client. The components are bound to this data at runtime and the content is rendered entirely in the browser. The user can work on the data that is on the client until a roundtrip to the server is really necessary for something like a page refresh. The resulting application will have enhanced performance and interactivity due to a reduced number of roundtrips to the server, longer interaction before page refresh, fast response time, and less bandwidth consumption. This programming model for Web applications is now often referred to as the Ajax pattern and is becoming very popular.

Back to top

Creating an application

The following steps explain how to create an application to use JWL components.

Create a new dynamic Web project in IRAD

1. On the File menu, click New > Dynamic Web Project.
2. Enter the project name in the Name box.
3. Click Finish to create the dynamic Web project.

Create a new JavaServer Page

1. In the new project, right-click the Web Content folder and choose New Faces JSP File.
2. Enter a name for the page in the File Name box.
3. Choose Basic with client-side data caching in the Model drop-down box.
4. Click Finish to add the JavaServer Page™ JSP to the dynamic Web project.

Import bean to use as your data source

1. Download SampleModel.zip at the end of this article.
2. In the new project, right-click the Java Source folder and choose Import.
3. In the Import box, select Zip File from the list of options and click Next.
4. Click the Browse button to locate the SampleModel.zip file that you have just downloaded.
5. Make sure all the folders that appear in the left pane are selected.
6. Click Finish to import the beans into your project.
7. The classes available to your application are structured as shown in Figure 1.

Create page data

1. In the Page Data view, right-click and select New Java Bean.
2. Click on the button beside the Class textfield and type in the name of the root class, Root in this case.
3. Type a name for the bean in the Name textfield.
4. Click Finish to create the Page Data.

Create client data

1. In the Client Data view, right-click and select New Client Data.
2. Choose your Page Data from the list and click OK.
3. Expand the nodes that appear in the Client Data view to see the beans and the properties available to your application.

Add a DataGrid to the page

1. Drag the DataGrid component from the Faces Client Components palette onto your JSP.
2. Expand the nodes in the Client Data view.
3. Choose the Positions array and drag it onto the DataGrid in the JSP.
4. The DataGrid is now bound to the Positions array and will display the records in that array.

Add an Output box to the page

1. Drag the Output component from the Faces Components palette and drop onto your JSP.
2. Expand the nodes in the Client Data view.
3. Choose the Symbol variable from the Positions array and drag and drop onto the DataGrid in the JSP.
4. The DataGrid is now bound to the Symbol variable, and will display the Symbol of the first Position Object in that array.

Run the application on a server

1. Right-click the JSP and choose Run > Run on Server.
2. The JSP page will run in the Web Browser view in IRAD.
3. The DataGrid will display a list of the Positions intialised in the Root bean you imported into the project, as can be seen in Figure 2.
4. The Output box will display the Symbol variable from the first of the Positions intialised in the same Root bean.

Back to top

Customising the DataGrid component

The JWL DataGrid is one of the Faces Client Components. It works on the client-side, allowing the user to sort, filter, scroll, page through, and manipulate data without causing any page refreshes.

When developing a JWL application, you can view the source of the components that you have added to the JSP page. This is available by opening the JSP page in IRAD and switching to the source tab of the JSP. The following is a snippet from the JSP that was created in the previous steps, and shows the source for the DataGrid component.

	<odc:dataGrid allowRowAddAndDelete="false" styleClass="dataGrid"
		showSelectionColumn="false" pageSize="10" id="dataGrid2">

		<odc:clientBinder
			value="#{pc_Page1.myBean.users[0].portfolios[0].positions}">
		</odc:clientBinder>
		
		<odc:dataGridCol
			attributeName="price" readOnly="true">
		</odc:dataGridCol>
		<odc:dataGridCol
			attributeName="purchaseDate" readOnly="true">
		</odc:dataGridCol>
		<odc:dataGridCol
			attributeName="quantity" readOnly="true">
		</odc:dataGridCol>
		<odc:dataGridCol
			attributeName="refNum" readOnly="true">
		</odc:dataGridCol>
		<odc:dataGridCol
			attributeName="symbol" readOnly="true">
		</odc:dataGridCol>
	</odc:dataGrid>
	

Not all the features available in the DataGrid have been used in the example above. The following is a table of all the attributes in the odc:dataGrid tag that are available to customise the DataGrid. They can be changed by editing the Source view, or by using the tools in the Properties view in IRAD.

Back to top

Customising the DataGrid Columns

You can use the Properties view in IRAD to specify the attributes for each column in the DataGrid. Switch to a column by selecting it from the Columns view, or by clicking on a column in the Design view. You can also change the attributes for each column by changing them in the Source view of the JSP in IRAD.

The following is a code snippet from the JSP that was created in the previous steps, and shows the tags created for all the DataGrid columns.

	<odc:dataGridCol
		attributeName="price" readOnly="true">
	</odc:dataGridCol>
	<odc:dataGridCol
		attributeName="purchaseDate" readOnly="true">
	</odc:dataGridCol>
	<odc:dataGridCol
		attributeName="quantity" readOnly="true">
	</odc:dataGridCol>
	<odc:dataGridCol
		attributeName="refNum" readOnly="true">
	</odc:dataGridCol>
	<odc:dataGridCol
		attributeName="symbol" readOnly="true">
	</odc:dataGridCol>

Not all the features available for the DataGrid Columns have been used in the example above. The following is a table of all the attributes in the odc:dataGridCol tag that are available to customise the DataGrid columns. They can be changed by editing the Source view, or by using the tools in the Properties view in IRAD.

Back to top

DataGrid events

The JWL allows you to create various handlers for component events. There are ten events defined for the DataGrid. There are two types of event handler that can be used directly through the tooling, or you can write custom handlers to manipulate the controls. I will explain the two handlers that are available, and also how to create a custom handler.

SelectAndActivate handler

All the controls on a page are automatically linked if they have been bound to the same client data. An update to data in one control will immediately be reflected in the other controls without a page refresh or roundtrip to the server. With this handler, however, you can configure the DataGrid so an event can alter to which data another control is bound. For example, highlighting a row in a DataGrid of Position Objects can change which Position Object an Output box is bound to and displays. The SelectAndActivate handler allows you to set a selected Object as the root in a target component. In this case, the Position Object was selected and the Output box is the target component.

Add a SelectAndActivate Event Handler to the DataGrid using IRAD tooling

1. In the JSP Design view, select the DataGrid and then open the QuickEdit view.
2. Click on the Highlight event, which will trigger the SelectAndActivate Event Handler when the user highlights a row in the DataGrid.
3. In the Code Snippet area, right-click and choose Insert Snippet > Set selected object as root in target component.
4. In the Source Object dropdown box, choose the Position Object.
5. In the Target components dropdown box, choose the Output box which you added to your application earlier and bound to Symbol from the Position Object.
6. The Output box will display the Symbol from the Position Object in a DataGrid row when that row is highlighted.

SelectAndSet handler

The other standard event handler binds the selected Object to another Object. This may seem similar to SelectAndActivate, but with SelectAndSet the selected Object in the source control is bound to an Object in the data model, rather than a specific control. Any control which is bound to this target Object will have its contents changed. This has the benefit that controls are not coupled. The downside is that a conduit Object is needed in the model. The conduit Object is a placeholder Object which is added to the model for this purpose only. The result of a event triggers the SelectAndSet handler to populate the conduit Object. Other components on the page are bound to the conduit Object and the values they display change when the value of the conduit Object changes.

Add a SelectAndSet Event Handler to the DataGrid using IRAD tooling

1. In the JSP Design view, select the DataGrid and then open the QuickEdit view.
2. Click the Select event that will trigger the SelectAndSet Event Handler.
3. In the Code Snippet area, right-click and choose Insert Snippet > Bind selected object to another object.
4. In the Source Object dropdown box, choose the Position Object.
5. Click on the icon beside the Bind To box to choose the Object you wish to bind the source Object to when the event is triggered.
6. The display will be updated for every component that is bound to this target Object when the event is triggered.

Custom handler

You can write your own custom handler that can also be used for any of the ten events defined for the DataGrid. Any piece of JavaScript™ code can be used. The most common types of handler written for JWL components use the EObject APIs to gain more information about the component that has had an event triggered.

Add a custom event handler to the DataGrid using IRAD tooling

1. In the JSP Design view select the DataGrid and then open the QuickEdit view.
2. Click the Select event that will trigger your Custom Event Handler.
3. In the Code Snippet area, enter the JavaScript you want executed when the event is triggered.
4. This example uses JavaScript code to display an alert box containing details of the selected row when the event is triggered.

This will appear as follows in the Source view of the JSP. The odc:dataGrid tag is updated to include an attribute for the new event that calls func_1 when the event is triggered.

	
	<odc:dataGrid allowRowAddAndDelete="false" styleClass="dataGrid"
	showSelectionColumn="false" pageSize="10" id="dataGrid1" 
	onhighlight="return func_1(this, event);">

The code snippet that the user wrote is added as a function within a SCRIPT tag in the HEAD tag of the JSP.

	
	<SCRIPT type="text/javascript">
	function func_1(thisObj, thisEvent) {
		//use 'thisObj' to refer directly to this component instead of keyword this
		//use 'thisEvent' to refer to the event generated instead of keyword event
		//thisEvent.eobject is the object mapped to the currently highlighted row.
		alert("We highlighted the row:"+ thisEvent.eobject.eGet('price')+ 
		thisEvent.eobject.eGet('purchaseDate')+ thisEvent.eobject.eGet('quantity')
		+ thisEvent.eobject.eGet('symbol') + thisEvent.eobject.eGet('refNum'));
	}
	</SCRIPT>

Figure 3 shows the results of this custom event handler being triggered in your application.

The following is a table of event tags available to customise the DataGrid.

Back to top

Summary

This article described the JWL DataGrid component. The article explains how to build a dynamic Web application using the JWL DataGrid, and how to customise the DataGrid. It also explains how to add events to the DataGrid component.

Back to top

Download

	Information about download methods

Resources

• Faces Client Component Developer Guide is a comprehensive guide to using Faces Client Components.
  
  
• The JWL Community Source Site contains forums, bug tracker feature requests etc for the JWL. You must be register to view this site.
  
  
• The JWL Component Catalog is available to those registered to view the JWL Community Source Site.
  
  
• Eclipse.org: For information about Eclipse development.
  
  
• IBM Rational Application Developer product page: Find technical documentation, how-to articles, education, downloads, and product information about Rational Application Developer.
  
  

• IBM Rational Application Developer: Download a trial version from developerWorks.
  
  

• Participate in the discussion forum.
  
  
• Rational Software Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about Rational Application Developer.

About the author

		Susan Gallagher works at the IBM Dublin Software Lab. She graduated with a BSc. in Computer Applications from Dublin City University in 2002, and is a Sun-Certified Java Developer. She is currently a member of the JWL (JSF Widget Library) team, developing the DataGrid component. You can reach Susan at susan.gallagher@ie.ibm.com

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top