eXtremeComponents使用总结--1(转载)

2009-07-31 09:24

前言

eXtremeComponents是一系列提供高级显示的开源JSP定制标签。当前的包含的组件为eXtremeTable，用于以表的形式显示数据。

本文档处于更新中。大部分章节我将仅仅描述如何使用eXtremeTable。当然，为了使程序高效并具有更高的灵活性，源代码被再三重构。随后, 我认为阐述一下如何做设计决定是值得的。我希望大家能知道使用extremeTable是多么容易，并且所有的东西都是可配置。如果你有任何的要求和建议, 请及时通过论坛或者 extremecomponents@gmail.com和我联系。

我想感谢Chris Bauer(Hibernate开发小组)和Rod Johnson(Spring开发小组)。 Chris提供并修改了DocBook-XSL使它能生成Hibernate参考指南。Rod对于使用从Hibernate 得到的这个软件来生成Spring文档提供了支持。我现在用它来生成eXtremeComponents的文档。

译者注:如果大家有什么疑问和建议，可以通过xplucky@gmail.com和我联系。

Chapter 1. 配置

1.1. 先决条件

Servlet 2.3或更高版本
JDK 1.3.1或更高版本

最小的Jars要求：

commons-beanutils 1.6
commons-collections 3.0
commons-lang 2.0
commons-logging 1.0.4
standard 1.0.2

PDF导出需要的Jars：

minimum jars (above)
avalon-framework 4.0
batik 1.5-fop-0.20-5
fop 0.20.5
xalan 2.5.1
xercesImpl 2.6.1
xml-apis 2.0.2

XLS导出需要的Jars：

minimum jars (above)
poi-2.5.1.jar

1.2. 安装

