[翻译]Chameleon介绍(3) : 列表控件

[原文]http://getben.com/archive/2007/01/11/introduction-to-chameleon-list-base-controls.aspx

这篇文章属于我的文章系列Chameleon介绍...

Chameleon 列表控件显示多个对象/值（例如一系列用户，或者同一主题里的若干论坛贴子）。和单值控件类似，列表控件也支持同样的基本属性（ControlIdsToHideWhenNotVisible, ContainerId, CssClass, Tag, DisplayConditions, LeaderTemplate, TrailerTemplate, DataSource, and Attributes），但它还定义了额外的模板，用于支持对列表中的每个对象/值进行布局。这些模板包括（以输出顺序）：
  1. LeaderTemplate
    LeaderTemplate包含了在控件内容之前，内容包装标签之内输出的标签。LeaderTemplate不支持数据绑定（这点不像单值控件）。

  2. HeaderTemplate
    HeaderTemplate代表要在ItemTemplate, AlternateItemTemplate以及NoneTemplate前面输出的内容。
    这个模板继承自Repeater（所有的Chameleon列表控件的基类）.

  3. ItemTemplate
    ItemTemplate代表DataSource里每一项的模板。
    这个模板继承自Repeater（所有的Chameleon列表控件的基类）。

  4. AlternateItemTemplate
    AlternateItemTemplate是可选的模板，用于交替输出DataSource内的项。如果未定义，所有的项都会以ItemTemplate输出。
    这个模板继承自Repeater（所有的Chameleon列表控件的基类）。

  5. NoneTemplate
    当DataSource不包含任何项时会输出NoneTemplate。在这种情况下，可以通过设置ShowHeaderFooterOnNone为 false来隐藏HeaderTemplate和FooterTemplate（ShowHeaderFooterOnNone默认为true）。

  6. SeparatorTemplate
    SeparatorTemplate在输出的DataSource项之间（在ItemTemplate和AlternatingItemTeplate之间）输出。
    这个模板继承自Repeater（所有的Chameleon列表控件的基类）。

  7. RowSeparatorTemplate
    RowSeparatorTemplate在预定义数量的项之后（并且在SeparatorTemplate的后面）输出。ItemsPerRow属性定义了RowSeparatorTemplate之间应该输出多少项。
    在以行和列的形式显示数据——比如相册里的图片时非常有用。
    注意除非ItemsPerRow的值大于零，否则RowSeparatorTemplate不会输出。

  8. AdTemplate
    AdTemplate表示要在DataSource的项之间显示的广告。广告出现的位置由属性AdPlacement（译注：目前 AdPlacementOptions枚举包括：None, PreFooter, PreSecond, PreSecondAndLast, Seperator）定义。

  9. FooterTemplate
    FooterTemplate表示要在ItemTemplate, AlternateItemTemplate以及NoneTemplate后面输出的内容。
    这个模板继承自Repeater（所有的Chameleon列表控件的基类）。

  10. TrailerTemplate
    TrailerTemplate包含了在控件内容之前，内容包装标签之内输出的标签。TrailerTemplate不支持数据绑定（这点不像单值控件）。

与单值控件类似，与Community Server API对象相关的列表控件也根据它们包含的对象（如User, Post，等等）而命名，包括：
  • UserList（<CSControl:UserList />）
  • PostList（<CSControl:PostList />）
  • SectionList（<CSControl:SectionList />）
  • GroupList（<CSControl:GroupList />）
  • 等等...
  
以及与特定应用相关的列表：
  • WeblogList（<CSBlog:WeblogList />）
  • WebLogPostList（<CSBlog:WebLogPostList />）
  • ForumList（<CSForum:ForumList />）
  • ForumPostList（<CSForum:ForumPostList />）
  • 等等...
当Community Server 2007发布后，我们会有每个控件的文档。大体上说，和单值控件一样，每个Community Server API对象都有一个相应的列表控件。
  
每个API相关列表控件都会根据它的上下文自动获取一系列对象。上下文由以下项定义：
  • URL里的对象引用（例如贴子名称，用户ID，节的Application Key，等等）
  • 父控件（通常由列表控件定义）
例如：
  • 如果页面中没有上下文（在URL中没有指定对象引用），UserList控件默认情况下会列出网站的所有用户。
  • 如果所在的页面指定了节ID或节的Application Key（比如一个博客页面），UserList控件将会列出此节的所有者。
  • 如果UserList控件在SectionList控件的ItemTeplate或AlternateItemTemplate里，它将会列出每个节的所有者。
  • 如果UserData控件在UserList控件的ItemTeplate或AlternateItemTemplate里，它会显示UserList控件中定义的当前用户。
