Blog posts by Azzlack

Custom Error Pages in EPiServer

Wed, 05 Aug 2015 01:48:47 GMT

Recently, we got a request from a customer to create custom error pages for their EPiServer website. Their requirements were that they should be able to set different error pages for different areas of the website and be able to edit the error page (meaning heading and rich bodytext).

This may sound straightforward, but it did prove to be a little tricky. EPiServer has it's own error page handling, and IIS has two different elements for custom error handling (<customErrors /> and <httpErrors />). In addition, ASP.NET performs a 302 redirect to the error pages specified in "<customErrors />" which is not good for SEO.

I.e: If someone links to a page that does not exist on your site, Google would follow that link. If that link then turns into a 302 temporary redirect, Google would put that page (which does not exist) into it's index. And you don't want that. It doesn't matter if it ends up with a 404 status code at the last page, Google still indexes that first page.

With that in mind, you have at least two ways of rolling your own custom error handling. You can either do everything yourself by hooking into the Application_Error event in global.asax, or try to configure the IIS error handling. In this blog post I will focus on how to do the latter.

First off, you need to disable the EPiServer error handling. You do that by opening your episerver.config and setting the "globalErrorHandling" attribute on the "<siteSettings />" element to "Off".

Then you open web.config and find the "<customErrors />" element. Ensure that the "mode" attribute to "RemoteOnly". (This is the default mode)

Now you need to create an error handler that will be the target of all errors that happen on your site. Create a page named "ErrorHandler.aspx" inside "/Templates/ErrorPages" and make it derive from EPiServer.TemplatePage. Add the following code to the class:

/// <summary>
/// Handles the Init event of the Page control.
/// </summary>
/// <param name="sender">The source of the event.</param>
/// <param name="e">The <see cref="System.EventArgs"/> instance containing the event data.</param>
protected void Page_Init(object sender, EventArgs e)
{
    var statusCode = this.GetStatusCode(Request.QueryString);
    var originalPage = this.GetOriginalPage(Request.QueryString);

    if (statusCode != 0)
    {
        var errorPage = this.GetErrorPage(originalPage, statusCode);

        if (errorPage != null)
        {
            CurrentPage = errorPage;
        }
    }
}

/// <summary>
/// Gets the HTTP status code from the query string.
/// </summary>
/// <param name="queryString">The query string.</param>
/// <returns>The HTTP status code</returns>
private int GetStatusCode(NameValueCollection queryString)
{
    var requestQueryStrings = string.Empty;

    // Try to get query string value in two different ways
    if (queryString.GetKey(0) != null)
    {
        requestQueryStrings = queryString.GetKey(0);
    }
    else if (queryString[0] != null)
    {
        requestQueryStrings = queryString[0];
    }

    if (requestQueryStrings.Split(';').Length > 0)
    {
        int code;

        if (int.TryParse(requestQueryStrings.Split(';')[0], out code))
        {
            return code;
        }
    }

    return 0;
}

/// <summary>
/// Gets the original page where the error occured.
/// </summary>
/// <param name="queryString">The query string.</param>
/// <returns>The originating page</returns>
private PageData GetOriginalPage(NameValueCollection queryString)
{
    int pageId;

    if (int.TryParse(queryString[0], out pageId)) 
    {
        return this.GetPage(new PageReference(pageId));
    }

    return CurrentPage;
}

/// <summary>
/// Gets the correct error page for the specified HTTP status.
/// </summary>
/// <param name="originalPage">The original page.</param>
/// <param name="statusCode">The status code.</param>
/// <returns>The error page</returns>
private PageData GetErrorPage(PageData originalPage, int statusCode)
{
    switch (statusCode)
    {
        case 404:
            Response.StatusCode = 404;
            Response.StatusDescription = "Not Found";
            return this.GetPageFromProperty(originalPage, "ErrorPage404");
        case 500:
            Response.StatusCode = 500;
            Response.StatusDescription = "Internal Server Error";
            return this.GetPageFromProperty(originalPage, "ErrorPage500");
        default:
            Response.StatusCode = 500;
            Response.StatusDescription = "Internal Server Error";
            return this.GetPageFromProperty(originalPage, "ErrorPage500");
    }
}

/// <summary>
/// Gets an error page from a page property.
/// </summary>
/// <param name="page">The page.</param>
/// <param name="propertyName">Name of the property.</param>
/// <returns>The error page</returns>
private PageData GetPageFromProperty(PageData page, string propertyName)
{
    var errorPageRef = page[propertyName] as PageReference;

    return !PageReference.IsNullOrEmpty(errorPageRef) ? GetPage(errorPageRef) : null;
}

If you take a closer look, you'll see that I try to get the error code in two different ways. That is because the 500 error query string and the 404 query strings are a little bit different. There are probably smarter ways to do this, but it solved the problem for me. The strings "ErrorPage500" and "ErrorPage404" are references to Dynamic Properties which we will configure later.

Now it's time to set the front end of the ErrorHandler page. This will decide how your error pages will look. I have a very simple page that only shows a heading and some text:

<%@ Page Language="C#" AutoEventWireup="true" ErrorPage="~/Error.htm" CodeBehind="ErrorHandler.aspx.cs" Inherits="EyeCatch.EpiServer.CustomErrorPage.Templates.ErrorPages.ErrorHandler" %>
<asp:Content ID="Content1" ContentPlaceHolderID="plContent" runat="server">
    <h1><EPiServer:Property ID="Property1" PropertyName="Heading" runat="server" /></h1>
    <EPiServer:Property ID="Property2" PropertyName="MainBody" runat="server" />
</asp:Content>

EDIT: Added ErrorPage property to the @Page directive, after tip from Tom Pipe in the comments below.

NOTE: The only thing you need to copy from the above sample is the "ErrorPage" property in the @Page directive. This is a pointer to a static HTML file that will act as a fallback if EPiServer has problems. The rest of the content of your ErrorHandler.aspx file you can customize yourself.

The ErrorHandler page we've just created however, will never be tied to a Page Type or template. For that we create two new template pages named "ErrorPage.aspx" and "NotFoundPage.aspx".

