ECSIDE标签

ECSIDE标签之<ec:table>标签的属性说明与使用  

EC side是基于jsp tag的开源列表组件，可以帮助我们快速实现墙大的列表的jsp标签。EC side可以展现列表（分页）、排序、过滤。

工作原理很简单：

先将要展现的列表的数据集合(Collection),放入request或者pagecontext或者session内(使用setAttribute方法.这个工作可以在action/servlet里完成,也可以在jsp页面内完成),然后页面跳转到使用ECSide标签的jsp页面,此时ECSide就可以帮助您展现出所需要的列表。

一个简单的流程通常是这样的：

1、客户端请求action/servlet。

2、action接受到请求后,调用相应的BO/dao,执行取列表数据的方法 。

3、取得数据后(通常是一个vo/map的list)，将数据放入request内(使用requset.setAttribute(name,value)方法。

4、将请求forward到使用ECSide标签的jsp页面。

5、ECSide将展现出列表。

<ec:table></ec:table>中的属性说明

◆ 属性: tableId  描述:  
设置列表的唯一标识,默认为"ec",当一个页面内有多个ECSIDE列表时,必须为每个列表指定不同的tableId.

◆ 属性: items  描述:  
设置要展现的数据对应的集合在内存中存放时使用的名字，也就是request.setAttribute("recordList", list);

◆ 属性: var  描述:  
设置指向数据迭代中的当前记录所对应的bean（是JavaBean）的变量的名称

◆ 属性: action  描述:  
列表执行翻页 过滤 排序等操作时所要提交的action

◆ 属性: insertAction  描述:  
可编辑列表时,插入数据所要提交的action

◆ 属性: updateAction  描述:  
可编辑列表时,更新数据所要提交的action

◆ 属性: deleteAction  描述:  
可编辑列表时,删除数据所要提交的action

◆ 属性: shadowRowAction  描述:  
显示shadowRow时所要提交的action

◆ 属性: theme  描述:  
设置列表的风格所使用的主题. 默认为ecside.

◆ 属性: generateScript  描述:  
是否自动生成ECSide所需的js脚本. 可选 true/false ( 默认:true )

◆ 属性: useAjax  描述:  
是否使用ajax技术进行翻页、过滤、排序等操作. 可选 true/false ( 默认:true )

◆ 属性: doPreload  描述:  
是否使用预读取技术. 可选 true/false ( 默认:true )

◆ 属性: classic  描述:  
是否使用传统的简单列表. 可选 true/false ( 默认:false )

◆ 属性: autoIncludeParameters  描述:  
是否开启"自动保留"特性.翻页 过滤 排序时当前页的表单域将以hidden input的形式被保留(传递到新页面). 可选 true/false ( 默认:true )  关于此项的更多说明可参见原版ec手册

◆ 属性: includeParameters  描述:  
在关闭"自动保留"时,希望被自动保留的表单域的标示,支持多个,用","分割

◆ 属性: excludeParameters  描述:  
在开启"自动保留"时,希望不被自动保留的表单域的标示,支持多个,用","分割  补充:  如果理解了 autoIncludeParameters 的用处 就不难理解以上两个属性的用处了  注意: excludeParameters 比 includeParameters 有更高的优先级  即 excludeParameters="a" includeParameters ="a" 时 a仍然将被排除，建议尽量使用 excludeParameters 不要使用 includeParameters ，除非你非常明确自己要包含的东西。  includeParameters 使用不当会使你忘记包含一些必须包含的东西.  excludeParameters="表单属性名称1,表单属性名称2" (表单属性名称不能含有半角的逗号)  includeParameters="表单属性名称3,表单属性名称4"

◆ 属性: toolbarContent  描述:  
设置工具条要显示的内容,以及各个元素的前后位置.  默认状态是 toolbarContent="navigation|pagejump |pagesize|refresh save add del|export|extend|status"  
例子 toolbarContent="pagejump|navigation|export|extend|status"  此时 工具条将不显示"页面行数调整"框和"刷新 保存 增删按钮" 同时顺序也会和默认的发生变化navigation 导航条  pagejump 页面跳转  pagesize 页面行数设置  refresh 刷新当前页  save 保存列表记录  add 添加记录  del 删除记录  export 导出按钮区  extend 自定义扩展区  status 数据信息区

◆ 属性: toolbarLocation  描述:  
设置工具条要显示的位置(列表的上面还是下面). 可选top/bottom/none, 默认top.

◆ 属性: paginationLocation  描述:  
同toolbarLocation.  
◆ 属性: rowsDisplayed  描述:  
设置每页显示的默认记录条数.

◆ 属性: pageSizeList  描述:  
设置调整"每页记录数"的下拉框内的候选值.  例如: pageSizeList="10,20,50,100,1000,2000,all"  其中的all为增加全部显示功能。  例子 pageSizeList="10,20,50"  
此时列表里将只显示 10 20 50供选择  max:数字 特性 :  pageSizeList="max:200,10,15,30,50,100,all"  如果 10--100以及all中，某一项大过了max的200则 不在列表中显示。  
也可以只使用pageSizeList="max:200" 此时将 使用默认设置，并用max限制。

◆ 属性: nearPageNum  描述:  
设置"邻近页导航"的前后区间范围

◆ 属性: maxRowsExported  描述:  
设置导出和打印操作所允许的最大记录条数

◆ 属性: resizeColWidth  描述:  
是否允许调整列宽. 可选 true/false ( 默认:true )

◆ 属性: minColWidth  描述:  
设置调整列宽时,任意一列所允许的最小宽度

◆ 属性: height  描述:  
设置列表的高度.

◆ 属性: minHeight  描述:

设置列表的最小高度

◆ 属性: xlsFileName  描述:  
设置导出xls的文件的文件名. 不指定时为不允许导出xls文件

◆ 属性: pdfFileName  描述:  
设置导出pdf的文件的文件名. 不指定时为不允许导出pdf文件

◆ 属性: csvFileName  描述:  
设置导出csv的文件的文件名. 不指定时为不允许导出csv文件

◆ 属性: showPrint  描述:  
是否显示打印按钮. true/false.

◆ 属性: editable  描述:  
是否开启可编辑列表功能.

◆ 属性: sortable  描述:  
是否允许对列表进行按列排序

◆ 属性: filterable  描述:  
是否开启过滤功能.

◆ 属性: title  描述:  
设置列表的标题,该标题将显示在列表的上方.

◆ 属性: showTitle  描述:  
是否显示列表的title.

◆ 属性: style  描述:  
设置列表的table的style,相当于html里的style.

◆ 属性: styleClass  描述:  
设置列表的table的style class,相当于html里的class.

◆ 属性: locale  描述:  
设置列表的本地化信息. 例如 fr_FR 将使列表使用法文方式显示(前提是已经正确提供相关资源文件).  
◆ 属性: interceptor  描述:  
自定义列表拦截器.值为对应的拦截器的实现.  该拦截器可用来添加或修改列表的属性

◆ 属性: retrieveRowsCallback  描述:

指定列表所使用的分页机制.值可以是自定义的完整的callback类名,也可以是在properties文件内指定的简称  
◆ 属性: filterRowsCallback  描述:  
指定列表所使用的过滤机制.值可以是自定义的完整的callback类名,也可以是在properties文件内指定的简称  
◆ 属性: sortRowsCallback  描述:  
指定列表所使用的排序机制.值可以是自定义的完整的callback类名,也可以是在properties文件内指定的简称  关于以上三个属性的使用请见"ECSide列表的RowsCallback机制"文档.

◆ 属性: width  描述:  
指定列表的宽度.相当于<table>的width属性

◆ 属性: listWidth  描述:  
Specify the location of pagination bar . Acceptable values are up or down.

◆ 属性: listHeight  描述:  
Specify the location of pagination bar . Acceptable values are up or down.

◆ 属性: height  描述:  
指定列表的高度.相当于<table>的height属性.当值为"auto"时,列表高度将随着列表内容自动调整.  只有在非classic模式下才有效.

◆ 属性: excludeTool  描述:  
Specify whether or not to show the rows displayed bar . Acceptable values are "true" or "false".

◆ 属性: showHeader  描述:  
是否显示列表表头

<ec:row></ec:row>中的属性说明

◆ 属性: rowId  描述:  
列表的行的id,对应<tr>的id属性.

◆ 属性: recordKey  描述:  
行所对应的记录的唯一主键值,主要用于gird列表的删改

◆ 属性: highlightRow  描述:  
鼠标经过某行时,该行是否变色.

◆ 属性: selectlightRow  描述:  
鼠标点击某行时,该行是否变色.

◆ 属性: interceptor  描述:  
自定义行拦截器.值为对应的拦截器的实现.  该拦截器可用来添加或修改行的属性

◆ 属性: ondblclick  描述:  
定义鼠标双击事件.相当于<tr>的ondblclick事件

◆ 属性: onclick  描述:  
定义鼠标的单击事件.相当于<tr>的onclick事件

◆ 属性: onmouseout  描述:  
定义鼠标的onmouseout事件.相当于<tr>的onmouseout事件

◆ 属性: onmouseover  描述:  
定义鼠标的onmouseover事件.相当于<tr>的onmouseover事件

◆ 属性: style  描述:  
相当于<tr>的style.

◆ 属性: styleClass  描述:  
相当于<tr>的class.  <ec:extend>标签 具体的内容可以是任何合法的HTML代码

◆ 属性: location  描述:  
在什么位置添加扩展内容.  top: 列表上方(在列表外部)  bottom: 列表下方(在列表外部)  留空: 工具条的 extend扩展区<ec:extendrow>标签  扩展一行.具体的内容可以是任何合法的<tr>相关的HTML代码

◆ 属性: location  描述:  
在什么位置添加扩展内容.  bottom: 列表内部的下方,和列表内容主体在一个<table>内  留空: 同上

<ec: column></ec: column >中的属性  
◆ 属性: columnId  描述:  
单元格的id,相当于<td>的id属性

◆ 属性: title  描述:  
列在列表表头里显示的名称.

◆ 属性: property  描述:  
指定该列所对应的列表bean<是JavaBean>(map)的属性(key).

◆ 属性: alias  描述:

列的别名.

◆ 属性: value  描述:  
列的数值.默认为当前行当前列对应的列表bean<还是JavaBean>(map)的属性的值.

◆ 属性: viewsAllowed  描述:  
指定当前列将在那些视图中被显示,可选项为:html xls csv pdf print  分别对应于页面展现,导出,打印

◆ 属性: viewsDenied  描述:  
指定当前列将在那些视图中被隐藏,可选项为:html xls csv pdf print  分别对应于页面展现,导出,打印

◆ 属性: tipTitle  描述:  
单元格的提示信息,,相当于<td>的title属性

◆ 属性: group  描述:  
是否对当前列进行编组. true/false.

◆ 属性: resizeColWidth  描述:  
是否允许调整该列的列宽  table为classic时无效

◆ 属性: minWidth  描述:  
允许调整列宽时,该列所允许的最小宽度,单位像素.

◆ 属性: sortable  描述:  
是否允许对该列进行排序.

◆ 属性: filterable  描述:  
是否允许对该列进行过滤操作.

◆ 属性: editable  描述:  
单元格是否允许编辑.

◆ 属性: cellValue  描述:  
单元格对应的值,详见"ECSide可编辑列表的使用指南"

◆ 属性: editTemplate  描述:  
编辑时,所使用的模板名称,详见"ECSide可编辑列表的使用指南"

◆ 属性: editEvent  描述:  
进入编辑转台所使用的页面事件,默认为双击,详见"ECSide可编辑列表的使用指南"

◆ 属性: mappingItem  描述:  
实现单元格的值,与显示的内容的映射.mappingItem的值为进行映射所使用的map在内存中存放的名称

◆ 属性: calc  描述:  
指定列所使用的统计方式.值可以是自定义的完整的calc类名,也可以是在properties文件内指定的简称,多个之间用","分割.  自带的统计有两种total(求和)与average(求平均值).

◆ 属性: calcTitle  描述:  
指定列所使用的统计方式所对应的统计名称,例如合计,平均等等.多个之间用","分割.

◆ 属性: calcSpan  描述:  
统计行的统计名称单元格所占用的列数.相当于<td>的colspan属性

◆ 属性: cell  描述:  
指定列表内该列所使用的cell的实现类.值可以是自定义的完整的cell类名,也可以是在properties文件内指定的简称

◆ 属性: interceptor  描述:  
自定义列拦截器.值为对应的拦截器的实现.  该拦截器可用来添加或修改列的属性

◆ 属性: escapeAutoFormat  描述:  
是否不进行自动格式的转换.

◆ 属性: format  描述:  
The format to use for the cell. For instance if used with a date cell then the format can be MM/dd/yyyy.

◆ 属性: parse  描述:  
Used if the format needs to be interpreted. For instance, a date needs to be parsed in the specific format, such as MM-dd-yyyy.

◆ 属性: ondblclick  描述:  
定义鼠标双击事件.相当于<td>的ondblclick事件

◆ 属性: onclick  描述:  
定义鼠标的单击事件.相当于<td>的onclick事件

◆ 属性: onmouseout  描述:  
定义鼠标的onmouseout事件.相当于<td>的onmouseout事件

◆ 属性: onmouseover  描述:  
定义鼠标的onmouseover事件.相当于<td>的onmouseover事件

◆ 属性: style  描述:  
相当于<td>的style.

◆ 属性: styleClass  描述:  
相当于<td>的class.

◆ 属性: width  描述:  
设置列的宽度.相当于<td>的width属性

◆ 属性: nowrap  描述:  
设置列的宽度.相当于<td>的nowrap属性

 

首先ecside展现列表、排序、过滤(该三种操作以下简称为 RSF )的实现原理完全和原版EC一样, 
如果您对原版EC的retrieveRowsCallback、sortRowsCallback、filterRowsCallback 非常熟悉，那么可以忽略此文.

先来简单介绍一下RSF操作方式. 
ecside对数据的展现操作有三种:分页展现,按列排序(目前只支持单列),按列过滤(支持多列联合过滤) 
(该三种操作以下简称为 RSF )

ecside提供了两种方式来实现RSF操作 : 基于java collection层 和 基于数据库层,下面先简单介绍一下原理:

========================================================= 
一:基于java collection层: 
这是ec的默认实现方式, 最简单易用.

您要做的就是将整个列表所要展现的全部数据放入collection 内,并交给EC来处理. 
其中RSF操作,全部由EC在内存中完成,由于您已经将全部数据放入了collection中, 
所以排序 过滤都是基于全部数据的.

您要在DAO中做的就是一个 查询操作,SQL语句中不需要加入 关于排序 分页 过滤的代码.

这种方式的优点非常明显:实现简单.

缺点同样明显,而且在很大程度上是致命的: 数据量大的时候速度慢,而且很可能outofmemery.

这时候我们就需要第二种方式了:

方式一您所要做的工作: 
1 通过DAO,查询出所有的数据,放入collection内 
2 将collection传给列表页面

二:基于数据库层:

在这种方式下,EC的角色发生了一点点变化. 
此时,EC负责把 collection 里的内容展现出来, 同时会向您提供RSF相关的参数. 
而这些参数需要您自己手动取得 并传入到DAO中(当然EC提供了很多方便的方法来帮助您取得这些参数), 
具体功能的实现需要您自己在DAO中组织相应的SQL语句.

方式二您所要做的工作: 
1 查询出所有的数据的总数 
2 取得一个ECSide提供的Limit对象 
3 在该对象的帮助下取得RSF操作的相关信息(如 数据的起止行数,排序的列和顺序,过滤的列和内容) 
4 将RSF操作的相关信息传入DAO内,来进行SQL语句的拼装(或者其他的操作,如使用ORM工具时)
5 通过DAO,查询出当前页所要显示的数据,放入collection内 
6 将collection传给列表页面

这种方式的优缺点正好和方式一相反.

关于两种方式的配置可以看一下 ecside.properties 文件中的下列内容

1. table.filterRowsCallback.process=org.extremecomponents.table.callback.ProcessRowsCallback
2. table.filterRowsCallback.limit=org.extremecomponents.table.callback.LimitCallback
3. table.sortRowsCallback.process=org.extremecomponents.table.callback.ProcessRowsCallback
4. table.sortRowsCallback.limit=org.extremecomponents.table.callback.LimitCallback
5. table.retrieveRowsCallback.process=org.extremecomponents.table.callback.ProcessRowsCallback
6. table.retrieveRowsCallback.limit=org.extremecomponents.table.callback.LimitCallback

其中 ProcessRowsCallback 采用了方式一 ,LimitCallback采用了方式二 
而table.retrieveRowsCallback.default会告诉EC您默认使用的是哪个. 
同样您也可以在 ec:table 标签里 指定

1. <ec:table filterRowsCallback="process/limit"  sortRowsCallback="process/limit"  retrieveRowsCallback="process/limit" ... >

大家可能还看到了 org.ecside.table.callback.CommonLimitCallback 这个是我自己随意组合出来的一个rowcallback 
他在执行分页的时候,使用了方式二,而排序 过滤的时候使用了方式一 
所以,大家可能会发现,DEMO中的排序 过滤方法只对当前页有效. 
我这么做其实是一种偷懒的方式,但多数情况下,正如网友所说"只排当页数据毫无意义",您们说的没错,的确如此:)

