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>

Chapter 3. TableTag