This is a post in my blog series Introduction to Chameleon...
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) is:
-
LeaderTemplate
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
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
ItemTemplate represents the template for items within the DataSource.
This template is inherited from Repeater (on which all Lists in Chameleon are based).
-
AlternateItemTemplate
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 (on which all Lists in Chameleon are based).
-
NoneTemplate
NoneTemplate is 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
SeparatorTemplate is 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
RowSeparatorTemplate is 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.
Note that the RowSeparatorTemplate is not rendered unless the value of ItemsPerRow is greater than zero.
-
AdTemplate
AdTemplate represents advertisements to be displayed between items of the DataSource. The placement of ads is defined by the AdPlacement property.
-
FooterTemplate
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
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 />)
-
etc...
and there are also application-specific lists including:
-
WeblogList (<CSBlog:WeblogList />)
-
WeblogPostData (<CSBlog:WeblogPostList />)
-
ForumList (<CSForum:ForumList />)
-
ForumPostList (<CSForum:ForumPostList />)
-
etc...
When Community Server 2007 is released, we will have documentation on each of these controls. In general, as with the single value controls, a list control exists for each object type in the Community Server API.
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 repect 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).
Note that 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(es) 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)
QueryType defines the method used to retrieve users. "Default" will retrieve users solely based on the control's context.
Note that 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. In general, most/all data loading options that are available through the API are exposed through QueryOverrides (but without requiring the writing of C# code).
A simple example of a UserList control:
<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>
would list the top 10 most active users by their display names (linked to a search for posts by the user). If there were no active users, the message "There are no active users!" would be rendered.
Note here that the <CSControl:UserData /> control in this example 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 made very easy.
If you have any questions regarding Chameleon, pelase send them to me via my contact form or add a comment. I will answer all the questions in the final post in this series.
In my next post in this series, I will discuss Form controls.