========================================== 
下面看一个简单的例子: (以 struts + dao 的方式演示,例子中采用的是ECSide 2.0 RC1版本)

jsp代码

1. <ec:table
2. retrieveRowsCallback="limit"
3. sortRowsCallback="limit"
4. filterRowsCallback="limit"
5. ...... >
6. ......
7. </ec:table>

在上面的JSP代码中,指定了所有的RSF操作都使用基于数据库层的.

action的代码

//默认每页显示的记录条数
    protected static int DEFAULT_PAGE_SIZE = 20;  

// 数据库端分页,适合数据量较大的情况
    public ActionForward doQuery(ActionMapping mapping, ActionForm form,
    HttpServletRequest request, HttpServletResponse response)
    throws Exception {
        UserInfoDAO userInfoDAO=(UserInfoDAO)getBean("userInfoDAO");  

// 当列表的分页 过滤 排序等操作是基于数据库时,必须要用到Limit对象.
// 注意,当页面有多个ec的时候,需要使用带 tableId参数的同名方法.
    //Limit limit=RequestUtils.getLimit(request,"ecGird的Id");  

        Limit limit=RequestUtils.getLimit(request);
// 基于数据库的排序.
// ECSide会帮助开发人员取得排序的相关信息:当前是按哪个(目前只支持单列排序)column排序的,以及排序的方式desc或asc,
// 这个信息以key-value方式存放在map里.
// 但是至于如果处理这些信息(如组装成sql语句),则是由开发人员自己在DAO里完成的.
        Sort sort=limit.getSort();
        Map sortValueMap = sort.getSortValueMap();  

// 基于数据库过滤.
// ECSide会帮助开发人员取得过滤的相关信息:当前是对哪些column进行过滤,以及过滤的内容是什么,这个信息以key-value方式存放在map里.
// 但是至于如果处理这些信息(如组装成sql语句),则是由开发人员自己在DAO里完成的.
        FilterSet filterSet =limit.getFilterSet();
        Map filterPropertyMap=filterSet.getPropertyValueMap();  

// 在本例中, sort 和 filter 相关信息将被传入 DAO,用于拼装sql语句.
// 其实,此时的排序 过滤就和我们以前的传统的查询非常类似:从查询页面取得查询条件,传入DAO.                 

// RequestUtils.getTotalRowsFromRequest(request);是一个工具类,用来从ECSIDE的列表中取得上次计算出的总行数
// 如果您不希望每次翻页都重新计算总行数,那么建议参考下面几行代码的做法.    

        int totalRows = RequestUtils.getTotalRowsFromRequest(request);
        if (totalRows < 0) {
// TODO ：  userInfoDAO.getUserInfoNumber()为能够取得总行数的方法，请替换为实际的实现。
// 取得记录总条数时,不要忘了把filter作为参数传入,因为要取得的总行数也是要接受条件限制的.
            totalRows = userInfoDAO.getUserInfoNumber(filterPropertyMap);
        }  

// DEFAULT_PAGE_SIZE ==0 时, 每页记录数会使用 properties文件内的默认设置
// DEFAULT_PAGE_SIZE <0 时, 每页记录数会等于全部记录数
        limit.setRowAttributes(totalRows, DEFAULT_PAGE_SIZE);  

//取得当前要查询的页面的记录起止行号
// offset表示数据编号的起始号. ORACLE数据库一般是从1开始的,HSQLDB是从0开始,默认是从0开始计数,在这里我们使用从0开始.
        int offset=0;
        int[] rowStartEnd =new int[] { limit.getRowStart() + offset, limit.getRowEnd() + offset };  

// TODO ：  userInfoDAO.getSomeUserInfo(rowStartEnd[0], rowStartEnd[1])
// 为查询记录的方法，请替换为实际的实现。rowStartEnd[0], rowStartEnd[1]为起止行
// rowStartEnd[0], rowStartEnd[1] 左闭 右开
        List rslist = userInfoDAO.getSomeUserInfo(rowStartEnd[0], rowStartEnd[1],sortValueMap,filterPropertyMap);  

        request.setAttribute("recordList", rslist);  

// 字典数据. 一个Map,存放的是  "编号" 到 "显示的文字" 的映射
        request.setAttribute("GENDER_MAP", CommonDictionary.GENDER);
        request.setAttribute("USERROLE_MAP", CommonDictionary.USERROLE);  

        return mapping.findForward("listPage");
    }  

