You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by ek...@apache.org on 2005/08/10 22:17:37 UTC
svn commit: r231311 -
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/pageflow_datagrid.xml
Author: ekoneil
Date: Wed Aug 10 13:17:35 2005
New Revision: 231311
URL: http://svn.apache.org/viewcvs?rev=231311&view=rev
Log:
Adding documentation for the NetUI Data Grid.
BB: self
DRT: cd docs/forrest/ && ant build.release
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/pageflow_datagrid.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/pageflow_datagrid.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/pageflow_datagrid.xml?rev=231311&r1=231310&r2=231311&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/pageflow_datagrid.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/pageflow/pageflow_datagrid.xml Wed Aug 10 13:17:35 2005
@@ -2,1007 +2,135 @@
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
<header>
- <title>Displaying Data Sets with Data Grids</title>
+ <title>Beehive NetUI Data Grids</title>
</header>
<body>
- <section id="database_driven">
- <title>Database-Driven Web Applications</title>
- <p>A database-driven Beehive web application has the the follow components:
- </p>
- <ul>
- <li>one or more page flows (= a controller file + JSP pages)</li>
- <li>one or more database control files</li>
- <li>one or more databases</li>
- </ul>
- <p>A basic schema for a database-driven application is shown below.</p>
- <p><img src="images/pageflow_database_app_1.png" alt="pageflow_database"/></p>
- <p><strong>The Database</strong></p>
- <p>The role of the database is as a storehouse for the data. The database persists
- the data from session to session and is the common object that users view and
- operate upon.</p>
- <p><strong>The Database Control</strong></p>
- <p>The database control handles the data traffic with the database. The database
- control is a Java class that handles the database connection and handles the individual
- operations on the database. Typically, the methods in the class have associated
- SQL statements: when a method is called, the associated SQL statement is sent to the
- database. Any data returned by the database is transformed by the method
- into an appropriate Java object so it is available to the rest of the web
- application.</p>
- <!--<p>For more database control implementations you can download and use in applications,
- see <a href="site:db-sample">Database Control Sample</a></p>-->
-
- <p><strong>The Page Flow</strong></p>
- <p>The Page Flow(s) form the front-end user interface of the application.
- Through
- the JSP pages, users can interact with the data in the database, by
- adding, deleting, and updating the data.</p>
- <section class="rendering_complex_data_sets"><title>Rendering Complex Data Sets as HTML</title>
- <p>Beehive provides a specialized tag library for viewing and managing
- the complex data sets associated with database applications:
- <a href="../apidocs/taglib/taglib-overview-summary.html#netui-data"><code><netui-data:xxx></code></a>.
- The central HTML-rendering tags are</p>
- <ul>
- <li><a href="../apidocs/taglib/beehive.apache.org/netui/tags-databinding-1.0/dataGrid.html"><netui-data:dataGrid></a></li>
- <li><a href="../apidocs/taglib/beehive.apache.org/netui/tags-databinding-1.0/repeater.html"><netui-data:repeater</a></li>
- </ul>
- <p>The <netui-data:dataGrid> tag is specifically for rendering HTML tables.</p>
- <p>The <netui-data:repeater> tag is for more general HTML rendering, including HTML tables, lists, and other shapes.</p>
- <p>These tags are capable of rendering the following
- Java objects into HTML: ArrayList, StringArray, RowSet, ResultSet, Vector, XMLBean, and others.</p>
- <p>The tags work by iterating over of the data set, and rendering HTML for each iteration.</p>
- <p>To render data, you pass the data set into the tag's <code>dataSource</code> attribute.</p>
- <source><netui-data:dataGrid name="myGrid" <strong>dataSource="someDatabindingContext.someDataSet"</strong>>
- ...
-</netui-data:dataGrid></source>
-<p>The tag then analyzes and iterates over the data set, rendering HTML as it goes.</p>
- <p>The remainder of this topic concentrates on using the <netui-data:xxx>
- tab library to handle data sets.</p>
- </section>
- </section>
- <section id="rendering_data_sets"><title>Rendering Data Sets as HTML Tables</title>
- <section id="what_objects_rendered"><title>What Objects Can Be Rendered?</title>
- <p>The data grid can render any of the following data structures as an HTML table.
- (The basic rule of thumb is: If you can iterate over the structure, the
- data grid can render it.)</p>
- <ul>
- <li>any subinterface or implementation of java.util.Collection, including List, Set,
- SortedSet, ArrayList, HashSet, Vector, etc.</li>
- <li>java.util.ResultSet</li>
- <li>java.util.RowSet</li>
- <li>Object[]</li>
- <li>any XMLBean structure</li>
- </ul>
- </section>
- <section id="how_objects_rendered"><title>How are Objects Rendered?</title>
- <p>The data sets above are rendered as multiple rows in an HTML table; a single
- object in the set is rendered as a single row.</p>
- <p>The properties of an object can be rendered as the cells of a single row.</p>
- <p>The HTML table has the following basic parts:</p>
- <table>
- <tr>
- <td><strong>Region Name</strong>
- </td>
- <td><strong>JSP tag</strong>
- </td>
- <td><strong>Rendered HTML Element</strong>
- </td>
- <td><strong>Renders</strong>
- </td>
- <td><strong>Required</strong>
- </td>
- </tr>
- <tr>
- <td>Caption
- </td>
- <td><netui-data:caption>
- </td>
- <td><caption>
- </td>
- <td>exactly once
- </td>
- <td>no
- </td>
- </tr>
- <tr>
- <td>Header
- </td>
- <td><netui-data:header>
- </td>
- <td><thead>
- </td>
- <td>exactly once
- </td>
- <td>no
- </td>
- </tr>
- <tr>
- <td>Data
- </td>
- <td><netui-data:rows>
- </td>
- <td><tbody>
- </td>
- <td>once per row of data in the page
- </td>
- <td>no
- </td>
- </tr>
- <tr>
- <td>Footer
- </td>
- <td><netui-data:footer>
- </td>
- <td><tfoot>
- </td>
- <td>exactly once
- </td>
- <td>no
- </td>
- </tr>
-</table>
- <p>The main body of the data grid (the section that renders inside the
- <netui-data:rows> tags) can contain the following different kinds
- of columns.</p>
- <table>
- <tr>
- <td><strong>JSP Tag</strong>
- </td>
- <td><strong>Rendered HTML Cell type</strong>
- </td>
- <td><strong>Rendered HTML Content Type</strong>
- </td>
- </tr>
- <tr>
- <td><netui-data:headerCell>
- </td>
- <td><th>
- </td>
- <td><span>
- </td>
- </tr>
- <tr>
- <td><netui-data:anchorCell>
- </td>
- <td><td>
- </td>
- <td><a>
- </td>
- </tr>
- <tr>
- <td><netui-data:imageAnchorCell
- </td>
- <td><td>
- </td>
- <td><a><img/></a>
- </td>
- </tr>
- <tr>
- <td><netui-data:imageCell>
- </td>
- <td><td>
- </td>
- <td><img/>
- </td>
- </tr>
- <tr>
- <td><netui-data:spanCell>
- </td>
- <td><td>
- </td>
- <td><span>
- </td>
- </tr>
- <tr>
- <td><netui-data:templateCell>
- </td>
- <td><td>
- </td>
- <td>None. Template cell
-contents are specified by the developer</td>
- </tr>
- </table>
- </section>
- <section id="css"><title>CSS Styles for Data Grids</title>
- <p>The data grid supports two modes for rendering CSS styles: "default" and "empty".</p>
- <p>Under the default mode, a CSS style prefix is prepended to a standard set of CSS
- style names (see table below). There are different CSS style names for
- different parts of the rendered HTML. The CSS style used is controlled by writing
- different prepending prefixes into the HTML.</p>
- <p>The prefix is controlled by setting the <code>styleClassPrefix</code> attribute
- of the <netui-data:dataGrid> tag.</p>
- <source><netui-data:dataGrid styleClassPrefix="myStyle"/></source>
- <p>If no prefix is specified, the default prefix is "<code>datagrid</code>".</p>
- <p>Under the empty mode, no prefixes are written into the HTML.</p>
- <p>The style mode used can be switched by setting the <code>styleClassPolicy</code>
- attribute on the <netui-data:dataGrid> tag.</p>
- <source><netui-data:dataGrid styleClassPolicy="empty"/></source>
- <p>The following table shows the standard CSS style names written into the HTML under
- both the default and standard modes, where <prefix> is the value of the
- <code>styleClassPrefix</code> attribute.</p>
- <table>
- <tr>
- <td><strong>Grid Component</strong>
- </td>
- <td><strong>Default Style Name</strong>
- </td>
- <td><strong>Empty Style Name</strong>
-
- </td>
- </tr>
- <tr>
- <td>Caption<br/>
- </td>
- <td><prefix></td>
- <td>""<br/>
-
- </td>
- </tr>
- <tr>
- <td>Header Row<br/>
- </td>
- <td><prefix>-header<br/>
- </td>
-
- <td>header<br/>
- </td>
- </tr>
- <tr>
- <td>Header Cells<br/>
- </td>
- <td><prefix></td>
-
- <td>""<br/>
- </td>
- </tr>
- <tr>
- <td>Header Cell Sortable<br/>
- </td>
- <td><prefix>-sortable</td>
-
- <td>sortable<br/>
- </td>
- </tr>
- <tr>
- <td>Header Cell Sorted<br/>
- </td>
- <td><prefix>-sorted</td>
-
- <td>sorted<br/>
- </td>
- </tr>
- <tr>
- <td>Data Row <br/>
- </td>
- <td><prefix>-even</td>
-
- <td>even<br/>
- </td>
- </tr>
- <tr>
- <td>Data Row Alternating<br/>
- </td>
- <td><prefix>-odd</td>
-
- <td>odd<br/>
- </td>
- </tr>
- <tr>
- <td>Data Cell<br/>
- </td>
- <td><prefix></td>
-
- <td>""<br/>
- </td>
- </tr>
- <tr>
- <td>Data Cell Sorted<br/>
- </td>
- <td><prefix>-sorted</td>
-
- <td>sorted<br/>
- </td>
- </tr>
- <tr>
- <td>Footer Row<br/>
- </td>
- <td><prefix>-footer</td>
-
- <td>footer<br/>
- </td>
- </tr>
- <tr>
- <td>Table<br/>
- </td>
- <td><prefix><br/>
- </td>
- <td>""<br/>
- </td>
- </tr>
-</table>
- <p>When writing a CSS file for the data grid, the style names should appear as follows:</p>
- <source>tr.datagrid-header{ ... }</source>
- <p>Of, if <code>datagrid</code> is replaced with <code><prefix></code>, then:</p>
- <source>tr.<prefix>-header{ ... }</source>
- </section>
- <section><title>Data Grid Properties File</title>
- <p>The data grid tags are configurable through a <code>.properties</code> file.
- The <code>.properties</code> file is referenced by
- the "<code>resourceBundlePath</code>" attribute on the
- <code><netui-data:dataGrid></code> tag.</p>
-
- <p>The <code>.properties</code> file is compiled (into a MessageResources object)
- and is referenced by its fully qualified class name.</p>
-
- <p>That is, if the file is located at:</p>
-
- <source>WEB-INF/src/<strong>datagrid/grid</strong>.properties</source>
-
- <p>Then the <code><netui-data:dataGrid></code> tag references it as follows:</p>
-
- <source><netui-data:dataGrid resourceBundlePath="<strong>datagrid.grid</strong>"></source>
-
- <p>The referenced <code>.properties</code> file is used to obtain internationalized
- strings, image names, and patterns that are used during data grid
- rendering.</p>
- <p>There are a set of default property values specified
- in the <code>data-grid-default.properties</code> file in the
- <code>beehive-netui-databinding.jar</code>
- file. </p>
-
- <p>The contents of the <code>data-grid-default.properties</code> file appears below.</p>
-
- <source>datagrid.resource.path=resources/images
-datagrid.msg.nodata=No data to display
-
-sort.asc.img=/sortdown.gif
-sort.desc.img=/sortup.gif
-sort.none.img=/sortable.gif
-
-pager.msg.first=First
-pager.msg.previous=Previous
-pager.msg.next=Next
-pager.msg.last=Last
-pager.fmt.banner=Page {0} of {1}</source>
-
- <p>These values can be overridden in one of two ways:</p>
- <ul>
- <li>by setting the <code>resourceBundlePath</code>
- on the <netui-data:dataGrid> tag
- <source><netui-data:dataGrid resourceBundlePath="datagrid.grid"/></source></li>
-
- <li>by using the <code><netui:attribute></code> tag
- with the <code>resource</code> facet to
- override the properties defined in either the default resource
- bundle or the user-provided
- <code>.properties</code> file using the
- <code>resourceBundlePath</code>.</li>
- </ul>
- <p>Developer specified attributes provided by an <code><netui:attribute></code> tag
- will override the values set in both the default and user-defined
- <code>.properties</code> files. For example, to
- override the text used for the "First" page in a pager, use:</p>
-
- <source><netui:attribute facet="resource" name="pager.msg.first" value="My First Page"/></source>
- </section>
- </section>
- <section id="setup_basic_grid"><title>Setting Up a Basic Grid</title>
- <p>This section takes you through a step by step process of setting up a basic grid
- for 'tabular' data, data such as a ResultSet, RowSet, or any kind of data
- that can easily be set out like table with rows and columns.
- </p>
- <section id="setup_netui-blank"><title>Setup the Page Flow Web App Template</title>
- <p>To set up a grid you first need a source of some tabular data.
- Below we use an in-memory ArrayList as the source
- of tabular data. In a real web application, this data source would
- come from a database, but the in-memory source is sufficient for learning
- how to render a data grid.</p>
- <p>In these setup instructions, we assume that you are using Tomcat as your web
- application container.</p>
- <p> Begin by copying the folder BEEHIVE_HOME/samples/netui-blank into
- CATALINA_HOME/webapps.
- </p>
- <p>Rename the folder <strong>netui-blank</strong> to the name <strong>gridSample</strong>.</p>
- </section>
- <section id="setup_datasource"><title>Create an In-Memory Data Source</title>
- <p>Now that the Page Flow template is set up, we are ready to create a
- data object (i.e., an ArrayList) suitable for rendering as a data grid.</p>
- <p><strong>Edit the Controller class</strong></p>
- <p>Edit the
- file <code>gridSample/Controller.java</code> as
- follows. Code to edit is shown in bold.</p>
- <p><strong><code>gridSample/Controller.java</code></strong></p>
-<source>import javax.servlet.http.HttpSession;
-
-import org.apache.beehive.netui.pageflow.Forward;
-import org.apache.beehive.netui.pageflow.PageFlowController;
-import org.apache.beehive.netui.pageflow.annotations.Jpf;
-
-@Jpf.Controller(
- simpleActions={
- @Jpf.SimpleAction(name="begin", path="index.jsp")
- },
- sharedFlowRefs={
- @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class)
- }
-)
-public class Controller
- extends PageFlowController
-{
- @Jpf.SharedFlowField(name="shared")
- private shared.SharedFlow sharedFlow;
-
- <strong>public java.util.ArrayList pets = new ArrayList();</strong>
-
- /**
- * Callback that is invoked when this controller instance is created.
- */
- protected void onCreate()
- {<strong>
- // build the pets ArrayList
-
- PetType pet1 = new PetType(1, "American Tabby", "Cat", 20.00);
- PetType pet2 = new PetType(2, "Short Haired", "Cat", 20.00);
- PetType pet3 = new PetType(3, "Long Haired", "Cat", 20.00);
- PetType pet4 = new PetType(4, "Blue Russian", "Cat", 80.00);
- PetType pet5 = new PetType(5, "Pixy Bob", "Cat", 20.00);
- PetType pet6 = new PetType(6, "Siamese", "Cat", 80.00);
- PetType pet7 = new PetType(7, "Minx", "Cat", 20.00);
- PetType pet8 = new PetType(8, "Bull Mastif", "Dog", 350.00);
- PetType pet9 = new PetType(9, "Dalmatian", "Dog", 20.00);
-
- pets.add(pet1);
- pets.add(pet2);
- pets.add(pet3);
- pets.add(pet4);
- pets.add(pet5);
- pets.add(pet6);
- pets.add(pet7);
- pets.add(pet8);
- pets.add(pet9);</strong>
- }
-
- /**
- * Callback that is invoked when this controller instance is destroyed.
- */
- protected void onDestroy(HttpSession session)
- {
- }
-
- <strong>// PetType Bean
- public class PetType
- {
-
- private int petID;
- private String name;
- private String description;
- private double price;
-
- public PetType() {}
-
- public PetType(int petID, String name, String description, double price) {
- this.petID= petID;
- this.name = name;
- this.description = description;
- this.price = price;
- }
-
- public int getPetID() {return petID;}
- public String getName() {return name;}
- public String getDescription() {return description;}
- public double getPrice() {return price;}
- }</strong>
-}</source>
- <p>You now have an in-memory data source of tabular data.
- In the next step you will
- point a data grid at this data to render it as HTML. </p>
- <p><strong>Compile the Page Flow Web App Template</strong></p>
- <p>Before proceeding, you should compile the web app.</p>
- <p>The compile step is necessary
- because you have modified the Controller.java file. In the steps below,
- where you only modify the JSP page <code>index.jsp</code>,
- you will *not* need to recompile the app to view your changes.</p>
- <p>To compile, edit the properties (1) <code>beehive.home</code>
- and (2) <code>contextPath</code> in the
- file <code>gridSample/WEB-INF/src/build.properties</code>, for example:</p>
- <source>beehive.home=C:/apache/apache-beehive-1.0
-contextPath=gridSample</source>
- <p>Then enter the following Ant command:</p>
- <source>ant -f %CATALINA_HOME%\webapps\gridSample\WEB-INF\src\build.xml clean build</source>
- </section>
- <section id="basic_grid"><title>Render a Basic Data Grid</title>
- <p>Edit <code>gridSample/index.jsp</code> so it appears as follows.</p>
- <p><strong><code>gridSample/index.jsp</code></strong></p>
- <source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%>
-<netui:html>
- <head>
- <title><strong>Data Grid</strong></title>
- <netui:base/>
- </head>
- <netui:body>
-<strong> <netui-data:dataGrid dataSource="pageFlow.pets" name="petGrid">
+<section id="overview">
+ <title>Overview</title>
+ <p>
+The NetUI data grid tag library is a high-level abstraction for rendering grids of data in an HTML. This tag library
+supports rendering uses from simple tables to complex sortable, filterable, pageable, and updatable grids of data. The
+<a href="../apidocs/taglib/beehive.apache.org/netui/tags-databinding-1.0/dataGrid.html"><netui-data:dataGrid></a> is
+part of NetUI's <a href="../apidocs/taglib/taglib-overview-summary.html#netui-data"><code><netui-data:xxx></code></a> tag
+library.
+ </p>
+</section>
+<section id="simple">
+ <title>A Simple Data Grid</title>
+<p>
+The simplest data grid will render a List of JavaBeans into a basic HTML table. Such a grid might look like:
+</p>
+ <source>
+ <netui-data:dataGrid dataSource="pageScope.pets" name="petGrid">
<netui-data:rows>
- <netui-data:spanCell value="${container.item.petID}" />
- <netui-data:spanCell value="${container.item.name}" />
- <netui-data:spanCell value="${container.item.description}"/>
- <netui-data:spanCell value="${container.item.price}"/>
- </netui-data:rows>
- </netui-data:dataGrid></strong>
- </netui:body>
-</netui:html></source>
-<p>When you visit the URL</p>
-<source>http://localhost:8080/gridSample/</source>
-<p>you should see the following page</p>
-<figure alt="categoryGrid1" src="images/categoryGrid1.gif"/>
- <p>The tabular data is rendered as an HTML table, by the remaining tags
- (<netui-data:rows> and <netui-data:spanCell). <!--[todo: more description here]--></p>
-<p>Here is the renderd HTML table.</p>
-<source> Page 1 of 1
-<table class="datagrid">
-<tr class="datagrid-even">
- <td class="datagrid"><span>1</span></td>
- <td class="datagrid"><span>American Tabby</span></td>
- <td class="datagrid"><span>Cat</span></td>
- <td class="datagrid"><span>20.0</span></td>
-</tr>
-<tr class="datagrid-odd">
- <td class="datagrid"><span>2</span></td>
- <td class="datagrid"><span>Short Haired</span></td>
- <td class="datagrid"><span>Cat</span></td>
- <td class="datagrid"><span>20.0</span></td>
-</tr>
-<tr class="datagrid-even">
- <td class="datagrid"><span>3</span></td>
- <td class="datagrid"><span>Long Haired</span></td>
- <td class="datagrid"><span>Cat</span></td>
- <td class="datagrid"><span>20.0</span></td>
-</tr>
-<tr class="datagrid-odd">
- <td class="datagrid"><span>4</span></td>
- <td class="datagrid"><span>Blue Russian</span></td>
- <td class="datagrid"><span>Cat</span></td>
- <td class="datagrid"><span>80.0</span></td>
-</tr>
-<tr class="datagrid-even">
- <td class="datagrid"><span>5</span></td>
- <td class="datagrid"><span>Pixy Bob</span></td>
- <td class="datagrid"><span>Cat</span></td>
- <td class="datagrid"><span>20.0</span></td>
-</tr>
-<tr class="datagrid-odd">
- <td class="datagrid"><span>6</span></td>
- <td class="datagrid"><span>Siamese</span></td>
- <td class="datagrid"><span>Cat</span></td>
- <td class="datagrid"><span>80.0</span></td>
-</tr>
-<tr class="datagrid-even">
- <td class="datagrid"><span>7</span></td>
- <td class="datagrid"><span>Minx</span></td>
- <td class="datagrid"><span>Cat</span></td>
- <td class="datagrid"><span>20.0</span></td>
-</tr>
-<tr class="datagrid-odd">
- <td class="datagrid"><span>8</span></td>
- <td class="datagrid"><span>Bull Mastif</span></td>
- <td class="datagrid"><span>Dog</span></td>
- <td class="datagrid"><span>350.0</span></td>
-</tr>
-<tr class="datagrid-even">
- <td class="datagrid"><span>9</span></td>
- <td class="datagrid"><span>Dalmatian</span></td>
- <td class="datagrid"><span>Dog</span></td>
- <td class="datagrid"><span>20.0</span></td>
-</tr>
- </table>
-</source>
-<p>The stages of the rendering are described below.</p>
-<p>First the data set is passed to the data grid tag
- through the <code>dataSource</code> attribute:</p>
-<source><netui-data:dataGrid name="productsGrid" <strong>dataSource="pageFlow.pets"</strong>></source>
-<p>The data grid tag then analyzes the data set and iterates over its parts. In this case, the
- data grid iterates over the elements in the ArrayList. Typically, a single element
- in the iteration is rendered as a single row in the HTML table.</p>
- <p>During the iteration, that data becomes accessible through
- the databinding contexts <strong><code>container</code></strong>,
- <strong><code>item</code></strong>, and <strong><code>index</code></strong>.
- </p>
- <ul>
- <li><strong><code>container</code></strong> refers to the data set passed into the data grid.</li>
- <li><strong><code>container.item</code></strong> refers to the current row
- of the data set. <code>container.item</code> refers to each row
- as the data grid iterates through the set.</li>
- <li><strong><code>container.item.[field_name]</code></strong> refers to an individual
- field of the current row.</li>
- <li><strong><code>container.index</code></strong> refers to the integer index of the current
- row.</li>
- </ul>
-
- <p>The <netui-data:rows> tag controls the rendering of the <tr> tags. Through the
- <netui-data:rows> tag, you can control the attributes of the rendered <tr> tags, attribute
- such as <code>align</code>, <code>valign</code>, and <code>style</code>.</p>
-
-<p>In a similar way, the <netui-data:spanCell> tag controls the rendering of the <td> tags.</p>
-
- </section>
- <section id="header"><title>Adding a Header</title>
-<p>To add a table header, use the <netui-data:headerCell> tag.</p>
-<p>Edit <code>index.jsp</code> so it appears as follows.</p>
-<source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%>
-<netui:html>
- <head>
- <title>Grid Sample</title>
- <netui:base/>
- </head>
- <netui:body>
- <netui-data:dataGrid dataSource="pageFlow.pets" name="petGrid">
- <strong><netui-data:header>
- <netui-data:headerCell headerText="Pet ID Number" />
- <netui-data:headerCell headerText="Name"/>
- <netui-data:headerCell headerText="Description"/>
- <netui-data:headerCell headerText="Price"/>
- </netui-data:header></strong>
- <netui-data:rows>
- <netui-data:spanCell value="${container.item.petID}" />
- <netui-data:spanCell value="${container.item.name}" />
+ <netui-data:spanCell value="${container.item.petId}"/>
+ <netui-data:spanCell value="${container.item.name}"/>
<netui-data:spanCell value="${container.item.description}"/>
<netui-data:spanCell value="${container.item.price}"/>
</netui-data:rows>
</netui-data:dataGrid>
- </netui:body>
-</netui:html></source>
-<p>Refresh the browser. You should see the following page.</p>
-<figure alt="categoryGrid2" src="images/categoryGrid2.gif"></figure>
-<p>The <netui-data:headerCell> renders the following HTML <code><tr><th></code> row.</p>
-<source><tr class="datagrid-header">
- <th class="datagrid">Pet ID Number</th>
- <th class="datagrid">Name</th>
- <th class="datagrid">Description</th>
- <th class="datagrid">Price</th>
-</tr></source>
- </section>
- <section id="CSS"><title>Controlling the CSS Style</title>
-<p>Notice the various <code>class</code> attributes in the rendered HTML.</p>
-<ul><li><code>class="datagrid"</code></li>
- <li><code>class="datagrid-header"</code></li>
- <li><code>class="datagrid-even"</code></li>
- <li><code>class="datagrid-odd"</code></li></ul>
- <p>You control the data grid's style by changing the <em>prefix</em> rendered in the
- <code>class</code> attributes. If no prefix value is explicitly specified,
- the default prefix value is <em>datagrid</em>.</p>
-<p>To put this into practice, first create the following CSS file.</p>
-<p><strong>gridSample/resources/css/style.css</strong></p>
-<source>/* Data grid styles */
-.gridStyle
-{
-color: #111111;
-font-size: 14px;
-text-align: left;
-vertical-align: middle;
-padding: 5px 5px 5px 5px;
-}
-.gridStyle-header
-{
-background-color: #aaddaa;
-color: #FFF;
-vertical-align: baseline;
-line-height: 18px;
-}
-.gridStyle-even
-{
-background-color: #FFFFFF;
-color: #111111;
-font-size: 14px;
-text-align: left;
-border-color: #999999;
-border-style: solid;
-border-width: 1px;
-padding-left: 12px;
-}
-.gridStyle-odd
-{
-background-color: #dddddd;
-color: #111111;
-font-size: 14px;
-text-align: left;
-border-color: #999999;
-border-style: solid;
-border-width: 1px;
-padding-left: 12px;
-}</source>
-<p>To reference this CSS file, edit <code>index.jsp</code> as shown below.</p>
-<p><strong>gridSample/index.jsp</strong></p>
-<source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%>
-<strong><link href="<%=request.getContextPath()%>/resources/css/style.css" type="text/css" rel="stylesheet"/></strong>
-<netui:html>
- <head>
- <title>Grid Sample</title>
- <netui:base/>
- </head>
- <netui:body>
- <netui-data:dataGrid dataSource="pageFlow.pets" name="petGrid" <strong>styleClassPrefix="gridStyle"</strong>>
- <netui-data:header>
- <netui-data:headerCell headerText="Pet ID Number" />
- <netui-data:headerCell headerText="Name"/>
- <netui-data:headerCell headerText="Description"/>
- <netui-data:headerCell headerText="Price"/>
- </netui-data:header>
+ </source>
+<p>
+This data grid binds to a List of PetBean objects stored in the PageContext's attribute map and renders an HTML table
+that is four cells wide (ie four columns) containing the petId, name, description, and price fields. The rendered table
+would appear as:
+</p>
+<source>
+ <strong>TODO</strong>
+</source>
+<p>
+The values for the cells are specified with a JSP 2.0 expression and can reference any implicit object. In this case, an
+expression like <code>${container.item.petId}</code> references an implicit object called <code>container</code> that the
+<code><netui-data:rows></code> tag provides. This implicit object has a <code>item</code> property that references
+the current item from data set bound to the <code>dataSource</code> attribute of the <code><netui-data:dataGrid></code>
+tag.
+</p>
+</section>
+<section id="datagrid-cells">
+ <title>Data Grid Cells</title>
+ <p>
+The data grid tags use cell based rendering. This means that their structure is not defined in terms of columns
+but rather in terms of cells in the table. This allows for greater flexibility to have cells span columns and rows as
+needed. Cells can be placed in two regions of the data grid -- the header and the body. The header of the grid is the
+region that renders at the top of the rows containing data and often has column titles, sorting / filtering links, and
+paging UI. Cells in the body of the data grid are used to render the grid's data; the <code>spanCell</code> tags in the
+simple example above are an example of this.
+ </p>
+ <section id="datagrid-cells-body">
+ <title>Body Cells</title>
+<p>
+Body cells are used to render rows that display data. For example:
+</p>
+<source>
+ <netui-data:dataGrid dataSource="pageScope.pets" name="petGrid">
<netui-data:rows>
- <netui-data:spanCell value="${container.item.petID}" />
- <netui-data:spanCell value="${container.item.name}" />
+ <netui-data:spanCell value="${container.item.petId}"/>
+ <netui-data:spanCell value="${container.item.name}"/>
<netui-data:spanCell value="${container.item.description}"/>
<netui-data:spanCell value="${container.item.price}"/>
</netui-data:rows>
</netui-data:dataGrid>
- </netui:body>
-</netui:html></source>
-<p>The resulting HTML page is shown below. (You will need to recompile to see these changes
- in the browser.)</p>
-<figure alt="categoryGrid3" src="images/categoryGrid3.gif"/>
- </section>
- <section id="config_pager">
- <title>Configuring the Pager</title>
- <p>The "pager" controls how many rows are included on a single page of data.</p>
- <p>The pager can be configured to appear above and/or below the data grid.</p>
-
- <p>To add a pager, edit <code>index.jsp</code> so it appears as
- follows.</p>
- <p><strong><code>gridSample/index.jsp</code></strong></p>
- <source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%>
-<link href="<%=request.getContextPath()%>/resources/css/style.css" type="text/css" rel="stylesheet"/>
-<netui:html>
- <head>
- <title>Grid Sample</title>
- <netui:base/>
- </head>
- <netui:body>
- <netui-data:dataGrid dataSource="pageFlow.pets" name="petGrid" styleClassPrefix="gridStyle">
- <strong><netui-data:configurePager pageSize="3" pagerFormat="prevNext" pageAction="begin.do"/></strong>
+</source>
+<p>
+This data grid displays <strong>TODO</strong>.
+<br/>
+<br/>
+ <strong>TODO</strong>
+<br/>
+<br/>
+</p>
+ </section>
+ <section id="datagrid-cells-header">
+ <title>Header Cells</title>
+ <p>
+Header cells are used to render HTML table cells at the top of a data grid. For example:
+ </p>
+<source>
+ <netui-data:dataGrid dataSource="pageScope.pets" name="petGrid">
<netui-data:header>
- <netui-data:headerCell headerText="Pet ID Number" />
+ <netui-data:headerCell headerText="Pet ID"/>
<netui-data:headerCell headerText="Name"/>
<netui-data:headerCell headerText="Description"/>
<netui-data:headerCell headerText="Price"/>
</netui-data:header>
<netui-data:rows>
- <netui-data:spanCell value="${container.item.petID}" />
- <netui-data:spanCell value="${container.item.name}" />
+ <netui-data:spanCell value="${container.item.petId}"/>
+ <netui-data:spanCell value="${container.item.name}"/>
<netui-data:spanCell value="${container.item.description}"/>
<netui-data:spanCell value="${container.item.price}"/>
</netui-data:rows>
</netui-data:dataGrid>
- </netui:body>
-</netui:html></source>
- <p>Refresh the browser. You will see the following page.</p>
- <figure alt="categoryGrid4" src="images/categoryGrid4.gif"/>
-
-
- </section>
- <!--<section id="link_columns"><title>Adding Linking Columns</title>
- <p>Linking columns allow you to link to details pages for individual
- items in the data
- set.</p>
- <p>The <netui-data:anchorCell tag adds a linking column to the
- data grid.</p>
- <p>The child <parameter> tag adds the string <code>productId=[some_value]</code>
- to the URL.</p>
- <source><%@ page language="java" contentType="text/html;charset=UTF-8"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>
-<link href="<%=request.getContextPath()%>/resources/css/style.css" type="text/css" rel="stylesheet"/>
-
-<netui-data:declarePageInput name="products" type="org.apache.beehive.samples.petstore.model.Product[]" required="false"/>
-
-<netui-data:dataGrid name="productsGrid" dataSource="pageInput.products" styleClassPrefix="gridStyle">
- <netui-data:configurePager pageSize="3" pagerFormat="prevNext" pageAction="viewCategory.do"/>
- <netui-data:header>
- <netui-data:headerCell headerText="PetID"/>
- <netui-data:headerCell headerText="Name"/>
- <netui-data:headerCell headerText="Description"/>
- </netui-data:header>
- <netui-data:rows>
- <strong><netui-data:anchorCell action="viewProduct" value="${container.item.productId}">
- <netui:parameter name="productId" value="${container.item.productId}"/>
- </netui-data:anchorCell></strong>
- <netui-data:spanCell value="${container.item.name}" />
- <netui-data:spanCell value="${container.item.description}"/>
- </netui-data:rows>
-</netui-data:dataGrid></source>
-<p>Notice that the PetId column now appears as linking text. </p>
-<p><img alt="categoryGrid5" src="images/categoryGrid5.gif"/></p>
- </section>-->
- <section id="filtering">
- <title>Filtering a Data Grid</title>
- <p>To be completed<!--[todo]--></p>
- <!--<p>A filter is specified using three bits of information - the filter expression,
- the filter operation, and the filter value. The filter expression is specified
- as an attribute on a grid's header cell and is used to loosely couple the filetr
- information for the header from the data displayed in the header. </p>
- <source>netui_filter=<grid name>~<filter expression>~<filter operation>~<filter value></source>
- <p>For example, the filter</p>
- <source>netui_filter=portfolio~symbol~eq~beas</source>
- <p>converts into the SQL filter</p>
- <source>WHERE symbol = beas</source>
- <p>Filters are added to the URL using JavaScript to convert an HTML form from the
- input fields into query parameters in the above format. </p>-->
- </section>
- <section id="sorting">
- <title>Sorting a Data Grid</title>
- <p>To be completed<!--[todo]--></p>
-<!--<p>A sort is specified using two bits of information - the sort expression and the sort
- direction. The sort expression is specified as an attribute on a grid's header cell
- and is used to loosely couple the sort information for the header from the data displayed
- in the header. A sort appears in the URL as:</p>
-
-<source>netui_sort=<grid name>~<direction><sort expression>[,<direction><sort expression>]</source>
-
-<p>The sort parameter is scoped to a data grid using the <grid name>. The <direction>
- defaults to ascending and is set to descending when <direction> is "-"
-There can be two sorts specified in the query param; if two are present, they are
-separated by a comma.</p>
-
-<p>A sort link is added to a <headerCell> when the disableFilterRendering attribute is false.
- If set to true, no sort link is rendered. The sort link for a header cell consists of all
- of the parameters on the previous URL with the direction of the current column's sort
- switched using the following state transitions:</p>
-
-<ul>
- <li>no sort > ascending</li>
- <li>ascending > descending</li>
- <li>descending > no sort</li>
-</ul>-->
- </section>
- <section><title>Nesting Data Grids</title>
- <p>To be completed<!--[todo]--></p>
- </section>
-<!-- <section id="sample_code">
- <title>Sample Code</title>
-
- <p><strong>carDB.java</strong></p>
- <source>package controls.data;
-
-import java.sql.SQLException;
-import java.sql.ResultSet;
-import org.apache.beehive.controls.system.jdbc.JdbcControl;
-
-/**
- * This control contains access to the car inventory
- */
-
-@org.apache.beehive.controls.api.bean.ControlExtension
-@JdbcControl.ConnectionDriver(databaseDriverClass="org.apache.derby.jdbc.EmbeddedDriver", databaseURL="jdbc:derby:C:/beehive_projects/Westside/Westside/data/testdb")
-
-public interface carDB extends JdbcControl {
-
- // countCars() - this is more of a test to see if everything is working
- @SQL(statement="SELECT COUNT(*) FROM CARS")
- public int countCars() throws SQLException;
-
- // getInventoryRS() - get all the cars from the inventory view
- @SQL(statement="SELECT * FROM CARINVENTORY")
- public ResultSet getInventoryRS() throws SQLException;
-
- // getItem() - get an individual car from the inventory view
- @SQL(statement="SELECT * FROM CARINVENTORY WHERE SKU = {nSKU}")
- public ResultSet getItem(int nSKU) throws SQLException;
-}</source>
- <p><strong>Controller.java</strong></p>
- <source>import java.sql.ResultSet;
-import javax.servlet.http.HttpSession;
-import org.apache.beehive.netui.pageflow.Forward;
-import org.apache.beehive.netui.pageflow.PageFlowController;
-import org.apache.beehive.netui.pageflow.annotations.Jpf;
-
-// Set up annotations
-@Jpf.Controller(
- simpleActions={
- @Jpf.SimpleAction(name="begin", path="index.jsp")
- }
- , sharedFlowRefs={ @Jpf.SharedFlowRef(name="shared", type=shared.SharedFlow.class) }
-)
-public class Controller
- extends PageFlowController
-{
- // Shared Flow - handle common exceptions, etc. here
- @Jpf.SharedFlowField(name="shared")
- private shared.SharedFlow sharedFlow;
-
- // Controls
- @org.apache.beehive.controls.api.bean.Control
- private controls.data.carDB carDB;
-
- // Objects to pass to page flow
- public ResultSet rs;
-
- // Actions
- @Jpf.Action(
- forwards = {
- @Jpf.Forward(name = "success", path = "list.jsp")
- }
- )
- public Forward processData() throws Exception
- {
- int nCount = carDB.countCars();
- getRequest().setAttribute("cars", nCount);
- rs = carDB.getInventoryRS();
- return new Forward("success");
- }
-
- @Jpf.Action(
- forwards = {
- @Jpf.Forward(name = "success", path = "item.jsp")
- })
- protected Forward item() throws Exception
- {
- int nSKU = Integer.parseInt(getRequest().getParameter("sku"));
- rs = carDB.getItem(nSKU);
- return new Forward("success");
- }
-
- // Callback that is invoked when this controller instance is created.
- protected void onCreate() {}
-
- // Callback that is invoked when this controller instance is destroyed.
- protected void onDestroy(HttpSession session) {}
-}</source>
- <p><strong>list.jsp</strong></p>
- <source><%@ taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui" %>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%>
-<%@ taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>
-<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
-<netui-template:template templatePage="/resources/jsp/template.jsp">
- <netui-template:setAttribute value="WAS - Inventory" name="title"/>
- <netui-template:section name="bodySection">
- <blockquote>
- <span class="subtitle">Inventory Section</span><br>
-
- <netui-data:dataGrid dataSource="pageFlow.rs" name="inventoryGrid" styleClassPrefix="gridStyle">
- <netui-data:configurePager pageSize="4" pagerFormat="prevNext" pageAction="processData.do" disableDefaultPager="true"/>
- <netui-data:caption>
- We currently have ${requestScope.cars} vehicles in our inventory.
- </netui-data:caption>
-
- <netui-data:header>
- <netui-data:headerCell headerText="Details"/>
- <netui-data:headerCell headerText="Make"/>
- <netui-data:headerCell headerText="Model" />
- <netui-data:headerCell headerText="Description"/>
- <netui-data:headerCell headerText="Inventory Number"/>
- <netui-data:headerCell headerText="Price"/>
- <netui-data:headerCell headerText="Status"/>
- </netui-data:header>
- <netui-data:rows>
- <netui-data:imageAnchorCell src="${pageContext.request.contextPath}/resources/images/${container.item.carid}sm.jpg" action="item" alt="Details for this vehicle" border="0">
- <netui:parameter name="sku" value="${container.item.sku}"/>
- </netui-data:imageAnchorCell>
- <netui-data:spanCell value="${container.item.make}"/>
- <netui-data:spanCell value="${container.item.model}" filterExpression="model" />
- <netui-data:spanCell value="${container.item.description}"/>
- <netui-data:spanCell value="${container.item.sku}"/>
- <netui-data:spanCell value="${container.item.price}">
- <netui:formatNumber pattern="$#,###"/>
- </netui-data:spanCell>
- <netui-data:spanCell value="${container.item.status}" styleClass="${container.item.status == 'Available' ? 'status-available' : 'status-sold'}"/>
- </netui-data:rows>
- <netui-data:footer>
- <td colspan="7" style="height: 50px;">
- <netui-data:renderPager/>
- </td>
- </netui-data:footer>
- </netui-data:dataGrid>
- </blockquote>
- </netui-template:section>
-</netui-template:template></source>
- </section>--></section>
+</source>
+<p>
+The data grid rendered here will have a single HTML table row that contains header cells
+with titles for the data columns. This table might appear as:
+<br/>
+<br/>
+ <strong>TODO</strong>
+<br/>
+<br/>
+</p>
+ </section>
+ <section id="datagrid-cell-formatting">
+ <title>Formatting Cells</title>
+ <p><strong>TODO</strong></p>
+ </section>
+</section>
+<section id="datagrid-styles-support">
+ <title>Adding Styles to the Data Grid</title>
+ <p><strong>TODO</strong></p>
+ <section id="datagrid-style">
+ <title>Style Attributes</title>
+ <p><strong>TODO</strong></p>
+ </section>
+ <section id="datagrid-css">
+ <title>CSS Attributes</title>
+ <p><strong>TODO</strong></p>
+ </section>
+</section>
+<section id="datagrid-javascript">
+ <title>Using Javascript with the Data Grid</title>
+ <p><strong>TODO</strong></p>
+</section>
</body>
</document>