tedgustaf.se

Introduction to 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.

  • 21 June 2010
  • 0

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):

Installing EPiServer CMS through Deployment Manager

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:

EPiServer CMS UI

Add references in your Visual Studio project

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

Adding reference to EPiServer Template Foundation in Visual Studio

(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.

Adding reference to Page Type Builder in Visual Studio 

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

dotless.Core.dll and EcmaScript.NET.modified.dll assemblies

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:

StartPage page type class inside the PageTypes folder

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:

tblPageType table inside 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”).

Editing the start page after adding EPiServer Template Foundation

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:

MetaWeblog support for EPiServer

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:

Add blog to Windows Live Writer

Next selected Other blog service and click Next:

Selecting blog service in Live Writer

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

Setting site URL and user credentials in Live Writer

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

Live Writer detecting MetaWeblog support in EPiServer

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

Live preview using theme detection in Live Writer

Finally, give your website a descriptive name:

Specifying a name for the EPiServer site in Live Writer

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:

EPiServer links in Live Writer

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

Creating new posts and pages in EPiServer using 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?

EPiServer Template Foundation settings

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:

Start page of the Public Templates website

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

First we’ll click New and New page:

Create new EPiServer page using Live Writer

Let’s give our new page a suitable name:

Naming our page in Live Writer

Edit EPiServer content through Live Writer

Next let’s edit some content:

Editing EPiServer content through Live Writer

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:

Inserting images in Live Writer

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:

Page Parent property for an EPiServer page in Live Writer

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

Selecting a page parent in Live Writer

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

Saving a page draft to EPiServer from Live Writer

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

image

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

EPiServer start page after publishing through Live Writer

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):

News item page in EPiServer published through Live Writer

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:

Create a new blog post in EPiServer using Live Writer

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

image

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:

Setting page properties for an EPiServer page in Live Writer

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

The start page after publishing a news article in EPiServer through Live Writer

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…
    Tags container property
    …and the Tag page type setting:
    Tag page type setting for ETF
  • 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
    Person page type setting
  • To have articles sorted into date folders the Date folder type setting must have been set:
    Date folder type setting

In this case we hadn’t specified the Date folder type setting, so the article was simply created beneath the News container:

Page tree after publishing a new article in EPiServer through Live Writer

Edit an existing post or news article

If we want to go back and edit an existing page or post we simply click File –> Open in Live Writer:

Opening an existing EPiServer page or post in Live Writer

Download EPiServer Template Foundation

Interested in trying out ETF? It’s available as the EPiServer Template Foundation project on Codeplex.

Don’t hesitate to post comments and questions below! Oh, and this blog post was obviously published through Live Writer! :)

Editing this blog post in Live Writer