ASP.NET 2.0 Web Parts in EPiServer CMS 4

Purpose

ASP.NET 2.0 introduces Web Parts as a set of controls for building portal-like pages. EPiServer CMS 4 makes use of this support from version 4.60 and extends it in a number of ways. This document describes the setup requirements and outlines the features that are built into the Web Part support in EPiServer CMS 4.

Web Parts is a framework for building portal-like, highly personalized pages in ASP.NET 2.0. The technology is known from the Microsoft SharePoint product family, where it has been available for a number of years. The release of .NET 2.0 made this technology available to ASP.NET developers not specifically targeted to SharePoint environments. In EPiServer CMS 4.60 and later we use Web Parts for our portal templates.

Overview

Web Parts are typically used for building portal-like Web applications. The framework has built-in support for various types of customization of the user interface (personalization) and provides a number of controls to back this up. All controls and classes defined in the framework are designed with extensibility in mind, so there are a lot of opportunities to plug in your own code for altering things like rendering and behavior.

The image above displays what a Web Parts page looks like when a couple of Web Parts have been applied. The example shows a Web Part displaying an RSS feed and a WSRP portlet in the left zone, and two Web Parts, one for displaying a page list and one for the contents of a page in the right zone.

The Web Parts in the right zone are connected, i.e. clicking a link in the list of pages in the upper Web Part will automatically update the Web Part below to display the content for the selected page. This view can be “private”, where the user that is logged specifies what should be displayed on the page, or it can be a view that is shared for all users (including anonymous users).

The page shows the Portal.aspx template, which is included in the EPiServer CMS 4 installation package for the Web Part support. The installation package also includes a template for displaying a combination of traditional content and Web Part content.

Templates

The EPiServer CMS 4 installation includes two templates that exemplify how to use the Web Parts features in general and the EPiServer CMS extensions in particular.

Portal.aspx

The portal template is used for traditional portal scenarios where all content is viewed using Web Parts. This template supports most of the various display modes that are available on a Web Part page. The page contains controls for switching between the different displays modes and for switching between private and shared personalization scope.

The image below displays the portal template displaying the Web Part Edit user interface for the Page List Web Part.

Mixed.aspx

In situations where you want a traditional Web page look, but want to expose a Web Part in a section of the page, you can make the WebPartProperty property of the ExtendedWebPartZone point to an EPiServer CMS page property of type WebPart. With this configuration the editor will be able to define which Web Part should be displayed in the zone.

This feature is implemented in the Mixed.aspx template, which basically replaces the right content placeholder with an ExtendedWebPartZone. The template expects a WebPart property named “SelectedWebPart” and a XHTML property named “MainBody” to be defined for the page type.

The image below displays the Edit tab of Edit mode for the "Mixed" content template. The SelectedWebPart property is displayed as a drop-down list of available Web Parts. The set of available Web Parts are defined in Admin mode.

The image below displays the "Mixed" content template showing the page tree in the left column, the main body in the main content area and a Web Part in the right column.

Configuration

This chapter outlines the various aspects concerning the configuration of Web Parts support.

Install ASP.NET 2.0

In order to use and develop pages with Web Part support in EPiServer CMS 4, the site must be running on .NET 2.0. The steps required to set this up are described in the technical note "WSRP Configuration".

Sample Package

There are two options if you want to use Web Parts in your site.

1. Install the entire template package for ASP.NET 2.0.
2. If you are upgrading an existing site, you may want to manually install the files required just for Web Parts. See a list of the files below.

The sample templates for ASP.NET 2.0 contain the following crucial files that must exist for Web Parts to work.

• /admin/webpartadmin.aspx
• /admin/webpartadminedit.aspx
• /bin/episerver.webparts.dll
• /templates/masterpages/masterpage.master
• /templates/webparts/mixed.aspx
• /templates/webparts/mixed.aspx.cs
• /templates/webparts/portal.aspx
• /templates/webparts/portal.aspx.cs
• /templates/webparts/portal.aspx.designer.cs
• /templates/webparts/scripts/rss.js
• /templates/webparts/units/rsscontrol.ascx
• /templates/webparts/units/rsscontrol.ascx.cs
• /templates/webparts/units/rsscontrol.ascx.designer.cs
• /templates/webparts/webcontrols/rsszone.cs

web.config

In order to make the database available for the Web Parts framework, the database connection string needs to be published in the ASP.NET 2.0 connectionsStrings element. Follow the instructions below to configure web.config.

1. Add the following element as a child element to the configuration element.



<connectionStrings>

    <add name="EPiServerDB"

        connectionString="Data Source=SERVER;

        Database=DATABASE;

        User Id=USER;

        Password=PASSWORD;

        Network Library=DBMSSOCN;"

    providerName="System.Data.SqlClient" />

</connectionStrings>



