EPiServer CMS Programmer's Reference

Product version:

EPiServer CMS 4.62

Document version:

1.0

Document creation date:

07-06-2006

Document last saved:

05-10-2007

Purpose

This programmer's reference is intended to be read by EPiServer CMS developers as an introduction to developing solutions with EPiServer CMS. The document outlines the basics for getting started with EPiServer CMS development, and also includes a description of the EPiServer CMS object model and an introduction to EPiServer CMS API.



Table of Contents

EPiServer CMS and .NET 
    - Object Orientation
    - EPiServer CMS 4.60 / 4.61 – ASP.NET 1.1 or ASP.NET 2.0?

EPiServer CMS System Overview
    - EPiServer CMS Architecture

Important Concepts
    - Page Type
    - Page
    - Page Template    
    - Framework Definition Files
    - Web Forms
    - Web User Control
    - Web Control

Getting Started with EPiServer CMS Development
    - Open the Project in Visual Studio.NET
    - Folder Contents and References
    - Compilation
    - Fixing HTML
    - IntelliSense
    - Runat=”server”
    - Aspnet_regiis
    - @ Register
    - Troubleshooting
    - EPiServer CMS Software Development Kit (SDK)

Creating a Basic Page Template

Developing User Controls in EPiServer CMS
    - Creating a Basic Web User Control
    - Creating A Basic Menu in an EPiServer CMS Page Template Using EPiServer CMS Web Controls
    - Creating Another Menu in EPiServer CMS

Appendix - EPiServer CMS API
    - Namespaces in EPiServer CMS
    - Base Classes in EPiServer CMS
    - Data Management



EPiServer CMS and .NET

EPiServer CMS is 100% based on .NET technology. .NET is a technology launched by Microsoft to meet future technology requirements. Some of the advantages of development with .NET:

  • Easier for developers to implement customer solutions quickly, because it is possible to create a number of template development functions in Visual Studio .NET using drag-and-drop functionality.
  • Increases the opportunities for integration with other systems and platforms using Web services.
  • Improves performance using the integrated cache functions in .NET.

The main difference between ASP.NET and traditional ASP pages is the fact that the code and the design are separated in quite a different way. The markup that determines the appearance, color and layout of the page is stored in a file with the extension .aspx and the code is stored in a file with an extension that depends on the programming language, which in the case of EPiServer CMS is .cs. It is also possible to create Web controls, which are reusable components that can be included and reused in different page templates.

.NET has been implemented in accordance with the guidelines provided by Microsoft. The fact that .NET is a language-independent architecture means that developers have a wide choice of development methods for their solutions. EPiServer CMS is written in C#, but developers are free to use another programming language such as VB.NET or J#. For further information on .NET, refer to Microsoft's .NET documentation.

Object Orientation

EPiServer CMS development in .NET makes it fully object-oriented. If you want to add new functionality in EPiServer CMS, you don't need to go into include files and change the program code. Instead you inherit the compiled base classes that are supplied and add the functionality you need, which can then be accessed by the Web developers.

EPiServer CMS 4.60 / 4.61 – ASP.NET 1.1 or ASP.NET 2.0?

EPiServer CMS 4.60 and 4.61 are, as previous EPiServer CMS 4 versions, based on .NET 1.1 to allow backwards compatibility and does not use technology introduced in .NET 2.0.

There are 2 template packages available for download in EPiServer CMS 4.60; one template package for ASP.NET 1.1 and another for ASP.NET 2.0. They contain the same functionality, but one package has been converted to work in the ASP.NET 2.0 environment. Projects built Visual Studio .NET 2003 can be converted to Visual Studio 2005 by using the built-in conversion wizard.

NOTE: As EPiServer CMS 4.60 and 4.61 are built on ASP.NET 1.1, the examples in this document are based on Visual Studio .NET 2003.

For further information on the changes when using ASP.NET 2.0 and Visual Studio 2005, refer to the EPiServer CMS 4.61 Release Notes.

EPiServer CMS System Overview

EPiServer CMS consists of a base platform that contains all basic functionality, like page templates and other technical details. Web pages that contain the company's graphical profile with logos, fonts, colors, and images are created on this platform.

EPiServer CMS uses Microsoft Internet Information Server as a Web server to handle Web publication. All the information displayed on these Web pages is stored behind the scenes in an SQL server or Oracle database. The Web server and the database are run on a Windows server. EPiServer CMS uses the same authorization model as Windows, which means authorization work is extremely simple. Images and documents that editors upload onto the Web server are stored in one or more separate data sources on the Web server.

EPiServer CMS customizations contain four parts:

  • The company's graphical profile that is stored in a style sheet.
  • Page templates that describe the functions to be used.
  • Access rights that editors and visitors have.
  • Information stored in a database.

EPiServer CMS Architecture

The basic requirements for the EPiServer CMS platform are Internet Information Server (IIS), .NET Framework and SQL Server or Oracle database. The Web interface is developed in ASP.NET. The figure below outlines EPiServer CMS architecture.