其实上面的代码和代码里的注释已经说的比较明白了.

DAO里的代码

public List getSomeUserInfo(int startRow,int endRow,Map sortValueMap,Map filterPropertyMap){
    StringBuffer bufSql = new StringBuffer();
    int size=endRow-startRow;  

// 使用传统JDBC时,根据不同条件拼装不同的SQL一向是非常恼人的事情.
// ECSide当然不能够帮助您解决这个问题.
// 再次重申一遍,当翻页 过滤 排序 均基于数据库时,ECSide只是能够帮助开发者在后台更方便的取得操作相关的数据.
// 而如何使用他们,仍然需要开发人员自己来决定.  

    bufSql.append("SELECT * FROM ");  

    StringBuffer whereSql = new StringBuffer(" WHERE 1=1 ");  

    if (filterPropertyMap!=null && !filterPropertyMap.isEmpty()){
// 根据过滤条件进行sql语句的拼装.  

// 在本例中,只有 USERROLE USERNAME GENDER 是可以进行过滤的.
// 在这里偷下懒,就不用 PreparedStatement 的方式了,而是直接把过滤项拼装进sql语句内.
        String filterProperty;
        String filterValue;  

        filterProperty="USERROLE";
        filterValue=(String)filterPropertyMap.get(filterProperty);
        if (filterValue!=null){
            whereSql.append(" AND ").append(filterProperty).append(" = '").append(StringEscapeUtils.escapeSql(filterValue)).append("' ");
        }  

        filterProperty="USERNAME";
        filterValue=(String)filterPropertyMap.get(filterProperty);
        if (filterValue!=null){
            whereSql.append(" AND ").append(filterProperty).append(" like '").append(StringEscapeUtils.escapeSql(filterValue)).append("' ");
        }  

        filterProperty="GENDER";
        filterValue=(String)filterPropertyMap.get(filterProperty);
        if (filterValue!=null){
            whereSql.append(" AND ").append(filterProperty).append(" = '").append(StringEscapeUtils.escapeSql(filterValue)).append("' ");
        }
    }  

    if (sortValueMap!=null && !sortValueMap.isEmpty()){
        bufSql.append("( SELECT * FROM USER_INFO  ");
        bufSql.append(whereSql);
        bufSql.append(ECSideUtils.getDefaultSortSQL(sortValueMap));
        bufSql.append(" ) ");
    }else{
        bufSql.append(" USER_INFO ");
        bufSql.append(whereSql);
    }  

    bufSql.append(" LIMIT ? OFFSET ?");  

    Connection conn=null;
    PreparedStatement pstmt = null;
    ResultSet rest = null;
    List userList=null;  

    try {
        conn = getConnection();
        pstmt = ConnectionUtils.prepareStatement(conn,bufSql.toString());
        int prarameterIndex=0;  

        pstmt.setInt(++prarameterIndex, size);
        pstmt.setInt(++prarameterIndex, startRow);  

        rest = pstmt.executeQuery();
        String[] columnName=getColumnName(rest);
        userList=new ArrayList();
        Map userInfo=null;
        while (rest.next()) {
            userInfo=new HashMap();
            buildRecord(rest,columnName,userInfo);
            userList.add(userInfo);
        }
    } catch (Exception e) {
        LogHandler.errorLog(logger, e);
        userList=null;
    }finally{
        close(rest, pstmt, conn);
    }  

    return userList;
}  

这个DAO同样没什么好说的了 非常好理解.

以上就是一个简单的实现,最有参考价值的就是ACTION的写法.