org.apache.beehive.netui.tags.databinding.datagrid
Class DataGrid

Object
  extended by SimpleTagSupport
      extended by AbstractSimpleTag
          extended by AbstractDataGridHtmlTag
              extended by DataGrid
All Implemented Interfaces:
JspTag, SimpleTag, IDataAccessProvider, IBehaviorConsumer, IHtmlCore, IHtmlEvents, IHtmlI18n, INetuiTag

public class DataGrid
extends AbstractDataGridHtmlTag
implements IDataAccessProvider, IBehaviorConsumer, IHtmlCore, IHtmlEvents, IHtmlI18n

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:

In addition, a data grid can also configure and render a pager using the ConfigurePager and RenderPager tags respectively.

Inside of the Header and 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:

The TemplateCell tag can be used as a container for arbitrary content that may be included in a cell's contents. The Footer tag's content can also use these tags.

When the data grid renders its data set, the container JSP EL implicit object is exposed in the JSP's JspContext and can be referenced using the ${contaimer} JSP EL expression. The current item of data from the data set can be referenced using the ${container.item} expression. If the item had a name property, it could be referenced as ${container.item.name}. 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 PagerModel.DEFAULT_PAGE_SIZE and can be changed by setting the ConfigurePager.setPageSize(int) attribute.

In addition to rendering a data grid, this tag set cooperates with a set of state management services exposed via the 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 DataGridStateFactory to obtain a PagerModel which can be used to determine the current PagerModel.getRow(). The grid will then use this row value to advance the grid to the appropriate page to display.

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 DataGridConfig and is obtained via the DataGridConfigFactory. The default implementation is DefaultDataGridConfig. Page authors may provide their own implementations of this object and set an instance via setDataGridConfig(org.apache.beehive.netui.databinding.datagrid.api.DataGridConfig). This can be used to change default behaviors, change the appearance of the pager, and change the messages displayed during rendering among other things.

A simple, sortable, and pageable data grid that uses a first / previous // next / last pager might be written as:

     <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>
 
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 details when clicked.


Constructor Summary
DataGrid()
           
 
Method Summary
 void doTag()
           Render a data grid.
 int getCurrentIndex()
          Get the index of the current item in the data set.
 Object getCurrentItem()
          Get the current item in the data set.
 Object getCurrentMetadata()
          Get metadata for the current item.
 String getDataSource()
          Get the data source for the data grid.
 IDataAccessProvider getProviderParent()
          Get the parent data access provider.
 String getTagName()
          The name of this tag; this value is used for error reporting.
 void setBehavior(String name, Object value, String facet)
           Implementation of the IBehaviorConsumer interface that extends the functionality of this tag beyond that exposed via the JSP tag attributes.
 void setBorder(String border)
          Sets the border attribute for the HTML table tag.
 void setCellpadding(String cellpadding)
          Sets the cellpadding attribute for the HTML table tag.
 void setCellspacing(String cellspacing)
          Sets the cellspacing attribute for the HTML table tag.
 void setDataGridConfig(DataGridConfig dataGridConfig)
           Set the DataGridConfig instance that this tag will use to create state containers and other data grid objects used during rendering.
 void setDataSource(String dataSource)
           Set the data source that references a data set to be rendered by the data grid.
 void setDir(String dir)
          Sets the dir attribute for the HTML table tag.
 void setFrame(String frame)
          Sets the frame attribute for the HTML table tag.
 void setLang(String lang)
          Sets the lang attribute for the HTML table tag.
 void setName(String name)
          Set the name of this data grid.
 void setOnClick(String onClick)
          Sets the onClick JavaScript event for the HTML table tag.
 void setOnDblClick(String onDblClick)
          Sets the onDblClick JavaScript event for the HTML tag.
 void setOnKeyDown(String onKeyDown)
          Sets the onKeyDown JavaScript event for the HTML tag.
 void setOnKeyPress(String onKeyPress)
          Sets the onKeyPress JavaScript event for the HTML tag.
 void setOnKeyUp(String onKeyUp)
          Sets the onKeyUp JavaScript event for the HTML tag.
 void setOnMouseDown(String onMouseDown)
          Sets the onMouseDown JavaScript event for the HTML tag.
 void setOnMouseMove(String onMouseMove)
          Sets the onMouseMove JavaScript event for the HTML tag.
 void setOnMouseOut(String onMouseOut)
          Sets the onMouseOut JavaScript event for the HTML tag.
 void setOnMouseOver(String onMouseOver)
          Sets the onMouseOver JavaScript event for the HTML tag.
 void setOnMouseUp(String onMouseUp)
          Sets the onMouseUp JavaScript event for the HTML tag.
 void setRenderRowGroups(boolean renderRowGroups)
           Sets a boolean that enables / disables rendering of HTML table row groups in the data grid.
 void setResourceBundlePath(String resourceBundlePath)
           Set the resource bundle path used when getting messages from a DataGridResourceProvider during data grid rendering.
 void setRules(String rules)
          Sets the rules attribute for the HTML table tag.
 void setStyle(String style)
          Sets the style for the HTML table tag.
 void setStyleClass(String styleClass)
          Sets the style class for the HTML table tag.
 void setStyleClassPolicy(String stylePolicy)
           Set the name of a CSS policy to use when rendering HTML elements in a data grid.
 void setStyleClassPrefix(String styleClassPrefix)
           Set the style class prefix used to namespace style class names rendered as attributes on HTML tags generated by the data grid.
 void setSummary(String summary)
          Sets the summary attribute for the HTML table tag.
 void setTagId(String tagId)
          Set the name of the tagId for the HTML table tag.
 void setTitle(String title)
          Sets the value of the title attribute for the HTML table tag.
 void setWidth(String width)
          Sets the width attribute for the HTML table tag.
 