The user interface works with the compiled base classes that are supplied. These base classes manage the logic within EPiServer CMS and are compiled objects. EPiServer CMS also has integrated functions for modifying and configuring the Web, using the files web.config and global.asax. This is handled by specific objects in EPiServer CMS.

Language processing is based on XML files and it is possible to add a new language simply by copying a language file to a folder. The language is then implemented automatically across the entire Web site. It is also possible to link language information to Web controls that you have developed.

Layering in EPiServer CMS is very clear. There is a clear-cut division between the user interface and the business logic and it is easy to distribute EPiServer CMS across a number of servers that represent logical units in the system. Debugging your own solutions is also relatively easy.

Important Concepts

Page Type

Administrators define the page types that will be available to editors in Admin mode. Each Web site can consist of numerous page types and each page type consists of several properties. Each property is displayed as a field when EPiServer CMS editors create pages. Properties that apply to several page types are created as dynamic properties for the Web site. Each property is of a certain type, deciding what kind of values can be entered for the property.

All page types are connected to a page template, which shows the content that the editor has created. Information about the page types and dynamic properties is stored in the database.

Page

Pages contain content and are created by editors by selecting which page type to use. Information that is saved on a page is stored in the EPiServer CMS database.

Page Template

A page template is an ASP.NET Web Form and is created using Visual Studio .NET. All page types are connected to a page template, but one page template can be used for several page types. Page templates contain functionality and design for the relevant page type.

In order for content that the editor has saved to be visible, the properties in page types must be called from page templates. When someone visits the Web site, the .aspx page fetches the correct information from the database.

Framework Definition Files

Framework definition files are generally created by EPiServer CMS developers and are ASP.NET user controls (.ascx files) used to create the visual layout of a Web site. Framework definition files and page templates form the EPiServer CMS Content Framework, which is the preferred method to separate layout from content. For more information about EPiServer CMS Content Framework, refer to the technical note "Building Web Sites Using EPiServer CMS Content Framework".

Web Forms

Web Forms pages can be used to create programmable Web pages that serve as the user interface for a Web application. Web Forms pages are based on Microsoft ASP.NET technology in which code that runs on the server dynamically generates Web page output to the browser or client device. Web Forms are compatible with any browser or mobile device and are compatible with any language supported by the .NET common language runtime. Web Forms are flexible because you can add user-created and third party controls to them.

Web User Control

A Web user control allows a developer to pack up a common user interface and program logic in such a way that this can be used as a component in Web solutions. It increases the reusability of code. The next time similar functionality is needed in pages written in ASP.NET, it is simply a case of using the control instead of rewriting the code from scratch. Web User controls encapsulate code and the user interface, which in turn means that pages in ASP.NET are easier to read and that the code is kept as clean as possible.

A Web user control is similar to a complete Web Forms page, with both a design file and a code-behind file. To be able to use a Web user control in a design file, it must be registered by placing the following code at the top of the file. 

<%@ Register TagPrefix="prefix" TagName="tag" Src="~path/file.ascx" %>

 

Web Control

Web controls are "tools" used by developers that serve a specific purpose. The EPiServer.WebControls namespace contains Web controls for rendering page information, tree structures, page lists, etc. to a browser. To be able to use a Web control in a design file, it must be registered by placing the following code at the top of the file. 

<%@ Register TagPrefix="EPiServer" Namespace="EPiServer.WebControls" Assembly="EPiServer" %>

The Property Web control is one of the most commonly used Web controls. It is used on Web Forms and Web user controls and renders the value of built-in or custom properties. The following example shows how to print the name of the page to HTML. 

<EPiServer:Property PropertyName="PageName" runat="server" />

 

Getting Started with EPiServer CMS Development

Open the Project in Visual Studio.NET

It is possible to develop solutions based on EPiServer CMS using any text editor, e.g. Notepad. This document describes EPiServer CMS development using Microsoft Visual Studio .NET 2003/2005 as it provides advantages such as easy compilation, IntelliSense, and online documentation. If you prefer to work with another tool, refer to the documentation for .NET Framework and the tool concerned.

The standard distribution of EPiServer CMS contains a sample project for Visual Studio.NET, which in most cases functions as a starting point for further development of Web solutions.

To open the project, open the file EPiServerSample.csproj.webinfo located at C:\Inetpub\MyEPiServer\, unless you specified another location during installation. This file contains the following information. Change the content to match the configuration on your workstation and open the EPiServer CMS project EPiServerSample.csproj

<VisualStudioUNCWeb>

       <Web URLPath = "http://localhost/EPiServerSample.csproj" />

</VisualStudioUNCWeb>

 

Folder Contents and References

Solution Explorer in Visual Studio contains a representation of the structure of the sample Web site. Start by clicking Show All Files in Solution Explorer to show all the files and references in the EPiServer CMS project.

NOTE: The folders that appear transparent are for some reason not included in the EPiServer CMS sample project. They may be system files and altering these files could affect future upgrades of the product.

Folder

Description

References

This directory stores references to the functionality desired. It is also possible to add references to Web Services here. References to the basic classes in EPiServer CMS are stored here.

admin

ASP.NET files for Admin mode. If any files in this directory are altered, the upgrade program will replace these files and any functionality developed in-house in Admin mode will be lost.