Add the above HTML to those pages as well (Don't copy the codebehind and the @Page directive, this should be left as it is when you create the file).

NOTE: The above step is not needed for this to work, but it enables editors to see what the resulting error page looks like. The only thing you need is for 404 and 500 page types to have the properties defined in ErrorHandler.aspx

Now go to EPiServer and create a Page Type that look like this:

Properties:

Do the same for the Not Found page, only exchange "ErrorPage" with "NotFoundPage".

Now you need to add some dynamic properties. Click on the "Dynamic Properties" link and then press "Add Property". Create a property that looks like this:

Do the same for the 500 Error Page, just change "ErrorPage404" to "ErrorPage500" and "404 Error Page" to "500 Error Page".

With that done we can go on to create the actual error pages and set the dynamic properties:

Create two pages of type "[Web] ErrorPage" and "[Web] NotFoundPage" somewhere in your site tree. (I created them right under the root node). Fill in the heading and body text (you can also insert an image if you like). Publish the pages.
Click your root node and then click on the "Dynamic Properties" icon on the toolbar. (The one with 3 blocks on it)
Set the "404 Not Found Page" and "500 Error Page" properties to the pages you just created. Click "Save".

Now it's time to return to web.config and do the last configuration. You can also perform this step from within IIS Manager, but I'm going to show the web.config way. (The result is the same).

Insert the following block at the end of the "<system.webServer />" block:

<httpErrors errorMode="Custom" existingResponse="Replace">
    <remove statusCode="404" subStatusCode="-1" />
    <remove statusCode="500" subStatusCode="-1" />
    <error statusCode="404" prefixLanguageFilePath="" path="/Templates/ErrorPages/ErrorHandler.aspx" responseMode="ExecuteURL" />
    <error statusCode="500" prefixLanguageFilePath="" path="/Templates/ErrorPages/ErrorHandler.aspx" responseMode="ExecuteURL" />
</httpErrors>

And you're done!

If you didn't understand what you just did, here is a walkthrough:

An error occurs on your site (404 Not Found or 500 Internal Server Error).
Since EPiServer is not doing any error handling, the event bubbles up to IIS.
IIS looks at the <httpErrors /> element and executes the URL that is specified for the HTTP status code.
It loads "ErrorHandler.aspx" directly (no redirects).
During the initialization of the ErrorHandler page, it checks what kind of error occured (404 or 500).
It then gets the page referenced in the Dynamic Property and loads the PageData for that page (Heading and BodyText).
ErrorHandler then inserts the Heading and the BodyText into the corresponding elements in the ErrorHandler designer.
The page is then loaded with your chosen text and with no ugly redirects.

I hope this tutorial is of use to you. If you have any questions or comments, don't hestitate to use the comment form below.

Using XForms and MVC in EPiServer 7

Wed, 05 Aug 2015 01:17:51 GMT

UPDATE: Updated blog post to solve issues and questions posted in the comment section, as well as generalizing it to work with XForm instances on pages as well. This version also supports redirection after form submission as well as proper validation.

The most awesome features of EpiServer 7 is arguably it's Block system and that it's possible to use MVC when developing sites.

Alas, some things in EPiServer 7 apparently has some issues when it comes to supporting MVC - XForms being one of them.

For one thing, XForms requires that you post to a url. That means you need to post to an instance of a page, or create a standalone controller for handling xform requests only.

This blog post will show you how to set up XForms using the former method.

First off, you need to create a base controller that all your pages must derive from:

public abstract class BasePageController<T> : PageController<T> where T : PageData
{
    /// <summary>
    /// The view data key format
    /// </summary>
    private const string ViewDataKeyFormat = "TempViewData_{0}";

    /// <summary>
    /// Initializes a new instance of the <see cref="BasePageController{T}" /> class.
    /// </summary>
    protected BasePageController()
    {
        this.ContentId = string.Empty;
    }
    
    /// <summary>
    /// Gets or sets the data factory
    /// </summary>
    /// <value>The content repository.</value>
    [SetterProperty]
    public IContentRepository ContentRepository { get; set; }

    /// <summary>
    /// Gets or sets the page route helper repository.
    /// </summary>
    /// <value>The page route helper repository.</value>
    [SetterProperty]
    public PageRouteHelper PageRouteHelperRepository { get; set; }

    /// <summary>
    /// Gets or sets the URL resolver.
    /// </summary>
    /// <value>The URL resolver.</value>
    [SetterProperty]
    public UrlResolver UrlResolver { get; set; }

    /// <summary>
    /// Gets or sets the xform handler.
    /// </summary>
    /// <value>The xform handler.</value>
    [SetterProperty]
    public XFormPageUnknownActionHandler XFormHandler { get; set; }

    /// <summary>
    /// Gets or sets the current page.
    /// </summary>
    /// <value>The current page.</value>
    public PageData CurrentPage { get; set; }

    /// <summary>
    /// Gets a value indicating whether the block [is in edit mode].
    /// </summary>
    /// <returns><c>true</c> if the block [is in edit mode]; otherwise, <c>false</c>.</returns>
    protected bool IsInEditMode
    {
        get
        {
            return PageEditing.GetPageIsInEditMode(this.HttpContext);
        }
    }

    /// <summary>
    /// Gets the view data key.
    /// </summary>
    /// <value>The view data key.</value>
    private string ViewDataKey
    {
        get
        {
            return string.Format(ViewDataKeyFormat, this.ContentId);
        }
    }

    /// <summary>
    /// Gets or sets the content id
    /// </summary>
    private string ContentId
    {
        get
        {
            return this.TempData["ContentID"] != null ? this.TempData["ContentID"].ToString() : (this.TempData["ContentID"] = string.Empty).ToString();
        }

        set
        {
            this.TempData["ContentID"] = value;
        }
    }

    /// <summary>
    /// Handles the XForm postback
    /// </summary>
    /// <param name="data">The posted form data.</param>
    /// <param name="contentId">The block id.</param>
    /// <returns>A view.</returns>
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult XFormPost(XFormPostedData data, string contentId = "")
    {
        if (!string.IsNullOrEmpty(contentId)) 
        {
            this.ContentId = contentId;
        }

        // Add posted xform instance id to viewdata, so we can retrieve it later
        this.ViewData["XFormID"] = data.XForm.Id;

        return this.XFormHandler.HandleAction(this);
    }

    /// <summary>
    /// Handles the XForm postback if it was successful.
    /// </summary>
    /// <param name="data">The posted form data.</param>
    /// <returns>A view.</returns>
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult Success(XFormPostedData data)
    {
        if (data.XForm.PageGuidAfterPost != Guid.Empty)
        {
            var page = this.ContentRepository.Get<PageData>(data.XForm.PageGuidAfterPost);

            return this.Redirect(this.UrlResolver.GetVirtualPath(page.ContentLink, page.LanguageBranch));
        }

        return this.Redirect(this.UrlResolver.GetVirtualPath(this.CurrentPage.ContentLink, this.CurrentPage.LanguageBranch));
    }

    /// <summary>
    /// Handles the XForm postback if it was successful.
    /// </summary>
    /// <param name="data">The posted form data.</param>
    /// <returns>A view.</returns>
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult Failed(XFormPostedData data)
    {
        return this.Redirect(this.UrlResolver.GetVirtualPath(this.CurrentPage.ContentLink, this.CurrentPage.LanguageBranch));
    }

    /// <summary>
    /// Called before the action method is invoked.
    /// </summary>
    /// <param name="filterContext">Information about the current request and action.</param>
    protected override void OnActionExecuting(ActionExecutingContext filterContext)
    {
        // Get current page
        this.CurrentPage = this.PageRouteHelperRepository.Page;

        // Set content id if it has not been set
        if (string.IsNullOrEmpty(this.ContentId))
        {
            this.ContentId = this.CurrentPage.PageLink.ID.ToString();
        }

        // Persist view data if this is a failed or successful xform postback, reset if this is a new postback
        if (filterContext.ActionDescriptor.ActionName == "Failed"
            || filterContext.ActionDescriptor.ActionName == "Success")
        {
            this.TempData[this.ViewDataKey] = this.ViewData;
        }
        else if (filterContext.ActionDescriptor.ActionName == "XFormPost")
        {
            this.TempData[this.ViewDataKey] = null;
        }
        
        // Merge tempdata into viewdata if it is not null
        var tempData = this.TempData[this.ViewDataKey] as ViewDataDictionary;

        if (tempData != null)
        {
            this.ViewData = tempData;
        }

        base.OnActionExecuting(filterContext);
    }
}

Making it work with pages

Create a page type class like this:

[ContentType(DisplayName = "XForm Page")]
public class XFormPage
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    [Display(
        Name = "The form",
        Description = "The form.",
        GroupName = SystemTabNames.Content,
        Order = 1)]
    [CultureSpecific]
    public virtual XForm Schema { get; set; }
}

Now you need to display the form on the page.
Create a ViewModel class for your page type class:

public class XFormPageViewModel : BasePageViewModel
{
    public XForm Schema { get; set; }

    public string ActionUrl { get; set; }
}

Then create a page controller that looks like this:

public class XFormPageController : BasePageController<XFormPage>
{
    private readonly UrlResolver urlResolver;

    public XFormPageController(UrlResolver urlResolver)
    {
        this.urlResolver = urlResolver;
    }

    public ActionResult Index(XFormPage currentPage)
    {
        var viewModel = new XFormPageViewModel()
                            {
                                Schema = currentPage.Schema
                            };

        if (currentPage.Schema != null)
        {
            var actionUrl = string.Format("{0}XFormPost/", this.urlResolver.GetVirtualPath(currentPage.PageLink, currentPage.LanguageBranch));
            actionUrl = UriSupport.AddQueryString(actionUrl, "XFormId", viewModel.Schema.Id.ToString());
            actionUrl = UriSupport.AddQueryString(actionUrl, "failedAction", "Failed");
            actionUrl = UriSupport.AddQueryString(actionUrl, "successAction", "Success");

            viewModel.ActionUrl = actionUrl;
        }

        var editHints = this.ViewData.GetEditHints<XFormPageViewModel, XFormPage>();
        editHints.AddConnection(v => v.Schema, p => p.Schema);

        return this.View(viewModel);
    }
}

You could avoid using a viewmodel like the one above and just use the page type as a viewmodel, but I like to adhere to the MVVM model and I want to be able to set a custom css class for an instance of the page.

Now we need to create a view. (If you're using ReSharper, just ALT+ENTER on the "return this.View(viewModel)" line)

@using EPiServer.Web.Mvc.Html
@model EPiServer.Demo.TwitterBootstrap.ViewModels.Pages.XFormPageViewModel

<div class="xformpage" @Html.EditAttributes(x => x.Schema)>
    @using (Html.BeginXForm(Model.Schema, new { Action = Model.ActionUrl, @class = "form xform" }))
    {
        Html.RenderXForm(Model.Schema);
    }
    if (Model.Schema.Id == ViewData["XFormID"])
    {
        @Html.ValidationSummary()
    }
</div>

Note: Html.ValidationSummary() is wrapped in an if statement to prevent the validation summary from showing errors from other forms on the same page.

Now you're ready to go. Just create an instance of a XFormPage, add a form to it and try i out.

Making it work with Blocks

This is very similar to making it work with pages, you just need one more parameter on the action url.

First off, you need to create your Block:

[ContentType(DisplayName = "XForm block")]
public class XFormBlock : BlockData
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    [Display(
        Name = "The form",
        Description = "The form.",
        GroupName = SystemTabNames.Content,
        Order = 1)]
    [CultureSpecific]
    public virtual XForm Schema { get; set; }
}

And the corresponding viewmodel:

public class XFormBlockViewModel
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    public XForm Schema { get; set; }

    /// <summary>
    /// Gets or sets the action URI.
    /// </summary>
    /// <value>The action URI.</value>
    public string ActionUri { get; set; }
}

Then you need to create a controller for showing the block on a page:

public class XFormBlockController : BlockController<XFormBlock>
{
    private readonly PageRouteHelper pageRouteHelper;

    private readonly UrlResolver urlResolver;

    public XFormBlockController(PageRouteHelper pageRouteHelper, UrlResolver urlResolver)
    {
        this.pageRouteHelper = pageRouteHelper;
        this.urlResolver = urlResolver;
    }

