21 June 2010

Introduction to EPiServer Template Foundation

This article was migrated from an older iteration of our website, and it could deviate in design and functionality.

In this post we’ll look at how to include EPiServer Template Foundation in your EPiServer project in order to use the different page type base classes and publish EPiServer pages using Windows Live Writer through the MetaWeblog API.

Estimated read time : 19 minutes

Getting started with EPiServer Template Foundation

In this post we’ll look at how to include EPiServer Template Foundation in your EPiServer project in order to use the different page type base classes and publish EPiServer pages using Windows Live Writer through the MetaWeblog API.

You may also want to check out this post on setting up a new EPiServer project from scratch with Template Foundation, or this earlier one on setting up a new EPiServer project (non ETF-specific).

Upcoming posts will cover other features of ETF such as:

Dynamic resizing/scaling/cropping of images
CSS parsing/minifying
RSS feeds
Date folders and tags

Update: CSS parsing and minifying is no longer part of ETF. You may use a framework such as dotLess CSS instead.

Add EPiServer Template Foundation to your EPiServer project

Install a new EPiServer site using Deployment Manager

Install your EPiServer CMS 6 website (for this post I installed the Public Templates package with globalized content):

If we log in to the EPiServer UI after the install completes we can see the standard properties that come with the Public Templates page types, as seen here for the start page:

Add references in your Visual Studio project

First we’ll add a reference to the TemplateFoundation assembly:

(The file is called TemplateFoundation.dll and is available as the EPiServer Template Foundation project on Codeplex.)

Next we’ll add a reference to the PageTypeBuilder assembly, available as the PageTypeBuilder project on Codeplex.

Next we’ll have to ensure we have the dotLess CSS assemblies (available for download here) in the bin folder:

Add HTTP handlers to web.config

ETF comes with a set of HTTP handlers for handling features such as:

MetaWeblog support
Windows Live Writer extensions
CSS parsing/minifying
Dynamic resizing/scaling/cropping of images
Loading embedded resources through HTTP requests
Handling links to permanent links (based on EPiServer page GUIDs)

For this example we’ll simply add the handlers required for MetaWeblog support and Windows Live Writer extensions (we’ll cover remaining HTTP handlers in future posts).

Open web.config and add the following to the <handlers> section:

<system.webServer>

  <handlers>

    <clear />

    <add name="MetaWeblog" type="TemplateFoundation.MetaWeblog.MetaWeblogHandler" path="/metaweblog" verb="*" />

    <add name="LiveWriterManifest" type="TemplateFoundation.MetaWeblog.ManifestHandler" path="/wlwmanifest.xml" verb="*" />

    <add name="ReallySimpleDiscovery" type="TemplateFoundation.MetaWeblog.ReallySimpleDiscoveryHandler" path="/rsd.xml" verb="*" />

    <!-- Remaining handlers go here -->

  </handlers>

</system.webServer>

Enabling EPiServer Template Foundation features

ETF requires Page Type Builder, and all page types in your project should inherit from one of the page type base classes available in EPiServer Template Foundation.

Make page types inherit from suitable base classes

Because the Public Templates project comes with a set of pre-existing page types we need to create Page Type Builder classes for these page types.

In this case we’ll create a new class called StartPage and map it to the existing Start page page type. This is only required if you decide to add EPiServer Template Foundation to an existing EPiServer project, such as the Public Templates project in this case.

We add a new folder called PageTypes in our project and add the StartPage class:

Below is the complete code for the StartPage class. Note that we haven’t added any page properties, but we made it inherit from the StartPageBase class (which is part of ETF):

using PageTypeBuilder;

using TemplateFoundation.PageTypes;

namespace EPiServer.Templates.Public.PageTypes

    [PageType("C7D6BEC6-FC5B-4417-9100-5868B070E07D",

        Name="Start page",

        Description = "Start page and settings container for the website",

        Filename = "/Default.aspx")]

    public class StartPage : StartPageBase

Note that we need to specify the page type GUID in order to have the class map to the existing page type. We can look up the GUID in the tblPageType table insider the EPiServer database:

We’ll do the same for the Standard page (inheriting from StandardPageBase)…

using PageTypeBuilder;

using TemplateFoundation.PageTypes;

namespace EPiServer.Templates.Public.PageTypes

    [PageType("74F6EF3E-407B-4132-8108-7FA831910197",

        Name="Standard page",

        Description = "Standard content page",

        Filename = "/Templates/Public/Pages/Page.aspx")]

    public class StandardPage : StandardPageBase

…and for the News item page type (inheriting from ArticleBase):

using PageTypeBuilder;

using TemplateFoundation.PageTypes;