bin

The compiled files for EPiServer CMS are stored in this directory, and the entire class library is stored in the episerver.dll file. All new functionality stored in the Web project will automatically be compiled into the EPiServerSample.dll file.

docrepository

Folder for storing documents that use the EPiServer CMS version control functionality.

edit

ASP.NET files for Edit mode. Any changes made to files will be lost on system upgrades.

images

Contains images that make up the main design of the Web site, e.g. logo, banners, buttons, etc. It is recommended that EPiServer CMS editors do not save images in this folder. This decreases the risk that editors change images that affect the main design of the Web site.
The /images folder is not changed at upgrade.

lang

Contains language files, stored as XML, for the Web site. If you want to make changes to these files, save the new XML files whose contents will apply instead of the original files. Language files are read in alphabetical order, so if you want to save new language data, you need to name the file so that it is placed after those supplied with the installation.

There are two language files for each language:

•             LanguageXX.xml, e.g. LanguageEN.xml, contains all the words in Edit and Admin mode. These files are replaced during system upgrade.

•             TemplateLanguageXX.xml, e.g. TemplateLanguageEN.xml contains the words used in the EPiServer sample site. These files are not replaced during system upgrade.

styles

Contains the cascading style sheets (css) for the Web site. Add the EditMenuName attribute to make it possible for editors to choose styles from the styles list in the Editor.
The /styles folder is not changed at upgrade.

templates

The templates folder contains all the page templates for the Web site and their corresponding code-behind files. It is common that customized Web sites have another folder containing customized page templates.

The /templates/Frameworks folder contains the framework definition file. The /templates/Units folder contains ASP.NET user controls.
The /templates folder is not changed at upgrade.

upload

When files are uploaded by editors, they are usually kept in this folder. Several different starting points can be used and sub-folders can be created automatically for each page, numerically. It is advisable that you decide at an early stage in the project whether editors should upload files as "global files" or "page files".
The /upload folder is not changed at upgrade.

Util

Utilities for Admin and Edit modes, mostly ASP.NET user controls. Also folders for style sheets, JavaScript files and images.
The Util folder may be changed at upgrade.

WebServices

Contains the XML Web Services files: Authenticate.asmx, CacheService.asmx, DataFactoryService.asmx, and PageMirroringService.asmx.

Compilation

As ASP.NET is a compiled environment, it is important to remember to recompile the project following any changes to code-behind files. This is necessary for the system to function and for changes to take effect. Changes to the .aspx pages, however, do not call for a recompile.

When you start developing using EPiServer, there are several things that can help you get started with your development.

Fixing HTML

If you switch to the Design tab in Visual Studio.NET, the system may make changes to the HTML code you produced on your ASP.NET page. A tip is to deactivate that functionality in Visual Studio .NET under Tools | Options | Text Editor | HTML/XML | Format.

It is also recommended that you apply a setting to Visual Studio so that all HTML pages, Active Server Pages, and Web Form pages are opened in HTML View. This prevents the Design view from making changes to the code when you open a file. This option is set in Visual Studio .NET under Tools | Options | HTML Designer. Select HTML View for all the radio buttons in this dialog.

IntelliSense

If you want to add IntelliSense specific to EPiServer CMS in the HTML tab, save the EPiServer.xsd file, which is available in the SDK zip file, in the directory for Visual Studio .NET 2003, C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\schemas\xml.

In order for it to function in the HTML layer, there are two ways to add a reference to an XML namespace:

  1. In the <body> tag of the ASP.NET page.


  2. <body xmlns:EPiServer="http://schemas.episerver.com">

    ...

    ...

    </body>


  3. In a <span> tag at the top of the file if the ASP.NET page does not include a <body> tag.

    <span xmlns:EPiServer="http://schemas.episerver.com">

Runat=”server”

When you add a Web control to an ASP.NET page, you must add runat=”server” along with the marker for the control that is to be executed by the server before it is distributed to the client.

Aspnet_regiis

When installing EPiServer CMS, it is sometimes required that the script library for .NET is registered. This is done by running the command aspnet_regiis in a command prompt with the flag -c.

Note This is only required if the installation program does not automatically register the script library for .NET.

@ Register

The @ Register directive is used to associate aliases with namespaces in a user control and can be used to:

  1. register the EPiServer CMS Web controls;
  2. register your Web controls or Web user controls.

Example

The following code fragment uses @ Register directives to declare tagprefix and tagname aliases for a server control and a user control.

  1. The first @ Register directive declares the EPiServer CMS alias as a tag prefix for all controls residing in the EPiServer.WebControls namespace.
  2. The second @ Register directive declares Demo:Birthday as a tagprefix:tagname pair for the user control in the file mydate.ascx.

The aliases are then used in custom server-control syntax within the form to insert an instance of each server control.

<%@ Page language="c#" Codebehind="birthday.aspx.cs" AutoEventWireup="false" Inherits="development.templates.birthday" %>

<%@ Register Tagprefix="EPiServer" Namespace="EPiServer.WebControls" Assembly="EPiServer" %>