Methods inherited from class AbstractDataGridHtmlTag
applyIndexedTagId, applyTagId, lookupDataGridTagModel, renderDefaultNameAndId, renderNameAndId
 
Methods inherited from class AbstractSimpleTag
getBufferBody, getHtmlTag, getIdForTagId, getInlineError, getPageContext, getScriptReporter, getUserLocale, hasErrors, registerTagError, registerTagError, reportErrors, rewriteName, setNonEmptyValueAttribute, setRequiredValueAttribute, write
 
Methods inherited from class SimpleTagSupport
findAncestorWithClass, getJspBody, getJspContext, getParent, setJspBody, setJspContext, setParent
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DataGrid

public DataGrid()
Method Detail

getTagName

public String getTagName()
The name of this tag; this value is used for error reporting.

Specified by:
getTagName in interface INetuiTag
Specified by:
getTagName in class AbstractSimpleTag
Returns:
the String name of this tag

setDataGridConfig

public void setDataGridConfig(DataGridConfig dataGridConfig)

Set the DataGridConfig instance that this tag will use to create state containers and other data grid objects used during rendering. Custom implementations of this class can be provided that will override the defaults set in the DefaultDataGridConfig.


setName

public void setName(String name)
Set the name of this data grid. The name should be a simple String that is used to uniquely identify a data grid inside of a JSP. This value is also used to namespace state information in the URL that is scoped to a data grid. Within a given scope in a page, the page author is responsible for ensuring that this name is unique.


setDataSource

public void setDataSource(String dataSource)

Set the data source that references a data set to be rendered by the data grid. The data source should be a NetUI EL expression and generally looks like a JSP EL expression without the '${' and '}' characters. For example, to reference an array of Employee objects exposed via a NetUI page input, the expression might look like:

     <netui-data:dataGrid dataSource="pageInput.employeeArray" name="employeeGrid">
 
This expression will be evaluated the data grid in order to obtain a reference to the data set.


setStyleClassPrefix

public void setStyleClassPrefix(String styleClassPrefix)

Set the style class prefix used to namespace style class names rendered as attributes on HTML tags generated by the data grid. For example, when using the default style policy without setting this attribute, the style rendered for the generated HTML table tag will be:

   <table class="datagrid">
 
With the style class prefix of foo, the rendered HTML style class will be:
   <table class="foo">
 


setResourceBundlePath

public void setResourceBundlePath(String resourceBundlePath)

