List Controls

Chameleon list controls display multiple objects/values (such as a list of Users or ForumPosts in a Thread). List controls support the same basic properties as single-value base controls (ControlIdsToHideWhenNotVisible, ContainerId, CssClass, Tag, DisplayConditions, LeaderTemplate, TrailerTemplate, DataSource, and Attributes), but add support for additional templates to layout each object/value in the list. 

The full list of templates (in rendered order) includes:

• LeaderTemplate - contains markup and controls to render before the content of the control and within the content wrapper. The LeaderTemplate is not databound (unlike for single-value base controls).

• HeaderTemplate - Represents the header for the ItemTemplate, AlternateItemTemplates, and NoneTemplate. This template is inherited from Repeater (on which all lists in Chameleon are based).
• ItemTemplate - Represents the template for items within the DataSource. This template is inherited from Repeater (on which all lists in Chameleon are based).
• AlternateItemTemplate - Represents the optional template for alternating items within the DataSource. If undefined, all items will be rendered using the ItemTemplate. This template is inherited from Repeater (upon which all lists in Chameleon are based).
• NoneTemplate - Displayed if the DataSource contains no items. The HeaderTemplate and FooterTemplate can be hidden in such situations by setting ShowHeaderFooterOnNone to false (ShowHeaderFooterOnNone defaults to true).
• SeparatorTemplate - Displayed between rendered items of the DataSource (between ItemTemplate and AlternatingItemTemplate). This template is inherited from Repeater (on which all lists in Chameleon are based).
• RowSeparatorTemplate - Displayed after a predefined number of items have been displayed (and after the SeparatorTemplate). The ItemsPerRow property defines how many items are rendered between each RowSeparatorTemplate. RowSeparatorTemplate is useful when displaying data in rows and columns -- such as photo gallery images. The RowSeparatorTemplate is not rendered unless the value of ItemsPerRow is greater than zero.
• AdTemplate - Represents advertisements to be displayed between items of the DataSource. The ad placement is defined by the AdPlacement property.

• FooterTemplate - Represents the footer for the ItemTemplate, AlternateItemTemplate, and NoneTemplate. This template is inherited from Repeater (on which all lists in Chameleon are based).

• TrailerTemplate - Contains markup and controls to render after the content of the control and within the content wrapper. The TrailerTemplate is not databound (unlike for single value base controls).

Similar to single value base controls, list controls are related to Community Server API objects and are named according to the object they list (User, Post, etc), including:

• UserList (<CSControl:UserList />)
• PostList (<CSControl:PostList />)
• SectionList (<CSControl:SectionList />)
• GroupList (<CSControl:GroupList />)

There are also application-specific lists, including:

• WeblogList (<CSBlog:WeblogList />)
• WeblogPostData (<CSBlog:WeblogPostList />)
• ForumList (<CSForum:ForumList />)
• ForumPostList (<CSForum:ForumPostList />)

Community Server API contains a list control exists for each object.

Each API-related list control automatically retrieves the list of objects based on its context.  The context is defined by

• Object references in the URL (such as a post name, user ID, section application key, etc.)
• Parent controls (commonly defined by list controls)

For example,

• A UserList control on a page with no context (no object references in the URL) would, by default, list all users on the site.
• A UserList control on a page with a section ID or section application key (such as a single blog page) would list the owners of the section.
• A UserList control within the ItemTemplate or AlternateItemTemplate of a SectionList control would list the owners of the section.
• A UserData control within the ItemTemplate or AlternateItemTemplate of a UserList control would render the current user as defined by the UserList control.

Most list controls also support an inner-property that can be used to influence or override the default implicit DataSource. This property is named QueryOverrides and its options depend greatly on the type of the items listed by the control.  For example, the UserList's QueryOverrides property supports:

• IncludeHiddenUsers – If true, hidden users will be included in the list.

• JoinedDate - The DateTime value to use when processing the JoinedDateComparer.

• JoinedDateComparer (LessThan, EqualTo, GreaterThan) - If a JoinedDate is specified, the JoinedDateComparer defines the criteria a User's joined date must match to be included in the list. For example, if JoinedDate is 6/8/2001 and JoinedDateComparer is GreaterThan, only users who joined the site after 6/8/2001 will be listed.

• LastPostDate - The DateTime value to use when processing LastPostDateComparer

• LastPostDateComparer (LessThan, EqualTo, GreaterThan) - If a LastPostDate is specified, the LastPostDateComparer defines the criteria a User's last post date must match to be included in the list. For example, if LastPostDate is 6/8/2001 and LastPostDateComparer is LessThan, only users whose last post date is before 6/8/2001 will be listed.

• SortOrder (Ascending, Descending) - The order by which Users are sorted with respect to SortBy. By default SortOrder is set to Ascending.

• PageIndex - The page to display. For example, if PageSize is set to 10 and PageIndex is set to 0, users 1 to 10 will be listed (if PageIndex was set to 1, users 11 to 20 would be listed).
  If a PagerID is specified, PageIndex is ignored and the pager's value for PageIndex is used instead.

• PageSize - The number of users to list on a page. If no PagerID is defined, this would be the total number of items displayed in the list.

• Role - If specified, only users in the specified role will be listed.

• SearchEmail - If true, SearchText will search user's email addresses.

• SearchUsername - If true, SearchText will search user's user names.

• SearchText - If specified, only users whose email address or user name (depending on the values of SearchEmail and SearchUsername) will be listed.

• SortBy (JoinedDate, Username, Website, LastActiveDate, Posts, Email, RecentPosts) - The method by which users are sorted. The order in which users are sorted is defined by SortOrder. By default, users are sorted by Username.

• AccountStatus (ApprovalPending, Approved, Banned, Disapproved, All) - If set, only users of the specified account status will be listed.

• Usernames - If specified, only users whose user names are included in the value of this property are listed. This property is a comma-separated list of user names.

• QueryType (Default, Search, ActiveUsers, ActiveModerators, CurrentUserFavorites, AccessingUserFavorites, UsersWatchingAccessingUser) - Defines the method used to retrieve users. Default will retrieve users solely based on the control's context.
  Many of the filter options are not available when QueryType is ActiveUsers, ActiveModerators, CurrentUserFavorites, AccessingUserFavorites or UsersWatchingAccessingUser.

• PagerID - The control ID of the pager (or PagerGroup) control to use to navigate pages of users in the list. Although this is a single control ID, a utility control (PagerGroup) exists to allow multiple pagers to be used to navigate a single list.

While these are the properties for the UserList's implementation of QueryOverrides, most lists support PageIndex, PageSize, and PagerID.  Each list exposes options specific to the data that it lists and these options are easily discoverable using Intellisense.

Post lists (WeblogPostList, ForumPostList, EntryList, and GalleryPostList), for example, expose all properties of the application-specific ThreadQuery implementations through their QueryOverrides inner-property. Most data-loading options that are available through the API are exposed through QueryOverrides (but without requiring C# code to be written).
For example, a UserList control would list the 10 most active users by their display names (linked to a search for posts by the user):

<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>

If there were no active users, the message There are no active users! would be rendered.

The <CSControl:UserData /> control in the example above displays data for the current user in the list. The UserData control retrieves the current user from the UserList control implicitly. There is no need to set the DataSource property on either the UserList or UserData control in this example.

With the exception of the specific options available via QueryOverrides, all Chameleon list controls work the same way. With the help of Intellisense, defining lists and browsing list options is very easy.