Developing User Controls in EPiServer

Size: px

Start display at page:

Download "Developing User Controls in EPiServer"

Juniper Anderson
5 years ago
Views:

1 Developing User Controls in EPiServer Abstract It is recommended that developers building Web sites based on EPiServer create their own user controls with links to base classes in EPiServer. This white paper introduces the concept of user controls and shows how easy it is to integrate them into EPiServer's API. Product version: 4.51 Document version: 1.0

2 2 Developing User Controls in EPiServer Table of Contents INTRODUCTION 3 WHAT IS A USER CONTROL? 3 A SIMPLE USER CONTROL... 3 A SIMPLE MENU IN EPISERVER 4 CREATING A CONTROL IN VISUAL STUDIO... 4 CREATING AN INTERFACE FOR THE CONTROL... 5 LINKING A DATA SOURCE TO THE CONTROL... 5 DISPLAYING THE CONTENTS OF THE DATALIST... 6 The contents of this document are protected by copyright. Contents of the document may be freely copied and distributed, either digitally or in printed format, to all EPiServer users. EPiServer is a registered trademark of ElektroPost Stockholm AB. Other product and company names mentioned in this document may be the trademarks for their respective owners.

3 Introduction 3 Introduction It is recommended that developers building Web sites based on EPiServer create their own user controls with links to base classes in EPiServer. These controls should be written in a general way so that they can be reused in future projects. User controls are also a perfect way to leverage the content framework that EPiServer uses to define the overall page layout. What is a User Control? A 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. 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 Simple User Control <%@ Control Language="c#" AutoEventWireup="false" Codebehind="mydate.ascx.cs" Inherits="development.templates.UserControls.mydate" %> <table width= 40% bgcolor= blue > <tr> <td><h3 style="color:yellow"> Current date is:</h3></td> </tr> <tr> <td><h4 style="color:white"><%= DateTime.Now.ToString() %> </h4></td> </tr> </table> The code example above shows a very simple Web control that displays the current date in a table. The difference between a Web control and an ordinary page in ASP.NET is partly the file extension (.ascx) and partly the control directive, which is used instead of the page directive in an ASP.NET page. The <html>, <head> and <body> sections are generally omitted, because a user component is normally regarded as part of a page. The first line of code is a directive that determines the name of the user control. The other lines show what will be displayed, in this case the current date. 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. In the directive you specify the namespace to which the user control belongs, using the parameter TagPrefix. In this case you can enter any value. The namespace is used to group the user controls logically. You can also give the control a name using the TagName parameter, and indicate the ascx file using Src. When you have done this, the control is registered on the page and is accessible as a tag in the HTML code. It is then accessible in the form <TagPrefix:TagName> and can be reused in a number of positions on the current page. The example below displays the file showdate.aspx. <%@ Register TagPrefix= ElektroPost TagName= MyDate Src= mydate.ascx %> <html>

4 Developing User Controls in EPiServer <head> <title> Demonstration of user control </title> </head> <body> <ElektroPost:MyDate id= MyDate1 runat= server /> </body> </html> The finished control

4 4 Developing User Controls in EPiServer <head> <title> Demonstration of user control </title> </head> <body> <ElektroPost:MyDate id= MyDate1 runat= server /> </body> </html> The finished control looks like this: A Simple Menu in EPiServer This chapter explains how to create a simple menu using the Microsoft DataList Web server control, which is supplied with Visual Studio.NET and EPiServer. This should only be regarded as an example, but the code can of course be developed to produce a general control. 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. In order to be able to test this control, you must have an EPiServer project open in Visual Studio.NET. Creating a Control in Visual Studio 1. Right-click the folder in the project in Visual Studio where you want to create your Web control. 2. Choose Add > Add Web User Control. 3. Name the control DemoMenu.ascx.

A Simple Menu in EPiServer 5 Figure 1 Creating a control Creating an Interface for the Control As this user control is based on the DataList object, you must drag a data list onto the work area in