Set the resource bundle path used when getting messages from a DataGridResourceProvider during data grid rendering. The resource bundle provided here will entirely override messages obtained from the DataGridResourceProvider and must include all message keys that are used for rendering. In order to replace individual messages, use the behavior available from the setBehavior(String, Object, String) method.


setStyleClassPolicy

public void setStyleClassPolicy(String stylePolicy)

Set the name of a CSS policy to use when rendering HTML elements in a data grid. The data grid supports the default style policy names defined here DefaultDataGridConfig.getStyleModel(String, String).


setRenderRowGroups

public void setRenderRowGroups(boolean renderRowGroups)

Sets a boolean that enables / disables rendering of HTML table row groups in the data grid. When row group rendering is enabled, the data grid tags will produce the thead, tbody, and tfoot HTML tags via the Header, Rows, and Footer tags respectively. In addition, as per the HTML specification, the data grid will reorder the output of the row groups to in order to produce valid HTML. When row group rendering is enabled and a page is using JavaScript, the data grid must be nested inside of a NetUI ScriptContainer in order for JavaScript rendering to be ordered correctly. Legacy JavaScript script mode is not supported by the data grid.


setOnClick

public void setOnClick(String onClick)
Sets the onClick JavaScript event for the HTML table tag.

Specified by:
setOnClick in interface IHtmlEvents
Parameters:
onClick - the onClick event.

setOnDblClick

public void setOnDblClick(String onDblClick)
Sets the onDblClick JavaScript event for the HTML tag.

Specified by:
setOnDblClick in interface IHtmlEvents
Parameters:
onDblClick - the onDblClick event.

setOnKeyDown

public void setOnKeyDown(String onKeyDown)
Sets the onKeyDown JavaScript event for the HTML tag.

Specified by:
setOnKeyDown in interface IHtmlEvents
Parameters:
onKeyDown - the onKeyDown event.

setOnKeyUp

public void setOnKeyUp(String onKeyUp)
Sets the onKeyUp JavaScript event for the HTML tag.

Specified by:
setOnKeyUp in interface IHtmlEvents
Parameters:
onKeyUp - the onKeyUp event.

setOnKeyPress

public void setOnKeyPress(String onKeyPress)
Sets the onKeyPress JavaScript event for the HTML tag.

Specified by:
setOnKeyPress in interface IHtmlEvents
Parameters:
onKeyPress - the onKeyPress event.

setOnMouseDown

public void setOnMouseDown(String onMouseDown)
Sets the onMouseDown JavaScript event for the HTML tag.

Specified by:
setOnMouseDown in interface IHtmlEvents
Parameters:
onMouseDown - the onMouseDown event.

setOnMouseUp

public void setOnMouseUp(String onMouseUp)
Sets the onMouseUp JavaScript event for the HTML tag.

Specified by:
setOnMouseUp in interface IHtmlEvents
Parameters:
onMouseUp - the onMouseUp event.

setOnMouseMove

public void setOnMouseMove(String onMouseMove)
Sets the onMouseMove JavaScript event for the HTML tag.

Specified by:
setOnMouseMove in interface IHtmlEvents
Parameters:
onMouseMove - the onMouseMove event.

setOnMouseOut

public void setOnMouseOut(String onMouseOut)
Sets the onMouseOut JavaScript event for the HTML tag.

Specified by:
setOnMouseOut in interface IHtmlEvents
Parameters:
onMouseOut - the onMouseOut event.

setOnMouseOver

public void setOnMouseOver(String onMouseOver)
Sets the onMouseOver JavaScript event for the HTML tag.

Specified by:
setOnMouseOver in interface IHtmlEvents
Parameters:
onMouseOver - the onMouseOver event.

setStyle

public void setStyle(String style)
Sets the style for the HTML table tag.

Specified by:
setStyle in interface IHtmlCore
Parameters:
style - the html style.

setStyleClass

public void setStyleClass(String styleClass)
Sets the style class for the HTML table tag.

Specified by:
setStyleClass in interface IHtmlCore
Parameters:
styleClass - the html style class.

setTitle

public void setTitle(String title)
Sets the value of the title attribute for the HTML table tag.