namespace EPiServer.Templates.Public.PageTypes

    [PageType("4593B5B5-C8B9-40F0-800C-C1CA2363BFC2",

        Name="News item",

        Description = "Page type for articles and posts",

        Filename = "/Templates/Public/Pages/NewsItem.aspx")]

    public class NewsItem : ArticleBase

Configuring EPiServer Template Foundation

Settings for ETF are managed through the Site settings tab on the start page (since the start page inherits from StartPageBase).

If we log in to the EPiServer UI again we’ll see the start page now has additional tabs and properties. If we go to Site settings we can specify things such as where articles and posts are to be published (“News container”) and which page types are to be used for pages and posts (“Standard page type” and “Article page type”).

Additional settings need to be set for features such as date folders, tags, contact person properties, RSS feeds etc, but we’ll leave these empty for now (more on these features in future posts).

Publish EPiServer pages using Windows Live Writer

Earlier we added HTTP handlers for adding MetaWeblog and Windows Live Writer support. We can verify these handlers work by browsing to the respective URLs:

/metaweblog
/rsd.xml (the Really Simple Discovery file)
/wlwmanifest.xml (let’s Live Writer know what features we support)

If we browse to http://mysite/metaweblog we should see a list of XML-RPC methods:

Adding the EPiServer site to Live Writer

Download Windows Live Writer if you haven’t already installed it and start it up.

Next click Blogs and Add blog account:

Next selected Other blog service and click Next:

Enter the URL of your EPiServer site and a valid username and password (any EPiServer user account with editor permissions will do):

Windows Live Writer then queries wlwmanifest.xml (remember the handler we added earlier?) for some information about the site’s capabilities:

The support for live previews is a bit dodgy right now, so select No when asked about theme detection:

Finally, give your website a descriptive name:

After clicking Finish you’ll see links in the upper-right corner of Live Writer to give editors the option of browsing to the site’s start page or log in to the edit mode in EPiServer:

That’s it! We can now create new pages or posts by clicking New in Live Writer:

Pages versus posts, what’s the difference?

A post is essentially a news item or blog post depending on what you want to call it. The important thing to remember about a post in ETF terms is:

A post is published using the “Article page type” and will be created under the “News container”.

See now why we had to configure it on the Site settings tab on the start page?

A page on the other hand is any page inheriting from StandardPageBase. This means you can use Live Writer to edit any of these pages, but when you create a new page using Live Writer it’ll be created using the “Standard page type”. The ETF definition of a page is thus:

A page is published using the “Standard page type” and will be created under the specified parent.

Publish an EPiServer page through Live Writer

The Public Templates website comes with a section called Events which is essentially a list of standard pages. You can see them listed on the right-hand side of the start page:

Let’s create a new event page using Live Writer!

First we’ll click New and New page:

Let’s give our new page a suitable name:

Edit EPiServer content through Live Writer

Next let’s edit some content:

Paste images on an EPiServer page

One cool feature in Live Writer is that you can paste any image directly inside the content and when the page is published these images will automatically be uploaded to the VPP (all images are uploaded to a folder called MetaWeblog inside the Global Files VPP folder).

This means you can pick a screenshot, screen clipping or any other image and simply hit CTRL + V inside Live Writer to insert an image:

Note that we can use all of Live Writer’s image tools, including resizing and styles (for example to create the neat mirroring effect seen above).

Select a parent for the new page

When creating EPiServer pages through Live Writer you’ll see a Page Parent dropdown among the page properties at the bottom:

Since we want to create a new event page on our site we’ll simply select the Events page as the parent:

Now we can save a draft of the page by clicking Save draft (essentially saving the page without publishing it):

But we’ll go right ahead and click Publish to immediately publish our new page on our EPiServer site:

Now, if we reload the start page we’ll see our new event page in the listing on the right-hand side:

If we click the link we’ll see our news item page with the embedded image (which now resides in the Global Files VPP folder):

Publish a post or article in EPiServer using Live Writer

When publishing posts through Live Writer there are a few subtle differences. For example there is no Page Parent property (all posts are published beneath the News container). Also, when publishing a post you’ll be able to set one or more categories (or tags as we call them in ETF).

Create a new blog post or article

First, let’s click New and New post in Live Writer:

We’ll set the page name in the same way as we did for the page earlier:

Content is also edited in the same way, including support for pasting images and using Live Writer plugins, but the page properties in the footer look a bit different:

If we publish the post we’ll see the new article on the start page:

Settings required for full feature support when publishing posts

In order to make use of categories (or tags) you need to set the Tags Container setting…

…and the Tag page type setting:
The Author property maps to the Contact person page property and is based on person pages on the site, which means the Person page type setting must have been set and at least 1 person page must have been created
To have articles sorted into date folders the Date folder type setting must have been set: