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/05/20 00:55:19 UTC
svn commit: r171008 - in
/incubator/beehive/trunk/netui/src/tags-databinding/org/apache/beehive/netui:
databinding/datagrid/runtime/config/DefaultDataGridURLBuilder.java
tags/databinding/datagrid/DataGrid.java
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 {@link 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 {@link org.apache.beehive.netui.databinding.datagrid.api.DataGridConfig}
- * object.
+ * <p>
+ * Package protected constructor. This class is intended only to be created via the default
+ * {@link 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 {@link Map} returned by this method
+ * will maintain the <i>current</i> state of the data grid and all of the associated URL parameters. The
+ * {@link 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 {@link 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 {@link 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 {@link 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 {@link 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
+ * {@link Sort} whose sort expression matches the given sort expression value. The {@link SortStrategy}
+ * associated with the data grid's {@link SortModel} will be used to choose the next
+ * {@link 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 {@link 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 {@link 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 {@link Header} tag</li>
+ * <li>data rows -- markup rendered in the data grid for each record in the data set must be contained
+ * in a {@link 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
+ * {@link Footer} tag</li>
+ * <li>caption -- an HTML table caption appears at the top of the table and is rendered using the
+ * {@link Caption} tag.</li>
+ * </ul>
+ * In addition, a data grid can also configure and render a pager using the {@link ConfigurePager} and
+ * {@link RenderPager} tags respectively.
* </p>
+ * <p>
+ * Inside of the {@link Header} and {@link 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 {@link Header}</li>
+ * <li>anchors -- these can be rendered using the {@link AnchorCell} tag</li>
+ * <li>images -- these can be rendered using the {@link ImageCell} tag</li>
+ * <li>image anchors-- these can be rendered using the {@link ImageAnchorCell} tag</li>
+ * <li>HTML spans -- these can be rendered using the {@link SpanCell} tag</li>
+ * </ul>
+ * The {@link TemplateCell} tag can be used as a container for arbitrary content that may be included in a cell's
+ * contents. The {@link 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 {@link 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 {@link PagerModel#DEFAULT_PAGE_SIZE}
+ * and can be changed by setting the {@link 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 {@link 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
+ * {@link org.apache.beehive.netui.databinding.datagrid.api.DataGridStateFactory} to obtain a {@link PagerModel}
+ * which can be used to determine the current
+ * {@link 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
+ * {@link DataGridConfig} and is obtained via the {@link DataGridConfigFactory}. The default implementation is
+ * {@link org.apache.beehive.netui.databinding.datagrid.runtime.config.DefaultDataGridConfig}. Page authors
+ * may provide their own implementations of this object and set an instance via
+ * {@link #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 {@link Header} tag</li>
+ * <li>data rows -- markup rendered in the data grid for each record in the data set must be contained
+ * in a {@link 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
+ * {@link Footer} tag</li>
+ * <li>caption -- an HTML table caption appears at the top of the table and is rendered using the
+ * {@link Caption} tag.</li>
+ * </ul>
+ * In addition, a data grid can also configure and render a pager using the {@link ConfigurePager} and
+ * {@link RenderPager} tags respectively.
+ * </p>
+ * <p>
+ * Inside of the {@link Header} and {@link 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 {@link Header}</li>
+ * <li>anchors -- these can be rendered using the {@link AnchorCell} tag</li>
+ * <li>images -- these can be rendered using the {@link ImageCell} tag</li>
+ * <li>image anchors-- these can be rendered using the {@link ImageAnchorCell} tag</li>
+ * <li>HTML spans -- these can be rendered using the {@link SpanCell} tag</li>
+ * </ul>
+ * The {@link TemplateCell} tag can be used as a container for arbitrary content that may be included in a cell's
+ * contents. The {@link 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 {@link 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 {@link PagerModel#DEFAULT_PAGE_SIZE}
+ * and can be changed by setting the {@link 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 {@link 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
+ * {@link org.apache.beehive.netui.databinding.datagrid.api.DataGridStateFactory} to obtain a {@link PagerModel}
+ * which can be used to determine the current
+ * {@link 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
+ * {@link DataGridConfig} and is obtained via the {@link DataGridConfigFactory}. The default implementation is
+ * {@link org.apache.beehive.netui.databinding.datagrid.runtime.config.DefaultDataGridConfig}. Page authors
+ * may provide their own implementations of this object and set an instance via
+ * {@link #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