Using web parts in EPiServer

Introduction

As Stein Viggo points out in his EPiServer on Steroids post, traditional page type templates can limit editor creativity. Having editors enter values for page properties and placing these values within well-defined templates can do miracles for accessibility and consistency - but you will often find that you have to add more page types or page properties, or implement custom properties, to overcome the limitations of traditional page template design. However, there are neat ways around it!

Two approaches to get there

Extension X3 is one approach to this drag-and-drop building block (notice the rhyme!) paradigm (see it in action on YouTube). Extension X3 is part of the Create+ package which was released not that long ago.

The other approach, which I will focus on here, is using web parts to allow editors to add, re-arrange and customize building blocks to allow for a flexible page layout.

Get started with the Web Part Framework for EPiServer

The Web Part Framework for EPiServer, published on EPiCode, makes it really easy to get started. I usually experiment using the EPiServer sample website which can be installed through EPiServer Manager. Here's what I did to extend it to play around with web parts in EPiServer:

1. Download the Web Part Framework for EPiServer .zip file from EPiCode
2. Start EPiServer Manager
3. Right-click on the site you want to extend with the Web Part Framework
4. Click "Install module"
5. Browse to the previously downloaded .zip file to install it
6. Done!

Ok, I've installed the module - now what?

The most obvious difference when you log in to the edit interface after installing the Web Part Framework module is that you have two additional page types available; Web Part Page and Web Part Page (3 col). I got to admit those are some pretty self-explanatory page type names!

To see these page types in action:

1. Create a new page based on either one of the two web part page types
2. Name your page and click "Save and view"
3. Right-click the page and then click "Edit Web Parts" (excited yet?)
4. You will now see two or three web part zones (depending on which page type you used)
5. Select one of the existing web part types using the Add web part dropdown and then click Add to - well - add it
6. Go ahead and add a few more so you can see how easily you can drag and drop the different web parts to re-arrange them

I decided to add a free text editor web part (called Editor) to the left zone, an RSS feed to the main zone and a Page List web part to the right zone:

Web parts included in the Web Part Framework

The Web Part Framework contains a few web parts out-of-the-box:

• Banner (for adding a linked banner by its URL)
• Page (to insert a link to an EPiServer page)
• Editor (for richtext content)
• Divider (you got it - it's a divider)
• Page List (for listing child pages including part of the main body)
• Rss List (reads an RSS feed and lists its items)

However, it doesn't get really cool until you start developing your own web parts and insert them in EPiServer!

Create your own web parts for EPiServer

Web parts can be created in many different ways. The Web Parts Framework contains a lot of different base classes that you can use to jump start your web part development.

However, I'm not a big fan of the cooking-show-I've-already-prepared-this approach, so I'll demonstrate an example where we start developing our web part from scratch. Let's head into the kitchen!

Create a new user control

I want to create a web part user control which outputs the current time and also allows the editor to specify the time zone. Yeah, it's not rocket science, but it demonstrates the concept in an intuitive way (I hope)!

First of all, add a new user control named Clock to your EPiServer project. Add two Literal controls to it for displaying a label and the actual time:

<p>
   <asp:Literal ID="litTitle" runat="server" /> <asp:Literal ID="litCurrentTime" runat="server" />
</p>

That's all the front-end coding we're going to be doing today. Next, open up the user control's code-behind file.

Inherit the IWebPart interface

Our user control should inherit the base class EPiServer.UserControlBase like any other EPiServer user control. However, to make our user control act as a web part we also want to inherit the IWebPart interface:

public partial class Clock : UserControlBase, IWebPart

Next, right-click the IWebPart interface name and select Implement Interface Explicitly to get the code stubs we need to implement in order to fulfill the interface contract:

Implement the interface properties

The IWebPart interface declares a number of properties that need to be implemented. Using the automatic properties introduced in .NET 3.0 makes this almost too easy:

#region IWebPart Members 

public string CatalogIconImageUrl { get; set; } 

public string Description { get; set; } 

public string Subtitle { get { return string.Empty; } } 

public string Title { get; set; } 

public string TitleIconImageUrl { get; set; } 

public string TitleUrl { get; set; } 

#endregion

Add the time zone parameter

When the web part loads I want to display the current time, taking into account the specified time zone. I want the editor to be able to specify the time zone when adding the web part to a page.

The property declaration for the TimeZone property looks like this:

[WebBrowsable] 
[Personalizable] 
[WebDisplayName("Time zone")] 
[WebDescription("The time zone expressed relative to UTC")] 
public int TimeZone { get; set; }

Note that I've added the WebBrowsable, WebDisplayName, WebDescription and Personalizable attributes. The WebBrowsable attribute is what makes the property show up in the edit interface when the web part is added or edited.

The Personalizable attribute states that the web part can be personalized. In this case this means that the property can have different (or personalized) values for each instance of the web part.

Implement the web part logic

The logic of this web part is trivial. I simply set the values of the two Literal controls we added to the user control's markup earlier:

protected void Page_Load(object sender, EventArgs e) 

{ 

    //Set the title (the + sign needs to be added explicitly for time zones that are greater than or equal to zero 

   litTitle.Text =  

        string.Format( 

        "Current time (UTC{0}):",  

        (TimeZone >= 0  

        ? string.Concat("+", TimeZone.ToString())  

        : TimeZone.ToString()));

   //Display the current time for the specified time zone 

   litCurrentTime.Text = DateTime.UtcNow.AddHours(TimeZone).ToString("hh:MM"); 

}

Make the web part available in the web part zone manager

In order to make our new web part available for editors to add we need to add it to the web part catalog. When you installed the Web Part Framework a file called managementconsole.ascx was added to the website.

Open it up and add a reference to your web part user control:

<%@ Register TagPrefix="Ted" TagName="Clock" Src="~/path/to/your/webpart/Clock.ascx" %>

Next, add the new web part to the <WebPartsTemplate> element of the CatalogZone control:

<asp:CatalogZone runat="server" ID="ThemeCatalogZone">
   <ZoneTemplate>
      <asp:DeclarativeCatalogPart runat="server" ID="ThemeDeclarativeCatalog">
         <WebPartsTemplate>
            <!-- Other web parts go here -->
            <Ted:Clock ID="ClockWebPart" Title="Clock" Description="Displays the current time" runat="server" />
         </WebPartsTemplate>
      </asp:DeclarativeCatalogPart>
   </ZoneTemplate>
</asp:CatalogZone>

All done - let's add the new web part to an EPiServer page!

Compile your project, open the website and then navigate to the web part page your created earlier. Right-click it and select "Edit web parts" to make the web part zone managers visible.

You should now see the remarkable Clock web part in the web part catalog (the dropdown list):

Select the Clock web part and then click Add to add it. Since the web part has a property with the WebBrowsable attribute it will let you edit the value of that property.

Specify a time zone (ranging from -12 to +13) in the text box and then click OK to add the web part to the page:

When you're done, right-click the page and select "Preview Web Parts" to see the finished result:

How cool is that?!

I admit it. I get overly excited at times. But if you move beyond this really trivial example you'll start to notice really neat ways of using web parts to make editors' lives easier - and more fun! At least while they're publishing EPiServer pages! :)

Implementing a custom web part editor

Without going the extra mile you can easily add web part properties such as strings, ints, booleans etc and have them be editable by web editors simply by adding the WebBrowsable and Personalizable attributes.

However, if you want to create a fully customized editor that pops up when you add or edit your web part you will want to have a look at the EditorPart class and how you can inherit from it to create a fully customized edit interface for configuring your web part.

Good luck!

Update: Another complementing approach to facilitate flexible publishing is Dynamic content (available in EPiServer CMS 5 R2).