5 A Simple Menu in EPiServer 5 Figure 1 Creating a control Creating an Interface for the Control As this user control is based on the DataList object, you must drag a data list onto the work area in the Designer view for the newly-created control. The code you create will be displayed as below: <%@ Control Language="c#" AutoEventWireup="false" Codebehind="DemoMenu.ascx.cs" Inherits="development.templates.Units.DemoMenu" TargetSchema=" <asp:datalist id="datalist1" runat="server"></asp:datalist> 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, we will use one of the predefined color schemes that are available. 1. Right-click DataList in the Designer view in Visual Studio. 2. Select Auto Format 3. Select the Professional 1 color scheme. 4. Click OK. When you look at the code that has been produced, you will see that a number of templates that control the format of the DataList have been added Linking 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. In.NET a data source can be a dataset in ADO.NET, but in this case we will use the EPiServer 4 object PageTreeLoader to fill the menu with the first level of the structure. PageTreeLoader is stored in a namespace called EPiServer. To access it without having to give the entire object path, we will include a reference to this namespace in the lines that begin with "using" in the code-behind file. We will also need to use PageDataCollection, which is stored in EPiServer.Core. (The examples below are from file DemoMenu.ascx.cs.) using System; using System.Data;

6 6 Developing User Controls in EPiServer using System.Drawing; using System.Web; using System.Web.UI.WebControls; using System.Web.UI.HtmlControls; using EPiServer; using EPiServer.Core A user control will by default inherit from the class System.Web.UI.UserControl, but to allow us to easily access EPiServer objects we want to inherit from EPiServer.UserControlBase, i e the class definition should look like this. public class DemoMenu : EPiServer.UserControlBase { // rest of the class definition } The instancing of the object takes place in the Page_Load event. To extract the information about the top level of pages in EPiServer we will call the method GetChildren which takes the parent page as in 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 (see how we can benefit from using built-in support to minimize the amount of coding needed). It would 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 simple 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. private void Page_Load(object sender, System.EventArgs e) { PageDataCollection mycoll = GetChildren(Configuration.StartPage); DataList1.DataSource = mycoll; DataList1.DataBind(); } Displaying 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 using Microsoft-specific techniques such as ADO.NET. <%@ Control Language="c#" AutoEventWireup="false" Codebehind="DemoMenu.ascx.cs" Inherits="development.templates.Units.DemoMenu" TargetSchema=" <asp:datalist id="datalist1" runat="server" BorderColor="#999999" BorderStyle="None" BackColor="White" CellPadding="3" GridLines="Vertical" BorderWidth="1px"> <SelectedItemStyle Font-Bold="True" ForeColor="White" BackColor="#008A8C"></SelectedItemStyle> <AlternatingItemStyle BackColor="#DCDCDC"></AlternatingItemStyle> <FooterStyle ForeColor="Black" BackColor="#CCCCCC"></FooterStyle> <ItemStyle ForeColor="Black" BackColor="#EEEEEE"></ItemStyle> <HeaderStyle Font-Bold="True" ForeColor="White" BackColor="#000084"></HeaderStyle> <HeaderTemplate><%#Configuration.SiteName%></HeaderTemplate> <FooterTemplate><%= DateTime.Now.ToShortDateString() %></FooterTemplate> <ItemTemplate> <a href='<%# DataBinder.Eval( Container.DataItem, "LinkURL" ) %>'> <%# DataBinder.Eval( Container.DataItem, "PageName" ) %> </a> </ItemTemplate> </asp:datalist>

7 A Simple Menu in EPiServer 7 The result is a menu as shown in the screen shot above. It is 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 white paper.

EPiServer Programmer's Reference

EPiServer Programmer's Reference Product version: 4.60 Document version: 1.0 Document creation date: 23-03-2006 Purpose This programmer's reference is intended to be read by EPiServer developers as an