<%@ Register Tagprefix="Demo" Tagname="Birthday" Src="~/templates/units/mydate.ascx" %>

<HTML>

 <body xmlns:EPiServer="http://schemas.episerver.com">

   <form id="Form1" runat="server">

      <EPiServer:Property runat="server" /><BR>

      <Demo:Birthday runat="server" />

   </form>

 </body>

</HTML>

 

Troubleshooting

Web.config

If you make amendments to the Web.config file and in any way violate the rules of XML, e.g. forget to properly terminate a tag, your Web application will not start. You will usually see a descriptive error message pinpointing the source of the problem. If you work on an EPiServer CMS installed on another physical server, you may also receive an error message, which is not particularly detailed. This makes troubleshooting more difficult.

Web Site Ceases to Function when a Compiling Error Occurs

As ASP.NET is basically a compiling language, the whole Web site ceases to function if there is a compilation error. This is unlike traditional ASP, which is an interpreter, where the error message only arises when the faulty code is executed.

CTRL+F5

If changes to the Web site do not appear at once, this might be due to caching in the client. Press CTRL+F5 from the Web browser instead of clicking Update.

EPiServer CMS Software Development Kit (SDK)

The EPiServer CMS Software Development Kit is downloaded from the EPiServer Download Center and contains a lot of information useful to EPiServer CMS developers, e.g. EPiServer CMS API documentation. The SDK zip file contains a compiled HTML Help file and other files that are useful for EPiServer CMS development, e.g. file to implement IntelliSense in Visual Studio .NET.

From EPiServer CMS 4.60, the EPiServer help file can easily be integrated into Visual Studio 2003/2005.

NOTE: Help file integration to Visual Studio will only integrate the help file – the other files can only be downloaded from the SDK zip file.

File Names

Explanation

ApprovalTask.ascx

User control for workflow.

ApprovalTask.ascx.cs

Code-behind file for ApprovalTask.ascx.

EPiServer.xsd

File to implement IntelliSense in Visual Studio.NET.

EPiServer4SDK.chm

Compiled HTML Help file, in which the whole of the API is specified and which can be used as a reference when developing Web sites.

FilterCount.cs

Sample filter in EPiServer CMS limiting the number of pages shown.

FilterEventArgs.cs

Source code for the argument class, which is called in a filter event.

PageList.cs

Sample code showing how page listing functions in EPiServer CMS.

PageTree.cs

Sample code showing controls for page trees.

PropertyNumber.cs

Sample code showing how a property is saved in EPiServer CMS.

PropertyWeekday.cs

Sample code showing how weekdays are displayed in Edit mode.

readme.htm

Information about the contents of the SDK zip file.

XFormsPostings.ascx

User control to get a list of XForms postings.

XFormPostings.ascx.cs

Code-behind file for XFormsPostings.ascx.

Creating a Basic Page Template

A basic template would be to add a property that allows EPiServer CMS editors to add the date and location of their birthday party to a page. (The fields can also be added to existing templates, but a new template is created in this example for demonstration purposes.)

1. Open Admin mode and go to the Page Type tab. Click Create New Page Type from the Manage Page Types section.

2. Enter a name, description and file search path for the page template, e.g. /templates/birthday.aspx.

Note The File name field must also contain the virtual directory in which EPiServer CMS was installed (if any), as in the example below.

3. Add a property to the page type by clicking Add Property. Enter a property name in the Name field. Note that the property name cannot contain blank spaces, as it will be included in the page template code. The value entered in the Edit Heading field appears in Edit mode as a label and the text in the Help Text field is the ToolTip for the field in Edit mode.

         

4. Open Visual Studio and create a template by right-clicking the folder under which you want to create your template, e.g. under /Templates, and select Add | Add Web Form. Enter the name of the Web Form in the Name field, e.g. Birthday.aspx. Enter the following code:

<%@ Page language="c#" Codebehind="birthday.aspx.cs" AutoEventWireup="false" Inherits="development.templates.birthday" %>

<%@ Register TagPrefix="EPiServer" Assembly="EPiServer" Namespace="EPiServer.WebControls" %>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >

<html>

<head>

    <title>Birthday</title>

</head>

<body xmlns:EPiServer="http://schemas.episerver.com">

    <form id="Form1" method="post" runat="server">

       <p>

       The date and time of my birthday party:

       <EPiServer:Property PropertyName="BirthdayPartyDate" runat="server"/>

       <br/>

              The birthday party will be held at:

    <EPiServer:Property PropertyName="BirthdayPartyLocation" runat="server"/>    

       </p>

    </form>

</body>

</html> 

5. Open the code-behind file for the Web Form, e.g. Birthday.aspx.cs, and make sure that the class inherits from an EPiServer CMS page template base class, usually   EPiServer.TemplatePage (marked in bold).

using System;

...

...

namespace development.templates

{

       public class birthday : EPiServer.TemplatePage

       {

              ...

              ...

              ...

       }

} 

6. Remember that all changes to code-behind files must be re-compiled in order for them to take affect, so build the project.

7. Go to Edit mode, create a page based on the Birthday page type and add information to the available properties. Click Save and Publish.