    public override ActionResult Index(XFormBlock currentBlock)
    {
        var id = (currentBlock as IContent).ContentLink.ID;

        // ViewData is not automatically passed to a block controller, need to get it from TempData if it exists
        var viewDataKey = string.Format("TempViewData_{0}", id);

        if (this.TempData[viewDataKey] != null)
        {
            this.ViewData = (ViewDataDictionary)this.TempData[viewDataKey];
        }

        // Create the viewmodel
        var viewModel = new XFormBlockViewModel()
                            {
                                Schema = currentBlock.Schema
                            };

        // Create postback url
        if (viewModel.Schema != null && this.pageRouteHelper.Page != null)
        {
            var actionUrl = string.Format("{0}XFormPost/", this.urlResolver.GetVirtualPath(this.pageRouteHelper.Page.PageLink, this.pageRouteHelper.Page.LanguageBranch));
            actionUrl = UriSupport.AddQueryString(actionUrl, "XFormId", viewModel.Schema.Id.ToString());
            actionUrl = UriSupport.AddQueryString(actionUrl, "failedAction", "Failed");
            actionUrl = UriSupport.AddQueryString(actionUrl, "successAction", "Success");
            actionUrl = UriSupport.AddQueryString(actionUrl, "contentId", id.ToString());

            viewModel.ActionUri = actionUrl;
        }

        var editHints = this.ViewData.GetEditHints<XFormBlockViewModel, XFormBlock>();
        editHints.AddConnection(v => v.Schema, p => p.Schema);

        return this.PartialView(viewModel);
    }
}

When that's done, create the partial view for the block:

@using EPiServer.Web.Mvc.Html
@model EPiServer.Demo.TwitterBootstrap.ViewModels.Partials.XFormViewModel

<div class="xformblock" @Html.EditAttributes(x => x.Schema)>
    @using (Html.BeginXForm(Model.Schema, new { Action = Model.ActionUri, @class = "form xform" }))
    {
        Html.RenderXForm(Model.Schema);
    }
    if (Model.Schema.Id == ViewData["XFormID"])
    {
        @Html.ValidationSummary()
    }
</div>

UPDATE: There is an issue with using the built-in XForm display template and multiple XForm blocks on the same page. Basically, it will replace the contents of all other forms with the content of the posted form on postback.

To solve this, put the following code in a file named XForm.cshtml in a folder called DisplayTemplates in your ~/Views/Shared folder:

@using EPiServer.HtmlParsing
@using Leroy.Web.EPiServer.BusinessLogic.Extensions
@model EPiServer.XForms.XForm
           
@if (Model != null)
{
    var fragments = Model.CreateHtmlFragments();

    // Check if this is a postback, and if it is get the posted fragments for this instance
    if (ViewData["XFormID"] != null && Model.Id == ViewData["XFormID"])
    {
        fragments = (IEnumerable<HtmlFragment>)ViewData["XFormFragments"];
    }
    
    // Render all fragments
    foreach (var fragment in fragments)
    {
        @Html.RenderCustomHtmlFragment(fragment, "XForm/" + Model.Id + "/" + fragment.GetType().Name)
    }
}

That is all. Now you just need to add your XFormBlock to a page using a ContentArea, and the XFormBlockController will take care of rendering the form.

When the user submits the form, the BasePageController will take care of storing the data and/or sending emails, etc.

Stay tuned for the next blog post where I'll show you how to completely customize the rendering of the form based on the built-in MVC rendering engine. :-)

Full customization of XForms with EPiServer 7 and MVC

Tue, 04 Aug 2015 19:39:32 GMT

By default ASP.Net MVC uses conventions for locating the correct view for a controller action. But MVC comes with a nifty feature that lets you register custom view location rules, and this blog post will show you how to utilize that to completely customize the XForm html.

UPDATE: The below step for forcing EPiServer to look in ~/Views/Shared/DisplayTemplates and ~/Views/Shared/EditorTemplates for templates is not needed from version 7.5 and upwards.

First we need to register a custom view locator. To do that you need to hook into the application startup events, and I will use the excellent WebActivator package for this:

using EPiServer.Demo.TwitterBootstrap;

[assembly: WebActivator.PreApplicationStartMethod(typeof(HtmlFragmentViewEngineBoostrapper), "PreStart")]

namespace EPiServer.Demo.TwitterBootstrap
{
    using System.Web.Mvc;

    /// <summary>
    /// Bootstrapper for configuring the razor view engine for HtmlFragment views
    /// </summary>
    public class HtmlFragmentViewEngineBoostrapper
    {
        /// <summary>
        /// Occurs before the application starts
        /// </summary>
        public static void PreStart()
        {
            var engine = new RazorViewEngine()
                             {
                                 PartialViewLocationFormats =
                                     new[]
                                         {
                                             "~/Views/Shared/DisplayTemplates/{0}.cshtml",
                                             "~/Views/Shared/DisplayTemplates/{0}.vbhtml",
                                             "~/Views/Shared/DisplayTemplates/{1}/{0}.cshtml",
                                             "~/Views/Shared/DisplayTemplates/{1}/{0}.vbhtml",
                                             "~/Views/Shared/EditorTemplates/{0}.cshtml",
                                             "~/Views/Shared/EditorTemplates/{0}.vbhtml",
                                             "~/Views/Shared/EditorTemplates/{1}/{0}.cshtml",
                                             "~/Views/Shared/EditorTemplates/{1}/{0}.vbhtml"
                                         }
                             };

            ViewEngines.Engines.Add(engine);
        }
    }
}

Note: HtmlFragment is the XForm "fragments" (table rows, input boxes, etc.)
Note2: {1} in the location format is the Controller name and {0} is the name of the view.

UPDATE: Some people have been asking me why the need for the below extension methods.
The answer is that XForm does not support having different editor templates for different forms out of the box. The class below lets us specify a folder where it should look for the editor templates before falling back on the built-in ones. You will find examples on how to use it later in this article.

We also need to create an extension to replace EPiServers own RenderXForm html helpers:

/// <summary>
/// Extensions for the <see cref="HtmlHelper"/> class
/// </summary>
public static class HtmlFragmentExtensions
{
    /// <summary>
    /// Writes the XForm to the view context's output steam.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper instance that this method extends.</param>
    /// <param name="xform">The XForm to write.</param>
    public static void RenderCustomXForm(this HtmlHelper htmlHelper, XForm xform)
    {
        if (xform == null)
        {
            return;
        }

        htmlHelper.RenderCustomXForm(xform, new XFormParameters());
    }

    /// <summary>
    /// Writes the XForm to the view context's output steam.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper instance that this method extends.</param>
    /// <param name="xform">The XForm to write.</param>
    /// <param name="parameters">The parameters to be used by the XForm.</param>
    public static void RenderCustomXForm(this HtmlHelper htmlHelper, XForm xform, XFormParameters parameters)
    {
        if (xform == null)
        {
            return;
        }

        htmlHelper.ViewContext.ViewData["XFormParameters"] = parameters;

        htmlHelper.RenderPartial(typeof(XForm).Name, xform);
    }

    /// <summary>
    /// Renders the html fragment.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper.</param>
    /// <param name="fragment">The fragment.</param>
    /// <param name="renderFragmentsWithoutView">if set to <c>true</c> [render fragments without view].</param>
    /// <returns>A HTML-encoded string.</returns>
    public static MvcHtmlString RenderCustomHtmlFragment(this HtmlHelper htmlHelper, HtmlFragment fragment, bool renderFragmentsWithoutView = true)
    {
        var value = new StringBuilder();

        using (var writer = new StringWriter(value))
        {
            // Try to find a matching partial view
            var viewEngineResult = ViewEngines.Engines.FindPartialView(htmlHelper.ViewContext, fragment.GetType().Name);

            if (viewEngineResult.View != null)
            {
                viewEngineResult.View.Render(viewEngineResult, htmlHelper.ViewContext, writer, fragment);
            }
            else if (renderFragmentsWithoutView)
            {
                // Render fragment directly unless otherwise specified
                writer.Write(fragment.ToString());
            }
        }

        return value.Length <= 0 ? MvcHtmlString.Empty : MvcHtmlString.Create(value.ToString());
    }

    /// <summary>
    /// Renders the HTML fragment.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper.</param>
    /// <param name="fragment">The fragment.</param>
    /// <param name="partialViewName">The partial view name.</param>
    /// <param name="useFallback">if set to <c>true</c> [use fallback].</param>
    /// <param name="renderFragmentsWithoutView">if set to <c>true</c> [render fragments without view].</param>
    /// <returns>A HTML-encoded string.</returns>
    public static MvcHtmlString RenderCustomHtmlFragment(this HtmlHelper htmlHelper, HtmlFragment fragment, string partialViewName, bool useFallback = true, bool renderFragmentsWithoutView = true)
    {
        var value = new StringBuilder();

        using (var writer = new StringWriter(value))
        {
            // Try to find a matching partial view
            var viewEngineResult = ViewEngines.Engines.FindPartialView(htmlHelper.ViewContext, partialViewName);

            if (viewEngineResult.View != null)
            {
                viewEngineResult.View.Render(viewEngineResult, htmlHelper.ViewContext, writer, fragment);
            }
            else
            {
                // Try to fall back to default view
                if (useFallback)
                {
                    return htmlHelper.RenderCustomHtmlFragment(fragment, renderFragmentsWithoutView);
                }

                // Render fragment directly unless otherwise specified
                if (renderFragmentsWithoutView)
                {
                    writer.Write(fragment.ToString());
                }
            }
        }

        return value.Length <= 0 ? MvcHtmlString.Empty : MvcHtmlString.Create(value.ToString());
    }

