Navigation menus and listings

Introduction

The navigation menu and listing controls in EPiServer CMS are used for many purposes, for example the creation of listings and website navigation through a top menu and submenus. This document provides an introduction to the EPiServer menu and listing controls available when developing with EPiServer for creating lists of pages, lists of recent news items and navigational menus. The EPiServer menu and listing controls have access to the EPiServer Data Source controls, making them an important part of the website.

EPiServer lists collect and display data

There are many attributes and functions available to the web control, these can be accessed in the code-behind by typing in the control ID and through intellisense a list of the controls attributes and methods is displayed for selection.

Collections of pages

The EPiServer menu and listing controls can handle a collection of pages contained in your EPiServer site. They can obtain this collection in different ways, by setting the following attributes for the listing control:

• PageLink provides a page reference to a page, the children of that page will become the collection used.
• PageLinkProperty provides the name of a property that contains a page reference. That reference will be used as PageLink. This is a commonly used method, since it allows editors to define the page reference for the property.
• DataSource lets the control data bind to the collection retrieved by another control. Useful when one control is most suited to retrieve the correct collection, while another may be more appropriate to render the results. Set the DataSource value to the id of the other control, using an inline data binding expression: <EPiServer:PageList DataSource='<%# ControlID %>' runat="server"... >

Templates controls

EPiServer controls lists are ASP.NET “Templated Controls”. The output generated by EPiServer and ASP.NET web controls is performed and controlled via templates. The templates allow you to control the rendering of data from the control. The templates provide various options and there is a certain way to utilize them. A key aspect of using the templates is specifying the appearance of the data bound to the control.

In the code example below, the PageLink property of the MenuList control is assigned the site’s start page, which will be the root page to read data from. To render the contents of PageLink we insert the PageLink property between the template tags <ItemTemplate> and </ItemTemplate>.

 <episerver:MenuList
    PageLink="<%#EPiServer.Core.PageReference.StartPage%>"
    runat="server" ID="Menu">
     <ItemTemplate>
         <episerver:property ID="Property1" 
         CssClass="NormalLink"
         PropertyName="PageLink" runat="server"/>
     </ItemTemplate>
</episerver:MenuList>

Using menu and listing controls

The EPiServer CMS “all-in-one” listing controls are implemented according to the .NET concept of templated controls, see the ASP.NET Web Server Controls Templates. The rendering of data from EPiServer list and menu controls is carried out through the web controls’ templates, see Templates Introduction for more information about the actual templates and what they do. For further information about deciding which template to use, refer to the relevant web control descriptions below.

When building EPiServer solutions the MenuList and PageList web controls are frequently used to create navigation on a main and sublevel. The NewsList control is used when you need to render different markup for the first pages in a list of pages.

As each control is designed for a certain type of list, it is recommended that you familiarize yourself with all the controls before starting developing.

The following basic approaches can be used when developing with the EPiServer listing controls types of lists:

• Use specific “all-in-one” EPiServer listing controls. One listing control contains the data from another listing control.
• Use EPiServer Data Source controls in the EPiServer listing control.

EPiServer uses the following menu and listing web controls, described in more detail below:

• EPiServer:PageList - controls rendering a page list, extends PageList with templates.
• EPiServer:MenuList - renders a menu list of top level items, useful for navigations with a top level menu and clickable sublevels.
• EPiServer:NewsList - control for rendering news list with a specialized template for top level news.
• EPiServer:PageTree - control for rendering page trees, extends PageTreeData with templates.

EPiServer:PageList

The PageList control is usually used to list EPiServer pages, and is very similar to other data controls, such as asp.Repeater. It has some built-in features that make it easy to use in certain scenarios, for example, you can easily filter the data and add paging to it.

Frequently used properties

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 EPiServer.Filters).
SortOrder	Takes a FilterSortOrder enum.

Frequently used templates

EPiServer:PageList Templates	Description
FooterTemplate	Template for listing a footer.
HeaderTemplate	Template for listing a header.
ItemTemplate	The default template for pages.
PagingFooterTemplate	Footer template for the paging items.
PagingHeaderTemplate	Header template for the paging items.

EPiServer:MenuList

The MenuList control is frequently used to create the top level menu when building the navigation in an EPiServer website. Start out with the MenuList for the top level menus, and use the PageTree control for the submenus.

Frequently used properties

EPiServer:MenuList Properties	Description
EnableVisibleInMenu	Show pages that have the Show in menus option cleared in Edit view.
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 selecting the start page.
NumberOfLevels	Set the number of levels to show in the 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	Show the root page.
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.

Frequently used templates

EPiServer:MenuList Templates	Description
FooterTemplate	The default template for a footer.
HeaderTemplate	The default template for a 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.

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 still only see 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.

Frequently used properties

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 EPiServer.Filters).
SortOrder	Takes a FilterSortOrder enum.

Frequently used templates

EPiServer:NewsList Templates	Description
FirstNewsTemplate	The template for the first news item.
SecondNewsTemplate	The template for the second news item.
ThirdNewsTemplate	The template for the third news item.
FourthNewsTemplate	The template for the fourth news item.
HeaderTemplate	Default header template for news 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 of news items.
PagingHeaderTemplate	Header template for the paging of news 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.

EPiServer:PageTree

The PageTree control is often used when developing more complex menus, such as site maps.

Frequently used properties

EPiServer:PageTree Properties	Description
EnableVisibleInMenu	Show pages that have the Show in menus option cleared in Edit view.
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	Set the 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	When rendering the root page as part of the tree, when data is data bound to another control that does the tree structure rendering.
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.

Frequently used templates

EPiServer:PageTree Templates	Description
FooterTemplate	The default template for the footer.
HeaderTemplate	The default template for the 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.
SelectedTopTemplate	The default template for selected top level pages.
UnindentTemplate	The template for unindent rendering.

See also

• Creating page templates and block controls in the EPiServer CMS SDK.
• Pages, page types and page templates in the EPiServer CMS SDK.
• For more examples of how the EPiServer controls are used in a website, install and browse the code and markup in the EPiServer CMS sample template packages.