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.
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.
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 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 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.
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.
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.
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.
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 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 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.
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 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" />
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>
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. |
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.
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.
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:
- In the <body> tag of the ASP.NET page.
<body xmlns:EPiServer="http://schemas.episerver.com">
...
...
</body>
- 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.
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.
The @ Register directive is used to associate aliases with namespaces in a user control and can be used to:
- register the EPiServer CMS Web controls;
- 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.
- The first @ Register directive declares the EPiServer CMS alias as a tag prefix for all controls residing in the
EPiServer.WebControls namespace.
- 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>
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.
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. |
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.
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.
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">