    /// <summary>
    /// Renders the HTML fragment.
    /// </summary>
    /// <param name="view">The view.</param>
    /// <param name="viewEngineResult">The view engine result.</param>
    /// <param name="context">The context.</param>
    /// <param name="writer">The writer.</param>
    /// <param name="fragment">The fragment.</param>
    private static void Render(this IView view, ViewEngineResult viewEngineResult, ViewContext context, TextWriter writer, HtmlFragment fragment)
    {
        var viewDataDictionaries = new ViewDataDictionary(fragment);

        foreach (var viewDatum in context.ViewData)
        {
            viewDataDictionaries[viewDatum.Key] = viewDatum.Value;
        }

        var viewContext = new ViewContext(context, viewEngineResult.View, viewDataDictionaries, context.TempData, writer);

        foreach (var modelState in context.ViewData.ModelState)
        {
            viewContext.ViewData.ModelState.Add(modelState.Key, modelState.Value);
        }

        viewEngineResult.View.Render(viewContext, writer);
        viewEngineResult.ViewEngine.ReleaseView(context.Controller.ControllerContext, viewEngineResult.View);
    }
}

What this allows us is to override the renderer for XForm in general. We can now use the following code to render an XForm:

(view code taken from previous blog post about XForms and MVC)

@using EPiServer.Web.Mvc.Html
@model EPiServer.Demo.TwitterBootstrap.ViewModels.Partials.XFormBlockViewModel

<div class="xformpage" @Html.EditAttributes(x => x.Schema)>
    @using (Html.BeginXForm(Model.Schema, new { Action = Model.ActionUrl, @class = "form xform" }))
    {
        Html.RenderCustomXForm(Model.Schema);
    }
        
    if (Model.Schema.Id == ViewData["XFormID"])
    {
        @Html.ValidationSummary()
    }
</div>

Right now this just renders the XForm with EPiServers default view, as we haven't implemented a custom view yet.
Create a file called XForm.cshtml in ~/Views/Shared/DisplayTemplates and insert the following code in it:

@using EPiServer.HtmlParsing
@model EPiServer.XForms.XForm

<h3>Custom XForm view</h3>
@if (Model != null)
{
    var fragments = Model.CreateHtmlFragments();

    // Check if this is a postback, and if it is get the posted fragments for this instance
    if (ViewData["XFormInstanceID"] != null && Model.Id == ViewData["XFormInstanceID"])
    {
        fragments = (IEnumerable<HtmlFragment>)ViewData["XFormFragments"];
    }
    
    // Render all fragments
    foreach (var fragment in fragments)
    {
        @Html.RenderCustomHtmlFragment(fragment, "XForm/" + Model.Id + "/" + fragment.GetType().Name)
    }
}

If you load a page with a XForm on now, you'll se a header with your xform id above your form.

Now, lets say we want to utilize some bootstrap styling on our forms. That means we need to get rid of those hideous tables and replace them with our own stuff.

Replace the RenderCustomHtmlFragment code in the view above with the following code:

@Html.RenderCustomHtmlFragment(fragment, "XForm/" + Model.Id + "/" + fragment.GetType().Name)

This code tells our html helper extension to look in the "~/Views/Shared/DisplayTemplates/XForm/{xform-id}/" folder for views for each html fragment.

Create the following files in the folder mentioned above (replace {xform-id} with the id of your xform):

InputFragment.cshtml

@model EPiServer.XForms.Parsing.InputFragment

<div class="form-group @Model.Reference @Model.Class">
    <label for="@Model.Reference">@Model.Label</label>
    @if (Model.Required)
    {
        @Html.TextBox(Model.Reference, Server.HtmlDecode(Model.Value) ?? string.Empty, new { @class = "form-control", size = Model.Size, placeholder = Model.Title, required = "required" })
    }
    else
    {
        @Html.TextBox(Model.Reference, Server.HtmlDecode(Model.Value) ?? string.Empty, new { @class = "form-control", size = Model.Size, placeholder = Model.Title })
    }
    @Html.ValidationMessage(Model.Reference) // EPiServer 7.0 to 7.1
    @Html.ValidationMessage(Model.ValidationReference) // EPiServer 7.5 and upwards
</div>

ElementFragment.cshtml

@model EPiServer.HtmlParsing.ElementFragment

EndElementFragment.cshtml

@model EPiServer.HtmlParsing.EndElementFragment

SubmitFragment.cshtml

@model EPiServer.XForms.Parsing.SubmitFragment

<div class="@Model.Class">
    <input type="submit" class="btn btn-default" name="@Html.Raw(Model.UniqueName)" title="@Html.Raw(Model.Title)" value="@Html.Raw(Model.Value)" />
</div>

TextareaFragment.cshtml

@model EPiServer.XForms.Parsing.TextareaFragment

<div class="form-group @Model.Reference @Model.Class">
    <label for="@Model.Reference">@Model.Label</label>
    @if (Model.Required)
    {
        @Html.TextArea(Model.Reference, Model.Value, Model.Rows, Model.Columns, new { @class = "form-control", placeholder = Model.Title, required = "required" })
    }
    else
    {
        @Html.TextArea(Model.Reference, Model.Value, Model.Rows, Model.Columns, new { @class="form-control", placeholder = Model.Title })
    }
    @Html.ValidationMessage(Model.Reference) // EPiServer 7.0 to 7.1
    @Html.ValidationMessage(Model.ValidationReference) // EPiServer 7.5 and upwards
</div>

Select1tAsDropdownListFragment.cshtml

@model EPiServer.XForms.Parsing.Select1Fragment

<div class="form-group @Model.Reference @Model.Class">
    <label for="@Model.Reference">@Model.Label</label>
    @if (Model.Required)
    {
        @Html.DropDownList(Model.Reference, Model.Options.Select(o => new SelectListItem() { Text = Server.HtmlDecode(o.Text), Value = Server.HtmlDecode(o.Value), Selected = o.SelectedItem }), new { @class = "form-control", @title = Model.Title, @required = "required" })
    }
    else
    {
        @Html.DropDownList(Model.Reference, Model.Options.Select(o => new SelectListItem() { Text = Server.HtmlDecode(o.Text), Value = Server.HtmlDecode(o.Value), Selected = o.SelectedItem }), new { @class = "form-control", @title = Model.Title })
    }
    @Html.ValidationMessage(Model.Reference) // EPiServer 7.0 to 7.1
    @Html.ValidationMessage(Model.ValidationReference) // EPiServer 7.5 and upwards
</div>

If you render your form now, you will see that it has very different html output.
This output is also compatible with Twitter Bootstrap and jQuery Validation, meaning you get (partial) client-side validation. Yay! :-)

All this allows us to go from the following form configuration

And it's default styling

To this beautiful form

What more can you do?

You can override the style of all the form fields. Here is a list of file names and models of all field types:

File name	Model	Description
ElementFragment.cshtml	EPiServer.HtmlParsing.ElementFragment	Inserted before each "fragment" (row, label, textbox, etc.), and template for horizontal rules.
EndElementFragment.cshtml	EPiServer.HtmlParsing.EndElementFragment	Inserted after each "fragment" (row, label, textbox, etc.)
InputFragment.cshtml	EPiServer.XForms.Parsing.InputFragment	Template for every textbox field
Select1tAsDropdownListFragment.cshtml	EPiServer.XForms.Parsing.Select1Fragment	Template for every dropdown field
SubmitFragment.cshtml	EPiServer.XForms.Parsing.SubmitFragment	Template for every submit button
TextareaFragment.cshtml	EPiServer.XForms.Parsing.TextareaFragment	Template for every textarea field
TextFragment.cshtml	EPiServer.HtmlParsing.TextFragment	Template for every heading field
SelectFragment.cshtml	EPiServer.XForms.Parsing.SelectFragment	Template for every checkbox field
Select1AsRadiobuttonFragment.cshtml	EPiServer.XForms.Parsing.Select1Fragment	Template for every radio button field

NOTE: You can find the default templates for some of these at "C:\Program Files (x86)\EPiServer\CMS\7.0.586.1\Application\Util\Views\Shared\EditorTemplates"

Full customization of XForms with EPiServer 7 and MVC

Wed, 25 Sep 2013 17:52:50 GMT

UPDATE: The below step for forcing EPiServer to look in ~/Views/Shared/DisplayTemplates and ~/Views/Shared/EditorTemplates for templates is not needed from version 7.5 and upwards.

First we need to register a custom view locator. To do that you need to hook into the application startup events, and I will use the excellent WebActivator package for this:

using EPiServer.Demo.TwitterBootstrap;

[assembly: WebActivator.PreApplicationStartMethod(typeof(HtmlFragmentViewEngineBoostrapper), "PreStart")]

namespace EPiServer.Demo.TwitterBootstrap
{
    using System.Web.Mvc;

    /// <summary>
    /// Bootstrapper for configuring the razor view engine for HtmlFragment views
    /// </summary>
    public class HtmlFragmentViewEngineBoostrapper
    {
        /// <summary>
        /// Occurs before the application starts
        /// </summary>
        public static void PreStart()
        {
            var engine = new RazorViewEngine()
                             {
                                 PartialViewLocationFormats =
                                     new[]
                                         {
                                             "~/Views/Shared/DisplayTemplates/{0}.cshtml",
                                             "~/Views/Shared/DisplayTemplates/{0}.vbhtml",
                                             "~/Views/Shared/DisplayTemplates/{1}/{0}.cshtml",
                                             "~/Views/Shared/DisplayTemplates/{1}/{0}.vbhtml",
                                             "~/Views/Shared/EditorTemplates/{0}.cshtml",
                                             "~/Views/Shared/EditorTemplates/{0}.vbhtml",
                                             "~/Views/Shared/EditorTemplates/{1}/{0}.cshtml",
                                             "~/Views/Shared/EditorTemplates/{1}/{0}.vbhtml"
                                         }
                             };

            ViewEngines.Engines.Add(engine);
        }
    }
}