大多数控件同时也支持一个内置属性，用于影响或改写默认的隐式数据源。这个属性的名称是“QueryOverrides”，它的属性很大程度上依赖于控件所列出的对象的类型。例如，UserList的QueryOverrides属性支持：
  
  1. IncludeHiddenUsers
    如果设为true，列表将包含隐藏用户。

  2. JoinedDate
    当处理JoinedDateComparer时使用的DateTime值。

  3. JoinedDateComparer（LessThan, EqualTo, GreaterThan）
    如果指定了JoinedDate，用户的注册时间必须匹配JoinedDateComparer定义的条件才会包含在列表中。例如，如果JoinedDate是"6/8/2001"， JoinedDateCompare是"GreaterThan"，那么只有在6/8/2001之后注册的用户才会被列出.

  4. LastPostDate
    当处理LastPostDateComparer时使用的DateTime值。

  5. LastPostDateCompare（LessThan, EqualTo, GreaterThan）
    如果指定了LastPostDate，用户的最后发贴时间必须匹配LastPostDateComparer定义的条件才会包含在列表中。例如，如果 LastPostDate是"6/8/2001"，LastPostDateComparer是"LessThan"，那么只有最后发贴时间在 6/8/2001之前的用户才会被列出。

  6. SortOrder（Ascending, Descending）
    对用户排序方式（SortBy）的补充说明，顺序还是倒序。
    默认情况下SortOrder的值是"Ascending"。

  7. PageIndex
    要显示的页码。例如，如果PageSize设置为10，PageIndex为0，将会显示第1到10条用户数据（如果PageIndex设为1，将会显示第11到20条）。
    注意如果指定了PagerId，属性PageIndex会被忽略，取代它作用的是分页器的PageIndex值

  8. PageSize
    一页要显示的用户的数量。如果没有指定PagerId，它将是列表中显示的用户的总数量。

  9. Role
    如果指定，只会显示属于指定角色的用户。

  10. SearchEmail
    如果为true，SearchText会用来搜索用户的邮件地址。

  11. SearchUsername
    如果为true，SearchText会用来搜索用户的名字。

  12. SearchText
    如果指定，只有邮件地址或用户名（取决于SearchEmail和SearchUsername的值）匹配的用户才会被列出。

  13. SortBy（JoinedDate, Username, Website, LastActiveDate, Posts, Email, RecentPosts）
    指定用户排序的依据。以顺序还是以倒序排序由SortOrder属性定义。
    默认情况下，用户根据Username排序。

  14. AccountStatus（ApprovalPending, Approved, Banned, Disapproved, All）
    如果指定，只有处于指定账号状态下的用户会被列出。

  15. Usernames
    如果指定，只有这个属性里包含了用户名的用户会被列出。这个属性的值应该是以逗号间隔用户名。

  16. QueryType（Default, Search, ActiveUsers, ActiveModerators, CurrentUserFavorites, AccessingUserFavorites, UsersWatchingAccessingUser）
    QueryType定义了用于获取用户列表的方法。"Default"将会单独以控件的上下文获取用户列表。
    注意当QueryType是"ActiveUsers", "ActiveModerators", "CurrentUserFavorites", "AccessingUserFavorites" 或 "UsersWatchingAccessingUser" 时，很多过滤选项不可用。

  17. PagerID
    分页器（或分页组,PagerGroup）的控件ID。这个控件用来在用户列表的不同页之间导航。
    仅管这只是单个控件的ID，但还是可以通过一个辅助控件（PagerGroup）使用多个分页器给单个列表进行导航。

尽管这只是UserList的QueryOverrides属性的实现，大多数列表也都支持PageIndex，PageSize，以及PagerID。每个列表暴露了与它所包含的数据相关的选项，这些选项可以通过智能提示方便地发现。例如，帖子列表（WeblogPostList, ForumPostList, EntityList, 以及GalleryPostList），通过它们的QueryOverrides内置属性，暴露了与具体应用相关的ThreadQuery实现。总体上来说，API提供的数据加载选项，大多数或者全部可以通过QueryOverrides使用（但是不需要编写C#代码）。

UserList控件的一个简单实例：

<CSControl:UserList runat="server" ShowHeaderFooterOnNone="false">
   <QueryOverrides QueryType="ActiveUsers" SortBy="RecentPosts" SortOrder="Descending" PageSize="10" />
   <HeaderTemplate>
      <ol>
   </HeaderTemplate>

   <ItemTemplate>
      <CSControl:UserData Property="DisplayName" runat="server" Tag="LI" LinkTo="PostsSearch" />
   </ItemTemplate>

   <NoneTemplate>
      There are no active users!
   </NoneTemplate>

   <FooterTemplate>
      </ol>
   </FooterTemplate>
</CSControl:UserList>

将会列出10个最后发帖的在线用户的昵称（链接到对用户帖子的搜索）。如果没有用户在线，将会输出消息“There are no active users!”。

注意<CSControl:UserData />控件在这个例子里显示了列表中的当前用户的数据。UserData控件隐式的从UserList控件获取当前用户。这个例子中，没有必要设置UserList或UserData的DataSource属性。

除了QueryOverrides里的特定选项以外，所有的Chameleon列表控件都以同样的方式运作。在智能提示的帮助下，定义列表以及浏览列表选项非常轻松。

如果你有任何关于Chameleon的问题，请通过我的联系表单或添加评论发送给我。我会在这一系列的最后一篇文章里回答它们。

这个系列的下一篇文章里，我会讨论表单控件。

posted on 2007-05-04 02:33  deerchao  阅读(946)  评论(1)  编辑  收藏  举报