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
EvaluateHasChildren Set PageLinkProperty to automatically populate PageLink from a given property
ExpandAll Expand all tree nodes.
ExpandNodeIfStartPage Set this property to automatically select a page when on start page
NumberOfLevels Number of levels to show in tree.
RequiredAccess Set or get the level of access rights filtering that will be done.
PageLinkProperty Set PageLinkProperty to automatically populate PageLink from a given property
ShowRootPage  
SortBy Gets or sets custom sorting on a property instead of using predefined sorting by setting SortOrder
SortOrder Predefined sort orders instead of using custom sorting by setting SortBy
SortDirection Direction for sorting listings specified by SortBy
PageLink The root page to read data from

Below are the template options it offers:

EPiServer:MenuList Templates Description
FooterTemplate 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
EnableVisibleInMenu Show pages that have visible in menu unchecked
EvaluateHasChildren Set PageLinkProperty to automatically populate PageLink from a given property
ExpandAll Expand all tree nodes.
ExpandNodeIfStartPage Set this property to automatically select a page when on start page
NumberOfLevels Number of levels to show in tree.
RequiredAccess Set or get the level of access rights filtering that will be done.
PageLinkProperty Set PageLinkProperty to automatically populate PageLink from a given property
ShowRootPage  
SortBy Gets or sets custom sorting on a property instead of using predefined sorting by setting SortOrder
SortOrder Predefined sort orders instead of using custom sorting by setting SortBy
SortDirection Direction for sorting listings specified by SortBy
PageLink 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.