Note: HtmlFragment is the XForm "fragments" (table rows, input boxes, etc.)
Note2: {1} in the location format is the Controller name and {0} is the name of the view.

We also need to create an extension to replace EPiServers own RenderXForm html helpers:

/// <summary>
/// Extensions for the <see cref="HtmlHelper"/> class
/// </summary>
public static class HtmlFragmentExtensions
{
    /// <summary>
    /// Writes the XForm to the view context's output steam.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper instance that this method extends.</param>
    /// <param name="xform">The XForm to write.</param>
    public static void RenderCustomXForm(this HtmlHelper htmlHelper, XForm xform)
    {
        if (xform == null)
        {
            return;
        }

        htmlHelper.RenderCustomXForm(xform, new XFormParameters());
    }

    /// <summary>
    /// Writes the XForm to the view context's output steam.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper instance that this method extends.</param>
    /// <param name="xform">The XForm to write.</param>
    /// <param name="parameters">The parameters to be used by the XForm.</param>
    public static void RenderCustomXForm(this HtmlHelper htmlHelper, XForm xform, XFormParameters parameters)
    {
        if (xform == null)
        {
            return;
        }

        htmlHelper.ViewContext.ViewData["XFormParameters"] = parameters;

        htmlHelper.RenderPartial(typeof(XForm).Name, xform);
    }

    /// <summary>
    /// Renders the html fragment.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper.</param>
    /// <param name="fragment">The fragment.</param>
    /// <param name="renderFragmentsWithoutView">if set to <c>true</c> [render fragments without view].</param>
    /// <returns>A HTML-encoded string.</returns>
    public static MvcHtmlString RenderCustomHtmlFragment(this HtmlHelper htmlHelper, HtmlFragment fragment, bool renderFragmentsWithoutView = true)
    {
        var value = new StringBuilder();

        using (var writer = new StringWriter(value))
        {
            // Try to find a matching partial view
            var viewEngineResult = ViewEngines.Engines.FindPartialView(htmlHelper.ViewContext, fragment.GetType().Name);

            if (viewEngineResult.View != null)
            {
                viewEngineResult.View.Render(viewEngineResult, htmlHelper.ViewContext, writer, fragment);
            }
            else if (renderFragmentsWithoutView)
            {
                // Render fragment directly unless otherwise specified
                writer.Write(fragment.ToString());
            }
        }

        return value.Length <= 0 ? MvcHtmlString.Empty : MvcHtmlString.Create(value.ToString());
    }

    /// <summary>
    /// Renders the HTML fragment.
    /// </summary>
    /// <param name="htmlHelper">The HTML helper.</param>
    /// <param name="fragment">The fragment.</param>
    /// <param name="partialViewName">The partial view name.</param>
    /// <param name="useFallback">if set to <c>true</c> [use fallback].</param>
    /// <param name="renderFragmentsWithoutView">if set to <c>true</c> [render fragments without view].</param>
    /// <returns>A HTML-encoded string.</returns>
    public static MvcHtmlString RenderCustomHtmlFragment(this HtmlHelper htmlHelper, HtmlFragment fragment, string partialViewName, bool useFallback = true, bool renderFragmentsWithoutView = true)
    {
        var value = new StringBuilder();

        using (var writer = new StringWriter(value))
        {
            // Try to find a matching partial view
            var viewEngineResult = ViewEngines.Engines.FindPartialView(htmlHelper.ViewContext, partialViewName);

            if (viewEngineResult.View != null)
            {
                viewEngineResult.View.Render(viewEngineResult, htmlHelper.ViewContext, writer, fragment);
            }
            else
            {
                // Try to fall back to default view
                if (useFallback)
                {
                    return htmlHelper.RenderCustomHtmlFragment(fragment, renderFragmentsWithoutView);
                }

                // Render fragment directly unless otherwise specified
                if (renderFragmentsWithoutView)
                {
                    writer.Write(fragment.ToString());
                }
            }
        }

        return value.Length <= 0 ? MvcHtmlString.Empty : MvcHtmlString.Create(value.ToString());
    }

    /// <summary>
    /// Renders the HTML fragment.
    /// </summary>
    /// <param name="view">The view.</param>
    /// <param name="viewEngineResult">The view engine result.</param>
    /// <param name="context">The context.</param>
    /// <param name="writer">The writer.</param>
    /// <param name="fragment">The fragment.</param>
    private static void Render(this IView view, ViewEngineResult viewEngineResult, ViewContext context, TextWriter writer, HtmlFragment fragment)
    {
        var viewDataDictionaries = new ViewDataDictionary(fragment);

        foreach (var viewDatum in context.ViewData)
        {
            viewDataDictionaries[viewDatum.Key] = viewDatum.Value;
        }

        var viewContext = new ViewContext(context, viewEngineResult.View, viewDataDictionaries, context.TempData, writer);

        foreach (var modelState in context.ViewData.ModelState)
        {
            viewContext.ViewData.ModelState.Add(modelState.Key, modelState.Value);
        }

        viewEngineResult.View.Render(viewContext, writer);
        viewEngineResult.ViewEngine.ReleaseView(context.Controller.ControllerContext, viewEngineResult.View);
    }
}

What this allows us is to override the renderer for XForm in general. We can now use the following code to render an XForm:

(view code taken from previous blog post about XForms and MVC)

@using EPiServer.Web.Mvc.Html
@model EPiServer.Demo.TwitterBootstrap.ViewModels.Partials.XFormBlockViewModel

<div class="xformpage" @Html.EditAttributes(x => x.Schema)>
    @using (Html.BeginXForm(Model.Schema, new { Action = Model.ActionUrl, @class = "form xform" }))
    {
        Html.RenderCustomXForm(Model.Schema);
    }
        
    if (Model.Schema.Id == ViewData["XFormID"])
    {
        @Html.ValidationSummary()
    }
</div>

@using EPiServer.HtmlParsing
@model EPiServer.XForms.XForm

<h3>Custom XForm view</h3>
@if (Model != null)
{
    var fragments = Model.CreateHtmlFragments();

    // Check if this is a postback, and if it is get the posted fragments for this instance
    if (ViewData["XFormInstanceID"] != null && Model.Id == ViewData["XFormInstanceID"])
    {
        fragments = (IEnumerable<HtmlFragment>)ViewData["XFormFragments"];
    }
    
    // Render all fragments
    foreach (var fragment in fragments)
    {
        @Html.RenderCustomHtmlFragment(fragment, "XForm/" + Model.Id + "/" + fragment.GetType().Name)
    }
}

If you load a page with a XForm on now, you'll se a header with your xform id above your form.

Now, lets say we want to utilize some bootstrap styling on our forms. That means we need to get rid of those hideous tables and replace them with our own stuff.

Replace the RenderCustomHtmlFragment code in the view above with the following code:

@Html.RenderCustomHtmlFragment(fragment, "XForm/" + Model.Id + "/" + fragment.GetType().Name)

This code tells our html helper extension to look in the "~/Views/Shared/DisplayTemplates/XForm/{xform-id}/" folder for views for each html fragment.

Create the following files in the folder mentioned above (replace {xform-id} with the id of your xform):

InputFragment.cshtml

@model EPiServer.XForms.Parsing.InputFragment

<div class="form-group @Model.Reference @Model.Class">
    <label for="@Model.Reference">@Model.Label</label>
    @if (Model.Required)
    {
        @Html.TextBox(Model.Reference, Server.HtmlDecode(Model.Value) ?? string.Empty, new { @class = "form-control", size = Model.Size, placeholder = Model.Title, required = "required" })
    }
    else
    {
        @Html.TextBox(Model.Reference, Server.HtmlDecode(Model.Value) ?? string.Empty, new { @class = "form-control", size = Model.Size, placeholder = Model.Title })
    }
    @Html.ValidationMessage(Model.Reference) // EPiServer 7.0 to 7.1
    @Html.ValidationMessage(Model.ValidationReference) // EPiServer 7.5 and upwards
</div>

ElementFragment.cshtml

@model EPiServer.HtmlParsing.ElementFragment

EndElementFragment.cshtml

@model EPiServer.HtmlParsing.EndElementFragment

SubmitFragment.cshtml

@model EPiServer.XForms.Parsing.SubmitFragment

<div class="@Model.Class">
    <input type="submit" class="btn btn-default" name="@Html.Raw(Model.UniqueName)" title="@Html.Raw(Model.Title)" value="@Html.Raw(Model.Value)" />
</div>

TextareaFragment.cshtml

@model EPiServer.XForms.Parsing.TextareaFragment

<div class="form-group @Model.Reference @Model.Class">
    <label for="@Model.Reference">@Model.Label</label>
    @if (Model.Required)
    {
        @Html.TextArea(Model.Reference, Model.Value, Model.Rows, Model.Columns, new { @class = "form-control", placeholder = Model.Title, required = "required" })
    }
    else
    {
        @Html.TextArea(Model.Reference, Model.Value, Model.Rows, Model.Columns, new { @class="form-control", placeholder = Model.Title })
    }
    @Html.ValidationMessage(Model.Reference) // EPiServer 7.0 to 7.1
    @Html.ValidationMessage(Model.ValidationReference) // EPiServer 7.5 and upwards
</div>

Select1tAsDropdownListFragment.cshtml

@model EPiServer.XForms.Parsing.Select1Fragment