Specified by:
setTitle in interface IHtmlCore
Parameters:
title - the title

setLang

public void setLang(String lang)
Sets the lang attribute for the HTML table tag.

Specified by:
setLang in interface IHtmlI18n
Parameters:
lang - the lang

setDir

public void setDir(String dir)
Sets the dir attribute for the HTML table tag.

Specified by:
setDir in interface IHtmlI18n
Parameters:
dir - the dir

setSummary

public void setSummary(String summary)
Sets the summary attribute for the HTML table tag.

Parameters:
summary - the summary

setWidth

public void setWidth(String width)
Sets the width attribute for the HTML table tag.

Parameters:
width - the width

setBorder

public void setBorder(String border)
Sets the border attribute for the HTML table tag.

Parameters:
border -

setFrame

public void setFrame(String frame)
Sets the frame attribute for the HTML table tag.

Parameters:
frame - the frame

setRules

public void setRules(String rules)
Sets the rules attribute for the HTML table tag.

Parameters:
rules - the rules

setCellspacing

public void setCellspacing(String cellspacing)
Sets the cellspacing attribute for the HTML table tag.

Parameters:
cellspacing - the cell spacing

setCellpadding

public void setCellpadding(String cellpadding)
Sets the cellpadding attribute for the HTML table tag.

Parameters:
cellpadding - the cell padding

setTagId

public void setTagId(String tagId)
              throws JspException
Set the name of the tagId for the HTML table tag.

Specified by:
setTagId in interface IHtmlCore
Parameters:
tagId - the the name of the tagId for the table tag.
Throws:
JspException

setBehavior

public void setBehavior(String name,
                        Object value,
                        String facet)
                 throws JspException

Implementation of the IBehaviorConsumer interface that extends the functionality of this tag beyond that exposed via the JSP tag attributes. This method accepts the following facets:

Facet NameOperation
resourceAdds or overrides a data grid resource key with a new value.
A new resource key is added in order to override a value defined in IDataGridMessageKeys. When a message is overridden or added here, the page author is able to override a single string resource such as a pager mesage or sort href.

Specified by:
setBehavior in interface IBehaviorConsumer
Parameters:
name - the name of the behavior
value - the value of the behavior
facet - th ebehavior's facet
Throws:
JspException - when the behavior's facet isnot recognized

doTag

public void doTag()
           throws JspException,
                  IOException

Render a data grid. This method implements the logic used to iterate through the data grid's rendering states defined in DataGridTagModel.

Specified by:
doTag in interface SimpleTag
Overrides:
doTag in class SimpleTagSupport
Throws:
JspException - when an error occurs evaluating the tag's body
IOException - when an error occurs writing to the output strema

getCurrentIndex

public int getCurrentIndex()
Get the index of the current item in the data set. This is a zero-based absolute index into the entire data set being rendered by the data grid. This value should only be data bound inside of the Rows.

Specified by:
getCurrentIndex in interface IDataAccessProvider
Returns:
the index of the current item

getCurrentItem

public Object getCurrentItem()
Get the current item in the data set. As the data grid iterates over the data set, this value will change to provide access to the current item in the data set. This value should only be data bound inside of the Rows.

Specified by:
getCurrentItem in interface IDataAccessProvider
Returns:
the current item

getCurrentMetadata

public Object getCurrentMetadata()
Get metadata for the current item. This operation is unsupported on the data grid.

Specified by:
getCurrentMetadata in interface IDataAccessProvider
Returns:
the metadata for the current item
Throws:
UnsupportedOperationException - as this method is unsupported

getDataSource

public String getDataSource()
Get the data source for the data grid. This value returns a NetUI EL expression which can be evaluated by the NetUI tag API.

Specified by:
getDataSource in interface IDataAccessProvider
Returns:
the expression

getProviderParent

public IDataAccessProvider getProviderParent()
Get the parent data access provider. This method requires access to the tag hierarchy and is not usable across tag file or JSP include rendering boundaries. The result of this method is used for evaluating expressions of the form ${container.container} where this tag's parent repeating tag is referenced.

Specified by:
getProviderParent in interface IDataAccessProvider
Returns:
the parent data access provider