Column Sorting and Formatting Any column of a table can be made sortable by giving it a sortable attribute—as in <display:column sortable="true">. This makes the column title a hyperlink that allows the user to sort the table's data in ascending or descending order. When the HTML for the table is generated, the column's header cell is output as <th class="order1"> (ascending) or <th class="order2"> (descending). This makes it easy to add up or down arrows as CSS background images for the column header.Note that by default, DisplayTag will only sort the data on the currently displayed page (see Page Navigation, below). To change this behavior, you can add a sort.amount=list property to displaytag.properties, as has been done in the sample application. Table data can be formatted by adding a format="Pattern" attribute to the column where you want to apply formatting. The Pattern attribute can be any valid java.text.MessageFormat pattern. For example, <display:column format="{0,date,short}"> would output a date such as November 1st, 2003, in the form 11/1/03 (the actual format is locale-specific in this case). Row Grouping and Subtotals One of DisplayTag's outstanding features is built-in support for row grouping and subtotals. Say you have queried a data source for order details that span a number of different orders and you want to display the results. One problem you are likely to run into is repeating information: consecutive rows representing line items from the same order will have the same customer name, order number, order date, etc. This makes it difficult to see which line items are associated with which orders. DisplayTag will group all rows that contain repeating data in any column that sports a group attribute, as in <display:column group="1">. In the article's sample application, I have set group="1" for the customer column, group="2" for the order number column, and group="3" for the order date column, which results in all three columns being grouped together (see Listing 1). Adding a TotalTableDecorator to a table will cause the values of any column that has a total attribute to be summed up by group and output on a separate row beneath the group. DisplayTag outputs the row with a CSS class of total, making it easy to apply a special style to subtotal rows. To set the table decorator you would use <display:table decorator="org.displaytag.decorator.TotalTableDecorator">. To enable subtotaling in a column, you would use <display:column total="true">. Page Navigation DisplayTag will add page navigation to any table with a pagesize attribute, as in <display:table pagesize="16">. To handle the many cases associated with page navigation—only one page of data, first of many pages, middle of many pages, last of many pages, etc.—DisplayTag provides properties like paging.banner.onepage, paging.banner.first, and paging.banner.full (see Listing 3). To illustrate how these properties are used, consider the following: paging.banner.full=<div class="pagelinks" align="right"><a href={1}><img src="images/first.gif"></a><a href={2}><img src="images/prev.gif"></a>{0}<a href={3} ><img src="images/next.gif"></a><a href={4}><img src="images/last.gif"></a></div>
This rather convoluted property tells DisplayTag to output a banner, similar to that shown in Figure 2, when all paging links are to be displayed.
|
|
Figure 2. Pagelinks: DisplayTagEx's paging banner displays all the paging links. |
A <div> is used here to set the CSS style for the banner to pagelinks. {1} is a placeholder that represents a link to the first page of data. Here it is being used as the target URL for a clickable image. {2}, {3}, and{4} are placeholders for the previous, next, and last pages, respectively. {0} is a special placeholder that outputs links to a set of numbered pages. Exporting Data to Excel, PDF, et al. Getting DisplayTag to export its data to CSV (comma separated value), XML, Excel, PDF, and RTF requires adding a table attribute, setting a number of configuration properties, and creating span styles for each export type. DisplayTag will display an export banner for tables whose export attribute is set—e.g. <display:table export="true">. As with page navigation, there are a large number of export properties to configure. Default properties should be set in the displaytag.properties file. Assuming that you want all of the supported formats to be made available to the user, the properties that are typically modified include export.banner and export.format.filename. For example, in the sample application, I wanted to enforce right alignment and to apply the pagelinks CSS class to the list of export formats. So, in the displaytag.properties file (see Listing 3), I wrote: export.banner=<div class="pagelinks" align="right">{0}</div>
Less obvious here is that when the export banner is rendered, each export format hyperlink is rendered within a <span> whose class is "export format"—e.g. <span class="export excel">. Accordingly, the sample application has a CSS class associated with each format, as in: span.excel {background-image: url(../images/ico_file_excel.png);background-repeat: no-repeat;width: 16px;}
To set the filename of the exported data, modify the export.format.filename properties, as in export.pdf.filename=data.pdf. Javascript Row Handlers My last requirement is for rows to be highlighted as the mouse passes over them and, if the user clicks anywhere on a row, a new request is generated that includes a parameter identifying the row that was clicked. To meet this requirement, I need to throw some JavaScript into the mix. The sample application has a JavaScript file, RowHandlers.js (see Listing 4), with a function called addRowHandlers() that adds three event handlers to each row in an HTML table:
- onmouseover—Saves the row's class attribute and then changes it to a new style that has a different background color or image.
- onmouseout—Restores the previous class attribute.
- onclick—Jumps to a specified URL and includes a request parameter from the selected table row.
To add RowHandlers.js to your JSP:
- Link to the script in the <head> section:
<script src="js/RowHandlers.js" language="javascript" type="text/javascript" /></script>
- Invoke addRowHandlers() in the <body> tag's onload attribute:
<body onload="addRowHandlers('row', 'rowMouseOver', 'OrderDetail.jsp', 'id', 0)">
Step 2 can be translated as: when the body section of the page has loaded, call the function addRowHandlers(), which will add handlers to each row in the table whose id is row. With the handlers in place, when the user moves the mouse over a row its CSS class attribute is changed to rowMouseOver. When the mouse moves out of a row, its CSS class attribute is set back to its original value. If the user clicks on a row, they are sent to OrderDetail.jsp, where the parameter id (whose value is taken from column 0 of the clicked row) is included in the request. In the sample application, OrderDetails.jsp (see Listing 1) uses RowHandlers.js as described above. OrderDetails.jsp also employs a little sleight of hand by placing the row id values in a hidden column. This is accomplished by setting the <display:column>'s class and headerClass attributes to hidden, which is a CSS style whose display property is none. This is a simple but effective method for keeping data available in the request scope without having to display it to the user. DisplayTag is an open-source tag library that makes it easy to display tables of data in JSP's. And its applicability is almost limitless—from search results that require page navigation to product listings that benefit from column sorting to financial reports that can take advantage of numeric formatting, group subtotals, and PDF export. The list goes on and on, and I am sure that you will find uses for it in your own web application. So what's next? Download the sample application and try it out. After that, you can use OrderDetails.jsp as a template for your own dynamic tables. The CSS file, JavaScript file, properties file, and images included in the download can be used as is, or modified as needed to suit the style of your application. |