<div class="form-group @Model.Reference @Model.Class">
    <label for="@Model.Reference">@Model.Label</label>
    @if (Model.Required)
    {
        @Html.DropDownList(Model.Reference, Model.Options.Select(o => new SelectListItem() { Text = Server.HtmlDecode(o.Text), Value = Server.HtmlDecode(o.Value), Selected = o.SelectedItem }), new { @class = "form-control", @title = Model.Title, @required = "required" })
    }
    else
    {
        @Html.DropDownList(Model.Reference, Model.Options.Select(o => new SelectListItem() { Text = Server.HtmlDecode(o.Text), Value = Server.HtmlDecode(o.Value), Selected = o.SelectedItem }), new { @class = "form-control", @title = Model.Title })
    }
    @Html.ValidationMessage(Model.Reference) // EPiServer 7.0 to 7.1
    @Html.ValidationMessage(Model.ValidationReference) // EPiServer 7.5 and upwards
</div>

All this allows us to go from the following form configuration

And it's default styling

To this beautiful form

What more can you do?

You can override the style of all the form fields. Here is a list of file names and models of all field types:

File name	Model	Description
ElementFragment.cshtml	EPiServer.HtmlParsing.ElementFragment	Inserted before each "fragment" (row, label, textbox, etc.), and template for horizontal rules.
EndElementFragment.cshtml	EPiServer.HtmlParsing.EndElementFragment	Inserted after each "fragment" (row, label, textbox, etc.)
InputFragment.cshtml	EPiServer.XForms.Parsing.InputFragment	Template for every textbox field
Select1tAsDropdownListFragment.cshtml	EPiServer.XForms.Parsing.Select1Fragment	Template for every dropdown field
SubmitFragment.cshtml	EPiServer.XForms.Parsing.SubmitFragment	Template for every submit button
TextareaFragment.cshtml	EPiServer.XForms.Parsing.TextareaFragment	Template for every textarea field
TextFragment.cshtml	EPiServer.HtmlParsing.TextFragment	Template for every heading field
SelectFragment.cshtml	EPiServer.XForms.Parsing.SelectFragment	Template for every checkbox field
Select1AsRadiobuttonFragment.cshtml	EPiServer.XForms.Parsing.Select1Fragment	Template for every radio button field

NOTE: You can find the default templates for some of these at "C:\Program Files (x86)\EPiServer\CMS\7.0.586.1\Application\Util\Views\Shared\EditorTemplates"

Using XForms and MVC in an EPiServer 7 Block

Mon, 28 Jan 2013 11:01:34 GMT

The most awesome features of EpiServer 7 is arguably it's Block system and that it's possible to use MVC when developing sites.

Alas, some things in EPiServer 7 apparently has some bugs when it comes to supporting MVC and blocks - XForms being one of them.

For one thing, XForms requires that you post to a url. That means you need to post to an instance of a page, or create a standalone controller for handling xform requests only.

This blog post will show you how to set up XForms using the former method.

First off, you need to create your Block:


/// <summary>
/// A xform block
/// </summary>
[ContentType(DisplayName = "XForm block")]
public class XFormBlock : BlockData
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    [Display(
        Name = "The form",
        Description = "The form.",
        GroupName = SystemTabNames.Content,
        Order = 1)]
    [CultureSpecific]
    public virtual XForm Schema { get; set; }

    /// <summary>
    /// Gets or sets the post controller.
    /// </summary>
    /// <value>The post controller.</value>
    [Display(
        Name = "Post Controller",
        Description = "The controller to post the form to.",
        GroupName = SystemTabNames.Settings,
        Order = 0)]
    public virtual string PostController { get; set; }

    /// <summary>
    /// Gets or sets the post action.
    /// </summary>
    /// <value>The post action.</value>
    [Display(
        Name = "Post Action",
        Description = "The action to run when posting.",
        GroupName = SystemTabNames.Settings,
        Order = 1)]
    public virtual string PostAction { get; set; }

    /// <summary>
    /// Gets or sets the success action.
    /// </summary>
    /// <value>The success action.</value>
    [Display(
        Name = "Success Action",
        Description = "The action to run on successful post.",
        GroupName = SystemTabNames.Settings,
        Order = 2)]
    public virtual string SuccessAction { get; set; }

    /// <summary>
    /// Gets or sets the failure action.
    /// </summary>
    /// <value>The failure action.</value>
    [Display(
        Name = "Failure Action",
        Description = "The action to run on post failure.",
        GroupName = SystemTabNames.Settings,
        Order = 3)]
    public virtual string FailedAction { get; set; }

    /// <summary>
    /// Gets or sets the CSS class.
    /// </summary>
    /// <value>The CSS class.</value>
    [Display(
        Name = "CSS class",
        Description = "The CSS class.",
        GroupName = SystemTabNames.Settings,
        Order = 5)]
    public virtual string CssClass { get; set; }

    /// <summary>
    /// Sets the default values.
    /// </summary>
    /// <param name="contentType">Type of the content.</param>
    public override void SetDefaultValues(ContentType contentType)
    {
        base.SetDefaultValues(contentType);

        this.PostController = string.Empty;
        this.PostAction = "XFormPost";
        this.SuccessAction = "Index";
        this.FailedAction = "Index";
    }
}

Then you need to create a controller for showing the XForm on a page:


public class XFormBlockController : BlockController<XFormBlock>
{
    public override ActionResult Index(XFormBlock currentBlock)
    {
        var viewModel = new XFormViewModel(currentBlock);

        if (viewModel.Form != null && this.PageRouteHelperRepository.Page != null)
        {
            var actionUri = this.PageRouteHelperRepository.Page.GetFriendlyUrl() + currentBlock.PostAction + "/";
            actionUri = UriSupport.AddQueryString(actionUri, "XFormId", viewModel.Form.Id.ToString());
            actionUri = UriSupport.AddQueryString(actionUri, "postController", currentBlock.PostController);
            actionUri = UriSupport.AddQueryString(actionUri, "postAction", currentBlock.PostAction);
            actionUri = UriSupport.AddQueryString(actionUri, "failedAction", currentBlock.FailedAction);
            actionUri = UriSupport.AddQueryString(actionUri, "successAction", currentBlock.SuccessAction);

            viewModel.ActionUri = actionUri;
        }

        var editHints = this.ViewData.GetEditHints<XFormViewModel, XFormBlock>();
        editHints.AddConnection(v => v.Form, p => p.Schema);

        return this.PartialView(viewModel);
    }
}

Here is the code for the viewmodel:


public class XFormViewModel
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    public XForm Form { get; set; }

    /// <summary>
    /// Gets or sets the CSS class.
    /// </summary>
    /// <value>The CSS class.</value>
    public string CssClass { get; set; }

    /// <summary>
    /// Gets or sets the action URI.
    /// </summary>
    /// <value>The action URI.</value>
    public string ActionUri { get; set; }
}

You could avoid using a viewmodel like the one above and just use the block type as a viewmodel, but I like to adhere to the MVVM model and I want to be able to set a custom css class for an instance of the block.

