Author: ekoneil
Date: Thu May 19 15:55:17 2005
New Revision: 171008
URL: http://svn.apache.org/viewcvs?rev=171008&view=rev
Log:
NetUI Javadoc.
BB: self
DRT: pass
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/runtime/config/DefaultDataGridURLBuilder.java
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/tags/databinding/datagrid/DataGrid.java
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/runtime/config/DefaultDataGridURLBuilder.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/runtime/config/DefaultDataGridURLBuilder.java?rev=171008&r1=171007&r2=171008&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/runtime/config/DefaultDataGridURLBuilder.java
(original)
+++
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/databinding/datagrid/runtime/config/DefaultDataGridURLBuilder.java
Thu May 19 15:55:17 2005
@@ -40,6 +40,11 @@
* URL parameters would be computed using this class and rendered to the UI so
that it is clickable for the
* next HTTP submit.
* <p/>
+ * <p>
+ * An instance of this class is associated with a single data grid by name.
Instances should be obtained
+ * via the [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.DataGridStateFactory#getDataGridURLBuilder(String)}
+ * method.
+ * </p>
*/
class DefaultDataGridURLBuilder
extends DataGridURLBuilder {
@@ -47,8 +52,10 @@
private transient DefaultDataGridStateCodec _codec;
/**
- * Package protected constructor. This class is intended only to be
created via the default [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.DataGridConfig}
- * object.
+ * <p>
+ * Package protected constructor. This class is intended only to be
created via the default
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.DataGridConfig} object.
+ * </p>
* @param codec the state codec providing state information which will be
converted into URLs here.
*/
DefaultDataGridURLBuilder(DefaultDataGridStateCodec codec) {
@@ -56,16 +63,27 @@
}
/**
- *
- * @return
+ * <p>
+ * Get the URL query parameter key used to store the current row for a
data grid's pager. The value
+ * of this key is:
+ * <br/>
+ * <pre>
+ * netui_row
+ * </pre>
+ * </p>
+ * @return the URL parameter key for the current row
*/
public String getPagerRowQueryParamKey() {
return DefaultDataGridStateCodec.PARAM_KEY_ROW;
}
/**
- *
- * @return
+ * <p>
+ * Get the query parameters for the currene state of the data grid. The
[EMAIL PROTECTED] Map} returned by this method
+ * will maintain the <i>current</i> state of the data grid and all of the
associated URL parameters. The
+ * [EMAIL PROTECTED] Map} contains key / value pairs of type String /
String[].
+ * </p>
+ * @return the current URL and data grid state
*/
public Map getQueryParams() {
Map params = _codec.getExistingParams();
@@ -82,8 +100,12 @@
}
/**
- *
- * @return
+ * <p>
+ * Get a URL query parameter map that will change the data grid's page
value to display the
+ * <i>first</i> page in a data set. This map also contains all of the
other existing URL
+ * parameters. The [EMAIL PROTECTED] Map} contains key / value pairs of
type String / String[].
+ * </p>
+ * @return the URL and data grid state needed to change to the
<i>first</i> page for a data grid
*/
public Map getQueryParamsForFirstPage() {
Map params = _codec.getExistingParams();
@@ -104,8 +126,13 @@
}
/**
- *
- * @return
+ * <p>
+ * Get a URL query parameter map that will change the data grid's page
value to display the
+ * <i>previous</i> page in a data set relative to the current page. This
map also contains all of
+ * the other existing URL parameters. The [EMAIL PROTECTED] Map} contains
key / value pairs of type
+ * String / String[].
+ * </p>
+ * @return the URL and data grid state needed to change to the
<i>previous</i> page for a data grid
*/
public Map getQueryParamsForPreviousPage() {
Map params = _codec.getExistingParams();
@@ -126,8 +153,13 @@
}
/**
- *
- * @return
+ * <p>
+ * Get a URL query parameter map that will change the data grid's page
value to display the
+ * <i>next</i> page in a data set relative to the current page. This map
also contains all of
+ * the other existing URL parameters. The [EMAIL PROTECTED] Map} contains
key / value pairs of type
+ * String / String[].
+ * </p>
+ * @return the URL and data grid state needed to change to the <i>next</i>
page for a data grid
*/
public Map getQueryParamsForNextPage() {
Map params = _codec.getExistingParams();
@@ -148,8 +180,12 @@
}
/**
- *
- * @return
+ * <p>
+ * Get a URL query parameter map that will change the data grid's page
value to display the
+ * <i>last</i> page in a data set. This map also contains all of the
other existing URL parameters.
+ * The [EMAIL PROTECTED] Map} contains key / value pairs of type String /
String[].
+ * </p>
+ * @return the URL and data grid state needed to change to the <i>last</i>
page for a data grid
*/
public Map getQueryParamsForLastPage() {
Map params = _codec.getExistingParams();
@@ -170,7 +206,16 @@
}
/**
- *
+ * <p>
+ * Get a String[] of the URL query parameter values that could when
submitted to a server to make a request
+ * can explicitly change the current page for a data grid to a specific
page. The returned pager parameter
+ * values are structured as:
+ * <pre>
+ * <datagrid-name>~<row-number>
+ * </pre>
+ * These values can be attached to a URL in order to submit a query string
which will set the data grid's
+ * current page.
+ * </p>
* @return
*/
public String[] getPagerParamValues() {
@@ -185,9 +230,17 @@
}
/**
- *
- * @param sortExpression
- * @return
+ * <p>
+ * Get a URL query parameter map that contains state which will change the
direction of a
+ * [EMAIL PROTECTED] Sort} whose sort expression matches the given sort
expression value. The [EMAIL PROTECTED] SortStrategy}
+ * associated with the data grid's [EMAIL PROTECTED] SortModel} will be
used to choose the next
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.sort.SortDirection} given the
sort's current
+ * sort direction. This map also contains all of the other existing URL
parameters. The [EMAIL PROTECTED] Map}
+ * contains key / value pairs of type String / String[].
+ * </p>
+ * @param sortExpression the sort expression whose direction to change
+ * @return the URL and data grid state needed to change the direction of a
[EMAIL PROTECTED] Sort} with the given
+ * sort expression
*/
public Map buildSortQueryParamsMap(String sortExpression) {
Modified:
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/tags/databinding/datagrid/DataGrid.java
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/tags/databinding/datagrid/DataGrid.java?rev=171008&r1=171007&r2=171008&view=diff
==============================================================================
---
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/tags/databinding/datagrid/DataGrid.java
(original)
+++
incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui/tags/databinding/datagrid/DataGrid.java
Thu May 19 15:55:17 2005
@@ -53,12 +53,190 @@
/**
* <p>
- * This tag is the top-level data grid tag which renders a data set into an
HTML table.
+ * This tag is the containing tag for all tags and markup used to render a
data grid. In its simplest form, a data
+ * grid is an HTML table containing an HTML table row for every item in a data
set. The data grid also provides
+ * functionality for rendering the following major regions:
+ * <ul>
+ * <li>a header -- a header contains the top-most rows in a data grid's HTML
table and is rendered using
+ * the [EMAIL PROTECTED] Header} tag</li>
+ * <li>data rows -- markup rendered in the data grid for each record in the
data set must be contained
+ * in a [EMAIL PROTECTED] Rows} tag</li>
+ * <li>a footer -- a footer contains the bottom-most rows in a data grid's
HTML table and is rendered using the
+ * [EMAIL PROTECTED] Footer} tag</li>
+ * <li>caption -- an HTML table caption appears at the top of the table and is
rendered using the
+ * [EMAIL PROTECTED] Caption} tag.</li>
+ * </ul>
+ * In addition, a data grid can also configure and render a pager using the
[EMAIL PROTECTED] ConfigurePager} and
+ * [EMAIL PROTECTED] RenderPager} tags respectively.
* </p>
+ * <p>
+ * Inside of the [EMAIL PROTECTED] Header} and [EMAIL PROTECTED] Rows}
rendering regions, the data grid renders HTML table cells. The
+ * data grid tag set provides a set of tags that can be used render these
cells with varying content including:
+ * <ul>
+ * <li>HTML <th> cells -- these are generally used inside the [EMAIL
PROTECTED] Header}</li>
+ * <li>anchors -- these can be rendered using the [EMAIL PROTECTED]
AnchorCell} tag</li>
+ * <li>images -- these can be rendered using the [EMAIL PROTECTED] ImageCell}
tag</li>
+ * <li>image anchors-- these can be rendered using the [EMAIL PROTECTED]
ImageAnchorCell} tag</li>
+ * <li>HTML spans -- these can be rendered using the [EMAIL PROTECTED]
SpanCell} tag</li>
+ * </ul>
+ * The [EMAIL PROTECTED] TemplateCell} tag can be used as a container for
arbitrary content that may be included in a cell's
+ * contents. The [EMAIL PROTECTED] Footer} tag's content can also use these
tags.
+ * </p>
+ * <p>
+ * When the data grid renders its data set, the <code>container</code> JSP EL
implicit object is exposed in the
+ * JSP's [EMAIL PROTECTED] JspContext} and can be referenced using the
<code>${contaimer}</code> JSP EL expression. The
+ * <i>current</i> item of data from the data set can be referenced using the
<code>${container.item}</code>
+ * expression. If the item had a <code>name</code> property, it could be
referenced as
+ * <code>${container.item.name}</code>. By default, the data grid renders a
paged data set which will only
+ * display a portion of the complete data set. The default page size is
[EMAIL PROTECTED] PagerModel#DEFAULT_PAGE_SIZE}
+ * and can be changed by setting the [EMAIL PROTECTED]
ConfigurePager#setPageSize(int)} attribute.
+ * </p>
+ * <p>
+ * In addition to rendering a data grid, this tag set cooperates with a set of
state management services exposed
+ * via the [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.DataGridStateFactory}. These
services
+ * help to manage state related to paging, sorting, and filtering. For
example, the first row displayed
+ * in the grid's current page and the sorts for a particular column of data
are can be read / written using these
+ * state objects. The data grid will use various state information from these
classes at reunder time. For example,
+ * when rendering a paged data set, the data grid will use the
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.DataGridStateFactory} to
obtain a [EMAIL PROTECTED] PagerModel}
+ * which can be used to determine the current
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.pager.PagerModel#getRow()}.
The grid will then
+ * use this row value to advance the grid to the appropriate page to display.
+ * </p>
+ * <p>
+ * By default, the data grid uses a configuration JavaBean which provides
instances of state containers and services
+ * that are used to maintain state and render grid markup. This config object
is a subclass of
+ * [EMAIL PROTECTED] DataGridConfig} and is obtained via the [EMAIL PROTECTED]
DataGridConfigFactory}. The default implementation is
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.runtime.config.DefaultDataGridConfig}.
Page authors
+ * may provide their own implementations of this object and set an instance via
+ * [EMAIL PROTECTED]
#setDataGridConfig(org.apache.beehive.netui.databinding.datagrid.api.DataGridConfig)}.
This cax be
+ * used to change default behaviors, change the appearance of the pager, and
change the messages displayed
+ * during rendering among other things.
+ * </p>
+ * <p>
+ * A simple, sortable, and pageable data grid that uses a first / previous //
next / last pager might be
+ * written as:
+ * <pre>
+ * <netui-data:dataGrid dataSource="pageScope.zooAnimals">
+ * <netui-data:configurePager disableDefaultPager="true"
pageAction="page" pagerFormat="firstPreviousNextLast"/>
+ * <netui-data:caption>
+ * <netui-data:renderPager/>
+ * <netui-data:caption>
+ * <netui-data:header>
+ * <netui-data:heaederCell value="Animal"
sortExpression="animal"/>
+ * <netui-data:heaederCell value="Quantity"
sortExpression="quantity"/>
+ * <netui-data:heaederCell value="Details"/>
+ * </netui-data:header>
+ * <netui-data:rows>
+ * <netui-data:spanCell value="${container.item.animalName}"/>
+ * <netui-data:spanCell value="${container.item.quantity}"/>
+ * <netui-data:anchorCell action="details" value="Details">
+ * <netui:parameter name="animalId"
value="${container.item.animalId}"/>
+ * </netui-data:anchorCell>
+ * </netui-data:rows>
+ * </netui-data:dataGrid>
+ * </pre>
+ * This data grid would render an HTML table with a <caption> that
contains a first / previous // next / last
+ * formated pager. The data grid would display a page with ten data rows and
three columns. The header
+ * contains the column titles with clickable sorting links for sorting by the
animal name and quantity. The
+ * body of the data grid contains three cells per row containing two HTML
<span> tags and an HTML anchor
+ * which will navigate to a Page Flow action caclled <code>details</code> when
clicked.
+ * </p>
+ *
* @jsptagref.tagdescription
+ * <p>
+ * This tag is the containing tag for all tags and markup used to render a
data grid. In its simplest form, a data
+ * grid is an HTML table containing an HTML table row for every item in a data
set. The data grid also provides
+ * functionality for rendering the following major regions:
+ * <ul>
+ * <li>a header -- a header contains the top-most rows in a data grid's HTML
table and is rendered using
+ * the [EMAIL PROTECTED] Header} tag</li>
+ * <li>data rows -- markup rendered in the data grid for each record in the
data set must be contained
+ * in a [EMAIL PROTECTED] Rows} tag</li>
+ * <li>a footer -- a footer contains the bottom-most rows in a data grid's
HTML table and is rendered using the
+ * [EMAIL PROTECTED] Footer} tag</li>
+ * <li>caption -- an HTML table caption appears at the top of the table and is
rendered using the
+ * [EMAIL PROTECTED] Caption} tag.</li>
+ * </ul>
+ * In addition, a data grid can also configure and render a pager using the
[EMAIL PROTECTED] ConfigurePager} and
+ * [EMAIL PROTECTED] RenderPager} tags respectively.
+ * </p>
+ * <p>
+ * Inside of the [EMAIL PROTECTED] Header} and [EMAIL PROTECTED] Rows}
rendering regions, the data grid renders HTML table cells. The
+ * data grid tag set provides a set of tags that can be used render these
cells with varying content including:
+ * <ul>
+ * <li>HTML <th> cells -- these are generally used inside the [EMAIL
PROTECTED] Header}</li>
+ * <li>anchors -- these can be rendered using the [EMAIL PROTECTED]
AnchorCell} tag</li>
+ * <li>images -- these can be rendered using the [EMAIL PROTECTED] ImageCell}
tag</li>
+ * <li>image anchors-- these can be rendered using the [EMAIL PROTECTED]
ImageAnchorCell} tag</li>
+ * <li>HTML spans -- these can be rendered using the [EMAIL PROTECTED]
SpanCell} tag</li>
+ * </ul>
+ * The [EMAIL PROTECTED] TemplateCell} tag can be used as a container for
arbitrary content that may be included in a cell's
+ * contents. The [EMAIL PROTECTED] Footer} tag's content can also use these
tags.
+ * </p>
+ * <p>
+ * When the data grid renders its data set, the <code>container</code> JSP EL
implicit object is exposed in the
+ * JSP's [EMAIL PROTECTED] JspContext} and can be referenced using the
<code>${contaimer}</code> JSP EL expression. The
+ * <i>current</i> item of data from the data set can be referenced using the
<code>${container.item}</code>
+ * expression. If the item had a <code>name</code> property, it could be
referenced as
+ * <code>${container.item.name}</code>. By default, the data grid renders a
paged data set which will only
+ * display a portion of the complete data set. The default page size is
[EMAIL PROTECTED] PagerModel#DEFAULT_PAGE_SIZE}
+ * and can be changed by setting the [EMAIL PROTECTED]
ConfigurePager#setPageSize(int)} attribute.
+ * </p>
+ * <p>
+ * In addition to rendering a data grid, this tag set cooperates with a set of
state management services exposed
+ * via the [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.DataGridStateFactory}. These
services
+ * help to manage state related to paging, sorting, and filtering. For
example, the first row displayed
+ * in the grid's current page and the sorts for a particular column of data
are can be read / written using these
+ * state objects. The data grid will use various state information from these
classes at reunder time. For example,
+ * when rendering a paged data set, the data grid will use the
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.DataGridStateFactory} to
obtain a [EMAIL PROTECTED] PagerModel}
+ * which can be used to determine the current
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.api.pager.PagerModel#getRow()}.
The grid will then
+ * use this row value to advance the grid to the appropriate page to display.
+ * </p>
+ * <p>
+ * By default, the data grid uses a configuration JavaBean which provides
instances of state containers and services
+ * that are used to maintain state and render grid markup. This config object
is a subclass of
+ * [EMAIL PROTECTED] DataGridConfig} and is obtained via the [EMAIL PROTECTED]
DataGridConfigFactory}. The default implementation is
+ * [EMAIL PROTECTED]
org.apache.beehive.netui.databinding.datagrid.runtime.config.DefaultDataGridConfig}.
Page authors
+ * may provide their own implementations of this object and set an instance via
+ * [EMAIL PROTECTED]
#setDataGridConfig(org.apache.beehive.netui.databinding.datagrid.api.DataGridConfig)}.
This cax be
+ * used to change default behaviors, change the appearance of the pager, and
change the messages displayed
+ * during rendering among other things.
+ * </p>
+ * <p>
+ * A simple, sortable, and pageable data grid that uses a first / previous //
next / last pager might be
+ * written as:
+ * <pre>
+ * <netui-data:dataGrid dataSource="pageScope.zooAnimals">
+ * <netui-data:configurePager disableDefaultPager="true"
pageAction="page" pagerFormat="firstPreviousNextLast"/>
+ * <netui-data:caption>
+ * <netui-data:renderPager/>
+ * <netui-data:caption>
+ * <netui-data:header>
+ * <netui-data:heaederCell value="Animal"
sortExpression="animal"/>
+ * <netui-data:heaederCell value="Quantity"
sortExpression="quantity"/>
+ * <netui-data:heaederCell value="Details"/>
+ * </netui-data:header>
+ * <netui-data:rows>
+ * <netui-data:spanCell value="${container.item.animalName}"/>
+ * <netui-data:spanCell value="${container.item.quantity}"/>
+ * <netui-data:anchorCell action="details" value="Details">
+ * <netui:parameter name="animalId"
value="${container.item.animalId}"/>
+ * </netui-data:anchorCell>
+ * </netui-data:rows>
+ * </netui-data:dataGrid>
+ * </pre>
+ * This data grid would render an HTML table with a <caption> that
contains a first / previous // next / last
+ * formated pager. The data grid would display a page with ten data rows and
three columns. The header
+ * contains the column titles with clickable sorting links for sorting by the
animal name and quantity. The
+ * body of the data grid contains three cells per row containing two HTML
<span> tags and an HTML anchor
+ * which will navigate to a Page Flow action caclled <code>details</code> when
clicked.
+ * </p>
* @netui:tag name="dataGrid" body-content="scriptless"
- * description="Top-level data grid tag for the data grid tag set.
- * Renders a pageable, sortable, and filterable HTML table containing a data
set"
+ * description="Containing tag for tags in the data grid tag set.
+ * Renders a pageable, sortable, and filterable HTML
table containing a data set"
*/
public class DataGrid
extends AbstractDataGridHtmlTag