从sourceforge 下载发行包。(http://sourceforge.net/projects/extremecomp/)

在压缩文件里你能找到开始使用需要的所有东西：

extremecomponents.jar
extremecomponents.tld
extremecomponents.css
默认的一组图片
源代码
test.jsp (用于确认安装是否正确)

将extremecomponents.jar文件拷贝到你的工程的/WEB-INF/lib目录下。

处理TLD文件有两种方式。你可以把extremecomponents.tld文件放到WEB-INF目录下的任何地方。不过，为了便于管理，我喜欢把我的TLD文件都放到/WEB-INF/tld目录下。你需要根据你的extremecomponents.tld 文件的位置来修改/WEB-INF/web.xml文件的标签映射。

<taglib>    <taglib-uri>/tld/extremecomponents</taglib-uri>    <taglib-location>/WEB-INF/tld/extremecomponents.tld</taglib-location></taglib>

随后，你需要向下面一样在你的JSP里把eXtremeTable包含进来：

<%@ taglib uri="/tld/extremecomponents" prefix="ec" %>

如果你的servlet容器支持JSP 1.2 (或更高版本)，它将能够自动发现TLD文件，那么你什么也不需要做。当extremecomponents.jar被容器加载的时候，在它的META-INF目录下的extremecomponents.tld文件将被找到。这时，你需要向下面一样在你的JSP里把eXtremeTable包含进来：

<%@ taglib uri="http://www.extremecomponents.org" prefix="ec" %>

为了使用eXtremeTable样式，从styles目录拷贝extremecomponents.css到你存放.css脚本的地方。当然在JSP页面里，你需要提供一个到CSS的链接。就像我将我的样式表放在/styles目录下。

<%@ taglib uri="/tld/c" prefix="c" %><link rel="stylesheet" type="text/css" href="<c:url value="/styles/extremecomponents.css"/>">

1.3. 导出过滤器(可选)

为了使导出功能有效，你需要设置导出过滤器。这是一个仅用于导出功能的可选配置。

如下所示在/WEB-INF/web.xml里配置过滤器：

<filter>  <filter-name>eXtremeExport</filter-name>  <filter-class>org.extremecomponents.table.filter.ExportFilter</filter-class></filter><filter-mapping>  <filter-name>eXtremeExport</filter-name>  <url-pattern>/*</url-pattern></filter-mapping>

过滤器还有一个可选的初始化参数，用于决定什么时候生成报头（headers）。我发现大多数的servlet容器倾向于在调用过滤器的doFilter()方法后才设置响应报头（response headers）。然而，一些servlet容器只有在调用过滤器的doFilter()方法前设置响应报头，过滤器才能正常工作。默认的方法是调用过滤器的doFilter()方法后设置响应报头，你可以通过使用responseHeadersSetBeforeDoFilter这个初始化参数调整它。

<filter>  <filter-name>eXtremeExport</filter-name>  <filter-class>org.extremecomponents.table.filter.ExportFilter</filter-class>    <init-param>      <param-name>responseHeadersSetBeforeDoFilter</param-name>      <param-value>true</param-value>    </init-param></filter>

如果你使用了Sitemesh，你将需要包含SitemeshPageFilter。SitemeshPageFilter扩展了正常的 sitemesh的PageFilter，它使得正在进行导出的JSP页面不被修饰。

如下所示在/WEB-INF/web.xml里配置过滤器：

<filter>  <filter-name>Sitemesh</filter-name>  <filter-class>org.extremecomponents.table.filter.SitemeshPageFilter</filter-class></filter><filter-mapping>  <filter-name>Sitemesh</filter-name>  <url-pattern>/*</url-pattern></filter-mapping>

1.4. 安装测试

使用发行包的test.jsp来测试安装。将test.jsp拷贝到web应用的最顶层，默认的图片文件在 /images/table/子目录下。为了测试，创建相应的目录并将拷贝所有需要的图片。所有工作都完成后，你可以在浏览器里运行test.jsp了。

提示: 我不提倡在JSP里使用脚本（scriplets），但为了不用使用框架而能进行快速测试，在test.jsp 使用脚本是唯一的办法。

Chapter 2. 概述

2.1. 引言

eXtremeTable在给定的servlet范围（scope）外取得Beans或Maps的集合用于JSP页面显示。 servelet范围的搜索顺序是：page, request, session和application。通过设定TableTage的items 属性，eXtremeTable知道哪些需要在servlet范围外被保持。

集合里的Beans是pojo，如果使用maps那么它就是键值对。你可以认为每一个bean就是表中的一行数据。在接下来的文档中，我将使用Beans集合来代替这两种集合。

实际表使用的最小语法如下所示：

<ec:table   items="presidents"   action="${pageContext.request.contextPath}/presidents.run"   imagePath="${pageContext.request.contextPath}/images/*.gif">  <ec:row>    <ec:column property="firstName"/>    <ec:column property="lastName"/>    <ec:column property="termDate"/>  </ec:row></ec:table>

这就是eXtremeTable的一个典型定义。通过这些定义，你将得到格式化的列和页头，工具栏的所有特性也能很好工作。

Chapter 3. TableTag

3.1. 引言

TableTag用来设定什么被显示并且如何进行显示。默认的eXtremeTable在servlet范围(按照page，request， session，applicaton的顺序)寻找具有名称和items属性设置相同的Beans集合（如前章所述它指Beans和Maps两种集合）。表将遍历所有列，它使用var属性将当前行对应的bean从集合传到page范围，因此你可以从page范围中重新得到这些数据进行操作。tableId用来唯一标识表，如果在JSP页面里包含两个或两个以上的表时需要设置它。

President bean定义如下:

public class President implements Serializable {  private String firstName;  private String lastName;

  public String getFirstName() {    return firstName;  }

  public void setFirstName(String firstName) {    this.firstName = firstName;  }

  public String getLastName() {    return lastName;  }

  public void setLastName(String lastName) {    this.lastName = lastName;  }}

Beans集合需要被组装并传到servlet范围中。我喜欢使用Spring框架，因此示例将使用Spring框架的控制器（Controller）。如果你正在使用Struts，它和Action的功能类似。如果你使用别的东西，比如直接使用 servlets，你只需要明白我所做的只是组装Beans集合并传到request范围中。

public class Presidents extends AbstractController {  protected ModelAndView handleRequestInternal(HttpServletRequest request,                                                 HttpServletResponse response)    throws Exception {    List presidents = new ArrayList();

    President president = new President();

    president.setFirstName("George");    president.setLastName("Washington");    presidents.add(president);

    president = new President();    president.setFirstName("John");    president.setLastName("Adams");    presidents.add(president);

    request.setAttribute("presidents", presidents);

    return new ModelAndView("/demo/presidents.jsp");}

现在你可以构造表了：

<%@ taglib uri="/tld/extremecomponents" prefix="ec" %>

<ec:table  items="presidents"  var="pres"  imagePath="${pageContext.request.contextPath}/images/*.gif"  action="${pageContext.request.contextPath}/presidents.run"  >  <ec:column property="firstName"/>  <ec:column property="lastName"/>    ${pres.lastName}  </ec:column></ec:table>

从本示例中你应该知道我们将名为presidents的Beans集合以presidents为名称放到request中。为了使表知道如何找到这个Beans集合，我们设置TableTag的items属性为presidents。同时我们定义了两列：firstName和lastName。firstName列是最普通的用法：我们仅仅想让这列从当前bean中得到相应 firstName的值；lastName列示另外一种用法：明确取得值。

从一列中明确取得值非常有用，但是你需要理解表是如何构造行的。为了构造行，表需要对所有行进行 rowsDisplayed属性设定次数的迭代。每次迭代都从Beans里取得下一个bean并使用var属性设定的名称传入page 范围。也可以说每次迭代你都访问的是集合中当前行对应的bean。

3.2. 显示图片

为了显示图片需要设置imagePath属性：

<ec:table  items="presidents"  var="pres"  imagePath="${pageContext.request.contextPath}/images/*.gif"  >  ...</ec:table>

eXtremeTable将找到一个目录下的所有图片并使用特殊的语法来定义他们是那类图片。本示例中所有的图片都直接保存在web上下文的images目录下。*.gif使eXtremeTable知道所有的图片都是GIF格式的。在我们讨论preferences后，你将发现你可以你可以通过在 extremecomponents.properties文件中设定这个属性，而不用再整个应用的每个eXtremeTable 中包含它。

3.3. 过滤、排序和动作（Action）

eXtremeTable内嵌了过滤和排序功能，你只需要决定是否需要使用他们。你要使用的属性是 filterable和sortable，他们都是布尔值并且默认值是true。默认的所有特性都有效，你可以按照需要来关掉一些特性。比如，如果你不想使用排序或过滤你可以把他们的属性设为false。

<ec:table  items="presidents"  var="pres"  imagePath="${pageContext.request.contextPath}/images/*.gif"  action="${pageContext.request.contextPath}/presidents.run"  filterable="false"  sortable="false"  >  ...</ec:table>

如果你仍不确信，你可以来验证他们。首先，设置filterable和sortable为true，你将看到 eXtremeTable允许你输入关键词来过滤结果集，它也允许你通过在页头（header）上滚动鼠标来排序。然后，设置filterable和sortable为fale，你将发现所有这些特性都不允许使用。

本示例需要指出的是使用action属性，action被用来告诉eXtremeTable当过滤或排序时如何回到当前的页面。本例中我通过Spring框架的controller（在这里是presidents.run）来得到Beans集合。你不需要担心传参问题，eXtremeTable将保存所有的参数并将它们和过滤器、排序、分页一起传递给 Beans集合。更详细的信息请参考ParameterTag。

3.4. 设定每页显示行数

默认地eXtremeTable一页将显示15行。你可以通过设定rowsDisplayed属性为你想显示行数的数值来改变它。rowsDisplayed也可以在extremecomponents.properties文件中设定。(参考Preferences)。

提示：如果你想在一页中显示所有行，只需要设置showPagination为false。

3.5. 样式

TableTag关联了很多样式属性：

<ec:table  cellspacing="0"  cellpadding="0"  border="0"  width="80%"  style=""  styleClass=""  />

所有这些都是可选的。

3.6. 保存表的状态

表新增了两个属性：state和stateAttr。state属性参照State接口并能插接如何保存表的状态的不同实现。

State借口如下：

public interface State {    public void saveParameters(TableModel model, Map parameters);    public Map getParameters(TableModel model);}

state属性使用预设的四种状态（default、notifyToDefault、persist和notifyToPersist）之一，你也可以插接自己的实现。default状态不维持任何状态；persist状态没有任何参数传入，将一直维持表的状态； notifyToDefault状态将一直维持表的状态直到你传入参数告诉它回到default状态；notifyToPersist状态将一直维持当前状态直到你传入参数告诉它维持persisted状态。

stateAttr为指定参数提供了一条途径，你也可以使用属性文件在全局范围内指定它。为了向后兼容，默认参数一直为useSessionFilterSort。

如果你想state按照不同方式工作你只要实现State接口，然后使用TableTag的state属性来指定实现类的全路径。

作为一条首要规则当使用state属性时，需要指定tableId。这是因为state使用tableId为名保存在session里。如果tableId不唯一，eXtremeTable将覆盖另一个同名的内容。tableId默认值为ec。

3.7. 其他属性

为了保持一致性，所有的显示特性都命名为showXXXX。他们包括showPagination、showStatusBar、 showTooltips、和showExports。

title属性将在表的上方显示标题，标题的位置根据使用的视图不同而不同。当前默认视图中标题位于表的上方工具条的左边。更详细的信息请参考View。

你会发现还有一些属性没有被探讨，因为他们将在其他章探讨。autoIncludeParameters在ParameterTag里被探讨； retrieveRowsCallback，sortRowsCallback和filterRowsCallback在Callbacks里被探讨。

3.8. 扩展属性

大多数标签包含一系列的固定属性，这样那些已经实现的功能能够被使用。然而，eXtremeTable具有一种更具弹性的架构，你可以添加自己的标签属性实现更多的定制工作。此外，eXtremeTable提供了非常清晰的钩子（hooks）允许你得到那些定制的标签属性来做一些你需要的工作。

通过addExtendedAttributes()方法将扩展属性包含到eXtremeTable里：

public void addExtendedAttributes(Table table);

如果方法被覆盖TableTag将调用它。你需要做的就是扩展TableTag，覆盖addExtendedAttributes()方法，然后添加自己的属性到表对象中。一个定制的TreeTag示例如下：

public class TreeTag extends TableTag {    private String parentAttribute;    private String identifier;

    public void setParentAttribute(String parentAttribute) {        this.parentAttribute = parentAttribute;    }

    public void setIdentifier(String identifier) {        this.identifier = identifier;    }

    public void addExtendedAttributes(Table table) {        table.addAttribute(TableConstants.PARENT_ATTRIBUTE, TagUtils.evaluateExpressionAsString("parentAttribute",                parentAttribute, this, pageContext));        table.addAttribute(TableConstants.IDENTIFIER, TagUtils.evaluateExpressionAsString("identifier",                identifier, this, pageContext));

        table.setFilterRowsCallback("org.extremecomponents.tree.ProcessTreeRowsCallback");        table.setSortRowsCallback("org.extremecomponents.tree.ProcessTreeRowsCallback");    }}

现在你添加了属性值到table对象。

另外，你也可以定制自己的标签和自己的TLD文件。你不需要修改extremecomponents.tld文件。你能象使用eXtremeTable里的标签一样使用自己的标签，除了使用你自己标签的参照。假如你的标签参照为mycompany 并且标签为customTable，你可以像下面一样使用他们：

<mycompany:customTable    items="presidents"    action="${pageContext.request.contextPath}/public/demo/presidents.jsp"    title="Presidents"    >  <ec:row>    <ec:column property="nickName"/>  </ec:row></mycompany:customTable>