Now we need to create a view for the block. (If you're using ReSharper, just ALT+ENTER on the "return this.PartialView(viewModel)" line)


@using EPiServer.Web.Mvc.Html
@model Leroy.Web.EPiServer.ViewModels.Partials.XFormViewModel

<div class="xformblock @Model.CssClass" @Html.EditAttributes("Form")>
    @Html.PropertyFor(x => x.Form)
</div>

We now have almost everything in place. The block is set up to post to an action named "XFormPost" on the current page. However, this action does not exist on a page by default, so we need to create it somehow.
We have accomplished it by creating a base class that all PageControllers inherit from:


/// <summary>
/// The base page controller.
/// </summary>
/// <typeparam name="T">The page type</typeparam>
public abstract class BasePageController<T> : PageController<T> where T : PageData
{
    /// <summary>
    /// Handles the XForm postback
    /// </summary>
    /// <param name="xFormpostedData">The posted xform data.</param>
    /// <returns>The current view.</returns>
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult XFormPost(XFormPostedData xFormpostedData)
    {
        var formData = new XFormPageHelper().GetXFormData(this, xFormpostedData);
        
        var result = XFormActionHelper.DoAction(formData, xFormpostedData, true);

        return this.RedirectToAction("Index");
    }
}

That is all. Now you just need to add your XFormBlock to a page using a ContentArea, and the XFormBlockController will take care of rendering the form. When the user submits the form, the BasePageController will take care of storing the data and/or sending emails, etc.

As you can see on the XFormBlock class, you can specify a custom action to post to, as well as custom actions to redirect to on success or failure. This will have to be implemented in the BasePageController or the controller for your specific Page Type.

Stay tuned for the next blog post where I'll show you how to completely customize the rendering of the form based on the built-in MVC rendering engine. :-)

Using XForms and MVC in EPiServer 7

Mon, 28 Jan 2013 11:01:34 GMT

The most awesome features of EpiServer 7 is arguably it's Block system and that it's possible to use MVC when developing sites.

Alas, some things in EPiServer 7 apparently has some issues when it comes to supporting MVC - XForms being one of them.

For one thing, XForms requires that you post to a url. That means you need to post to an instance of a page, or create a standalone controller for handling xform requests only.

This blog post will show you how to set up XForms using the former method.

First off, you need to create a base controller that all your pages must derive from:

public abstract class BasePageController<T> : PageController<T> where T : PageData
{
    /// <summary>
    /// The view data key format
    /// </summary>
    private const string ViewDataKeyFormat = "TempViewData_{0}";

    /// <summary>
    /// Initializes a new instance of the <see cref="BasePageController{T}" /> class.
    /// </summary>
    protected BasePageController()
    {
        this.ContentId = string.Empty;
    }
    
    /// <summary>
    /// Gets or sets the data factory
    /// </summary>
    /// <value>The content repository.</value>
    [SetterProperty]
    public IContentRepository ContentRepository { get; set; }

    /// <summary>
    /// Gets or sets the page route helper repository.
    /// </summary>
    /// <value>The page route helper repository.</value>
    [SetterProperty]
    public PageRouteHelper PageRouteHelperRepository { get; set; }

    /// <summary>
    /// Gets or sets the URL resolver.
    /// </summary>
    /// <value>The URL resolver.</value>
    [SetterProperty]
    public UrlResolver UrlResolver { get; set; }

    /// <summary>
    /// Gets or sets the xform handler.
    /// </summary>
    /// <value>The xform handler.</value>
    [SetterProperty]
    public XFormPageUnknownActionHandler XFormHandler { get; set; }

    /// <summary>
    /// Gets or sets the current page.
    /// </summary>
    /// <value>The current page.</value>
    public PageData CurrentPage { get; set; }

    /// <summary>
    /// Gets a value indicating whether the block [is in edit mode].
    /// </summary>
    /// <returns><c>true</c> if the block [is in edit mode]; otherwise, <c>false</c>.</returns>
    protected bool IsInEditMode
    {
        get
        {
            return PageEditing.GetPageIsInEditMode(this.HttpContext);
        }
    }

    /// <summary>
    /// Gets the view data key.
    /// </summary>
    /// <value>The view data key.</value>
    private string ViewDataKey
    {
        get
        {
            return string.Format(ViewDataKeyFormat, this.ContentId);
        }
    }

    /// <summary>
    /// Gets or sets the content id
    /// </summary>
    private string ContentId
    {
        get
        {
            return this.TempData["ContentID"] != null ? this.TempData["ContentID"].ToString() : (this.TempData["ContentID"] = string.Empty).ToString();
        }

        set
        {
            this.TempData["ContentID"] = value;
        }
    }

    /// <summary>
    /// Handles the XForm postback
    /// </summary>
    /// <param name="data">The posted form data.</param>
    /// <param name="contentId">The block id.</param>
    /// <returns>A view.</returns>
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult XFormPost(XFormPostedData data, string contentId = "")
    {
        if (!string.IsNullOrEmpty(contentId)) 
        {
            this.ContentId = contentId;
        }

        // Add posted xform instance id to viewdata, so we can retrieve it later
        this.ViewData["XFormID"] = data.XForm.Id;

        return this.XFormHandler.HandleAction(this);
    }

    /// <summary>
    /// Handles the XForm postback if it was successful.
    /// </summary>
    /// <param name="data">The posted form data.</param>
    /// <returns>A view.</returns>
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult Success(XFormPostedData data)
    {
        if (data.XForm.PageGuidAfterPost != Guid.Empty)
        {
            var page = this.ContentRepository.Get<PageData>(data.XForm.PageGuidAfterPost);

            return this.Redirect(this.UrlResolver.GetVirtualPath(page.ContentLink, page.LanguageBranch));
        }

        return this.Redirect(this.UrlResolver.GetVirtualPath(this.CurrentPage.ContentLink, this.CurrentPage.LanguageBranch));
    }

    /// <summary>
    /// Handles the XForm postback if it was successful.
    /// </summary>
    /// <param name="data">The posted form data.</param>
    /// <returns>A view.</returns>
    [AcceptVerbs(HttpVerbs.Post)]
    public ActionResult Failed(XFormPostedData data)
    {
        return this.Redirect(this.UrlResolver.GetVirtualPath(this.CurrentPage.ContentLink, this.CurrentPage.LanguageBranch));
    }

    /// <summary>
    /// Called before the action method is invoked.
    /// </summary>
    /// <param name="filterContext">Information about the current request and action.</param>
    protected override void OnActionExecuting(ActionExecutingContext filterContext)
    {
        // Get current page
        this.CurrentPage = this.PageRouteHelperRepository.Page;

        // Set content id if it has not been set
        if (string.IsNullOrEmpty(this.ContentId))
        {
            this.ContentId = this.CurrentPage.PageLink.ID.ToString();
        }

        // Persist view data if this is a failed or successful xform postback, reset if this is a new postback
        if (filterContext.ActionDescriptor.ActionName == "Failed"
            || filterContext.ActionDescriptor.ActionName == "Success")
        {
            this.TempData[this.ViewDataKey] = this.ViewData;
        }
        else if (filterContext.ActionDescriptor.ActionName == "XFormPost")
        {
            this.TempData[this.ViewDataKey] = null;
        }
        
        // Merge tempdata into viewdata if it is not null
        var tempData = this.TempData[this.ViewDataKey] as ViewDataDictionary;

        if (tempData != null)
        {
            this.ViewData = tempData;
        }

        base.OnActionExecuting(filterContext);
    }
}

Making it work with pages

Create a page type class like this:

[ContentType(DisplayName = "XForm Page")]
public class XFormPage
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    [Display(
        Name = "The form",
        Description = "The form.",
        GroupName = SystemTabNames.Content,
        Order = 1)]
    [CultureSpecific]
    public virtual XForm Schema { get; set; }
}

Now you need to display the form on the page.
Create a ViewModel class for your page type class:

public class XFormPageViewModel : BasePageViewModel
{
    public XForm Schema { get; set; }

    public string ActionUrl { get; set; }
}

Then create a page controller that looks like this:

public class XFormPageController : BasePageController<XFormPage>
{
    private readonly UrlResolver urlResolver;

    public XFormPageController(UrlResolver urlResolver)
    {
        this.urlResolver = urlResolver;
    }

    public ActionResult Index(XFormPage currentPage)
    {
        var viewModel = new XFormPageViewModel()
                            {
                                Schema = currentPage.Schema
                            };

        if (currentPage.Schema != null)
        {
            var actionUrl = string.Format("{0}XFormPost/", this.urlResolver.GetVirtualPath(currentPage.PageLink, currentPage.LanguageBranch));
            actionUrl = UriSupport.AddQueryString(actionUrl, "XFormId", viewModel.Schema.Id.ToString());
            actionUrl = UriSupport.AddQueryString(actionUrl, "failedAction", "Failed");
            actionUrl = UriSupport.AddQueryString(actionUrl, "successAction", "Success");

            viewModel.ActionUrl = actionUrl;
        }

        var editHints = this.ViewData.GetEditHints<XFormPageViewModel, XFormPage>();
        editHints.AddConnection(v => v.Schema, p => p.Schema);

        return this.View(viewModel);
    }
}

Now we need to create a view. (If you're using ReSharper, just ALT+ENTER on the "return this.View(viewModel)" line)

@using EPiServer.Web.Mvc.Html
@model EPiServer.Demo.TwitterBootstrap.ViewModels.Pages.XFormPageViewModel

<div class="xformpage" @Html.EditAttributes(x => x.Schema)>
    @using (Html.BeginXForm(Model.Schema, new { Action = Model.ActionUrl, @class = "form xform" }))
    {
        Html.RenderXForm(Model.Schema);
    }
    if (Model.Schema.Id == ViewData["XFormID"])
    {
        @Html.ValidationSummary()
    }
</div>

Note: Html.ValidationSummary() is wrapped in an if statement to prevent the validation summary from showing errors from other forms on the same page.

Now you're ready to go. Just create an instance of a XFormPage, add a form to it and try i out.

Making it work with Blocks

This is very similar to making it work with pages, you just need one more parameter on the action url.

First off, you need to create your Block:

[ContentType(DisplayName = "XForm block")]
public class XFormBlock : BlockData
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    [Display(
        Name = "The form",
        Description = "The form.",
        GroupName = SystemTabNames.Content,
        Order = 1)]
    [CultureSpecific]
    public virtual XForm Schema { get; set; }
}

And the corresponding viewmodel:

public class XFormBlockViewModel
{
    /// <summary>
    /// Gets or sets the form.
    /// </summary>
    /// <value>The form.</value>
    public XForm Schema { get; set; }

    /// <summary>
    /// Gets or sets the action URI.
    /// </summary>
    /// <value>The action URI.</value>
    public string ActionUri { get; set; }
}

Then you need to create a controller for showing the block on a page:

public class XFormBlockController : BlockController<XFormBlock>
{
    private readonly PageRouteHelper pageRouteHelper;

    private readonly UrlResolver urlResolver;

    public XFormBlockController(PageRouteHelper pageRouteHelper, UrlResolver urlResolver)
    {
        this.pageRouteHelper = pageRouteHelper;
        this.urlResolver = urlResolver;
    }

