One topic that could have been covered more in my Introduction to Chameleon posts is pager controls. Pager controls in Community Server 2007 are now completely customizable, interchangeable, groupable, and support some cool new features.
As I mentioned when introducing list controls, most list controls support specifying a PagerID on their <QueryOverrides /> inner-property. When specified, the list will be paged using the pager with the specified ID using the PageSize also defined on the <QueryOverrides /> inner-property of the list.
Pagers available in CS2007 include:
- Pager (<CSControl:Pager />)
The generic Pager control supports URL-based paging (GET request). It's properties include the standard single-value control properties as well as:
- TotalPages
TotalPages reports the total number of pages for the current page and related data list.
- PageIndex
PageIndex reports the zero-starting page number for the current page selected by the pager.
- PageSize
PageSize reports the number of items included in each page.
- TotalRecords
TotalRecords reports the total number of items in the related data list.
- Duration
Duration reports the time that elapsed while loading the related data list.
- ShowTotalSummary
If true, the total summary will be rendered (overridden by TotalSummaryTemplate). Default: false.
- ShowFirst
If true, the "first" link will be rendered (overridden by FirstLinkTemplate). Default: true.
- ShowLast
If true, the "last" link will be rendered (overridden by LastLinkTemplate). Default: true.
- ShowNext
If true, the "next" link will be rendered (overridden by NextLinkTemplate). Default: true.
- ShowPrevious
If true, the "previous" link will be rendered (overridden by PreviousLinkTemplate). Default: true.
- ShowPagerItems
If true, page links will be rendered. Default: true.
Setting ShowPagerItems to false is equivalent to setting ShowFirst, ShowLast, ShowNext, ShowPrevious, and ShowIndividualPages to false.
- ShowIndividualPages
If true, individual page links will be rendered (overridden by PageLinkTemplate and CurrentPageLinkTemplate). Default: true.
- CurrentPage
Reports the current 1-based page number.
- IndividualPagesDisplayedCount
Defines the maximum number of page links to render. Default: 5.
- PagerUrlFormat
If defined, the pager will use this format when creating page links. This format should be registered in the siteurls.config file (or siteurls_override.config) to rewrite the formatted value to the QueryStringProperty.
- QueryStringProperty
QueryStringProperty defines the querystring property name used to store the current page number. Default: PageIndex.
The Pager control also allows customization of the rendered markup using the following templates (in rendered order):
- TotalSummaryTemplate
The TotalSummaryTemplate renders if ShowTotalSummary is true and allows for the placement of <CSControl:PagerData /> controls to report on the properties of the current pager such as Duration, TotalRecords, CurrentPage, TotalPages, etc.
If ShowTotalSummary is set to true and the TotalSummaryTemplate is not defined, the following will render:
Page X of Y (Z items)
Note that specifying a TotalSummaryTemplate will completely override this default.
- FirstLinkTemplate
FirstLinkTemplate renders the "first" link which will be rendered only if CurrentPage is greater than 3 and TotalPages is greater than IndividualPagesDisplayedCount and ShowFirst is true.
The first link can be customized by specifying the FirstLinkTemplate and using a <CSControl:CSLinkData /> control to place the "first" link.
- PreviousLinkTemplate
PreviousLinkTemplate renders the "previous" link which will be rendered only if CurrentPage is greater than 1 and TotalPages is greater than IndividualPagesDisplayedCount and ShowPrevious is true.
The previous link can be customized by specifying the PreviousLinkTemplate and using a <CSControl:CSLinkData /> control to place the "previous" link.
- PageLinkTemplate
PageLinkTemplate renders each page link except for the current page if ShowIndividualPages is true. A maximum of IndividualPagesDisplayedCount page links will be displayed.
The page link can be customized by specifying the PageLinkTemplate and using a <CSControl:CSLinkData /> control to place the "page" link.
- CurrentPageLinkTemplate
CurrentLinkTemplate renders the current page link if ShowIndividualPages is true.
The current page link can be customized by specifying the CurrentPageTemplate and using a <CSControl:CSLinkData /> control to place the "page" link.
- SeparatorTemplate
SeparatorTemplate is rendered between each link.
- NextLinkTemplate
NextLinkTemplate renders the "previous" link which will be rendered only if CurrentPage is greater than 1 and TotalPages is greater than IndividualPagesDisplayedCount and ShowNext is true.
The next link can be customized by specifying the NextLinkTemplate and using a <CSControl:CSLinkData /> control to place the "next" link.
- LastLinkTemplate
LastLinkTemplate renders the "first" link which will be rendered only if CurrentPage is more than 3 less than TotalPages and TotalPages is greater than IndividualPagesDisplayedCount and ShowLast is true.
The last link can be customized by specifying the LastLinkTemplate and using a <CSControl:CSLinkData /> control to place the "last" link.
As an example,
<CSControl:UserList runat="server">
<QueryOverrides QueryType="Search" Role="Registered Users" PageSize="10" PagerID="UserPager" />
<ItemTemplate>
<CSControl:UserData runat="server" Property="DisplayName" LinkTo="Profile" Tag="h4" />
</ItemTemplate>
</CSControl:UserList>
<CSControl:Pager runat="server" id="UserPager" ShowTotalSummary="true" />
would page registered users, 10 at a time, and show the default total summary.
Note that the modified URL generated by the Pager control will include any persistence values registered via CSControlUtility.Instance().RegisterQueryStringValue().
- PostbackPager (<CSControl:PostbackPager />)
The PostbackPager control includes all of the properties of the Pager control (except PagerUrlFormat and QueryStringProperty) but issues an ASP.NET postback (POST request) to change pages instead using the URL (GET request) for paging.
The PostBackPager is useful when paging data on an ASPX page that also includes form controls as it ensures that the values of the form elements will be persisted through paging changes.
- CallbackPager (<CSControl:CallbackPager />)
The CallbackPager control includes all of the properties of the Pager control (except PagerUrlFormat and QueryStringProperty) but issues an callback (AJAX request) to change pages instead of using the URL or a full ASP.NET postback. Paging data using the CallbackPager causes only the paged data to be updated and does not require a full page refresh to change pages.
The syntax for the CallbackPager is a little different from other pagers, however. The CallbackPager must enclose the paged content within its PagedContent inner-property.
For example,
<CSControl:CallbackPager runat="server" ID="UserPager">
<PagedContent>
<CSControl:UserList runat="server">
<QueryOverrides QueryType="Search" Role="Registered Users" PageSize="10" PagerID="UserPager" />
<ItemTemplate>
<CSControl:UserData runat="server" Property="DisplayName" LinkTo="Profile" Tag="h4" />
</ItemTemplate>
</CSControl:UserList>
</PagedContent>
</CSControl:CallbackPager>
would render the sample user list as the example for the Pager control, but would not require a full page refresh when changing pages.
Note that the CallbackPager always renders the pager links below the paged content.
- ScrollingPager (<CSControl:ScrollingPager />)
The ScrollingPager control is my favorite. It uses callbacks (AJAX requests) to page data using a horizontally scrolling area. The ScrollingPager control uses two associated controls: ScrollingPagerItem and ScrollingPagerData.
ScrollingPagerItem encloses scrollable items within the associated ScrollingPager (identified using the ScrollingPagerID property of the ScrollingPagerItem control). An item can be one or more records rendered by the related list control.
ScrollingPagerData works similar to other single-value Chameleon controls with support for the LinkTo property which provides easy access to the first, last, previous page, next page, previous item, and next item links associated with a ScrollingPager (identified using the ScrollingPagerID property of the ScrollingPagerData control).
For example,
<CSControl:ScrollingPager runat="server" ID="UserPager" Tag="Div" style="border: solid 1px #000; padding: 2px;">
<PagedContent>
<CSControl:UserList runat="server">
<QueryOverrides QueryType="Search" Role="Registered Users" PageSize="10" PagerID="UserPager" />
<ItemTemplate>
<CSControl:ScrollingPagerItem runat="server" ScrollingPagerID="UserPager">
<CSControl:UserData runat="server" Property="DisplayName" LinkTo="Profile" />
</CSControl:ScrollingPagerItem>
</ItemTemplate>
</CSControl:UserList>
</PagedContent>
<ItemLoadingTemplate>
Loading user...
</ItemLoadingTemplate>
<PagerLoadingTemplate>
JavaScript is required to see the user list.
</PagerLoadingTemplate>
</CSControl:ScrollingPager>
<CSControl:ScrollingPagerData ScrollingPagerID="UserPager" LinkTo="PreviousItem" Text="Previous" runat="server" /> |
<CSControl:ScrollingPagerData ScrollingPagerID="UserPager" LinkTo="NextItem" Text="Next" runat="server" />
would scroll the same user list as in the other Pager examples.
ScrollingPager includes the properties TotalPages, PageIndex, PageSize, TotalRecords, Duration, and CurrentPage similar to the Pager control, but adds the following scrolling-specific properties:
- ItemWidth
The static pixel-width of each paged item in the ScrollingPager. Default: 200.
- ItemHeight
The static pixel-height of each paged item in the ScrollingPager. Default: 100.
- GroupedItemsPerPage
If more than one list item is displayed within each <CSControl:ScrollingPagerItem /> control, GroupItemsPerPage should be set to this number. Default: 1.
ScrollingPager also uses different templates than the other Pagers. It's templates include:
- ItemLoadingTemplate
ItemLoadingTemplate contains the content to display in each paged item while the item's content is being loaded.
- PagerLoadingTemplate
PagerLoadingTemplate contains the content to display within the ScrollingPager while the ScrollingPager initializes.
The PagerLoadingTemplate can include a note to users who may have JavaScript disabled to identify that JavaScript is required for the ScrollingPager to function.
- PagedContent
PagedContent, as with the CallbackPager control, must contain the content that will be paged.
Note, however, that <CSControl:ScrollingPagerItem /> controls define the beginning and ending of each item being rendered. If no <CSControl:ScrollingPagerItem /> controls exist in the PagedContent inner-property of the ScrollingPager, no content will be displayed in the ScrollingPager when it renders.
These pagers can be used with any Chameleon list control. Additionally, if you would like to attach multiple pagers to a single list control to provide, for example, a pager above and below the list being paged, you can use the <CSControl:PagerGroup /> control.
The PagerGroup control supports interacting with a list control (by specifying the PagerGroup as the pager for the list using the PagerID property of <QueryOverrides />) and distributing that interaction across multiple pagers identified by its PagerIds property.
For example,
<CSControl:Pager runat="server" id="TopPager" ShowTotalSumamry="true" />
<CSControl:UserList runat="server">
<QueryOverrides QueryType="Search" Role="Registered Users" PageSize="10" PagerID="UserPager" />
<ItemTemplate>
<CSControl:UserData runat="server" Property="DisplayName" LinkTo="Profile" Tag="h4" />
</ItemTemplate>
</CSControl:UserList>
<CSControl:PagerGroup runat="server" id="UserPager" PagerIds="TopPager,BottomPager" />
<CSControl:Pager runat="server" id="BottomPager" ShowTotalSummary="true" />
would display the same user list as in the other pager examples, but with a pager above and below the paged list.
I hope this post excites theme developers paging ambitions. If you have questions, please leave a comment or send an email. I'll update this post with good questions.