8. The page should be displayed as below in View mode.

    See the chapter, "Creating a Basic Web User Control" for an example of what the page that was created with the above page template together with a basic Web user control looks like.

    Developing User Controls in EPiServer CMS

    It is recommended that developers building Web sites based on EPiServer CMS create their own user controls with links to base classes in EPiServer CMS. This chapter shows how easy it is to integrate them into the EPiServer CMS API. User controls are also a perfect way to leverage the content framework that EPiServer CMS uses to define the overall page layout.

    Creating a Basic Web User Control

           1.       Open Visual Studio and create a Web user control by right-clicking the folder under which you want to create your template, e.g. under /Templates/Units, and select Add | Add Web User Control. Enter the name of the Web user control in the Name field, e.g. mydate.ascx. Enter the following code to create a Web user control that displays the current date and time.
    The first line of code is a directive that determines the name of the user control. The other line shows what will be displayed, in this case the current date and time.

    <%@ Control Language="c#" AutoEventWireup="false" Codebehind="mydate.ascx.cs" Inherits="development.templates.Units.mydate" TargetSchema="http://schemas.microsoft.com/intellisense/ie5" %>

    <p> The current date is: <%= DateTime.Now.ToString() %> </p>

           2.       To display a user control on a page that is written in ASP.NET, you must register it and indicate where the control file is stored. You do this using the @ Register directive. See the "@ Register" chapter for further information on  this.
    The example below displays the user control in the Web Forms page created in the chapter, "Creating a Basic Page Template."

    <%@ Page language="c#" Codebehind="birthday.aspx.cs" AutoEventWireup="false" Inherits="development.templates.birthday" %>

    <%@ Register TagPrefix="EPiServer" Assembly="EPiServer" Namespace="EPiServer.WebControls" %>

    <%@ Register TagPrefix="Demo" TagName="Birthday" Src="~/templates/units/mydate.ascx" %>

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >

    <html>

    <head>

        <title>Birthday</title>

    </head>

    <body xmlns:EPiServer="http://schemas.episerver.com">

        <form id="Form1" method="post" runat="server">

           <p>

         The date and time of my birthday party:

          <EPiServer:Property PropertyName="BirthdayPartyDate" runat="server"/>

         <br/>

          The birthday party will be held at:

           <EPiServer:Property PropertyName="BirthdayPartyLocation"

           runat="server"/>    

           <Demo:Birthday runat="server"/>

         </p>

        </form>

    </body>

    </html>

    The finished Web Forms page with the Web user control should look something like this: 

     

    Creating A Basic Menu in an EPiServer CMS Page Template Using EPiServer CMS Web Controls

    This chapter describes how to create a simple menu in an EPiServer CMS Page Template. The example uses the Web User Control that was created in the previous chapter.

    Create a Web User Control

           1.       Create a Web user control by right-clicking the folder under which you want to create your template, e.g. under /Templates/Units, and select Add | Add Web User Control. Enter the name of the Web user control in the Name field, e.g. DemoMenu2.ascx.

           2.       This user control is to be based on the EPiServer CMS MenuList Web control. Enter the following text into the HTML view:

    <%@ Register TagPrefix="EPiServer" Namespace="EPiServer.WebControls" Assembly="EPiServer" %>

    <EPiServer:MenuList PageLink='<%# Configuration.StartPage %>' runat="server">

           <HeaderTemplate>

                  <br/><b><%# Configuration.SiteName %></b><br/>

           </HeaderTemplate>

           <FooterTemplate>

                  <b><%= DateTime.Now.ToShortDateString() %></b><br/>

           </FooterTemplate>

           <ItemTemplate>

                  <EPiServer:Property PropertyName="PageLink" runat="server" />

                  <br/>

           </ItemTemplate>

    </EPiServer:MenuList>

    Data Bind the Control

    When using a data binding expression to set PageLink, we need to explicitly data bind the control.

           1.       Open the code-behind file connected to your user control, in this example DemoMenu2.ascx.cs. A user control will by default inherit from the class System.Web.UI.UserControl, but to allow easy access to EPiServer objects, it is preferable to inherit from EPiServer.UserControlBase.

    Change the class definition so that it looks something like below:

    public class DemoMenu2: EPiServer.UserControlBase

    {

    // rest of the class definition

    }

     

           2.       In order to data bind the menu to its data source, add the following to DemoMenu2.ascx.cs. Save and re-compile.

    ...

    private void Page_Load(object sender, System.EventArgs e)

    {

           if(!IsPostBack)

                  DataBind();

    }

    ... 

    Include the User Control in Your EPiServer CMS Page Template

    To view the appearance of your menu, register and include it in an EPiServer CMS page template.

           1.       Register the user control in the Birthday page template by adding the following code to birthday.aspx that you created in the previous chapter.

    <%@ Register TagPrefix="Demo1" TagName="DemoMenu2" Src="~/templates/units/demomenu2.ascx" %> 

     

    and add the reference to the user control with the following code in the same file.

    <Demo1:DemoMenu2 runat="server" id=DemoMenu2 />

    The result is a menu that should look like below. It is, of course, possible to develop the menu in such a way that it shows the complete tree structure, but that is not within the scope of this document.

    Creating Another Menu in EPiServer CMS

    This chapter explains how to create a simple menu using the Microsoft CMS DataList Web server control, which is supplied with Visual Studio.NET and EPiServer CMS. This should only be regarded as an example, but the code can of course be developed to produce a general control.

    NOTE: The reason for using the DataList control in this example is that it is easy to use and automatically creates code based on the Web browser that calls it. It also has an intuitive and attractive interface for configuring the appearance and content of the control in the design view.

    Create a Web Forms Page and User Control

           1.       Open Visual Studio and create a template by right-clicking the folder under which you want to create your template, e.g. under /Templates, and select Add | Add Web Form. Enter the name of the Web Form in the Name field, e.g. showmenu.aspx. Enter the following code:

    <%@ Page language="c#" Codebehind="ShowMenu.aspx.cs" AutoEventWireup="false" Inherits="development.templates.ShowMenu" %>

    <%@ Register TagPrefix="EPiServer" Assembly="EPiServer" Namespace="EPiServer.WebControls" %>

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >

    <html>

    <head>

        <title>ShowMenu</title>

    </head>

    <body xmlns:EPiServer="http://schemas.episerver.com"/>

       <form id="Form1" method="post" runat="server">

           <p>

           The following example shows how to create a basic menu that looks

           something like this:

           </p>

        </form>

    </body>

    </html>

           2.       Remember that all changes to code-behind files (including adding new files) must be re-compiled in order for them to take affect, so build the project.

           3.       Create a Web user control by right-clicking the folder under which you want to create your template, e.g. under /Templates/Units, and select Add | Add Web User Control. Enter the name of the Web user control in the Name field, e.g. DemoMenu.ascx.

           4.       This user control is to be based on the DataList object. Change to Design View in DemoMenu.ascx and drag a DataList from the Web Forms tab in the toolbox onto the work area. When you change to HTML view, the code will be displayed as below:

    <%@ Control Language="c#" AutoEventWireup="false" Codebehind="DemoMenu.ascx.cs" Inherits="development.templates.Units.DemoMenu" TargetSchema="http://schemas.microsoft.com/intellisense/ie5"%>

       <asp:DataList id="DataList1" runat="server"></asp:DataList>

           5.       DataList controls include a number of different tools that allow you to change the appearance of the control in Visual Studio.NET. To make the menu look more attractive, use one of the predefined color schemes that are available. Right-click DataList in the Design view in Visual Studio and select Auto Format… Select the Colorful 3 color scheme and click OK.

           6.       When you look at the code that has been produced in the HTML view, you will see that a number of styles that control the format of the DataList have been added.

    Link a Data Source to the Control

    So far we have only created an empty shell for the control. To make it really interesting, we also need a data source.

           1.       Open the code-behind file connected to your user control, in this example DemoMenu.ascx.cs, and add the lines marked in bold to the code.

    using System;

    using System.Data;

    using System.Drawing;

    using System.Web;

    using System.Web.UI.WebControls;

    using System.Web.UI.HtmlControls;

    using EPiServer;

    using EPiServer.Core

     

           2.       A user control will by default inherit from the class System.Web.UI.UserControl, but to allow easy access to EPiServer CMS objects, it is preferable to inherit from EPiServer.UserControlBase.
    Change the class definition so that it looks something like below:

    public class DemoMenu : EPiServer.UserControlBase

    {

    // rest of the class definition

    } 

           3.       Don't forget to re-compile your solution after making any changes to the code-behind file.

    The instancing of the object takes place in the Page_Load event. To extract the information about the top level of pages in EPiServer CMS we will call the method GetChildren, which takes the parent page as a parameter.

    In this case we will choose the Web site's home page, which is stored in EPiServer.Global.EPConfig.StartPage, but since we inherit from UserControlBase we can access that information via Configuration.StartPage.

    (It may, of course, be a good idea to include a property in the control that allows you to use any home page. In order to keep the example basic and make the code easy to read, we have not included this property here.)

    The method GetChildren returns a PageDataCollection which can be used as a data source to the DataList. Finally the method DataBind() must be called by the DataList in order to perform the data binding.

           4.       Add the following to DemoMenu.ascx.cs. Save and re-compile.

    ...

    private void Page_Load(object sender, System.EventArgs e)

    {

       PageDataCollection myColl = EPiServer.Global.EPDataFactory.GetChildren(EPiServer.Global.EPConfig.StartPage);

       DataList1.DataSource = myColl;

       DataList1.DataBind();

    }

    ...

     

    Display the Contents of the DataList

    In order to display the contents of the DataList, we need a container object, which is available when you are writing code inside the templates of a templated control.

           1.       Add the following code to DemoMenu.ascx and save the file.

    <asp:DataList>

    ...

       <HeaderTemplate><%# EPiServer.Global.EPConfig.SiteName %></HeaderTemplate>

       <FooterTemplate><%= DateTime.Now.ToShortDateString() %></FooterTemplate>

       <ItemTemplate>

          <a href='<%# DataBinder.Eval( Container.DataItem, "LinkURL" ) %>'>

          <%# DataBinder.Eval( Container.DataItem, "PageName" ) %>

          </a>

       </ItemTemplate>

    ...

    </asp:DataList>

           2.       Register the user control in the Web Form by adding the following code to ShowMenu.aspx.

    <%@ Register TagPrefix="Demo1" TagName="DemoMenu" Src="~/templates/units/demomenu.ascx" %>

     

    and add the reference to the user control with the following code in the same file. 

    <Demo1:DemoMenu runat="server" id=DemoMenu1 />

    The result is a menu that should look like below. It is, of course, possible to develop the menu in such a way that it shows the complete tree structure, but that is not within the scope of this document.

    Appendix - EPiServer CMS API

    Namespaces in EPiServer CMS

    EPiServer is an assembly in .NET with a database and a GUI written in ASP.NET. The most interesting feature for developers is the assembly, which contains all the namespaces and objects that make up the publishing functionality in EPiServer CMS. A namespace is a natural grouping of objects that handles different parts of the system. A short description of the namespaces provided with EPiServer CMS is given below:

    EPiServer

    The EPiServer root namespace contains some of the most important and central classes, like DataFactory, PageBase, TemplatePage, UserControlBase, ApplicationConfiguration and the Global class.

    EPiServer.ClientTools

    The EPiServer.ClientTools namespace contains classes that support client tools like the Microsoft Office Add-In.

    EPiServer.Core

    The EPiServer.Core namespace contains all the basic Web publishing functionality. This namespace will be the one used most frequently by developers who want to extend the publishing functionality in EPiServer CMS.

    Objects in the EPiServer.Core namespace manage the functionality for categories, page properties, language processing, and page information. This namespace also contain the important EPiServer.Core.PageReference structure which functions as a pointer to other pages in the system.

    EPiServer.Core.Html

    The EPiServer.Core.Html namespace contains classes for text searching, Index Server support and content parsing. This namespace includes the HtmlParser class that can parse HTML and return valid XHTML as a string or as an XmlDocument.

    EPiServer.DataAbstraction

    The EPiServer.DataAbstraction namespace contains simple data classes that abstract the base data types in EPiServer CMS, like frames and page types. Use DataAccess to load/save data.

    Note EPiServer.DataAbstraction will be compatible with EPiServer CMS 5.

    EPiServer.DataAccess

    EPiServer.DataAccess manages data transfers within the system and is primarily of interest to developers who want to modify the way in which data is moved within EPiServer. This layer abstracts the underlying functionality for the rest of the system and hides all the SQL queries.

    It is possible to build solutions based on a DBMS other than SQL Server or Oracle. To do this, the objects in DataAccess have to be rewritten so that they link to another type of database. However, it is important that the object's interface is kept intact.

    Note EPiServer.DataAccess will not be available in EPiServer CMS 5 and should not, therefore, be called directly from your code.

    EPiServer.Editor

    The EPiServer.Editor namespace contains classes for extending the editor with custom plug-ins.

    EPiServer.Editor.Tools

    The EPiServer.Editor.Tools namespace contains classes for extending the editor with custom plug-ins.

    EPiServer.Enterprise

    The EPiServer.Enterprise namespace contains classes to export and import EPiServer CMS information.

    EPiServer.FileSystem

    The EPiServer.FileSystem namespace contains classes to access user-defined file and folders.

    EPiServer.FileSystem.Handler

    The EPiServer.FileSystem.Handler namespace contains classes for building custom file systems and customizing the file system delivered with EPiServer.

    EPiServer.FileSystem.Mapping

    The EPiServer.FileSystem.Mapping namespace contains classes for building custom mappers and mappings delivered with EPiServer CMS.

    EPiServer.Filters

    Filters are used to specify, in a sophisticated way, how listings are displayed on a Web site. With the introduction of filters, much of the code can be replaced and the functions can be managed by compiled objects in EPiServer CMS, which will dramatically improve performance. In addition, this means that development work will be reduced to a minimum, as only a few lines of code will need to be written.

    EPiServer.Personalization

    The EPiServer.Personalization namespace supplies classes for personalization and subscription. The PersonalizedData class can be used to retrieve and save information about a user, in addition to storing global personalized values or page-specific values.

    EPiServer.PlugIn

    The EPiServer.PlugIn namespace is used to extend the Edit and Admin interfaces with custom functionality.

    EPiServer.Security

    This namespace contains the logon functionality. It is possible to add additional functions, which allow users to be authorized and validated by EPiServer CMS. See the "Configurable Authentication Provider Chain" technical note for further information.

    EPiServer.SpecializedProperties

    The EPiServer.SpecializedProperties namespace contains property classes for various special Edit mode requirements like the PropertyWeekDay class, which renders a list of check boxes, for each weekday, for the user to select.

    EPiServer.WebControls

    Web controls are a feature in .NET. These objects can be used directly in the Visual Studio.NET design view. They contain the compiled functionality behind the templates supplied with EPiServer CMS. For example, if you want to include a calendar function in a template, it is easy to drag a Web control onto a template page in EPiServer CMS.

    Base Classes in EPiServer CMS

    As already mentioned, EPiServer CMS includes a collection of classes that handle the functionality needed to build Web sites that are both easy to administer and user-friendly. Developers and template designers will use these base classes in their day-to-day work with EPiServer CMS. The most common base classes are described below:


    Base Classes for Files

    UnifiedDirectory

    The UnifiedDirectory class contains information about a directory and methods to delete, move and create new directories.

    UnifiedFile

    The UnifiedFile class contains information about a file and methods to delete, move and copy files.

    UnifiedFileSystem

    UnifiedFileSystem is the global class for the file systems used in EPiServer. This class contains methods to load and create directories and files.


    Base Classes for Pages

    ApplicationConfiguration

    This base class contains the functionality that allows you to modify the web.config file. This file contains all the settings for the current Web, the modules to be loaded, and the settings for ASP.NET.

    DataFactory

    DataFactory is an object that extracts functionality for managing data transfers in EPiServer CMS. All the classes that primarily need access to the database use this object.

    EditPage

    The EditPage class is a base class for EPiServer CMS pages that needs to save page data or create new pages.

    Global

    The Global class is one of the most important classes in EPiServer CMS. This class is the one used by global.asax for initialization of the site. The Global class reads the configuration from disk, sets up the LanguageManager and registers the authentication modules that is to be used for this site.

    IPageSource

    The IPageSource interface is implemented by many classes - like PageBase (and descendants), DataFactory, PageControlBase (which most web controls inherit from) and even more. This means there are ample chances for you to get to other pages or page information when you work with templates and controls.

    PageBase

    The PageBase class is an abstract class used as base class for one of the more specialized derived classes like SimplePage or TemplatePage. The latter is the most used base class for templates in EPiServer CMS. All Web forms that is to be used as page templates in EPiServer CMS must inherit from SimplePage or PageTemplate.

    PageData

    The PageData class contains information about a specific page. This includes the name of the page (PageName), reference (PageLink) and URL (LinkURL). Additionally you can get the values of all custom properties defined for the page through the Property property.

    PageDataCollection

    The PageDataCollection class represents a collection of PageData objects. Control authors might need to fill this kind of collection from code. Mostly you will work on collections retrieved by a GetChildren(...) call or from a Web control.

    PageReference

    The PageReference structure is used to point to pages. Instead of using raw integer IDs, the ID is packaged in a PageReference structure. A page can have several versions and even be located on another physical server. This information is also stored inside the structure.

    PropertyData

    PropertyData is an abstract class that all properties inherit from. You can make your own properties and use them just as the built-in EPiServer CMS properties.

    SimplePage

    This is the simplest form of Web page and contains the basic properties found throughout the Web site. These can be inherited and fine-tuned for specific customer solutions.

    SystemPage

    This object handles the functionality in the editor's and administrator's interface.

    TemplatePage

    This is the base class for EPiServer CMS page templates that should support simple edit access and shortcut menu (right-click menu) access to Edit and Admin modes.

    UnifiedPrincipal

    The UnifiedPrincipal class contains information about the currently logged on user (or the anonymous account if not.) You can also get information about the currently logged on EPiServer CMS user through the UserData property (which is also used for personalization.)

    UserControlBase

    The UserControlBase class simplifies the code in user controls. By inheriting from the UserControlBase class, you do not have to cast the Page property of the UserControl class to a PageBase class. Instead use CurrentPage and the other members like you would directly from a PageBase or TemplatePage. The purpose is to give access to frequently used methods and properties of the PageBase class without having to cast the Page property.


    Base Classes for Personalization

    PersonalizedData

    PersonalizedData is a data class handling personalized information for a user. Access current instance of this class either through the static property UserData retrieved from the CurrentUser property in the PageBase class.


    Base Classes for Tree Structures

    PageTreeLoader

    This class is used to define a tree structure in EPiServer CMS.

    PageTreeReader

    PageTreeReader is used to move through and read a tree structure consisting of pages in EPiServer CMS.

    PageTreeXML

    This class allows you to output a tree structure in XML format and input it to any program or platform.


    Data Management

    Data management in EPiServer CMS is divided into three layers, which allows the developer to make the best use of all the special features of a DBMS in a structured way. It also gives the developer the opportunity to change to a different DBMS.

    Database

    EPiServer CMS comes with support for SQL Server and Oracle Database Servers 9i and 10g. All database queries are managed as before by stored procedures. No direct queries are sent to the tables.

    DataAccess

    This layer encapsulates all the database queries made via ADO.NET. This allows the database traffic to be optimized, resulting in excellent performance, and means that DBMS-specific functions can be included here. As all the communication with the database takes place in this layer, it is possible to rewrite the code in DataAccess, so that it will function with another DBMS such as Access or MySQL, whilst retaining the existing interface.

    Data Factory

    The base classes in EPiServer CMS use Data Factory, which has an interface adapted to the base classes. Data Factory is exposed as a Web service, which makes it accessible to other systems on other platforms. Caching and other types of performance optimization also form part of this layer.