    public override ActionResult Index(XFormBlock currentBlock)
    {
        var id = (currentBlock as IContent).ContentLink.ID;

        // ViewData is not automatically passed to a block controller, need to get it from TempData if it exists
        var viewDataKey = string.Format("TempViewData_{0}", id);

        if (this.TempData[viewDataKey] != null)
        {
            this.ViewData = (ViewDataDictionary)this.TempData[viewDataKey];
        }

        // Create the viewmodel
        var viewModel = new XFormBlockViewModel()
                            {
                                Schema = currentBlock.Schema
                            };

        // Create postback url
        if (viewModel.Schema != null && this.pageRouteHelper.Page != null)
        {
            var actionUrl = string.Format("{0}XFormPost/", this.urlResolver.GetVirtualPath(this.pageRouteHelper.Page.PageLink, this.pageRouteHelper.Page.LanguageBranch));
            actionUrl = UriSupport.AddQueryString(actionUrl, "XFormId", viewModel.Schema.Id.ToString());
            actionUrl = UriSupport.AddQueryString(actionUrl, "failedAction", "Failed");
            actionUrl = UriSupport.AddQueryString(actionUrl, "successAction", "Success");
            actionUrl = UriSupport.AddQueryString(actionUrl, "contentId", id.ToString());

            viewModel.ActionUri = actionUrl;
        }

        var editHints = this.ViewData.GetEditHints<XFormBlockViewModel, XFormBlock>();
        editHints.AddConnection(v => v.Schema, p => p.Schema);

        return this.PartialView(viewModel);
    }
}

When that's done, create the partial view for the block:

@using EPiServer.Web.Mvc.Html
@model EPiServer.Demo.TwitterBootstrap.ViewModels.Partials.XFormViewModel

<div class="xformblock" @Html.EditAttributes(x => x.Schema)>
    @using (Html.BeginXForm(Model.Schema, new { Action = Model.ActionUri, @class = "form xform" }))
    {
        Html.RenderXForm(Model.Schema);
    }
    if (Model.Schema.Id == ViewData["XFormID"])
    {
        @Html.ValidationSummary()
    }
</div>

To solve this, put the following code in a file named XForm.cshtml in a folder called DisplayTemplates in your ~/Views/Shared folder:

@using EPiServer.HtmlParsing
@using Leroy.Web.EPiServer.BusinessLogic.Extensions
@model EPiServer.XForms.XForm
           
@if (Model != null)
{
    var fragments = Model.CreateHtmlFragments();

    // Check if this is a postback, and if it is get the posted fragments for this instance
    if (ViewData["XFormID"] != null && Model.Id == ViewData["XFormID"])
    {
        fragments = (IEnumerable<HtmlFragment>)ViewData["XFormFragments"];
    }
    
    // Render all fragments
    foreach (var fragment in fragments)
    {
        @Html.RenderCustomHtmlFragment(fragment, "XForm/" + Model.Id + "/" + fragment.GetType().Name)
    }
}

That is all. Now you just need to add your XFormBlock to a page using a ContentArea, and the XFormBlockController will take care of rendering the form.

When the user submits the form, the BasePageController will take care of storing the data and/or sending emails, etc.

Stay tuned for the next blog post where I'll show you how to completely customize the rendering of the form based on the built-in MVC rendering engine. :-)

Custom Error Pages in EPiServer

Thu, 08 Sep 2011 18:26:53 GMT

First off, you need to disable the EPiServer error handling. You do that by opening your episerver.config and setting the "globalErrorHandling" attribute on the "<siteSettings />" element to "Off".

Then you open web.config and find the "<customErrors />" element. Ensure that the "mode" attribute to "RemoteOnly". (This is the default mode)

/// <summary>
/// Handles the Init event of the Page control.
/// </summary>
/// <param name="sender">The source of the event.</param>
/// <param name="e">The <see cref="System.EventArgs"/> instance containing the event data.</param>
protected void Page_Init(object sender, EventArgs e)
{
    var statusCode = this.GetStatusCode(Request.QueryString);
    var originalPage = this.GetOriginalPage(Request.QueryString);

    if (statusCode != 0)
    {
        var errorPage = this.GetErrorPage(originalPage, statusCode);

        if (errorPage != null)
        {
            CurrentPage = errorPage;
        }
    }
}

/// <summary>
/// Gets the HTTP status code from the query string.
/// </summary>
/// <param name="queryString">The query string.</param>
/// <returns>The HTTP status code</returns>
private int GetStatusCode(NameValueCollection queryString)
{
    var requestQueryStrings = string.Empty;

    // Try to get query string value in two different ways
    if (queryString.GetKey(0) != null)
    {
        requestQueryStrings = queryString.GetKey(0);
    }
    else if (queryString[0] != null)
    {
        requestQueryStrings = queryString[0];
    }

    if (requestQueryStrings.Split(';').Length > 0)
    {
        int code;

        if (int.TryParse(requestQueryStrings.Split(';')[0], out code))
        {
            return code;
        }
    }

    return 0;
}

/// <summary>
/// Gets the original page where the error occured.
/// </summary>
/// <param name="queryString">The query string.</param>
/// <returns>The originating page</returns>
private PageData GetOriginalPage(NameValueCollection queryString)
{
    int pageId;

    if (int.TryParse(queryString[0], out pageId)) 
    {
        return this.GetPage(new PageReference(pageId));
    }

    return CurrentPage;
}

/// <summary>
/// Gets the correct error page for the specified HTTP status.
/// </summary>
/// <param name="originalPage">The original page.</param>
/// <param name="statusCode">The status code.</param>
/// <returns>The error page</returns>
private PageData GetErrorPage(PageData originalPage, int statusCode)
{
    switch (statusCode)
    {
        case 404:
            Response.StatusCode = 404;
            Response.StatusDescription = "Not Found";
            return this.GetPageFromProperty(originalPage, "ErrorPage404");
        case 500:
            Response.StatusCode = 500;
            Response.StatusDescription = "Internal Server Error";
            return this.GetPageFromProperty(originalPage, "ErrorPage500");
        default:
            Response.StatusCode = 500;
            Response.StatusDescription = "Internal Server Error";
            return this.GetPageFromProperty(originalPage, "ErrorPage500");
    }
}

/// <summary>
/// Gets an error page from a page property.
/// </summary>
/// <param name="page">The page.</param>
/// <param name="propertyName">Name of the property.</param>
/// <returns>The error page</returns>
private PageData GetPageFromProperty(PageData page, string propertyName)
{
    var errorPageRef = page[propertyName] as PageReference;

    return !PageReference.IsNullOrEmpty(errorPageRef) ? GetPage(errorPageRef) : null;
}

Now it's time to set the front end of the ErrorHandler page. This will decide how your error pages will look. I have a very simple page that only shows a heading and some text:

<%@ Page Language="C#" AutoEventWireup="true" ErrorPage="~/Error.htm" CodeBehind="ErrorHandler.aspx.cs" Inherits="EyeCatch.EpiServer.CustomErrorPage.Templates.ErrorPages.ErrorHandler" %>
<asp:Content ID="Content1" ContentPlaceHolderID="plContent" runat="server">
    <h1><EPiServer:Property ID="Property1" PropertyName="Heading" runat="server" /></h1>
    <EPiServer:Property ID="Property2" PropertyName="MainBody" runat="server" />
</asp:Content>

EDIT: Added ErrorPage property to the @Page directive, after tip from Tom Pipe in the comments below.

The ErrorHandler page we've just created however, will never be tied to a Page Type or template. For that we create two new template pages named "ErrorPage.aspx" and "NotFoundPage.aspx".

Add the above HTML to those pages as well (Don't copy the codebehind and the @Page directive, this should be left as it is when you create the file).

Now go to EPiServer and create a Page Type that look like this:

Properties:

Do the same for the Not Found page, only exchange "ErrorPage" with "NotFoundPage".

Now you need to add some dynamic properties. Click on the "Dynamic Properties" link and then press "Add Property". Create a property that looks like this:

Do the same for the 500 Error Page, just change "ErrorPage404" to "ErrorPage500" and "404 Error Page" to "500 Error Page".

With that done we can go on to create the actual error pages and set the dynamic properties:

Create two pages of type "[Web] ErrorPage" and "[Web] NotFoundPage" somewhere in your site tree. (I created them right under the root node). Fill in the heading and body text (you can also insert an image if you like). Publish the pages.
Click your root node and then click on the "Dynamic Properties" icon on the toolbar. (The one with 3 blocks on it)
Set the "404 Not Found Page" and "500 Error Page" properties to the pages you just created. Click "Save".

Now it's time to return to web.config and do the last configuration. You can also perform this step from within IIS Manager, but I'm going to show the web.config way. (The result is the same).

Insert the following block at the end of the "<system.webServer />" block:

<httpErrors errorMode="Custom" existingResponse="Replace">
    <remove statusCode="404" subStatusCode="-1" />
    <remove statusCode="500" subStatusCode="-1" />
    <error statusCode="404" prefixLanguageFilePath="" path="/Templates/ErrorPages/ErrorHandler.aspx" responseMode="ExecuteURL" />
    <error statusCode="500" prefixLanguageFilePath="" path="/Templates/ErrorPages/ErrorHandler.aspx" responseMode="ExecuteURL" />
</httpErrors>

And you're done!

If you didn't understand what you just did, here is a walkthrough:

An error occurs on your site (404 Not Found or 500 Internal Server Error).
Since EPiServer is not doing any error handling, the event bubbles up to IIS.
IIS looks at the <httpErrors /> element and executes the URL that is specified for the HTTP status code.
It loads "ErrorHandler.aspx" directly (no redirects).
During the initialization of the ErrorHandler page, it checks what kind of error occured (404 or 500).
It then gets the page referenced in the Dynamic Property and loads the PageData for that page (Heading and BodyText).
ErrorHandler then inserts the Heading and the BodyText into the corresponding elements in the ErrorHandler designer.
The page is then loaded with your chosen text and with no ugly redirects.

I hope this tutorial is of use to you. If you have any questions or comments, don't hestitate to use the comment form below.