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 2006/01/29 20:18:34 UTC
svn commit: r373339 - in
/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs:
controls/testing.xml controls/tutorial.xml
netui/tags/datagridSortAndFilter.xml
Author: ekoneil
Date: Sun Jan 29 11:18:29 2006
New Revision: 373339
URL: http://svn.apache.org/viewcvs?rev=373339&view=rev
Log:
Add document on sorting and filter in the data grid.
BB: self
Test: docs clean / bulid pass
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/testing.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial.xml
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tags/datagridSortAndFilter.xml
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/testing.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/testing.xml?rev=373339&r1=373338&r2=373339&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/testing.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/testing.xml Sun Jan 29 11:18:29 2006
@@ -10,6 +10,30 @@
<section id="overview">
<title>Overview</title>
<p>
+
+ </p>
+ </section>
+ <section id="container">
+ <title>The JUnit Controls Container</title>
+ <p>
+ todo
+ </p>
+ </section>
+ <section id="control-instantiation">
+ <title>Control Instantiation</title>
+ <p>
+ todo
+ </p>
+ </section>
+ <section id="junit-control-baseclass">
+ <title>Using the ControlsTestCase Base Class</title>
+ <p>
+ todo
+ </p>
+ </section>
+ <section id="junit-other-baseclass">
+ <title>Using another Base Class</title>
+ <p>
todo
</p>
</section>
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial.xml?rev=373339&r1=373338&r2=373339&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/controls/tutorial.xml Sun Jan 29 11:18:29 2006
@@ -12,11 +12,11 @@
how to write, build, package, and test a simple Hello Control. The following concepts will be convered here:
</p>
<ul>
- <li>How to create a standalone Beehive Control project</li>
- <li>How to create a Control interface and implementation</li>
- <li>How to compile a Control</li>
- <li>How to package a Control into a JAR file</li>
- <li>How to test a Control using JUnit</li>
+ <li>Creating a standalone Beehive Control project</li>
+ <li>Creating a Control interface and implementation</li>
+ <li>Compiling a Control</li>
+ <li>Packaging a Control into a JAR file</li>
+ <li>Testing a Control using JUnit</li>
</ul>
<p>
For a technical description of Controls, see the <a href="site:docs/controls/programming">Controls programming guide</a>.
@@ -309,7 +309,7 @@
<footer>
<legal>
Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
- <br/>© 2005, Apache Software Foundation
+ <br/>© 2006, Apache Software Foundation
</legal>
</footer>
</document>
Modified: beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tags/datagridSortAndFilter.xml
URL: http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tags/datagridSortAndFilter.xml?rev=373339&r1=373338&r2=373339&view=diff
==============================================================================
--- beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tags/datagridSortAndFilter.xml (original)
+++ beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/tags/datagridSortAndFilter.xml Sun Jan 29 11:18:29 2006
@@ -7,11 +7,282 @@
<title>Sorting and Filtering in a Data Grid</title>
</header>
<body>
- <section id="Overview">
+ <section id="overview">
<title>Overview</title>
<p>
- todo
+ The NetUI <a href="datagrid.xml">data grid</a> JSP tags support maintaining and displaying UI based on an abstract set of
+ sorts and filters applied to a data set. Sorts and filters are Java objects that can be created manually or can be inferred
+ from state that is encoded in a URL. These objects represent an abstract notion of a sort and filter that are not coupled to
+ any specific query language. As such, they can be used to programmatically sort or filter a data set or to parameterize a
+ query string in a specific query language like SQL, XQuery, EJB-QL, and so on.
</p>
+ <p>
+ This document describes the structure of sort and filter objects and discusses how they can be created, used to sort a data set,
+ and how they relate to the data grid. A concrete example that demonstrates some of the sort and filter features can be found
+ in a Beehive sample available in <em>samples/netui-samples/web/ui/datagrid/sortandfilter</em>. This sample demonstrates the
+ data grid's support for sorting data by clicking on a grid's header cell and for filtering data using an HTML form.
+ </p>
+ <p>
+ For the sake of concrete descriptions, this documentation applies abstract Sort and Filter objects to SQL in order to make the
+ examples interesting. It is possible to build a mapping from the Sort and Filter objects to any other query language.
+ </p>
+ </section>
+ <section id="sorts">
+ <title>Sorts</title>
+ <p>
+ A data grid sort is represented by the <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/sort/Sort.html">
+ Sort</a> class which has several properties:
+ </p>
+ <table>
+ <tr><td>Property Name</td><td>Description</td></tr>
+ <tr>
+ <td>sortExpression</td>
+ <td>The sort expression is a String that describes the data to be sorted.</td>
+ </tr>
+ <tr>
+ <td>sortDirection</td>
+ <td>
+ The sort direction is an enumeration value that describes the order in which data should be sorted. In the general case, this
+ is one of <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/sort/SortDirection.html#ASCENDING">ASCENDING</a>
+ or <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/sort/SortDirection.html#DESCENDING">DESCENDING</a>.
+ </td>
+ </tr>
+ </table>
+ <p>
+ In more concrete terms, a sort expression of "name" and sort direction of <code>SortDirection.ASCENDING</code> could be used to produce
+ a SQL <code>ORDER BY</code> fragment like <code>ORDER BY name ASC</code>.
+ </p>
+ <section id="sort-datagrid">
+ <title>Data grid Support for Sorting</title>
+ <p>
+ The data grid JSP tags can be used to manipulate the sort state for a data grid in a URL. This allows a URL to explicitly
+ describe the sort appearance of a data grid and makes for easy, transparent bookmarking. A sort is often applied to a
+ <em>column</em> in a data grid and can be specified by setting the <code>sortExpression</code> attribute for any data grid
+ <code>headerCell</code> tag. By default, a sort can be activated by clicking on a column's header in the rendered data grid;
+ this will cycle the sorted state through a series of states from NONE to ASCENDING to DESCENDING. The change in state
+ can be observed by watching the URL. By default, a sort appears in the URL as:
+ </p>
+ <source>
+netui_sort=<namespace>;(|-)<sortExpression>
+ </source>
+ <p>
+ The namespace is taken from the data grid's <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/tags/datagrid/DataGrid.html#setName()">name</a>
+ attribute in order to scope a sort to a particular data grid.
+ The sort expression is explicitly in the parameter value; the default sort direction is ASCENDING unless a <code>-</code> is
+ present to change the sort direction to DESCENDING.
+ </p>
+ <p>
+ The list of Sort(s) available on the URL can be read using a
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/DataGridState.html"><code>DataGridState</code></a>
+ object that parses state information from a query string and can return the list of states. This can be done using the following
+ code:
+ </p>
+ <source>
+DataGridState dataGridState = DataGridStateFactory.getInstance(httpServletRequest).getDataGridState("<namespace>");
+List sorts = dataGridState.getSortModel().getSorts();
+ </source>
+ <p>
+ Although the data grid may use a sort expression, the data will not be sorted until code executes to actually sort the data.
+ <em>The data grid does not automatically sort data</em>. In order to sort data, controller code must be implemented to
+ apply Sort objects to a data grid.
+ </p>
+ <p>
+ The sort state of a particular sort expression can also be used to configure the styles of a data grid column's header cell and
+ data cells. When a column is sorted, it will render a <code>sorted</code> style for both the header and data cells.
+ </p>
+ </section>
+ <section id="sort-using">
+ <title>Sorting a Data Set</title>
+ <p>
+ Sorts must be manually applied to a data set in order to cause data to be sorted in a particular direction. This sorting can
+ be implemented in several ways including converting a Sort object into a query language fragment and letting a query engine sort
+ a data set or manually writing code to sort a data set. To convert Sort(s) into a query language fragment, a converter must be
+ built to produce the fragment from the Sort(s). A simple SQL converter called
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/runtime/sql/SQLSupport.html">SQLSupport</a>
+ can be used for this purpose. A sort of the form <em>netui_sort=customers;-customerid</em> will be converted into a
+ SQL fragment of the form <code>ORDER BY customerid DESC</code> using the code:
+ </p>
+ <source>
+List sorts = dataGridState.getSortModel().getSorts();
+String sort = SQLSupport.getInstance().createOrderByClause(sorts);
+ </source>
+ <p>
+ A list of Sort(s) can also be used to manually filter a data set, particularly when sorting on a single sort expression (column
+ of data). In this case, a reasonably sized data set can be sorted in-memory quickly using a custom <code>Comparator</code>
+ and the <code>java.util.Collections.sort(...)</code> method. An example of this is available in the data grid sort / filter
+ sample in the distribution.
+ </p>
+ </section>
+ <section id="sort-creation">
+ <title>Creating a Sort</title>
+ <p>
+ Sort objects can also be created programmatically. When creating a Sort object manually, the Sort object should be created
+ from the <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/DataGridConfig.html">DataGridConfig</a>
+ object for a data grid. The DataGridConfig object is used as a configuration object
+ that can be used in its default state or can be extended to provide, extend, or change the operation of the data grid. In
+ most cases, the DataGridConfig object can be created with:
+ </p>
+ <source><![CDATA[DataGridConfig dataGridConfig = DataGridConfigFactory.getInstance();]]></source>
+ <p>
+ And, the DataGridConfig can be used to create a Sort with:
+ </p>
+ <source><![CDATA[Sort sort = dataGridConfig.createSort();]]></source>
+ <p>
+ Once a Sort is created, it can be configured by setting its JavaBean properties and can be applied to a data set
+ as described <a href="#sort-using">here</a>.
+ </p>
+ </section>
+ </section>
+ <section id="filters">
+ <title>Filters</title>
+ <p>
+ A data grid filter is represented by the <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/filter/Filter.html">Filter</a>
+ JavaBea which has several properties:
+ </p>
+ <table>
+ <tr><td>Property Name</td><td>Description</td></tr>
+ <tr>
+ <td>filterExpression</td>
+ <td>The filter expression is a String that describes a property from the data set to filter.</td>
+ </tr>
+ <tr>
+ <td>filterOperation</td>
+ <td>A query language specific representation of a filter operation. A filter operation may provide an operator that is used
+ when building a query string. For example, some languages may represent equals as '=' or as 'eq'.</td>
+ </tr>
+ <tr>
+ <td>filterOperationHint</td>
+ <td>A query language neutral hint of the type operation to perform. Not all operation hints will be supported for all query languages.</td>
+ </tr>
+ <tr>
+ <td>typeHint</td>
+ <td>A hint provided to describe the type of the filter value to a query engine. This is needed in order to correctly build a query string
+ describing a filter or to correctly filter a value of a particular type. For example, when building a filter expression for a String,
+ the String value may need to be wrapped in quotes to be interpreted by a query engine.
+ </td>
+ </tr>
+ <tr>
+ <td>value</td>
+ <td>The value of an operation that provides a constraint to a fliter. For example, when filtering to a specific integer value, this
+ is the value of that integer.
+ </td>
+ </tr>
+ </table>
+ <p>
+ The filter operation hint can be one of many values that represent filtering options such as:
+ </p>
+ <ul>
+ <li>
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/filter/FilterOperationHint.html#EQUAL">EQUAL</a>
+ </li>
+ <li>
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/filter/FilterOperationHint.html#GREATER_THAN">GREATER_THAN</a>
+ </li>
+ <li>
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/filter/FilterOperationHint.html#IS_ONE_OF">IS_ONE_OF</a>
+ </li>
+ <li>
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/filter/FilterOperationHint.html#STARTS_WITH">STARTS_WITH</a>
+ </li>
+ <li>
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/filter/FilterOperationHint.html#CONTAINS">CONTAINS</a>
+ </li>
+ </ul>
+ <p>
+ As a concrete example, a filter on a value of "companyname" with an operator of "contains" and a value "wheel" with type String
+ could be used to produce a SQL <code>WHERE</code> clause like <code>WHERE companyname LIKE '%wheel%'</code>.
+ </p>
+ <section id="filter-datagrid">
+ <title>Data grid Support for Filtering</title>
+ <p>
+ The data grid's support for filtering is different than that for sorting; the data grid itself does not provide logic for
+ filtering and instead has the ability to mark a column of data as filtered and leaves the construction of filter UI
+ to the developer. A common pattern for building filter UI is to provide an embedded filter form or a filter pop-up that
+ implements filter logic. A data grid header cell can be linked to a filter expression using the filterExpression attribute
+ on the <code>headerCell</code>.
+ </p>
+ <p>
+ The data grid APIs support reading filter information that is encoded in the URL. One benefit of adding this information
+ to a query string as query parameters is that a filtered data grid can be bookmarked, which can make it easy to return to
+ a specific view into a data set. The default format for filters in the URL is:
+ </p>
+ <source>
+netui_filter=<namespace>;<filterExpression>~<filterOperation>~<value>
+ </source>
+ <p>
+ The namespace of the filter is taken from the data grid's
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/tags/datagrid/DataGrid.html#setName()">name</a> attribute, and
+ the filter's expression, operation type, and value are encoded in the remainder of the query parameter. The filters on a URL
+ query string can be read using a
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/DataGridState.html"><code>DataGridState</code></a>
+ which is used to manage a grid's state from some state source. The filters can be extracted from the query string using the
+ following code:
+ </p>
+ <source>
+DataGridState dataGridState = DataGridStateFactory.getInstance(httpServletRequest).getDataGridState("<namespace>");
+List filters = dataGridState.getFilterModel().getFilters();
+ </source>
+ <p>
+ Filters can be placed on the URL by JavaScript in the page or by extending the data grid itself to support filtering.
+ </p>
+ </section>
+ <section id="filter-creation">
+ <title>Creating a Filter</title>
+ <p>
+ Filter objects can be created programmatically and applied to a data set either manually or by converting Filter{s) into
+ query fragments to be executed by a query engine. A
+ <a href="../apidocs/javadoc/org/apache/beehive/netui/databinding/datagrid/api/DataGridConfig.html">DataGridConfig</a>
+ object can be used get a factory that can provide a <code>Filter</code> object for a specific type of data grid. This can
+ usually be created with:
+ </p>
+ <source><![CDATA[DataGridConfig dataGridConfig = DataGridConfigFactory.getInstance();]]></source>
+ <p>
+ And, the DataGridConfig can be used to create a Filter with:
+ </p>
+ <source><![CDATA[Filter filter = dataGridConfig.createFilter();]]></source>
+ <p>
+ This <code>Filter</code> object can be configuerd usints its JavaBean properties to set the expression, type hint, value, and operation hint.
+ Then, the filter can be used to filter a data set as described in <a href="#filter-using">here</a>
+ </p>
+ </section>
+ <section id="filter-using">
+ <title>Filtering a Data Set</title>
+ <p>
+ Once a set of Filter objects have been obtained, they can be used to filter a data set by using a query engine or by manually filtering a data set.
+ A query engine can be used by converting a set of Filter objects into a fragment of a query string. For example, a filter can be configured
+ and converted into a SQL <code>WHERE</code> clause <code>WHERE companyname LIKE '%wheel%'</code> using the following code:
+ </p>
+ <source>
+ // create the DataGridConfig object for a grid
+ DataGridConfig dataGridConfig = DataGridConfigFactory.getInstance();
+
+ // configure the filter
+ Filter filter = dataGridConfig.createFilter();
+ filter.setFilterExpression("companyname");
+ filter.setOperation(SQLSupport.mapFilterHintToOperation(FilterOperationHint.CONTAINS);
+ filter.setTypeHint(FilterTypeHint.STRING);
+ filter.setValue("wheel");
+ List filterList = new LinkedList();
+ filterList.add(filter);
+
+ // create the WHERE clause
+ String whereClause = SQLSupport.getInstance().createWhereClause(filters);
+ </source>
+ <note>
+ If the Filter(s) are encoded in the URL, the Filter creation / configuration above can be replaced by the code
+ to parse filters from the query string.
+ </note>
+ <p>
+ Notice that the type hint is explicitly specified in the example above; the type of the <em>companyname</em> could be read
+ from a relational database's DatabaseMetaData object, but this is a very expensive way to determine the type of a column
+ of data. Once the where clause has been obtained, it can be used to parameterize a SQL query statement.
+ </p>
+ <p>
+ It is also possible to programmatically filter a data set. As an example, a simple set of filter predicate objects
+ are available in the Beehive sample listed above. In this case, the filters are created manually, and a data set is filtered
+ in-memory to provide a subset matching the filter criteria that should be rendered.
+ </p>
+ </section>
</section>
</body>
</document>