Introduction
This article provides an introduction to navigation and listing controls in EPiServer CMS.
Menu and Listing Controls
The EPiServer CMS “all-in-one” listing controls are implemented according to the .NET concept of templated controls (see the the MSDN introductory article on ASP.NET Web Server Controls Templates). The rendering of data from EPiServer List and Menu controls is carried out through the web controls' templates. For further information about deciding which template ro use refer to the relevant webcontrol below.
When building EPiServer solutions the MenuList and PageList Web controls are frequently used to to create main level and sub level navigation. The NewsList control is frequently used when developers need to render different markup for the first pages in a list of pages. Each EPiServer list control is designed for a certain type of list. The EPiServer CMS Menu and List controls are described below:
As each control is designed for a certain type of list it is recommended that you familiarize yourself with all the controls before commencing development.
| EPiServer Menu and Listing Web Controls | Description |
|---|---|
| EPiServer:MenuList | Renders a menu list of top level items, useful for navigations that contain a top level menu displaying subtree's as clicked. |
| EPiServer:PageList | Control for rendering page list, extends PageList with templates. Supports paging. |
| EPiServer:NewsList | Control for rendering news list with specialized template for top level news. |
| EPiServer:PageTree | Control for rendering page tree's, extends PageTreeData with templates. |
EPiServer:PageList
The PageList control is usually used to list EPiServer pages. The PageList control is very similar to ASP Net data controls you may be familiar such as the asp:Repeater. It has some built in features that make it easy to use in certain scenarios. For instance, you can easily filter the data and add paging to it. A few of the most commonly used public properties of the PageList class:
| EPiServer:PageList Properties | Description |
|---|---|
| MaxCount | The number of PageData objects (EPiServer pages) to list |
| PageLink | The root page to get children from |
| PageLinkProperty | The page property, gets the children of that page |
| PagesPerPagingItem | When paging is enabled, how many PageData objects per page |
| Paging | Controls if paging is used. Set to true to enable paging |
| PublishedStatus | Takes a PagePublishedStatus enum. Default is published |
| RequiredAccess | Takes an AccessLevel enum. Default is read |
| SkipCount | Skip the first x pages. Useful when doing something else with the first x number of pages |
| SortBy | Sort after an EPiServer property |
| SortDirection | Takes a FilterSortDirection enum (remember to add using EPiServer.Filters) |
| SortOrder | Takes a FilterSortOrder enum |
Below are the template options it offers:
| EPiServer:PageList Templates | Description |
|---|---|
| FooterTemplate | Template for listing footer |
| HeaderTemplate | Template for listing header |
| ItemTemplate | The default template for pages |
| PagingFooterTemplate | Footer template for the paging items |
| PagingHeaderTemplate | Header template for the paging items |
See the code example for PageList control in the How To section in this Developers Guide.
EPiServer:MenuList
The MenuList Web control is frequently used to create the top level menu in an EPiServer website. A few of the most commonly used public properties of MenuList are:
| EPiServer:MenuList Properties | Description |
|---|---|
| EnableVisibleInMenu | Show pages that have visible in menu unchecked |
| Set PageLinkProperty to automatically populate PageLink from a given property | |
| Expand all tree nodes. | |
| Set this property to automatically select a page when on start page | |
| Number of levels to show in tree. | |
| Set or get the level of access rights filtering that will be done. | |
| Set PageLinkProperty to automatically populate PageLink from a given property | |
| Gets or sets custom sorting on a property instead of using predefined sorting by setting SortOrder | |
| Predefined sort orders instead of using custom sorting by setting SortBy | |
| Direction for sorting listings specified by SortBy | |
| The root page to read data from |
Below are the template options it offers:
| EPiServer:MenuList Templates | Description |
|---|---|
| The default template for footer | |
| HeaderTemplate | The default template for heading |
| ItemTemplate | Template used for displaying items in the navigation bar |
| SelectedTemplate | Template used for displaying selected items in the navigation bar |
| SeparatorTemplate | The template used between pages |
See the code example for MenuList control in the How To section in this Developers Guide.
EPiServer:NewsList
NewsList has special templates for the first four news and a default NewsTemplate, if you specify NewsTemplate it will be used as fallback for the first four templates that have not been set. If you have defined all templates except NewsTemplate, you will never see more than four news (you only have definitions for the first four news).
If you have defined four templates, but only have two news pages to display, then only two news will be displayed. The NewsList control sets SortBy to "PageStartPublish" and SortDirection to Descending by default. See the NewsList class for information regarding its properties.
Below are the all template options the NewsList control offers:
| EPiServer:NewsList Templates | Description |
|---|---|
| FirstNewsTemplate | The template for the first item |
| SecondNewsTemplate | The template for the second item |
| ThirdNewsTemplate | The template for the third item |
| FourthNewsTemplate | The template for the fourth item |
| HeaderTemplate | Default header template for pages |
| NewsTemplate | If you specify NewsTemplate it will be used as fallback for the first four templates that have not been set |
| PagingFooterTemplate | Footer template for the paging items |
| PagingHeaderTemplate | Header template for the paging items |
| TemplateControl |
Gets or sets a reference to the template that contains this control.
(Inherited from Control.) |
| TemplateSourceDirectory |
Gets the virtual directory of the
Page
or
UserControl that contains the current server control.
(Inherited from Control.) |
| FooterTemplate |
Default template for pages
|
A few of the most used public properties of the NewsList class:
| EPiServer:NewsList Properties | Description |
|---|---|
| MaxCount | The number of PageData objects (EPiServer pages) to list |
| PageLink | The root page to get children from |
| PageLinkProperty | The page property, gets the children of that page |
| PagesPerPagingItem | When paging is enabled, how many PageData objects per page |
| Paging | Controls if paging is used. Set to true to enable paging |
| PublishedStatus | Takes a PagePublishedStatus enum. Default is published |
| RequiredAccess | Takes an AccessLevel enum. Default is read |
| SkipCount | Skip the first x pages. Useful when doing something else with the first x number of pages |
| SortBy | Sort after an EPiServer property |
| SortDirection | Takes a FilterSortDirection enum (remember to add using EPiServer.Filters) |
| SortOrder | Takes a FilterSortOrder enum |
EPiServer:PageTree
The PageTree control is often used when developing more complex menus such as site maps. The PageTree control has many templates that can be utilized, see below:
| EPiServer:PageTree Templates | Description |
|---|---|
| FooterTemplate | The default template for footer |
| HeaderTemplate | The default template for heading |
| ItemTemplate | Template used for displaying items in the navigation bar |
| ExpandedItemTemplate | The default template for expanded pages |
| ExpandedTopTemplate | The template used between pages |
| IndentTemplate | The template for indent rendering |
| SelectedExpandedItemTemplate | The default template for selected and expanded pages |
| SelectedExpandedTopTemplate | The default template for selected and expanded top level pages |
| SelectedItemTemplate | The default template for selected pages |
| TopTemplate | The default template for top level pages |
| UnindentTemplate | The template for unindent rendering |
| EPiServer:PageTree Properties | Description |
|---|---|
| Show pages that have visible in menu unchecked | |
| Set PageLinkProperty to automatically populate PageLink from a given property | |
| Expand all tree nodes. | |
| Set this property to automatically select a page when on start page | |
| Number of levels to show in tree. | |
| Set or get the level of access rights filtering that will be done. | |
| Set PageLinkProperty to automatically populate PageLink from a given property | |
| Gets or sets custom sorting on a property instead of using predefined sorting by setting SortOrder | |
| Predefined sort orders instead of using custom sorting by setting SortBy | |
| Direction for sorting listings specified by SortBy | |
| The root page to read data from |
Further Information
For examples of how the EPiServer controls are used in a website solution, install and browse the code and mark-up in the demo EPiServer CMS template packages.