ecside使用文档.doc

Ecside使用文档
1.EC Side介绍：
EC Side是一个开源的列表组件。他源自著名开源列表组件 eXtremeComponents（http://www.extremecomponents.org），但现在已经脱离eXtremeComponents,独立发展（仍有部分代码来自 eXtremeComponents）。“做最实用易用的列表组件”是ECSide的目标。
2. 工作原理简介：
ECSide是有一个基于jsp tag的开源列表组件.简单的说,它就是一组可以帮助你快速实现强大的列表的jsp标签.它的工作原理很简单.您将要展现的列表的数据集合(Collection),放入request/pagecontext/session内(使用setAttribute方法.这个工作可以在action/servlet里完成,也可以在jsp页面内完成),然后页面跳转到使用ECSide标签的jsp页面,此时ECSide就可以帮助您展现出所需要的列表.
一个简单的流程通常是这样的.
1 客户端请求action/servlet(如 http://10.195.129.101/test/userlist.do)
2 action接受到请求后,调用相应的BO/dao,执行取列表数据的方法.
3 取得数据后(通常是一个vo/map的list),将数据放入request内(使用requset.setAttribute(key,value)方法.)
4 将请求forward到使用ECSide标签的jsp页面.
5 ECSide将展现出列表.
3.功能特点：
1.基于jsp taglib
2.支持文件导出
3.支持数据预读取
4.工具条可配置
5.扩展按钮定制
6.多种分页模式
3.1主要特性
1 可设置工具条位置（上 下 或 不显示）：
ec:table属性增加toolbarLocation 用来控制工具条在上还是在下显示， 可选值 "bottom" "top" "none"（不显示）
2 可设置工具条内容（显示哪些 不显示哪些）：
可自定义工具条显示那些内容，以及排列顺序
默认： toolbarContent="navigation|pagejump |pagesize|refresh save add del|export|extend|status"
例子 toolbarContent="pagejump|navigation|export|extend|status"
此时 工具条将不显示"页面行数调整"框 同时顺序也会和默认的发生变化
navigation 导航条
pagejump 页面跳转
pagesize 页面行数设置
export 导出按钮区
extend 自定义扩展区
status 数据信息区
同时 为ec:table增加属性 nearPageNum="数字", 用来设置导航条前后显示的邻近页数,不设置将使用默认值，设置为0则不显示邻近页。
3 可设置工具条上各个功能按钮的相对位置
4 增加了调整页大小的选择框，并可自定义选择框内的内容
5 增加了带有邻近页面的导航条
6 增加了可跳转到指定页面的跳转框
7 增加了当前选中行高亮
8 为ec:table 增加了 excludeParameters 和 includeParameters 属性，可以实现更快捷简便的“参数保留/不保留”功能
9 可添加自定义的html代码到工具条内 或其他位置
10 可手动调整列宽，可通过js调整列表高度
11 增加了“列表内部滚动条”(实现列表头固定，列表体滚动的功能)
12 为ec:row和ec:column 添加更多的html事件支持，现支持：onmouserover onmouserout onclick ondbclick
13 为ec:table ec:row ec:column增加了自定义扩展属性功能
14 增加 ec:extendrow 标签，实现列表扩展行的功能
15 增加shadowRow(影子行)功能：每行下面可以再加一个子行 这个行里显示什么可以由大家自己定义
16 增加页面变量 ${TOTALROWCOUNT} 用来标示当前纪录在全部记录中的行数
17 增加了打印功能（尚不完善）
18 ec:column属性增加 ellipsis ,实现单元格内数据过长的时候 自动截短并加"..."的功能(ie only)
19 实现了跨列的列表头
20 统计栏的标题格可跨列
21 增加了若干种cell 和 headerCell,例如checkbox radiobox
22 取消了imagePath属性,样式相关的图片信息全部提入css内
23 重（第4声）用了js 和css ，很多功能用js来实现
24 支持了ajax翻页 (可设置 客户端 还是 服务端进行 html代码剪裁 )
25 支持预查询功能，在察看第n页的时候，把n+1页的数据也查询出来（隐藏着）备用，加快查看下一页的速度
26 将导出excel所使用的组件由poi切换成了 jxl
27 xls导出方式修改 原始的导出是导出的vo/map里的原始数值 现在是导出页面实际显示的内容
28 增加简捷导出方式 (通过ec:table的 xlsFileName pdfFileName csvFileName属性)
29 支持pdf简体中文导出。
30 代码进行了大规模的重构
31 增加了很多ajax相关特性
32 实现了可编辑列表功能
33 实现了cell的映射功能
34 easyList、easyDataAccess、easyDataExport特性：可通过简单的配制，快速实现列表数据的展现、查询、修改、删除、导出。
35 支持复杂表头的自定义与导出。
36 支持横向统计。
37 可以对列表内容进行灵活多样的escape。
4.使用说明：

4.1 <ec:table>标签属性说明

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

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

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

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

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

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

4.1.7属性: autoIncludeParameters
描述:
是否开启"自动保留"特性.翻页 过滤 排序时当前页的表单域将以hidden input的形式被保留(传递到新页面). 可选 true/false ( 默认:true )
关于此项的更多说明可参见原版ec手册
4.1.8 属性: includeParameters
描述:
在关闭"自动保留"时,希望被自动保留的表单域的标示,支持多个,用","分割

4.1.9 属性: excludeParameters
描述:
在开启"自动保留"时,希望不被自动保留的表单域的标示,支持多个,用","分割

补充:
如果理解了 autoIncludeParameters 的用处 就不难理解以上两个属性的用处了
注意: excludeParameters 比 includeParameters 有更高的优先级
即 excludeParameters="a" includeParameters ="a" 时 a仍然将被排除
建议尽量使用 excludeParameters 不要使用 includeParameters ，除非你非常明确自己要包含的东西。
includeParameters 使用不当会使你忘记包含一些必须包含的东西.

excludeParameters="表单属性名称1,表单属性名称2" (表单属性名称不能含有半角的逗号)
includeParameters="表单属性名称3,表单属性名称4"

4.1.10 属性: 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 数据信息区
4.1.11 属性: toolbarLocation
描述:
设置工具条要显示的位置(列表的上面还是下面). 可选top/bottom/none, 默认top.

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

4.1.14 属性: 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限制。

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

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

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

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

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

4.1.20 属性: minHeight
描述:
设置列表的最小高度

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

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

4.1.23 属性: csvFileName
描述:
设置导出csv的文件的文件名. 不指定时为不允许导出csv文件
4.1.24 属性: showPrint
描述:
是否显示打印按钮. true/false.

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

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

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

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

4.1.29 属性: shadowRowAction
描述:
显示shadowRow时所要提交的ACTION

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

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

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

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

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

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

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

4.1.37 属性: items
描述:
设置要展现的数据对应的集合在内存中存放时使用的名字

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

4.1.39 属性: locale
描述:
设置列表的本地化信息. 例如 fr_FR 将使列表使用法文方式显示(前提是已经正确提供相关资源文件).

4.1.40 属性: interceptor
描述:
自定义列表拦截器.值为对应的拦截器的实现.
该拦截器可用来添加或修改列表的属性
4.1.41 属性: retrieveRowsCallback
描述:
指定列表所使用的分页机制.值可以是自定义的完整的callback类名,也可以是在properties文件内指定的简称

4.1.42 属性: filterRowsCallback
描述:
指定列表所使用的过滤机制.值可以是自定义的完整的callback类名,也可以是在properties文件内指定的简称

4.1.43 属性: sortRowsCallback
描述:
指定列表所使用的排序机制.值可以是自定义的完整的callback类名,也可以是在properties文件内指定的简称

关于以上三个属性的使用请见"ECSide列表的RowsCallback机制"文档.

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

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

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

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

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

4.1.49 属性: showHeader
描述:
是否显示列表表头
4.2 <ec:row>标签属性说明
4.2.1 属性: rowId
描述:
列表的行的id,对应<tr>的id属性.

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

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

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

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

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

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

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

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

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

4.2.11 属性: styleClass
描述:
相当于<tr>的class.

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

4.4 <ec:extendrow>标签属性说明
扩展一行.具体的内容可以是任何合法的<tr>相关的HTML代码

4.4.1 属性: location
描述:
在什么位置添加扩展内容.
bottom: 列表内部的下方,和列表内容主体在一个<table>内
留空: 同上
4.5 <ec:column>标签属性说明
4.5.1 属性: columnId
描述:
单元格的id,相当于<td>的id属性

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

4.5.3 属性: property
描述:
指定该列所对应的列表bean(map)的属性(key).

4.5.4 属性: alias
描述:
列的别名.

4.5.5 属性: value
描述:
列的数值.默认为当前行当前列对应的列表bean(map)的属性的值.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.5.26 属性: 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.

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

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

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

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

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

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

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

4.5.34 属性: nowrap
描述:
设置列的宽度.相当于<td>的nowrap属性
4.6 <ec:parameter>属性说明
为列表所在表单添加属性.属性将以<input type=hidden name= value=>形式加入到form内

4.6.1 属性: name
描述:
属性的名字
4.6.2 属性: value
描述:
属性的值
4.7 <ec:attribute>标签属性说明
为它的外层标签增加扩展属性.
该标签的设计思想来源于xlst里的 <xls:attribute>标签.
看看 <xls:attribute>标签.的说明和示例可以更好的帮助您理解<ec:attribute>
4.8<ec:options>属性说明
帮助生成<select>的option项.

4.8.1 属性: items
设置要转换成option项的map在内存中存放时使用的名字

4.8.2 属性: defaultKey
默认的选项

4.8.3 属性: tagAttributes
其他扩展的html标签内的属性