2. Replace SERVER, DATABASE, USER and PASSWORD with your values.
3. Make sure that the Web Parts tag prefix is registered in the pages element.
   
   

   <pages validateRequest="false" enableEventValidation="false">

       <controls>

           <add tagPrefix="EPiServer" namespace="EPiServer.WebControls" assembly="EPiServer" />

           <add tagPrefix="WebParts" namespace="EPiServer.WebParts.WebControls" assembly="EPiServer.WebParts" />

           <add tagPrefix="WebParts" namespace="EPiServer.WebParts.WebControls.Wsrp" assembly="EPiServer.WebParts" />

       </controls>

   </pages> 



4. The personalization default engine used for extracting and persisting personalized data is the SqlPersonalizationProvider. EPiServer CMS 4 uses an altered version of the SqlPersonalizationProvider named EPiServerPersonalizationProvider which handles the multiple pages per page template model used in EPiServer CMS. You enable this personalization provider by adding the following element somewhere inside the system.web element.



<webParts>

    <personalization defaultProvider="EPiServerPersonalizationProvider">

        <providers>

            <add name="EPiServerPersonalizationProvider" type="EPiServer.WebParts.Core.EPiServerPersonalizationProvider" connectionStringName="EPiServerDB" />

        </providers>

        <authorization>

            <allow verbs="enterSharedScope" roles="WebAdmins, WebEditors, Administrators" />

        </authorization>

    </personalization>

</webParts> 

  

5. Make sure to point out the correct connection string in the connectionStringName attribute of the add element. The section above also sets the permission for entering shared scope to only allow WebAdmins and WebEditors.

Configuring the Database

The personalization provider relies on a specific database schema. This schema can easily be set using the aspnet_regsql command line tool found in %windir%\Microsoft.NET\Framework\v2.0.50727\. This tool can be used to set up specific parts or the entire database schema necessary for the available ASP.NET 2.0 providers (membership, roles, personalization, profiles and Web events).

The following command enables the entire ASP.NET 2.0 scheme using SQL authentication:

aspnet_regsql /S SERVER /d DATABASE /U USER /P PASSWORD /A all

The following command does the same thing using integrated security:

aspnet_regsql /S SERVER /d DATABASE /E /A all

The following command installs the minimum parts necessary for the Web Parts support, i.e. personalization and membership. The example uses integrated security:

aspnet_regsql /S SERVER /d DATABASE /E /A mc

Importing the Sample Templates

Sample templates can be imported from <EPiServerSample dir>\Util\Setup\PortalTemplates.epi4.

Administration

Web Part Registration

In order to make it possible to change the set of available Web Parts in a live site, there is a new administration page for registering and altering Web Parts. Web Parts that have been registered are available from the custom WebPart property that can be added to a page type. It is also available from the RegisteredWebPartsCatalog that can be added to any catalog zone in the EPiServer CMS site. The registration process makes it possible to extend the available services of the site without having to recompile or even change any markup files.

Register a Web Part

1. From the Config tab in Admin mode, click Web Parts and Install Web Part.
2. Enter a name, description and specify the control to be used by entering its physical path relative to the application root. You specify the application root using the tilde character (~). Enter "~/templates/webparts/units/rsscontrol.ascx" in the Control field to point to the RSS control available in the sample package. Click Save.
3. You can specify properties of the Web Part by selecting its name.
4. In the properties table, enter values for the properties you need to specify.




5. The Src property of the RssControl in the above example is set to point to the MSDN feed at http://msdn.microsoft.com/rss.xml.
6. Click Add to define the property.
7. Remove any property by selecting Delete in the table.

If you need to expose WSRP portlets, you can make them available by registering them in a similar way.

1. From the WebParts page in Admin mode, select Consume Portlet.
2. Enter a name and a description. Select one of the producers registered in the WSRP Sources section of Admin mode in the Producer field.
3. Select one of the available portlets for the selected producer. Click Save.

Example 1 – Displaying Content from EPiServer CMS in a Web Part

This example shows how to build a simple Web Part for displaying content from EPiServer CMS. The idea is to display a configurable property from a configurable page.

Derive from a Web Part?

In ASP.NET 2.0 there are three main choices when selecting a base class for a Web Part control.

1. Deriving from System.Web.UI.WebControls.WebParts.WebPart will give you a tight integration with the Web Part framework. The (major) drawback is that you must provide the markup of your control using code.
2. Deriving from System.Web.UI.WebControls.UserControl gives you the possibility to separate code and layout, but you will not have all the features of Web Part deriving control. Most of the features can be “re-engineered”.
3. Derive from any other member of the System.Web.UI.WebControls namespace, or any other Web control. You do this to extend or customize an existing control.

The example uses markup to define the layout, so we create a new user control and name it PropertyPart.ascx.

Markup

The markup for the control is trivial.

Note that the @Control declaration still contains a code-behind file, although the code is targeted for ASP.NET 2.0. This is because the control is created in a Web Application Project which is how the sample project for ASP.NET 2.0 is packaged.

In the markup we simply add two control declarations; a Label for displaying messages and a Property control for displaying the EPiServer content.

Code-Behind File

Code view will look something like this:

to specify which page and property to display. There are two new properties for this: Url and PropertyName.