Loading...
Area: Optimizely CMS
Applies to versions: 10-11
Other versions:
ARCHIVED This content is retired and no longer maintained. See the version selector for other versions of this topic.

Navigation menus and listings

Recommended reading 

Note: This topic applies to Web Forms.

You can use the navigation menu and listing controls in Episerver CMS for many purposes, such as the creation of listings and website navigation through a top menu and submenus. This topic introduces the Episerver menu and listing controls available for creating lists of pages, 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, which you access in the code-behind by typing in the control ID. Intellisense displays a list of the control's attributes and methods 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 become the collection used.
  • PageLinkProperty. Provides the name of a property that contains a page reference, which is used as PageLink. This is a commonly used method because it lets editors define the page reference for the property.
  • DataSource. Lets the control data bind to the collection retrieved by another control, which is 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"... >
    Note: You can combine DataSource with one of the two attributes above, leading to a merged collection from two sources. However, for Episerver's data source controls, you should pass the data is by setting the DataSourceID attribute, rather than the inline syntax described above.

Templates controls

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

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

 <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 occurs through the web controls’ templates. For information about deciding which template to use, refer to the relevant web control descriptions in this topic.

When you build Episerver solutions, use the MenuList and PageList web controls to create navigation on a main and sublevel. Use the NewsList control 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, familiarize yourself with all controls before you start developing.

You can use the following basic approaches 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:

EPiServer:PageList

Use the PageList control to list Episerver pages. This is similar to other data controls, such as asp.Repeater. It has built-in features to use in certain scenarios, such as filtering data and adding paging to it.

Frequently used properties

EPiServer:PageList PropertiesDescription
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 whether 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 TemplatesDescription
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

Use the MenuList control to create the top level menu when building website navigation. Start with the MenuList for the top level menus, and use the PageTree control for the submenus.

Frequently used properties

EPiServer:MenuList PropertiesDescription
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 TemplatesDescription
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 pages and a default NewsTemplate. If you specify NewsTemplate, it is used as fallback for the first four templates that were not set. If you defined all templates except NewsTemplate, you still see only four news pages (you only have definitions for the first four news pages).

If you have defined four templates, but only have two news pages to display, only two news pages are displayed. The NewsList control sets SortBy to PageStartPublish, and SortDirection to Descending by default. See the NewsList class for information about its properties.

Frequently used properties

EPiServer:NewsList PropertiesDescription
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 TemplatesDescription
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 is 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

Use the PageTree control to develop more complex menus, such as site maps.

Frequently used properties

EPiServer:PageTree PropertiesDescription
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 TemplatesDescription
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.

Related topics

Do you find this information helpful? Please log in to provide feedback.

Last updated: Oct 27, 2016

Recommended reading