This content is archived. See latest version here.

Last updated: Mar 31 2014

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"... >
Note DataSource can be combined with one of the two attributes above, leading to a merged collection from two sources. However, for EPiServer’s data source controls the preferred way of passing the data is by setting the DataSourceID attribute, rather than the inline syntax described above.

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.

Comments