Blog posts by Joel Abrahamsson2013-09-16T14:08:01.0000000Zhttps://world.optimizely.com/blogs/Joel-Abrahamsson/Optimizely WorldUpdate on my EPiServer bookTwo new chapters. One of them is the first!
<p>It has been almost a month since I <a href="/link/b6bac5d89c584dda8ff527bff37b9951.aspx?id=557&epslanguage=en">announced</a> that I'm writing <a href="http://leanpub.com/episerver-7-cms-development/">a book about EPiServer 7 development</a>. Since then I've received a lot of helpful feedback and comments. Not unexpectedly the EPiServer development community has again proven its awesomeness to me!</p>
<p>While I've made two minor updates to the book since its initial release I'm today happy to announce a more major update. In the recently published version (#4) you'll find two brand new chapters. Somewhat ironically one of those is actually the first chapter, which up until now hasn't been done. And, actually it probably still isn't entirely done.</p>
<p>You see, the first chapter is something that I've been thinking about writing for years. It's not about EPiServer. Instead it's an attempt to take a step back and see how a CMS, such as EPiServer, could come to be. In the chapter we follow a site from its infancy with a single static HTML page and see how it evolves into a fairly respectable CMS based sites.</p>
<p><img class="thumbnail-centered" src="/PageFiles/678/chapter1.png" alt="" width="500" height="364" /></p>
<p>My hope is that this chapter will provide a gentle, understandable introduction for those new to CMS development in general and to EPIServer development in particular. I also hope that it may provide for some interesting reflection for senior EPiServer developers. However, with such ambitions it's hard to get it right the first time and I hope to improve it based on your feedback.</p>
<p>Anyway, if you've already bought the book, please <a href="http://leanpub.com/episerver-7-cms-development/">grab the latest version</a> and give me feedback. If you haven't yet bought the book, now may be a good time ;-)</p>
2013-09-16T14:08:01.0000000ZBlog postWorkaround: On Page Editing broken after rendering a block<p>In patch 3 for EPiServer 7 CMS there's a nasty little bug that manifests it self on sites built using ASP.NET MVC. After rendering a block that doesn't have a controller but instead is rendered using only a partial view (which, as we know, is good for performance) other properties that are rendered using the <span class="code-concept">PropertyFor</span> method may not be editable in OPE mode.</p>
<p>Luckily there's an easy workaround for that, which we can use until the issue is resolved by EPiServer; create custom display templates for the types <span class="code-concept">ContentData</span> and <span class="code-concept">ContentArea</span>. Implement each display template like the original ones shipped by EPiServer, using <span class="code-concept">RenderContentData</span> and <span class="code-concept">RenderContentArea</span>, but wrap the method calls in code that stores the value of <span class="code-concept">ViewContext.RouteData.Values["currentContent"]</span> in a variable prior to invoking the method and restores it afterwards.</p>
<p><strong>/Views/Shared/DisplayTemplates/ContentData.cshtml:</strong></p>
<pre class="language-csharp"><code>@using EPiServer.Web.Mvc.Html<br />@model EPiServer.Core.IContentData<br />@{<br /> var original = ViewContext.RouteData.Values["currentContent"];<br />}<br />@{Html.RenderContentData(Model, false);}<br />@{<br /> ViewContext.RouteData.Values["currentContent"] = original;<br />}</code></pre>
<p><strong>/Views/Shared/DisplayTemplates/ContentArea.cshtml:</strong></p>
<pre class="language-csharp"><code>@using EPiServer.Web.Mvc.Html<br />@model EPiServer.Core.ContentArea<br />@{<br /> var original = ViewContext.RouteData.Values["currentContent"];<br />}<br />@{Html.RenderContentArea(Model);}<br />@{<br /> ViewContext.RouteData.Values["currentContent"] = original;<br />}</code></pre>
2013-08-25T19:55:48.0000000ZBlog postA book about EPiServer developmentAfter years of blogging about EPiServer CMS I decided it was time to get real.
<p><img class="thumbnail-centered" src="/PageFiles/673/book_devices.png" alt="The cover of the new EPiServer book displayed in an iPhone and a Kindle." width="500" height="293" /></p>
<p>I'm happy to announce a little project that I've been working on lately; <a href="http://leanpub.com/episerver-7-cms-development/">a book about how to develop EPiServer CMS sites</a>. I'm publishing it on Leanpub and embracing their motto of publishing early and publishing often. So, while the book is far from done I have published a first version of it and early buyers will be getting it a discounted price.</p>
<h2>Content - current and planned</h2>
<p>This is a project that I've been thinking about doing for several years but haven't quite gotten around to, until now. Despite having contemplated writing the book for years the exact table of contents isn't entirely decided yet, and I hope to get reader feedback to help guide it. However, the plan is roughly to cover:</p>
<ul>
<li>General CMS concepts - I actually started writing this chapter about a year ago, but I'm not yet finished with it :)</li>
<li>Installation - "done"</li>
<li>Using the CMS - "done"</li>
<li>Core classes and concepts - "done"</li>
<li>Tools - "done"</li>
<li>A hands-on tutorial for building a first, simple site - in progress and a first version is featured in the current version of the book</li>
<li>Deep dives into content types, properties and templates</li>
<li>Caching and performance</li>
<li>How to build large scale sites, such as media sites</li>
<li>Different ways to build integrations</li>
<li>Extending the CMS in various ways</li>
</ul>
<p>Whether I'll cover all of the above topics and/or other topics will probably depend on whether there is an interest for the book and on reader feedback.</p>
<p>The book is, and will be, written as a mix of theory and practical tutorials. The examples will be using MVC, primarily as I felt MVC made it easier to focus on EPiServer's API. However, there will be asides/notes describing how to achieve the same thing with Web Forms.</p>
<h2>Pricing</h2>
<p>Prior to publishing the book interested readers could sign up to be notified when it was published and also suggest a price. The average suggested price was $38 which is actually pretty closed to what I initially thought I'd charge for the book. However, I feel that early readers should be rewarded for taking the "risk" of buying an unfinished product and, even more, be rewarded for providing feedback. Therefor I've set the minimum price (buyers can choose their own actual price depending on how much they think it's worth) at $20 and will probably increase that in the future as the book progresses.</p>
<h2>An e-book</h2>
<p>Books on Leanpub are only available as e-books. If there's a lot of interest in a print version I may look in to that in the future, but for now I'm embracing the fact that it's possible to continously publish an e-book.</p>
<p>Leanpub books are published and made available to readers in PDF, EPUB (for iPad) and MOBI (for Kindle).</p>
2013-08-20T00:34:12.0000000ZBlog postEPiServer editing delight challenge - MVC solutionSolving a small but tricky problem related to customised rendering of a property in EPiServer 7 with ASP.NET MVC.
<p>Starting with the simple stuff we render each of the properties using the PropertyFor method.</p>
<pre class="language-csharp"><code><h1>@Html.PropertyFor(x => x.Heading)</h1>
<p>@Html.PropertyFor(x => x.Intro)</p><br /></code></pre>
<p>Then we make both properties editable using a text area by adding a UI hint to each of them.</p>
<pre class="language-csharp"><code>//using EPiServer.Web;
[UIHint(UIHint.Textarea)]
public virtual string Heading { get; set; }
[UIHint(UIHint.Textarea)]
public virtual string Intro { get; set; }</code></pre>
<h2>Customise the rendering</h2>
<p>Moving on to the next requirement we create an extension method for strings that replaces line breaks with br tags. We make it return an IHtmlString so that the br tags won't be encoded.</p>
<pre class="language-csharp"><code>public static IHtmlString ToLineBreakString(this string original)
{
var parsed = string.Empty;
if (!string.IsNullOrEmpty(original))
{
parsed = HttpUtility.HtmlEncode(original);
parsed = parsed.Replace("\n", "<br />");
}
return new MvcHtmlString(parsed);
}</code></pre>
<p>Now, how do we use this method? We could modify the view to render the property's value directly and add edit attributes to the h1 tag, like this:</p>
<pre class="language-csharp"><code><h1 @Html.EditAttributes(x => x.Heading)>
@Model.Heading.ToLineBreakString()
</h1></code></pre>
<p>At first it may seem like we've solved the challenge. Both properties are editable in on-page-edit mode using text areas and a line break in the Heading property is replaced with a br tag. However, let's look at what happens when we make a change to the Heading property:</p>
<p><img class="thumbnail-centered" src="/Global/broken_preview.png" alt="" width="769" height="518" /></p>
<p>The line break in the Heading property isn't replaced with a br when the new value is inserted into the page during editing. We're not meeting the requirement that both properties should offer a realistic preview at all times.</p>
<p>This happens because the CMS has no way of knowing that we're customizing the rendering of the property in our view. Instead it updates the DOM node that represents the property with what would be rendered by the PropertyFor method.</p>
<h2>Fixing the preview</h2>
<p>If you've read my article about <a href="/link/97755f93eb134f98b538ec69de3fe450.aspx?id=534&epslanguage=en">how PropertyFor works</a> you know that means it will replace it with what the DisplayFor method would return, meaning the default display template for strings.</p>
<p>To fix this we could create a display template named string or Textarea (matching the UI hint) and render the value with the help of our extension method there. Given that we update the view to again render the Heading property using either PropertyFor or DisplayFor we would then have fixed the preview issue.</p>
<p>That would however mean that a line break in the Intro property would also be replaced with a br tag, violating the requirement that it should not be.</p>
<p>What to do then? Seems like the requirements are conflicting. Perhaps all is lost and it's time to give up?</p>
<p>Not quite. We just need to sprinkle our code with some magic dust made exactly according to the recipe.</p>
<p>First we create a display template named LineBreaked that renders a string using our extension method.</p>
<p><img class="thumbnail-centered" src="/Global/display_template.png" alt="" width="209" height="71" /></p>
<pre class="language-csharp"><code>@model string
@Model.ToLineBreakString()<br /></code></pre>
<p>Next we add another UI hint to the Heading property, this time with the name of the display template.</p>
<pre class="language-csharp"><code><strong>[UIHint("LineBreaked")]</strong>
[UIHint(UIHint.Textarea)]
public virtual string Heading { get; set; }</code></pre>
<p>That alone doesn't yield any effect as we now have two UI hints and, at least for me, the Textarea one will be used.</p>
<p>The final step that makes it all work is to modify the second UI hint so that it won't be used by PropertyFor or DisplayFor, only by the CMS when locating the approriate editor for the property. To do so we use an overload of the UIHintAttribute class' constructor and pass it a string representing a "presentation layer". Specifically the string exposed by the Edit constant in EPiServer's PresentationLayer class.</p>
<pre class="language-csharp"><code>[UIHint("LineBreaked")]
[UIHint(UIHint.Textarea, <strong>PresentationLayer.Edit</strong>)]
public virtual string Heading { get; set; }</code></pre>
<p>And with that the challenge is solved.</p>
<p><img class="thumbnail-centered" src="/PageFiles/652/fixed_preview.png" alt="" width="766" height="518" /></p>
<h2>Alternative solution</h2>
<p>The above solution works and will effect all of the places where the Heading property is rendered. There is however also an alternative, simpler, solution that will only effect the rendering in a specific place.</p>
<p>Instead of adding the additional UI hint and specifying presentation layer for the Textarea UI hint we can render the property using PropertyFor and specify a tag matching the display templates name.</p>
<pre class="language-csharp"><code><h1>@Html.PropertyFor(x => x.Heading, new { tag = "LineBreaked"})</h1><br /></code></pre>
2013-05-21T06:00:00.0000000ZBlog postEPiServer editing delight challenge - Web Forms solutionSolving a small but tricky problem related to customised rendering of a property in EPiServer 7 with ASP.NET Web Forms.
<p>Starting with the simple stuff we render each of the properties using the Property control.</p>
<pre class="language-csharp"><code><EPiServer:Property PropertyName="Heading" CustomTagName="h1" runat="server" />
<EPiServer:Property PropertyName="Intro" CustomTagName="p" runat="server" /></code></pre>
<p>Then we make both properties editable using a text area by adding a UI hint to each of them.</p>
<pre class="language-csharp"><code>//using EPiServer.Web;
[UIHint(UIHint.Textarea)]
public virtual string Heading { get; set; }
[UIHint(UIHint.Textarea)]
public virtual string Intro { get; set; }</code></pre>
<h2>Customise the rendering</h2>
<p>Moving on to the next requirement, we need to replace line breaks in the Heading property with br tags before rendering it. To do so we can change the rendering of it from using the Property control to using a h1 tag that we turn into a control by adding runat="server" and an ID to it.</p>
<pre class="language-csharp"><code><h1 ID="headingControl" runat="server"></h1><br /></code></pre>
<p>Next, in code behind, we set its InnerHtml to the modified value and make it editable in on-page-editing mode using the ApplyEditAttributes extension method.</p>
<pre class="language-csharp"><code>//using EPiServer.Web;
protected override void OnLoad(EventArgs e)
{
base.OnLoad(e);
if (!string.IsNullOrEmpty(CurrentPage.Heading))
{
headingControl.InnerHtml = CurrentPage.Heading.Replace("\n", "<br />");
}
headingControl.ApplyEditAttributes<StandardPage>(x => x.Heading);
}</code></pre>
<p>At first it may seem like we've solved the challenge. Both properties are editable in on-page-edit mode using text areas and a line break in the Heading property is replaced with a br tag. However, let's look at what happens when we make a change to the Heading property:</p>
<p><img class="thumbnail-centered" src="/PageFiles/654/broken_preview.png" alt="" width="769" height="518" /></p>
<p>The line break in the Heading property isn't replaced with a br when the new value is inserted into the page during editing. We're not meeting the requirement that both properties should offer a realistic preview at all times.</p>
<p>This happens because the CMS has no way of knowing that we're customizing the rendering of the property in our view. Instead it updates the DOM node that represents the property with what would be rendered by the Property control.</p>
<h2>Fixing the preview</h2>
<p>In order to fix the preview we could go back to rendering the property using the Property control and then modify how either all strings or string properties with a Textarea UI hint are rendered.</p>
<p>That would however violate the requirement that a line break in the Intro property should not be replaced with a br tag. Therefor we'll have to find a way to customize only the rendering of the Heading property. Luckily there are a few ways to do that.</p>
<p>One is to first render it using the Property control and specify a tag using RenderSettings:</p>
<pre class="language-csharp"><code><EPiServer:Property PropertyName="Heading" CustomTagName="h1" runat="server">
<RenderSettings Tag="LineBreaked" />
</EPiServer:Property></code></pre>
<p>Next we create a user control that inherits from PropertyControlBase<string> and add a TemplateDescriptor attribute to it in which we specify the same tag.</p>
<pre class="language-csharp"><code>[TemplateDescriptor(TagString = "LineBreaked")]
public partial class LineBreaked : PropertyControlBase<string>
{
}</code></pre>
<p>Still in code behind for our custom property control we create a property that exposes the original value, which we can retrieve through the CurrentData property, modified the way we like.</p>
<pre class="language-csharp"><code>protected string Formated
{
get
{
if (string.IsNullOrEmpty(CurrentData))
{
return string.Empty;
}
return CurrentData.Replace("\n", "<br />");
}
}</code></pre>
<p>Finally, in the markup part of the user control we output the return value of the property.</p>
<pre class="language-csharp"><code><%= Formated %><br /></code></pre>
<p>And with that the challenge is solved.</p>
<p><img class="thumbnail-centered" src="/PageFiles/654/fixed_preview.png" alt="" width="766" height="518" /></p>
<h2>Alternative solution</h2>
<p>Above we change how the Heading property is rendered by specifying a tag when rendering it with the Property control. This works well but it only modifies how the property is rendered, including preview, in a single place.</p>
<p>If we instead wanted to change how it's rendered everywhere where the Property control is used we could use an alternative approach - using UI hints.</p>
<pre class="language-csharp"><code><strong>[UIHint("LineBreaked")]</strong>
[UIHint(UIHint.Textarea<strong>, PresentationLayer.Edit</strong>)]
public virtual string Heading { get; set; }</code></pre>
<p>In the above code we've added a second UIHint attribute to the Heading property. This UI hint has the same value as the tag that our custom property control supports, meaning that it will be rendered using our custom control.</p>
<p>However, we also want the property to be edited using a text area meaning we need to keep the existing UI hint, creating a conflict. To fix that we use an overload of the UIHintAttribute class' constructor and pass it a string representing a "presentation layer". Specifically the string exposed by the Edit constant in EPiServer's PresentationLayer class.</p>
2013-05-21T05:00:00.0000000ZBlog postEPiServer editing delight challengeDo you consider yourself to be an EPiServer development ninja? Or do you aspire to become one? Then here's a challenge for you.
<p>In EPiServer 7 On-Page-Editing is the default way of editing a page. An editor clicks on a part of the page that represents a property and can update it using whatever type of editor (textbox, textarea, Tiny MCE etc) is configured for the property. All while almost instantly seeing the updated result on the page.</p>
<p><strong>For us developers</strong> the live-preview way of editing pages in EPiServer 7 can present challenges. Especially when the design requires us to somehow modify whatever the editor has entered before rendering it.</p>
<p>In order to preserve our vocational pride and keep customers happy we need to ensure that the editors get a correct preview of the content.</p>
<p><strong>Putting ourselves</strong> in the editors shoes, imagine that we edit a page and modify a couple of properties. All while checking how the page looks. Then we publish the page, only to find ourselves looking at something different from what the preview showed us. That wouldn't be very fun and we'd lose trust in the system.</p>
<p>On this topic and based on a simple case that I ran into not long ago, here's a challenge that will test your EPiServer development skills when it comes to rendering properties and your understanding of how EPiServer 7 CMS works.</p>
<h2>The challenge</h2>
<p>You have a page type class with two properties:</p>
<table class="table table-striped table-bordered" border="0">
<thead>
<tr>
<td><strong>Name</strong></td>
<td><strong>Type</strong></td>
<td><strong>Element</strong></td>
</tr>
</thead>
<tbody>
<tr>
<td>Heading</td>
<td>string</td>
<td>h1</td>
</tr>
<tr>
<td>Intro</td>
<td>string</td>
<td>p</td>
</tr>
</tbody>
</table>
<p>You should create a template for this page type that displays both properties. It should meet the following conditions:</p>
<ol>
<li>Both properties should be edited using a text area.</li>
<li>If the Heading property contains line breaks those should be replaced with br tags when it's rendered, allowing editors to create headings that span multiple lines.</li>
<li>If the Intro property happens to contain line breaks those should <strong>not</strong> be replaced. That is, editors should not be able to force new lines in the Intro property.</li>
<li>Both properties should be editable by clicking on them in on-page-edit mode.</li>
<li>Both properties should offer a realistic preview at all times.</li>
<li>The preview of the page should not rely on a full refresh of the page. That is, methods whos name contain <em>FullRefresh</em> are not allowed.</li>
<li>You are not allowed to change the types of the properties and you are not allowed to move them to a block.</li>
</ol>
<p>Here's an example of how a page that meets these conditions should look in edit mode:</p>
<p><img class="thumbnail-centered" src="/PageFiles/650/in_edit_mode.png" alt="" width="537" height="150" /></p>
<p>Sounds and looks pretty simple, right? As it turns out, while each requirement on its own is straight forward, combine them and it's not entirely obvious how to meet them all. Give it a try!</p>
<h2>Solutions</h2>
<p>Solutions can be found in separate articles:</p>
<ul>
<li><a href="/link/9d046eba9be640cd8ac81d227f9f5382.aspx?id=545&epslanguage=en">Solution for Web Forms</a></li>
<li><a href="/link/d9fc0983be834c91bc0c5c7edc454bbc.aspx?id=544&epslanguage=en">Solution for MVC</a></li>
</ul>
2013-05-20T06:00:00.0000000ZBlog postRelated content with EPiServer FindWether it's done for editorial content, products or recipes, linking to related content can be a good way to enrich a site. For visitors, for business and for SEO. While manually selecting what content to link to often produces the best results automatic functionality for displaying related complement can be a good complement.
<p>EPiServer Find has a number of methods that can be used for finding related or similar content. Combine them and they can offer a powerful way to help visitors find interesting content and improve search engine rankings through internal links.</p>
<h2>Find similar pages using MoreLike</h2>
<p>Built into Find's .NET API is a method named <span class="code-concept">MoreLike</span>. It requires a string as argument and adds a query to a search request that will match indexed objects with similar text.</p>
<pre class="language-csharp"><code>SearchClient.Instance.Search<PageData>()
<strong>.MoreLike("banana")</strong></code></pre>
<p>When using MoreLike the search results are ranked by how similar their texts are to the one we pass as argument to it. The similarity is essentially based on common words and there are <a href="http://find.episerver.com/Documentation/dotnet-api-more-like-related-documents">a number of adjustments</a> that can be made to the algorithm to optimise it to suit the specific nature of the content on a specific site.</p>
<h2>Add business logic using BoostMatching</h2>
<p>On its own the result of the MoreLike method is highly dependent on the textual content on the site, producing varying results in terms of quality depending on the nature of the content on the site. It produces results based on similarity between texts but doesn't guarantee that there is any relation between the content other than shared usages of words in the text.</p>
<p>Find's .NET API also features a method named <span class="code-concept">BoostMatching</span> which can be used to apply boost factors using whatever criteria that can be described using a filter. In other words, pretty much anything. Using that we can upgrade a MoreLike query from producing <em>similar</em> content to <em>related</em> content.</p>
<pre class="language-csharp"><code>SearchClient.Instance.Search()
.MoreLike("banana")
<strong>.BoostMatching(x => x.InCategory(42), 3)</strong></code></pre>
<p>What conditions we use for boosting is, naturally, dependent on the nature of the site and the type of content for which we want to find related content. If it's a blog post we may boost blog posts that share the same categories and tags. If it's a recipe site we may boost recipes that share the same ingredients. If it's a product we can boost based on categories, price and stock balance.</p>
<p>In other words, BoostMatching allows us to apply custom business logic tailored for our specific site and needs of the business.</p>
<h2>An example</h2>
<p>On this site I have functionality to relate content using a number of mechanisms such as categories, tags and topics. If an article is grouped in a topic other articles in the same topic is listed.</p>
<p>For articles that doesn't have such lists I still want to display a list of, as far as it's possible, related articles. That's accomplished using the below method.</p>
<pre class="language-csharp"><code>//using System.Collections.Generic;
//using EPiServer.Find;
//using EPiServer.Find.Cms;
//using EPiServer.Find.Framework;
public virtual IEnumerable<EditorialPageBase> GetSimilarPages(EditorialPageBase page)
{
//Create search request for pages of the type(s) that we're interested in
//and apply a MoreLike query using the concatenated values of all searchable
//properties on the current page.
IQueriedSearch<EditorialPageBase> query = SearchClient.Instance
.Search<EditorialPageBase>()
.MoreLike(page.SearchText());
//Apply major boost to articles in the same category.
foreach (var category in page.Categories)
{
query = query.BoostMatching(x => x.Categories.Match(category), 4);
}
//Apply a smaller but still significant boost to articles sharing tags with
//the current page.
foreach (var tagLink in page.TagReferences)
{
query = query.BoostMatching(x => x.TagReferences.Match(tagLink.ToString()), 2);
}
return query
//Utilize/apply editorial settings for how desirable a certain page
//is in the results.
.BoostMatching(x => x.SearchPriority.Match(Priority.VeryLow), 0.1)
.BoostMatching(x => x.SearchPriority.Match(Priority.Low), 0.3)
.BoostMatching(x => x.SearchPriority.Match(Priority.High), 1.5)
.BoostMatching(x => x.SearchPriority.Match(Priority.VeryHigh), 2.5)
//Exclude the current page (which is naturally the most similar page).
.Filter(x => !x.ContentLink.Match(page.ContentLink))
//Exclude unpublished and filter based on access rights and language.
.FilterForVisitor()
//Execute the query
.Take(8)
.GetContentResult(cacheForSeconds: 3600, cacheForEditorsAndAdmins: true);
}</code></pre>
2013-05-06T09:40:00.0000000ZBlog postBuilding large scale EPiServer sitesIt has been proven by numerous sites that EPiServer CMS can handle huge amounts of content. Doing so does bring a few challenges though. Here's a few few patterns that I've identified when it comes to building large scale EPiServer sites with great performance.
<p>Last week I received an e-mail with the subject ”Huge number of pages (>500 000) in EPiServer?” As you can imagine the e-mail contained questions related to whether EPiServer CMS can handle sites with A LOT of content.</p>
<p>It has been proven on a number of occasions that it indeed can. For instance, several of the biggest newspapers in Sweden, with millions of pages, run EPiServer. There are also government sites with several hundreds of thousands of pages.</p>
<p>That doesn’t mean that we’re not faced with challenges when building large EPiServer sites though.</p>
<p>In my experience, what those challenges are differs depending on the type of site, or rather, depending on how the content is structured on the site. While an individual site may be a mix of the two, there are two categories of large scale sites in terms of how they structure their content.</p>
<h3>Content that fit naturally in a deep hierarchy</h3>
<p>This is common for government sites and the like. Such sites may publish a lot of content that is organized and exposed to visitors in a hierarchy based on topics, subtopic and so on.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/Deep-hierarchy-london.png" alt="" width="630" height="485" /></p>
<p>Alternatively the content may fit naturally in a date-based hierarchy, such as an archive with publications.</p>
<ol> </ol>
<h3>Content that isn’t hierarchical or the hierarchy is shallow</h3>
<p>This is very common on media sites such as newspapers. Those sites typically have a shallow hierarchy made up of sections. There may for instance be a first level section called "Sport" and a subsection to that called "Football".</p>
<p>An article about one of the Champions League semifinals 2013 is displayed in the context of Sport/Football but beyond that it has no natural place in a tree like structure. On a site with a lot of content this in turn means that an article in context of its place in the hierarchy may have thousands, or even millions, of siblings.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/Shallow-hierarchy-mail-online.png" alt="" width="696" height="665" /></p>
<ol> </ol>
<h2>Finding content based on non-hierarchical criteria</h2>
<p>Given that we’re dealing with a site that has a lot of content that fit nicely into a tree based structure EPiServer CMS works great out-of-the-box for editors. The CMS stores content in a tree, the content tree, and expose that to editors using UI components such as the Page tree and the Block gadget that also lets editors work with content in a tree.</p>
<p><strong>While there is</strong> a lot of content, meaning that the content tree has a lot of branches and leafs editors can easily find the right place to publish new content. They can also find old content simply by navigating the content tree, or the site, the same way a public visitor would.</p>
<p>In cases where the standard navigation doesn’t suffice, such as when an editor or visitors needs to find content that, in their view, isn’t placed where it should be on the site, basic free text search functionality typically can handle that.</p>
<p>As for developers building navigation components is typically easy as all they have to do is utilize the page tree. EPiServer's methods for doing that, such as Get, GetChildren and GetAncestors are highly optimized and aggresively cached with clever dependencies for releasing their caches when needed and only then.</p>
<p><strong>However, no matter</strong> how natural the content hierarchy is there are usually a number of requirements for components that lists content in a way that isn’t based on the hierarchy. Examples of such components could for instance be the most recently published pages of a certain type, all articles published be a certain author or department and all publications categorized with a certain keyword.</p>
<p>For such requirements EPiServer CMS only has the method FindPagesWithCriteria to offer. Besides obvious usability issues for developers FPWC has some serious performance issues, especially on a site with a large volume of content.</p>
<p>In other words, on a large scale EPiServer site with content fitting naturally into a deep hierarchy we’re faced with the challenge of finding content based on non-hierarchical criteria.</p>
<p><strong>There are two</strong> common solutions to this problem. One is to somehow store the answer to such questions at a time where we know that the answer is changing. For instance, this may mean storing a list of the ten last published pages of a given type serialized into a property somewhere or in the Dynamic Data Store, updating each time a page is published. This requires quite a lot of development time and, worse, it requires us to know what questions will need answering beforehand. It’s also rather error prone.</p>
<p>The second, and much better, common solution to this is to use a search engine. This has been done on a number of large EPiServer sites using different search engines. Today though the obvious solution is to use <a href="/link/6f0db1b72ffa49968a45c16b1146b95a.aspx?id=43&epslanguage=en">EPiServer Find</a>, the search and content retrieval product that EPiServer offers. Find was in many ways built exactly to address this problem in a way that offers great usability for developers and short development time.</p>
<p class="conclusion"><strong>Solution:</strong> Use a EPiServer Find to create navigations and listings of content that are not based on the contents place in the content tree.</p>
<h2>Non-hierarchical content</h2>
<p>When the content can’t naturally be fitted into a deep hierarchy additional challenges arise. First, EPiServer’s API and editorial interface is designed for sites organizing content in a tree. If the content can’t be organized into a deep hierarchy performance will suffer. Here’s how I put it in my reply to the e-mail:</p>
<blockquote>“The content tree can handle millions of items BUT if those items aren't stored in a deep hierarchy there will be performance problems. That is, if you have a page with ten thousand children you have a problem. If you have a page with a hundred children and each of those have a hundred children you won't have a problem.”</blockquote>
<p>While I knew this from experience, after sending that reply, I decided to conduct a few experiments to prove it.</p>
<p>In the context of a scheduled job I wrote code that created ten thousand pages below the same parent. It also created a hundred pages below another common parent and then a hundred pages below each of those pages. Everything was done in batches of a hundred pages and the mean time for creating a page during each batch was logged.</p>
<p>Let’s look at the results for creating 100x100 pages in a hierarchy first.</p>
<table class="table table-striped table-bordered table-condensed" border="0">
<thead>
<tr>
<td><strong>Batch</strong></td>
<td><strong>Avg. time per published page (ms)</strong></td>
</tr>
</thead>
<tbody>
<tr>
<td>1-100</td>
<td>22</td>
</tr>
<tr>
<td>201-300</td>
<td>22</td>
</tr>
<tr>
<td>501-600</td>
<td>22</td>
</tr>
<tr>
<td>901-1000</td>
<td>24</td>
</tr>
<tr>
<td>1901-2000</td>
<td>24</td>
</tr>
<tr>
<td>4901-5000</td>
<td>33</td>
</tr>
<tr>
<td>9901-10000<span style="white-space: pre;"> </span></td>
<td>30</td>
</tr>
</tbody>
</table>
<p>There are of course some variances which would likely even themselves out with a larger sample (I ran the test only four times), but it's pretty clear that it takes almost exactly the same amount of time to create page number ten thousand as page number one when storing pages in a hierarchy where each page has ninetynine siblings. </p>
<p>Now, let’s compare that to creating 10000 pages below the same parent.</p>
<table class="table table-striped table-bordered table-condensed" border="0">
<thead>
<tr>
<td><strong>Batch</strong></td>
<td><strong>Avg. time per published page (ms)</strong></td>
</tr>
</thead>
<tbody>
<tr>
<td>1-100</td>
<td>22</td>
</tr>
<tr>
<td>201-300</td>
<td>26</td>
</tr>
<tr>
<td>501-600</td>
<td>34</td>
</tr>
<tr>
<td>901-1000</td>
<td>50</td>
</tr>
<tr>
<td>1901-2000</td>
<td>83</td>
</tr>
<tr>
<td>4901-5000</td>
<td>180</td>
</tr>
<tr>
<td>9901-10000<span> </span></td>
<td>414<br /></td>
</tr>
</tbody>
</table>
<p>As we can see the time required to publish a page grows based on the number of existing pages below the page’s parent page. Plotted into a diagram we can see that this growth is linear.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/time-growth.png" alt="" width="347" height="208" /></p>
<p>Beyond API performance issues, expanding the tree node for a page revealing it’s ten thousand pages in edit mode takes time. Below is what FireBug reported for me when I tried to expand a none with ten thousand children. </p>
<p><img class="thumbnail-centered" src="/PageFiles/643/loading-10000-children.png" alt="" width="400" height="216" /></p>
<p>After receiving the response from the server Firefox reported an unresponsive JavaScript on the page and it took several minutes before I actually got to see the pages in the page tree. </p>
<p>Of course, even if it the page tree wouldn't have any issues with displaying thousands of children for a node such a list would hardly be useful for editors.</p>
<p class="conclusion"><strong>Conclusion:</strong> EPiServer is built and optimized for sites that stores content in a hierarchy in which each node has hundreds and not thousands of child nodes.</p>
<p>Clearly, EPiServer's page tree doesn't work well for large scale sites with huge volumes of non-hierarchical content. Not in terms of performance and not in terms of editor usability.</p>
<p>Luckily there's a fairly easy solution that has proven to work very well. In fact, I've seen it done so many times that I'd call it a pattern. What is is? Faking it!</p>
<h3>Structuring bulk content in arbitrary hierarchies</h3>
<p>We know that EPiServer needs, or prefers, organizing pages in such a way that each node in its content tree doesn't have more than hundreds of immediate children. EPiServer does not however care about why a certain page belongs in a certain place in the tree. Therefor we can automatically place pages in a hierarchy based on some arbitrary criteria.</p>
<p>For articles on a media site this is commonly done by placing them in a structure based on publish date.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/page-tree-date-structure.png" alt="" width="394" height="191" /></p>
<p>There are a number of ways to implement such functionality but it typically involves:</p>
<ol>
<li>Defining a root node for a certain type of content.</li>
<li>Hooking up to events from EPiServer's API listening to when content is created.</li>
<li>When a page of a matching type is created ensure that there is a place for it in the date structure below the root, otherwise create it.</li>
<li>Move the newly created content to its parent in the date structure.</li>
</ol>
<p>Of course, when content resides in a structure whose only purpose is to work well with EPiServer performance wise we can't utilize the content hierarchy when building navigations. The solution to that typically involves four things:</p>
<ol>
<li><strong>Defining one or</strong> several properties on the content types that will be used for "bulk content". These properties are typically of type PageReference, ContentReference or ContentArea. For instance, an article may have a property named Section of type PageReference which points to the Football section.</li>
<li><strong>Utilizing the above</strong> mentioned property/properties when rendering pages to determine in what context they should be shown. For instance, an article about a Champions League game may have a Section property pointing to a page named Football which in turn is a child of a page named Sport. Based on that the article's content is displayed framed by a header, navigation elements and right column from Football or Sport. </li>
<li><strong>Using a search</strong> engine to create listings. Essentially I'm talking about the same problem as we looked at before here, finding content based on non-hierarchical criteria. The only difference is that we now need to apply the same solution in more places as the majority of the content of the site's content is organized in such a way in the content tree that it can't be used to build navigations and listings. <br /><strong>With that said</strong>, we can still utilize EPiServer's standard API methods for components such as the main navigation as those pages aren't the "bulk content" and therefor works well with the page tree. Again while we can use pretty much any search engine that offers good performance and scalability, EPiServer Find is the best option as it was born out of these specific needs.</li>
<li><strong>Rewriting URLs.</strong> By default URLs on an EPiServer site is built up using the page's name prefixed by the name of each of its ancestors in the page tree. When storing articles or other content in a structure that has nothing to do with how visitors sees the page on the site URLs won't seem very logical. For instance an URL like /2013/04/23/champions-league.. is hardly helpful and doesn't look very good. With older versions of EPiServer CMS we typically handled that using a custom URL rewriter. Nowadays with EPiServer 7 we do it using <a href="/link/e9ec501e09a64e74bdad2df4f1102ae4.aspx?id=526&epslanguage=en">custom routing</a>.</li>
</ol>
<p class="conclusion"><strong>Solution:</strong> Automatically organize non-hierarchical content in arbitrary hierarchies based on creation date, first letter in their names or some other criteria. Use properties on the content to tie it to pages in the page tree which provide the context in which the content should be rendered. Use EPiServer Find to build listings.</p>
<p>Using the above approach we solve the performance issues when dealing with non-hierarchical content of the type that is often found on media sites, blogs and the like. While that works great we have one more problem to solve - how editors create and find the content for which the page tree is more or less useless.</p>
<h3>Custom components for editorial workflows</h3>
<p>We could tell editors "To create a new article click on the Articles node in the page tree. We have some code that will automatically move it a few levels down in a date based structure. Oh, and don't forget to set the Section property." However, odds are we wouldn't find much jobs afterwards and we'd see buch of angry comments about EPiServer on Twitter.</p>
<p><strong>Clearly, if we're</strong> dealing with the type of site that the page tree doesn't work well with we can't just be content with solving performance issues. We'll also need to extend EPiServer's edit mode to provide good workflows for editors. </p>
<p>Exactly how such components should work and be implemented differs from site to site but it typically involves functionality to:</p>
<ul>
<li>Create "bulk content" without having to use the page tree gadget.</li>
<li>Either automatically populating "infrastructure properties" such as Section or making it very easy for editors to do so.</li>
<li>List the most recent content. Especially on media sites it's a very common requirement to have a list that displays all articles that have either been published today, not yet been published or is scheduled to be published.</li>
<li>Find content based on criteria such as author, publish date and section.</li>
</ul>
<p>I've built such functionality both in EPiServer 6 and EPiServer 7 and based on those experiences I've created the <a href="/link/c307dee82d384e9cbfa436f08a8b949d.aspx?id=509&epslanguage=en">PowerSlice</a> project. PowerSlice is one way of addressing several of the above requirements and may solve all needs for some sites. For other sites it may be used for inspiration.</p>
<p><img class="thumbnail thumbnail-centered" src="/PageFiles/643/creating-content-in-slice.png" alt="" width="377" height="152" /></p>
<p><strong>Either way, it's</strong> very much possible to build the components needed by editors. With EPiServer 7 it typically involves creating custom Dojo/Dijit widgets and utilizing EPiServer Find.</p>
<p class="conclusion"><strong>Solution:</strong> Extend EPiServer's edit mode with custom components tailor made for the needs of the editors. PowerSlice may be an option and/or used for inspiration.</p>
<p>Are you still with me? Perhaps it's about time we looked at an example.</p>
<h2>An example - this site</h2>
<p>This site doesn't exactly fit the "large scale" description. However, as it's primarily a blog it, along with certain parts of many other "small" sites, does have non-hierarchical content. Therefor I applied the above mentioned techniques to it, meaning that we can look at it as an example of how a large scale site, such as a media site, can be built.</p>
<h3>Organizing pages</h3>
<p>In terms of hiearchy there are two types of pages on the site. Articles and tags are automatically organized in two separate structures. Sections and standard pages are not.</p>
<p>All articles resider under a node below the start page. Under that node they are grouped first by year and then by month.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/example-page-tree.png" alt="" width="258" height="516" /></p>
<p>Articles have a property named MainCategory edited using a drop down from which it's possible to select one of the categories (sections) on the site.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/example-category-property.png" alt="" width="228" height="40" /></p>
<p>This property is used for breadcrumbs and context specific things when rendering an article.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/Example-MainCategory-usage.png" alt="" width="448" height="77" /></p>
<p>Articles also have a content area property to which other categories can be added.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/example-additional-categories-property.png" alt="" width="590" height="92" /></p>
<p>MainCategory and any categories added to AdditionalCategories are combined by a code only property on articles named AllCategories.</p>
<p>New articles can be created using a UI component that's created using PowerSlice.</p>
<p><img class="thumbnail-centered" src="/PageFiles/643/Example-create-new-article.png" alt="" width="477" height="273" /></p>
<p>When an article is created it's initial parent is the root node for articles. Using a modified version of my old open source project <a href="https://github.com/joelabrahamsson/PageStructureBuilder">PageStructureBuilder</a> the article as automatically moved to a year/month structure.</p>
<h3>Listings and routing</h3>
<p>Categories/sections list articles "belonging" to them based ordered by publication date. This is done using a fairly simple search query using EPiServer Find that filters on article's AllCategories property.</p>
<pre class="language-csharp"><code>_searchClient.Search()
.Filter(page => page.Categories.Match(currentPage.ContentLink))
.CurrentlyPublished()
.FilterOnReadAccess()
.OrderByDescending(x => x.StartPublish);</code></pre>
<p>As for URLs I use a custom partial router, which I've <a href="/link/e9ec501e09a64e74bdad2df4f1102ae4.aspx?id=526&epslanguage=en">previously described in great detail</a>.</p>
<h2>Dealing with traffic</h2>
<p>So far this article has been about how to build sites with large volumes of content on EPiServer CMS. There's of course another way to interpret "large scale sites" - sites with a lot of traffic.</p>
<p>Again, it's already been proven by a number of existing EPiServer customers that EPiServer can handle huge volumes of traffic. With that said, it's of course also very much possible to build a site on EPiServer that crumbles once it's hit with more than a couple of concurrent requests.</p>
<p><strong>A robust EPiServer</strong> site that can handle a lot of traffic and let editors work efficiently at the same time requires a good implementation. And a good implementation requires skilled and experienced developers who know what they are doing.</p>
<p>In general EPiServer CMS's API is highly optimized and the most significant methods for getting content based on the hierarchy are cached. As for EPiServer Find it's fast, highly scalable and also has mechanisms for caching that can be used when needed. So, as first step in hardening a site for production it's absolutely vital to use the API methods visely. Having done so the site will hold well on its own.</p>
<p><strong>Sometimes though, </strong>we're dealing with a site that has so much traffic that it's not just enough use caching to prevent database calls. The actual rendered HTML output needs to be cached as well. For that EPiServer offers a fairly basic <a href="/link/cc5f6e31902d4913b22a2f7c573bbde7.aspx?id=184&epslanguage=en">output cache</a> that can be used.</p>
<p>While that may be an option, for site with really, really, really much traffic we may need even more efficient output caching. In those cases we can either construct a custom output cache to use on the webservers or, which I prefer, use a web content accelerator/caching reverse proxy such as Varnish. We may also want to look in to using a CDN instead or as a compliment.</p>
<p><strong>One thing to</strong> beware of though is that any form of output caching, with the exception of partial caching, will limit editors ability to use some of the functionality built into the CMS such as personalization. If that's a problem we can often work around that by loading parts of pages using JavaScript and not caching such requests. Of course that means more requests to the site though.</p>
<p>In general, my philosophy is to build the site as robust and performant as possible without so that it can handle the traffic without any other form of caching. After that, if it's needed or economically motivated some sort of cache can be put in front of the site.</p>
<p>This approach has two benefits. First of all we can choose to use output caching for the right reasons. Second, using output caching tends to hide performance problems in the application and while those may not be a problem at first they may be whenever the cache is released or if there's an issue with the output cache. Then it's very valuable if the web applciation can hold on its own.</p>
<h2>Summary</h2>
<ul class="check">
<li>EPiServer CMS can handle sites with millions of pages.</li>
<li>For large scale sites FindPagesWithCriteria doesn't work for non-hierarchical queries. Use EPiServer Find for that.</li>
<li>EPiServer relies on content being split up into a hierarchy. If the content doesn't fit naturally into such a hierarchy, make one up and use a combination of properties, Find and edit mode extensions for creating new content and building listings.</li>
</ul>
2013-04-29T09:13:03.0000000ZBlog postHow EPiServer's HTML helper PropertyFor worksPropertyFor is the counterpart of the Property control when building websites using EPiServer 7 and ASP.NET MVC. However, it does not work the same way as the Property control and understanding how it works is key to rendering the markup that you want and need.
<p>When using Web Forms the standard/default/recommended way to render an EPiServer property is to use the EPiServer:Property control. When using ASP.NET MVC its counterpart is the HTML helper <strong><span class="code-concept">PropertyFor</span></strong>.</p>
<p>That is, PropertyFor is the counterpart the Property control in MVC in terms of being the recommended way to render a property. It is however <em>not</em> the equivalent of the Property control in terms of functionality.</p>
<h2>Wrapping elements</h2>
<p>As you may know, the Property control always wraps the property value in a HTML element. The element differs depending on the property type and can be customized using the CustomTag attribute on the control. This isn't the case with PropertyFor.</p>
<p>To exemplify, let's look at the code below where we use the PropertyFor method to render a string property.</p>
<pre class="language-csharp"><code><div>
@Html.PropertyFor(x => x.Heading)
</div></code></pre>
<p>Given the Heading property has the value "Banana", the above will output the following when the page is rendered in view mode.</p>
<pre class="language-csharp"><code><div>
Banana
</div><br /></code></pre>
<p>When the page is rendered in edit mode the output will instead be:</p>
<pre class="language-csharp"><code><div>
<div class="epi-editContainer" data-epi-property-name="Heading" data-epi-use-mvc="True">Banana</div>
</div></code></pre>
<p>As you can see, the property's value has been wrapped in a div with a CSS class and a couple of data-attributes. </p>
<p class="conclusion"><strong>Conclusion</strong>: PropertyFor <em>never</em> wraps the property's value in an element when rendering it in view mode. <em>It always</em> wraps the property's value in an element when rendering it in edit mode.</p>
<h3>CustomTag and CssClass</h3>
<p>As I've previously written about, it's possible to <a href="/link/7e15400e6eaf4ab7921d0a1becacb9b3.aspx?id=283&epslanguage=en">pass settings such as CustomTag and CssClass to PropertyFor</a>. With the Property control the CustomTag setting controls the type of element that the property is wrapped in and the CssClass setting adds one or more CSS classes to the wrapping element.</p>
<p>Let's modify the previous example to see what PropertyFor does with them.</p>
<pre class="language-csharp"><code><div>
@Html.PropertyFor(x => x.Heading, new { CustomTag = "h1", CssClass ="muted" })
</div></code></pre>
<p>In view mode this changes the output to:</p>
<pre class="language-csharp"><code><div>
Banana
</div></code></pre>
<p>That's right, it doesn't change the output at all.</p>
<p>What about when rendered in edit mode?</p>
<pre class="language-csharp"><code><div>
<h1 class="epi-editContainer" data-epi-property-name="Heading" data-epi-use-mvc="True" data-epi-property-rendersettings="{&quot;customTag&quot;:&quot;h1&quot;,&quot;cssClass&quot;:&quot;muted&quot;}" class="heading">Banana</h1>
</div></code></pre>
<p>Starting with CustomTag we can see that setting it to h1 changed the type of the wrapping element that PropertyFor added in edit mode.</p>
<p class="conclusion"><strong>Conclusion:</strong> CustomTag changes the type of element that wrapes the rendered property when rendered in edit mode.</p>
<p>As for CssClass that added a class attribute with the specified value to the element. However, there already was another class attribute on the element and our custom CSS class wasn't added to that. It was added as a separate class attribute, meaning that the browser will ignore it. Here's how FireBug sees the rendered markup:</p>
<p><img class="thumbnail" src="/PageFiles/633/firebug-custom-class.png" alt="" width="625" height="74" /></p>
<p>So, it appears that while CustomTag changes the type of wrapping element that PropertyFor renderes the property in in edit mode CssClass doesn't, in practice, have any effect on the class attribute on the wrapping element.</p>
<p>However, there's another setting we can pass to PropertyFor, EditContainerClass. Let's see what happens if we use that instead of CssClass, like this:</p>
<pre class="language-csharp"><code><div>
@Html.PropertyFor(x => x.Heading, new { CustomTag = "h1", EditContainerClass ="muted" })
</div></code></pre>
<p>That produces the following when rendered in edit mode:</p>
<pre class="language-csharp"><code><div>
<h1 class="muted" data-epi-property-name="Heading" data-epi-use-mvc="True" data-epi-property-rendersettings="{&quot;customTag&quot;:&quot;h1&quot;,&quot;editContainerClass&quot;:&quot;muted&quot;}">Banana</h1>
</div></code></pre>
<p>Look at that. No second class attribute has been added and the first has changed from "epi-editContainer" to the value we specified in EditContainerClass.</p>
<p class="conclusion"><strong>Conclusion:</strong> CssClass does not change the CSS class for the wrapping element when rendered in edit mode. EditContainerClass does.</p>
<p>Us specifying CustomTag, CssClass and, later, EditContainerClass also brought another change to the rendered markup in edit mode - a data-epi-property-rendersettings attribute was added to the wrapping element. The attributes value looks to be the serialized version of the anonymous object we used to pass the settings to PropertyFor with.</p>
<h2>How PropertyFor renders property values</h2>
<p>So far we've looked at how and when PropertyFor wraps the output for a property. But, beyond rendering a wrapping element in edit mode, how does it actually render a property?</p>
<p>In Web Forms the Property control uses the ClassFactory to resolve a control to which it delegates the actual rendering of the property. This way different controls are used for different types of properties. For instance, a string is rendered as is (wrapped in a p tag) while a LinkCollection is rendered as an ul-li list.</p>
<p>The PropertyFor method works quite differently but in a way that achieves similar results - it delegates the actual rendering to ASP.NET MVC's <strong><span class="code-concept">DisplayFor</span></strong> method.</p>
<p class="conclusion"><strong>Conclusion:</strong> In view mode PropertyFor isn't much more than an alias for DisplayFor. In edit mode it adds a wrapping element to whatever is rendered by DisplayFor. The wrapping element contains attributes that the CMS uses to identify editable properties.</p>
<h3>DisplayFor and display templates</h3>
<p>The DisplayFor method uses a number of rules to determine what to render for a given object. These, in an abbreviated form based on the official <a href="http://msdn.microsoft.com/en-us/library/ee407390(v=vs.98).aspx">documentation</a> on MSDN, are:</p>
<ul>
<li>If the property is typed as a primitive type (integer, string, and so on), the method renders a string that represents the property value.</li>
<li>If the property type is Boolean, the method renders an HTML input element for a check box.</li>
<li>If a property is annotated with a data type attribute, the attribute specifies the markup that is generated for the property. For example, if the property is marked with the EmailAddress attribute, the method generates markup that contains an HTML anchor that is configured with the mailto protocol.</li>
<li>If the object contains multiple properties, for each property the method generates a string that consists of markup for the property name and markup for the property value.</li>
</ul>
<p><strong>What the documentation</strong> doesn't say clearly though is that the rendering is based on templates which can be overridden. That can be done by placing a partial view whose name matches the type of object that is to be displayed or whose name matches either a data type name or UI hint.</p>
<p>EPiServer adds a number of such templates to our site using a virtual path provider. These are the ones that handle the acutal rendering of EPiServer specific types such as LinkCollection, ContentArea etc.</p>
<p><strong>Should we want</strong> to we can <a href="/link/f2b4323122994d50aaefa2e9a3e53242.aspx?id=253&epslanguage=en">customize the rendering</a> of such types by creating our own display templates. We can also specify that a specific template should be used for a specific property, no matter its type, by adding a UI hint to it.</p>
<h2>PropertyFor and content areas</h2>
<p>So far we've concluded that PropertyFor acts as a wrapper for DisplayFor and wraps the output from DisplayFor in an element, but only when invoked in edit mode context. There's seemingly an exception to that rule.</p>
<p>Let's look at what happens when we render a property of type ContentArea. The code may look like this:</p>
<pre class="language-csharp"><code><div>
@Html.PropertyFor(x => x.Contents)
</div></code></pre>
<p>Given that the content area is empty this results in the following output in edit mode:</p>
<pre class="language-csharp"><code><div>
<div class="epi-editContainer" data-epi-property-name="Contents" data-epi-use-mvc="True"></div>
</div></code></pre>
<p>Nothing surprising there. The call to PropertyFor results in a wrapping element, the div. Of course, since we're in edit mode that's expected.</p>
<p>Now, let's look at the output in view mode:</p>
<pre class="language-csharp"><code><div>
</div></code></pre>
<p>Nothing surprising there either. The wrapping element is gone. As we've already concluded that it should be in view mode.</p>
<p>Let's see what happens when we add something to the content area. In this case I've added a page for which there is a very simple partial renderer which simply outputs "Partial renderer output".</p>
<p>Here's the output in edit mode:</p>
<pre class="language-csharp"><code><div>
<div class="epi-editContainer" data-epi-property-name="Contents" data-epi-use-mvc="True">
<div data-epi-block-id="4" data-epi-content-name="Home">
Partial renderer output
</div>
</div>
</div></code></pre>
<p>Again, no surprises. The wrapping element is there. The single content in the area is also wrapped in a div which is used to communicate information about item in the area to the CMS.</p>
<p>What about view mode then?</p>
<pre class="language-csharp"><code><div>
<div>
<div>
Partial renderer output
</div>
</div>
</div></code></pre>
<p>That's quite a few div tags! Compare them to the output we saw in edit mode and you find that the wrapping element for the property (the second div) is there, even though we're in view mode. </p>
<p><strong>It appears as</strong> though there's something treating content areas in a special way in PropertyFor, always outputting the wrapping element if the area isn't empty no matter in what context the area is being rendered.</p>
<p>That's not the case though. Instead it's the default display template for content areas that works in a way that gives that effect.</p>
<p>That display template delegates the rendering of the area to a method named <strong><span class="code-concept">RenderContentArea</span></strong> located in the class EPiServer.Web.Mvc.Html.ContentAreaExtensions. That method checks if the context is view mode and if it is outputs the wrapping element.</p>
<p><strong>Why? Well, imagine</strong> you want to render the content area as an ul-li list. In that case you'd want to invoke PropertyFor with ChildrenCustomTagName set to "li" in order to make each item in the area wrapped with an li instead of a div.</p>
<p>Then you'd want to have the li tags wrapped in an ul. If you were to wrap the call to PropertyFor in an ul that would work great in view mode but you'd end up with <ul><div><li> in edit mode as PropertyFor always wraps the output in a div, or some other tag specified using CustomTag. </p>
<p><strong>On the other hand,</strong> if you didn't wrap the call to PropertyFor in an ul tag and set CustomTag to "ul" you'd end up with an ul-li list in edit mode but a lone set of li tags in view mode. To prevent that, the default display template for content areas, by means of the RenderContentArea method, outputs the wrapping element in view mode.</p>
<p class="conclusion"><strong>Conclusion:</strong> The default display template for content areas is implemented in such a way that the wrapping element is always outputted no matter if the property is rendered in view mode or edit mode, but only if the content area isn't empty.</p>
<h2>Rendering properties without PropertyFor</h2>
<p>While PropertyFor is the primary intended way to render properties when building EPiServer templates using MVC there's nothing that says that we have to use it. We're free to render properties of content objects such as PageData or BlockData, or properties of view models, however we want.</p>
<p>Of course, when doing so it's up to us to add the attributes the CMS needs to identify editable properties in preview/on-page-edit mode. To do that we can use the HTML helper extension EditAttributes. Using that method we feed it an expression which specifies a given property on the model in the view and it spits out whatever attributes the CMS needs on its wrapping element.</p>
<p>Here's a simple example:</p>
<pre class="language-csharp"><code><h1 @Html.EditAttributes(x => x.Heading)>@Model.Heading</h1></code></pre>
<p>One important thing to keep in mind though - when editing the page in on-page-edit mode the CMS will replace the value in the element that wraps the property value with the updated value. This means that if we're rendering something other than what the display template for the property does editors won't get a realistic preview.</p>
<p>How that works and how to handle that is an article of its own :)</p>
<h2>Summary</h2>
<ul class="check">
<li>PropertyFor acts as a wrapper for DisplayFor. Therefor, to understand how PropertyFor works we need to look at how DisplayFor works.</li>
<li>Beyond wrapping DisplayFor, PropertyFor wraps the output in an element needed by the CMS when in edit mode.</li>
<li>The wrapping element is by default a div but can be changed using CustomTag.</li>
<li>A custom CSS class can be added to the wrapping element when in edit mode using EditContainerClass.</li>
<li>When used with content areas the wrapping element will be outputted in view mode as well due to how the default display template for ContentArea works.</li>
</ul>
2013-04-20T14:04:32.0000000ZBlog postAdd UIHint to an EPiServer property without affecting its editor<p>We can use UI hints to make the PropertyFor and DisplayFor methods use a specific display template when rendering properties with ASP.NET MVC.</p>
<p>For instance, when rendering a property like this...</p>
<pre class="language-csharp"><code>[UIHint("Banana")]<br />public virtual string Heading { get; set; }</code></pre>
<p>...using Html.PropertyFor() it will be "sent" to a display template named Banana, given such a template exists.</p>
<p>There's just one problem. When adding a UI hint that no editor descriptor cares about we loose the original editing functionality for the property and it will be edited using the "legacy" editing functionality. That is, instead of a textbox for a string property editors will see a button saying "Click the button to edit".</p>
<p>To fix that, use an overload for the UIHint attribute and specify <strong><span class="code-concept">PresentationLayer.Website</span></strong>, like this:</p>
<pre class="language-csharp"><code>[UIHint("Banana", PresentationLayer.Website)]<br />public virtual string Heading { get; set; }</code></pre>
<p>One caveat, while this works great with PropertyFor it won't work with DisplayFor which won't recognize the UI hint any longer.</p>
2013-04-18T15:49:30.0000000ZBlog postSpecify z-index for a property's overlay in EPiServer's on page edit mode<p>Sometimes two property values overlap when rendered in a template. It may for instance be a string property whose value should be rendered on top of an image which is also a property. Or it may be a link/URL property that should be rendered at the of a string property.</p>
<p>By default both properties will have an overlay, the thin blue border that is positioned on top of the element in which the property value is rendered. However, only one of them will be clickable.</p>
<p>To handle that we can specify the z-index for the overlay for the property that isn't clickable. To do so add a <strong><span class="code-concept">data-epi-overlay-z-index</span></strong> attribute to the element that contains the property. For instance, when using ASP.NET MVC and Razor:</p>
<pre class="language-csharp"><code><h1 data-epi-overlay-z-index="123" @Html.EditAttributes(x => x.Heading)>
@Model.Heading
</h1><br /></code></pre>
2013-04-18T15:31:47.0000000ZBlog postEPiServer Find 101New to EPIServer Find and want a jump start? Here's what you need to know.
<p>If you're new to EPiServer Find and going to use it in a project, or just want to try it out, there's plenty of <a href="http://find.episerver.com/Documentation">documentation on Find's site</a>. There's also training offered by EPiServer. Not to mention <a href="http://world.episerver.com/Modules/Forum/Pages/Forum.aspx?id=58826&epslanguage=en">the forum</a> on EPiServer World.</p>
<p>Sometimes you need a little quick start though. Here's the most essential things to know about Find's .NET API and CMS integration.</p>
<h2>Setting up</h2>
<p>You can grab yourself a free test index at <a href="http://find.episerver.com">find.episerver.com</a>. Once you have created your index you can copy and paste the necessary configuration into your app.config or web.config.</p>
<p><img class="thumbnail-centered" src="/PageFiles/623/Find-configuration.png" alt="" width="714" height="378" /></p>
<p>Finally you need to download and reference Find's .NET API. That's easily done through NuGet given that you have EPiServer's NuGet feed added as a package source. There's three packages to choose from. For an EPiServer CMS site install <strong>EPiServer Find CMS Integration</strong>. For any other type of .NET application install <strong>EPiServer Find Client API</strong>.</p>
<h2>Communicating with the REST API</h2>
<p>You can use the .NET API from any .NET application. When doing so, all communication with Find's REST API goes through an instance of the <strong><span class="code-concept">IClient</span></strong> interface. To obtain such an instance when not using the CMS integration you can use the <strong><span class="code-concept">Client.CreateFromConfig()</span></strong> method to create it based on settings in app.config/web.config.</p>
<p>If you're using the CMS integration or any other integration for other EPiServer products <em>always</em> use the singleton <strong><span class="code-concept">SearchClient.Instance</span></strong>. This is important. The singleton is preconfigured with conventions set up for CMS content.</p>
<blockquote>"If you're using the CMS integration always use the singleton SearchClient.Instance"</blockquote>
<h2>Finding things</h2>
<p>Once you have a client search for indexed objects (CMS objects are automatically indexed upon save) using the <strong><span class="code-concept">Search<T>()</span></strong> method where T is the type of objects you want to search for. The method supports inheritance and searching for objects that implement an interface.</p>
<p>The Search method returns an object which you can add queries and filters to. Use the <strong><span class="code-concept">For</span></strong> method for free text search. Use the <strong><span class="code-concept">Filter</span></strong> method to apply criterias.</p>
<p>The Filter method is very similar to LINQ's Where method but has a slightly different syntax. You can filter on any property of a "simple" type, such as int, string, DateTime, double, GUID etc. Check out <a href="http://find.episerver.com/Documentation/dotnet-api-filtering">the documentation</a> for more information or use Intellisense.</p>
<p>You can use methods with familiar names from LINQ to apply sorting, projections and paging - <strong><span class="code-concept">OrderBy</span></strong>, <strong><span class="code-concept">Select</span></strong>, <strong><span class="code-concept">Skip</span></strong>, <strong><span class="code-concept">Take</span></strong> etc.</p>
<p>Once you're done building your search request execute it against the REST API and get the result using the <strong><span class="code-concept">GetResult()</span></strong> method. The returned object will be an object the implements IEnumerable<T> so you can start iterating over the results straight away.</p>
<p>Note that if you're searching for CMS objects such as PageData and want to fetch the full objects you shouldn't use GetResult but instead use the <strong><span class="code-concept">GetContentResult()</span></strong> method. When using the integration for CMS 6, that's called GetPagesResult.</p>
<blockquote>"if you're searching for CMS objects such as PageData and want to fetch the full objects ... use the GetContentResult() method"</blockquote>
<h3>Unified Search</h3>
<p>One of the things that makes Find powerful and easy to use at the same time is the fact that it let's us index our own .NET object and search for them in a strongly typed way. Sometimes though, such as building a search page, we want to search over many different types. Find makes that easy to using a concept called <a href="http://find.episerver.com/Documentation/unified-search">Unified Search</a>.</p>
<p>In general - use the regular Search method for building listings, navigations and specialized search page with ease and use Unified Search when building free text search pages where users should search in *everything*.</p>
<h2>Where to go from here</h2>
<p>That's it. A few key concepts to get you started and a few important things to remember to avoid being faced by a YSOD.</p>
<p>Once you've familiarized yourself with Find's .NET API you can move on to <a href="http://find.episerver.com/Documentation/dotnet-api-indexing">indexing custom objects</a> or why not check out some of the more specialized and interesting methods such as <a href="http://find.episerver.com/Documentation/dotnet-api-more-like-related-documents">MoreLike</a> and <a href="http://find.episerver.com/Documentation/dotnet-api-boosting-with-filters">BoostMatching</a>. Also, don't miss out of the many types of <a href="http://find.episerver.com/Documentation/dotnet-api-facets">facets</a> which you can use to build many interesting things.</p>
<p>Want to build a search page for an EPiServer site quickly? <a href="/link/d90bae5d27f847289132b12e7b94750f.aspx?id=254&epslanguage=en">Here's one</a> complete with annotated source code for you.</p>
<p><strong>Happy Finding!</strong></p>
2013-04-16T22:36:20.0000000ZBlog postPattern for EPiServer block preview MVC controller<pre class="language-csharp"><code>using System.Web.Mvc;
using EPiServer.Core;
using EPiServer.Framework.DataAnnotations;
using EPiServer.Framework.Web;
using EPiServer.Web;
namespace MySite
{
[TemplateDescriptor(
Inherited = true,
TemplateTypeCategory = TemplateTypeCategories.MvcController,
Tags = new [] { RenderingTags.Preview },
AvailableWithoutTag = false)]
public class PreviewController : Controller, IRenderTemplate<BlockData>
{
public ActionResult Index(IContent currentContent)
{
//TODO: Create model suitable for the view and return ViewResult
return View();
}
}
}</code></pre>
<p>Explained:</p>
<pre class="language-csharp"><code>using System.Web.Mvc;
using EPiServer.Core;
using EPiServer.Framework.DataAnnotations;
using EPiServer.Framework.Web;
using EPiServer.Web;
namespace MySite
{
[TemplateDescriptor(
//Support everything inheriting from BlockData.
Inherited = true,
//By default controllers implementing IRenderTemplate<T> where T is BlockData
//are registered as partial renderers. As this will be a "full page" renderer
//we need to change that.
TemplateTypeCategory = TemplateTypeCategories.MvcController,
//Should only be used for preview
Tags = new [] { RenderingTags.Preview },
AvailableWithoutTag = false)]
public class PreviewController : Controller,
//Register as template for BlockData. To only support a specific type
//change the type parameter from BlockData to that type and optionally
//set Inherited = false in the the TemplateDescriptor attribute above.
IRenderTemplate<BlockData>
{
public ActionResult Index(
//While we implement IRenderTemplate for BlockData model binding
//can only deal with IContent, ie shared blocks in this case.
IContent currentContent
)
{
//TODO: Create model suitable for the view and return ViewResult
return View();
}
}
}</code></pre>
2013-04-15T10:26:49.0000000ZBlog postHiding EPiServer properties from editors<p>When managing a property in EPiServer's admin mode there is a setting named "<strong>Display in Edit Mode</strong>". To control this setting from code in EPiServer 7 use the <strong><span class="code-concept">ScaffoldColumn</span></strong> attribute.</p>
<p>When set to false it will hide the property from editors, meaning that while they may seem the rendered value in preview mode they won't see a blue box around it and they won't be able to click on the property to edit it. The property won't be visible in forms editing mode either.</p>
<p>There is also the <strong><span class="code-concept">Editable</span></strong> attribute. When this is set to false the property will still be visible to editors in both preview mode, with a blue box around it, and in forms editing mode. The editor for it will however be disabled, meaning that while editors can inspect the property's value they can't modify it.</p>
2013-04-14T16:10:08.0000000ZBlog postCustom routing for EPiServer contentTwo real-world examples of how to customize the routing for EPiServer pages to take control of the site's URLs and links.
<p>EPiServer 7 CMS uses the built in routing functionality in ASP.NET for URL handling. The default routing when using EPiServer 7 mimics the friendly URL functionality in older versions of the CMS in which the URL for a page is built up of it's URLSegment property prefixed by it's ancestors URL segments.</p>
<p><img class="thumbnail-centered" src="/PageFiles/617/page-tree-routing.png" alt="" /></p>
<p>There are many nice aspects of the default behavior. For instance, URL's for pages match their places in the page tree and in navigation elements making them seem logical and predictable. However, it also has the drawback of tying the URL for a page to it's location in the page tree making it risky to move content.</p>
<p><strong>Also, in some</strong> situations, such as when you have a site with a lot of content, it may not be appropriate to place content in a specific place in the content tree even though it belongs there.</p>
<p>It may also be that a page is only used as a data bearer without a template and links to it should lead to some other page, optionally with some parameters in the URL.</p>
<p>In such cases we need to extend or modify EPiServer's default routing. In this article I'll show two real-world examples of doing just that.</p>
<h2>Custom routing using partial routing</h2>
<p>The first example is drawn from how articles are routed on this site. The article you're currently reading is tied to the EPiServer CMS category (a page) on the site which is reflected in navigation elements.</p>
<p><img class="thumbnail-centered" src="/PageFiles/617/navigation-elements.png" alt="" width="718" height="315" /></p>
<p>It does not however reside under the CMS category's page. Instead it's placed in a hierarchical structure based on the date it was created.</p>
<p><img class="thumbnail-centered" src="/PageFiles/617/place-in-page-tree.png" alt="" width="675" height="341" /></p>
<p>Why articles is stored this way is beyond the scope of this article but, as you can probably imagine, storing them this way brings a few problems.</p>
<p><strong>Making the article</strong> belong to the CMS category is straight forward. All that's needed is a property of type ContentReference or PageReference on the page type used for articles. That can then be used when building menus and breadcrumbs.</p>
<p>Listing content based on categories is a bit trickier to achieve performance wise with the CMS' API but in my case I have Find to help me with that.</p>
<p>Finally, the URL for an article will be /<year>/<month>/<URLSegment>/. While that's not terrible it's not what I want. Instead I wanted the URL's for articles to be simply the host name followed by their URL segments.</p>
<h3>Partial routing</h3>
<p>EPiServer 7 features a concept called partial routing. In <a href="/link/2f25082cc83c41c282edf9bf3ab743d1.aspx">the developer guide</a> it's described as</p>
<blockquote>Partial routing makes it possible to extend routing beyond pages. You can use partial routing either to route to data outside EPiServer CMS or to route to other content types than pages.</blockquote>
<p>We can however also use it to route ordinary pages, like articles in this case.</p>
<p>To utilize partial routing we create a class implementing IPartialRouter<TContent, TRoutedData> found in the EPiServer.Web.Routing namespace. The first type parameter specifies the type of content we're interested in routing children for. The second the type of content, or other type of object that we'll be routing.</p>
<p>Did I lose you there? Perhaps a fruity example can clarify things.</p>
<p><strong>A class that implements</strong> IPartialRouter<Banana, Apple> will be able to route outgoing URLs whenever the object to route is an apple. Whenever a part of the URL for an incoming request has been routed to a content object of type Banana and there are still parts of the URL left to route it will be handed the banana and information about the remaining URL and asked to return an apple.</p>
<p>Crystal clear, right? Perhaps not. Let's look at how we can use it to route articles.</p>
<h3>Implementing IPartialRouter</h3>
<p>Given that we want articles to have relative URLs that are simply their URL segments the first type parameter when implementing IPartialRouter is the page type class that is used for the start page. The second type parameter is the page type used for articles.</p>
<p>Let's create a class that implements IPartialRouter with those type parameters and have Visual Studio generate the required methods for us.</p>
<pre class="language-csharp"><code>using System.Web.Routing;<br />using EPiServer.Web.Routing;<br />using EPiServer.Web.Routing.Segments;<br />using MySite.Models.Pages;<br /><br />namespace MySite.Routing<br />{<br /> public class ArticleRouter : IPartialRouter<StartPage, ArticlePage><br /> {<br /> public object RoutePartial(StartPage content, SegmentContext segmentContext)<br /> {<br /> throw new System.NotImplementedException();<br /> }<br /><br /> public PartialRouteData GetPartialVirtualPath(<br /> ArticlePage content, <br /> string language, <br /> RouteValueDictionary routeValues,<br /> RequestContext requestContext)<br /> {<br /> throw new System.NotImplementedException();<br /> }<br /> }<br />}</code></pre>
<p>As you can see, there are two methods that we'll need to implement. RoutePartial is for incoming requests while GetPartialVirtualPath is for outgoing.</p>
<p>We'll start by implementing the RoutePartial method.</p>
<h3>RoutePartial</h3>
<p>The RoutePartial method will be invoked whenever a the first parts of the URL points to a page of the TContent type parameter and there are remaining parts of the URL left to route. In this example, as we're implementing the IPartialRouter interface with the start page's type as the TContent parameter that will pretty much always be the case.</p>
<p>The method is invoked with two arguments. The first is the content of type TContent that the first parts of the URL route to, the start page in our case. The second is an object of type SegmentContext which contains information about the next segment in the URL to route.</p>
<p>Using the two arguments it's our job to figure out what article, if any, the request should be routed to.</p>
<pre class="language-csharp"><code>public object RoutePartial(StartPage content, SegmentContext segmentContext)<br />{<br /> if (!content.ContentLink.CompareToIgnoreWorkID(ContentReference.StartPage))<br /> {<br /> return null;<br /> }<br /><br /> var nextSegment = segmentContext.GetNextValue(segmentContext.RemainingPath);<br /> var urlSegment = nextSegment.Next;<br /> if (string.IsNullOrEmpty(urlSegment))<br /> {<br /> return null;<br /> }<br /> <br /> ArticlePage article = null;<br /><br /> //TODO: Figure out which article it is we're routing based on the urlSegment variable, if any, and populate the article variable with that.<br /><br /> if (article != null)<br /> {<br /> segmentContext.RemainingPath = nextSegment.Remaining;<br /> segmentContext.RoutedContentLink = article.ContentLink;<br /> }<br /> <br /> return article;<br />}</code></pre>
<p>There's quite a few things going on in the above code.</p>
<p><strong>First of all it</strong> verifies that the root content is indeed an object for which we want to route remaning parts of the URL. In other words, if we for some reason are dealing with a page of the StartPage type that is not the start page. Not likely when dealing with start pages perhaps, but stranger things have happened and this check may be vital in other scenarios.</p>
<p>Next we proceed to retrieve the next part of the URL which we assign to the urlSegment variable. For an URL such as /hello-world/ the urlSegment variable's value will be "hello-world". For an URL such as /hello/world/ the urlSegment variable's value will be "hello".</p>
<p>Given that there is indeed at least one more segment in the URL we proceed to locate an article whose URL segment matches that. As that's code specific to the site I've omitted my implementation.</p>
<p><strong>How one would do</strong> this can vary greatly from site to site. On a small site we may simply retrieve all articles and use LINQ's Where method to find an article with a matching URLSegment property. On a larger site we may use EPiServer Find or we may make the page's ID a part of the URL when implementing outgoing routing which we'll get to shortly.</p>
<p>However we choose to locate articles, or whatever it it we're routing, we need to make sure to do it in a good way performance wise. This code will be called <em>a lot</em>!</p>
<p><strong>Given that we've</strong> found an article that we wish to route to we remove the URL segment that we've taken care of from the SegmentContext by assigning the remaning part of the URL to its RemainingPath property. That is, given an article with a URL such as /hello-world/ where we have extracted "hello-world" from the segment context we update it to set its remaining path to nothing.</p>
<p>Also, given that we've found an article, we modify the segment context so that it knows that we've found content that we want to route to.</p>
<p>Finally we return the article, or null, if we didn't find one. If we return null nothing in particular will happen. The routing will proceed as usual routing to a page of some other type or resulting in a 404.</p>
<h3>GetPartialVirtualPath</h3>
<p>The GetPartialVirtualPath method will be invoked when an article is being outgoing routed. That is, when we for instance create a link to an article with the PageLink HTML helper method.</p>
<p>It's invoked with four arguments which we can use to determine the context in which the article is being routed. Based on those we need to return an object of type PartialRouteData.</p>
<p>The PartialRouteData class has two properties - BasePathRoot and PartialVirtualPath. The generated relative URL will be a combination of the relative URL of the content referenced by BasePathRoot and whatever we set PartialVirtualPath to.</p>
<pre class="language-csharp"><code>public PartialRouteData GetPartialVirtualPath(<br /> ArticlePage content, <br /> string language, <br /> RouteValueDictionary routeValues,<br /> RequestContext requestContext)<br />{<br /> var contentLink = ContentRoute.GetValue("node", requestContext, routeValues) <br /> as ContentReference;<br /><br /> if (!content.ContentLink.CompareToIgnoreWorkID(contentLink))<br /> {<br /> return null;<br /> }
if (PageEditing.PageIsInEditMode)<br /> {<br /> return null;<br /> }<br /><br /> return new PartialRouteData<br /> {<br /> BasePathRoot = ContentReference.StartPage,<br /> PartialVirtualPath = content.URLSegment<br /> };<br />}</code></pre>
<p><strong>In the implementation</strong> above we begin by extracting a reference to the content that is being routed using the ContentRoute.GetValue method. Typically this will be a reference to the same article that is being passed to the method as the "content" parameter. However, I've found at least one situation when that wasn't the case.</p>
<p>If the method is invoked in context of routing something else than the article passed in as the "content" variable we're not interested in modifying the routing so we simply return null. </p>
<p>Likewise, if the request is in context of EPiServer's edit mode we return null as we don't have any reason to modify the routing then. That is, we don't care what the URL is when the page is loaded into the CMS's IFrame and if we modify it things may not work as expected.</p>
<p>If however we are dealing with an article that we want to modify the routing for we create a new PartialRouteData object, populate its properties and return it.</p>
<p>Since in this example we want articles to simply have their own URL segments as URLs we set the BasePathRoot to a reference to the start page and the PartialVirtualPath to the article's URLSegment property.</p>
<h3>Using the partial router</h3>
<p>Our partial router class is done. In order for it to be used we need to add it to the site's route table during start-up though. That's easily done using an initialization module and the RegisterPartialRouter extension method that EPiServer provides (in the EPiServer.Web.Routing namespace).</p>
<pre class="language-csharp"><code>using System.Web.Routing;<br />using EPiServer.Framework;<br />using EPiServer.Framework.Initialization;<br />using EPiServer.Web.Routing;<br /><br />namespace MySite.Routing<br />{<br /> [ModuleDependency(typeof(EPiServer.Web.InitializationModule))]<br /> public class RouteInitialization : IInitializableModule<br /> {<br /> public void Initialize(InitializationEngine context)<br /> {<br /> var articleRouter = new ArticleRouter();<br /> RouteTable.Routes.RegisterPartialRouter(articleRouter);<br /> }<br /><br /> public void Uninitialize(InitializationEngine context)<br /> {<br /> }<br /><br /> public void Preload(string[] parameters)<br /> {<br /> }<br /> }<br />}</code></pre>
<h3>Restoring tree-like URLs</h3>
<p>In the above example we modify EPiServer's default routing to make pages of a specific type, articles, have URLs that are simply their URL segments. That's what I wanted for this site as it decouples article's URLs from both their place in the tree and their categories.</p>
<p><img class="thumbnail-centered" src="/PageFiles/617/startpage_as_url_root.png" alt="" width="718" height="319" /></p>
<p>However, we're not limited to that specific use case. For instance we may instead want articles in the example scenario we've looked at here to have a URL based on their categories instead. As if they were actually placed under their categories in the page tree.</p>
<p><img class="thumbnail-centered" src="/PageFiles/617/category_as_url_root.png" alt="" width="718" height="319" /></p>
<p>To accomplish that we would need to make a few modifications to our partial router class.</p>
<p>Since the "URL homes", the base path, for articles won't be the start page but instead a categories the first step is to modify the TContent type parameter when implementing IPartialRouter. Instead of the start page's type we set it to the type under which articles will reside URL-wise. In the case of this site that would be the class CategoryPage.</p>
<pre class="language-csharp"><code>public class ArticleRouter : IPartialRouter<<strong>CategoryPage</strong>, ArticlePage></code></pre>
<p>Changing the type parameter of the implemented interface we need to change the type of the RoutePartial method's first parameter or the compiler will complain.</p>
<pre class="language-csharp"><code>public object RoutePartial(<strong>CategoryPage</strong> content, SegmentContext segmentContext)</code></pre>
<p>Now the compiler is happy but we'll need to make some changes to the code as well. Let's start with the GetPartialVirtualPath method as that's easiest.</p>
<p>All we need to do there is change what we set the BasePathRoot property on the object we return to. Instead of setting it to a reference to the start page we set it to a reference to some other page that will provide the first part of the article's URL. For our example scenario that would be the property that points to the article's main category.</p>
<pre class="language-csharp"><code>return new PartialRouteData<br />{<br /> BasePathRoot = <strong>content.MainCategory</strong>,<br /> PartialVirtualPath = content.URLSegment<br />};</code></pre>
<p>The RoutePartial method will need to undergo larger changes.</p>
<p>We can skip the initial check that the root content which is passed in in as the "content" variable is indeed the root page we care about as we now have multiple possible roots.</p>
<p>Instead we'll need to verify that the root, the category, should be used as the routing parent for the article that we're routing.</p>
<pre class="language-csharp"><code>ArticlePage article = null;<br /><br />//TODO: Figure out which article it is we're routing based on the urlSegment variable, if any, and populate the article variable with that.<br /><br />if (article == null <br /> || <strong>content.ContentLink.CompareToIgnoreWorkID(article.MainCategory)</strong>)<br />{<br /> return null;<br />}<br /><br />segmentContext.RemainingPath = nextSegment.Remaining;<br />segmentContext.RoutedContentLink = article.ContentLink;<br /> <br />return article;</code></pre>
<h2>Custom routing using a custom segment</h2>
<p>We've now seen an example of how we can use the partial routing concept in EPiServer 7 to implement custom routing. In the next example we'll look at another way of customizing routing - by using a custom implementation of the ISegment interface.</p>
<p><strong>On this site I use</strong> pages to define tags. That is, each tag is a page somewhere in the page tree and articles have a content area to which I can add one or more tag pages. This allows me to change the name of a tag without having to update all pages tagged with it. It also gives me the possibility to add unique content to a tag beyond its name.</p>
<p>When I tag a page with one or more existing tags I simply drag them to the content area. When I render a list of tags I simply output a link to each tag using the PageLink HTML helper.</p>
<p>As I have a separate template for tag pages this works great. However, when the site first went live I didn't have that template. Instead I wanted a tag-link to point to a search for the tag using the site's search page.</p>
<p><img class="thumbnail-centered" src="/PageFiles/617/tag_search_url.png" alt="" width="718" height="367" /></p>
<p>One way to solve that would of course have been to find all places where links to tags were rendered and modify the code there to link to the search page. That wouldn't have been a very flexible solution though. By instead modifying the outgoing URLs for tag pages by modifying routing for them I didn't have to touch any other code.</p>
<p><strong>At first glance it</strong> may seem like we could use partial routing for this scenario as well but a case like this, where we want to route to a specific page with one or more query string parameters isn't really what partial routing is for.</p>
<p>Instead we can handle cases like this by creating a custom implementation of the ISegment interface and register a route that uses the segment.</p>
<h3>Creating a segment</h3>
<p>In order to create a custom segment we create a class that implements ISegment (in the EPiServer.Web.Routing.Segments namespace). Alternatively we can let our class inherit SegmentBase which I'll do in this example.</p>
<pre class="language-csharp"><code>using System;<br />using System.Web.Routing;<br />using EPiServer.Web.Routing.Segments;<br /><br />namespace MySite.Routing<br />{<br /> public class TagSearchSegment : SegmentBase<br /> {<br /> public TagSearchSegment(string name) : base(name)<br /> {<br /> }<br /><br /> public override bool RouteDataMatch(SegmentContext context)<br /> {<br /> throw new NotImplementedException();<br /> }<br /><br /> public override string GetVirtualPathSegment(<br /> RequestContext requestContext, <br /> RouteValueDictionary values)<br /> {<br /> throw new NotImplementedException();<br /> }<br /> }<br />}</code></pre>
<p>As you can see from the code above, where I've had Visual Studio autogenerate required methods for me, SegmentBase has two abstract methods that we must implement - RouteDataMatch and GetVirtualPathSegment.</p>
<p>RouteDataMatch is invoked during in-bound routing. We get passed information about the current context and can use that to determine if we want to modify the routing. If we do we modify the context in some way and return true. However, as we only care about out-bound routing in this example we can simply implement it to return false.</p>
<pre class="language-csharp"><code>public override bool RouteDataMatch(SegmentContext context)<br />{<br /> return false;<br />}</code></pre>
<h3>GetVirtualPathSegment</h3>
<p>The GetVirtualPathSegment method is invoked during outgoing routing and in order to modify the URL we'll need to return a string with the URL, or part of the URL, that we want to route to. We'll also need to remove values that we feel we've taken care of from the RouteValueDictionary that is passed to the method.</p>
<pre class="language-csharp"><code>public override string GetVirtualPathSegment(<br /> RequestContext requestContext, <br /> RouteValueDictionary values)<br />{<br /> if (GetContextMode(requestContext.HttpContext, requestContext.RouteData) <br /> != ContextMode.Default)<br /> {<br /> return null;<br /> }<br /><br /> var contentLink = ContentRoute.GetValue("node", requestContext, values) <br /> as ContentReference;<br /><br /> if (ContentReference.IsNullOrEmpty(contentLink))<br /> {<br /> return null;<br /> }<br /><br /> var contentLoader = ServiceLocator.Current.GetInstance<IContentLoader>();<br /> var tagToRoute = contentLoader.Get<IContent>(contentLink) as TagPage;<br /> if (tagToRoute == null)<br /> {<br /> return null;<br /> }<br /><br /> string tagSearchUrl = null;<br /><br /> //TODO: Figure out the url we want to route to, if any, and set the tagSearchUrl variable to that<br /><br /> if (tagSearchUrl == null)<br /> {<br /> return null;<br /> }<br /><br /> values.Remove("node");<br /> values.Remove("controller");<br /> values.Remove("action");<br /> values.Remove("routedData");<br /><br /> return tagSearchUrl;<br />}</code></pre>
<p>That's quite a mouthful! Let's go through it step by step.</p>
<p>First we check that we're not in edit mode using a helper method. This is necessary as we will otherwise get a 404, or worse, when viewing tag pages in edit mode as our code will route to the search page while EPiServer will add the tag's ID to the URL, meaning that we'll end up viewing invoking the search page's template with the tag page as the current page.</p>
<p>The GetContextMode method looks like this:</p>
<pre class="language-csharp"><code>private static ContextMode GetContextMode(<br /> HttpContextBase httpContext, <br /> RouteData routeData)<br />{<br /> var contextModeKey = "contextmode";<br /> if (routeData.DataTokens.ContainsKey(contextModeKey))<br /> {<br /> return (ContextMode)routeData.DataTokens[contextModeKey];<br /> }<br /> if ((httpContext == null) || (httpContext.Request == null))<br /> {<br /> return ContextMode.Default;<br /> }<br /> if (!PageEditing.GetPageIsInEditMode(httpContext))<br /> {<br /> return ContextMode.Default;<br /> }<br /> return ContextMode.Edit;<br />}</code></pre>
<p>Next we proceed to extract a reference to the content that is being routed. If we can't find such a reference we're probably routing a file or something else that we don't care about so we return null.</p>
<p>Given that we have a content reference we proceed to fetch the content that we're routing. If it isn't a tag we don't care about it so we return null.</p>
<p><strong>If however the</strong> content that we're routing is a tag we build up the URL we want to route to. I've omitted that code as it may be specific to each site and use case.</p>
<p>Given that we have a URL that we want to route to we return it, but before doing so we remove route values that we don't want anyone else who cares about routing to see as we've already taken care of them.</p>
<h3>Using the segment</h3>
<p>With the custom segment done we need to register a route that uses it for it to matter. As this should be done during start-up of the site we add an initialization module.</p>
<pre class="language-csharp"><code>using System.Collections.Generic;<br />using System.Web.Routing;<br />using EPiServer.Framework;<br />using EPiServer.Framework.Initialization;<br />using EPiServer.Web.Routing;<br />using EPiServer.Web.Routing.Segments;<br /><br />namespace MySite.Routing<br />{<br /> [ModuleDependency(typeof(EPiServer.Web.InitializationModule))]<br /> public class RouteInitialization : IInitializableModule<br /> {<br /> public void Initialize(InitializationEngine context)<br /> {<br /> var segment = new TagSearchSegment("tag");<br /> var routingParameters = new MapContentRouteParameters()<br /> {<br /> SegmentMappings = new Dictionary<string, ISegment>()<br /> };<br /> routingParameters.SegmentMappings.Add("tag", segment);<br /><br /> RouteTable.Routes.MapContentRoute(<br /> name: "tags",<br /> url: "{language}/{tag}",<br /> defaults: new { action = "index" },<br /> parameters: routingParameters);<br /> }<br /><br /> public void Uninitialize(InitializationEngine context)<br /> {<br /> }<br /><br /> public void Preload(string[] parameters)<br /> {<br /> }<br /> }<br />}</code></pre>
<p>Using the code in the Initialize method above we register a route for "{language}/{tag}". We map the {tag} part to our custom segment meaning that it will be replaced with whatever we return from the segment's GetVirtualPathSegment method.</p>
<h2>Basic routing</h2>
<p>We've just seen two fairly advanced examples of how the routing for content can be customized when using EPiServer 7. In both cases we're more or less in complete control and can execute custom logic on a per-request basis.</p>
<p>That's nice, but there may be cases where we want to do something simpler. Were we don't need all that power and flexibility. For instance, let's say we for some reason wanted to support outputting only the first n characters of the name of a page given that the request is for a page followed by /name/<n>/.</p>
<p>Not the most realistic scenario perhaps, but it does make for a simple example. Anyhow, To handle such a case we wouldn't have to create a partial router or a custom segment. All we need to do is register a route using the MapContentRoute method during start-up.</p>
<pre class="language-csharp"><code>RouteTable.Routes.MapContentRoute(<br /> "myRoute", "{language}/{node}/{action}/{charcount}", <br /> new {action = "name"});</code></pre>
<p>Now, given that we're using MVC, we can add an action to controllers for pages named Name which will be used for matching requests.</p>
<pre class="language-csharp"><code>public ActionResult Name(CategoryPage currentPage, int charCount)<br />{<br /> if (currentPage.PageName.Length < charCount)<br /> {<br /> charCount = currentPage.PageName.Length;<br /> }<br /> return new ContentResult()<br /> {<br /> Content = currentPage.PageName.Substring(0, charCount)<br /> };<br />}</code></pre>
<p><img class="thumbnail-centered" src="/PageFiles/617/name_routing.png" alt="" width="511" height="207" /></p>
<p>For another example of this type of custom routing check the <a href="/link/93f6e76b807943689b9aedef019fc067.aspx">routing section</a> in EPiServer's developers guide.</p>
<h2>Conclusion</h2>
<p>We've seen a couple of examples of how we can take charge of the routing for specific types of content. With this in our toolbox we can free the URLs for pages from the content tree, change where pages links to as well as other interesting stuff.</p>
<p>A couple of words of warning is in place though.</p>
<p><strong>First of all, when</strong> modifying both the outbound and inbound routing as in the first example, the one with articles, we're bypassing EPiServer's functionality for ensuring that no two pages can have the same URL. That is, in the example with the articles we'll need to ensure that no two articles have the same URL segment.</p>
<p>Second, do think about that the methods for routing, such as the ones we've looked at in this article may be invoked a lot, so be sure to test the performance with realistic data before deploying to production.</p>
<p>With that said, I must say that it's nice that we can control the routing in just about any way we'd like. That brings many interesting possibilities.</p>
<p>Happy routing!</p>
2013-04-09T06:30:00.0000000ZBlog postSlice your EPiServer content with PowerSlice!Lately I've been working on a little module for EPiServer CMS for listing and creating contents in other ways than using the page tree. I call it PowerSlice and it's now available for download.
<p><em>Want to get slicing right away or prefer a short introduction video? Check out <a href="/link/c307dee82d384e9cbfa436f08a8b949d.aspx?id=509&epslanguage=en">PowerSlice's site</a>.</em></p>
<p>Content manangement using EPiServer CMS is largely based on a hierarchical structure - the content tree. Pages is organized in the page tree and blocks in folders.</p>
<p>This hierarchy is great in many ways. By using the hierarchy as data source for navigation and listing components when developing templates editors are free to organize the site's content in a flexible way while not having to call on developers to modify functionality for navigation components and the like.</p>
<p><strong>However, not all</strong> content fits naturally into a hierarchical structure. On a medium sized corporate websites most of the content is naturally fitted into a hierarchical structure - but then there's the news room and the corporate blog.</p>
<p>Such content may share a natural first level parent but other than that there may not be anything specific that groups the content into a hierarchy. At least not naturally.</p>
<p><strong>On other types of</strong> sites, such as media sites and blogs, almost none of the content can be fitted into a deep hierarchical structure. Instead sections, categories and keywords/tags is used to create the site's taxonomy and navigation.</p>
<h2>Freeing content from the content tree using Find</h2>
<p>EPiServer CMS doesn't handle such content very well out of the box. Luckily EPiServer Find provides the perfect compliment. Using Find we as developers can easily list all content in a specific category no matter of where it's located in the content tree. Or all content tagged with a given combination of tags.</p>
<p><strong>By using Find we</strong> can easily build templates without a dependency on the page tree. However, in order to easily work with content that isn't easily grouped using a tree structure editors need some help. Find can come to the rescue here as well, but we as developers will need to extend EPiServer's user interface.</p>
<h3>Freeing editors from the content tree using PowerSlice</h3>
<p>I've worked quite a lot with media sites using EPiServer. I've also built this site, which features articles classified by categories and tags rather than a hierarchy, on EPiServer.</p>
<p>Therefor, to make it easier to handle non-hierarchical content and illustrate how media sites, news room functionality or blogs can be built using EPiServer CMS and Find I've created an extension module that makes it easy to list content matching a defined set of criteria. Each such listing is called a "slice". Why? It's a slice of the site's content tree.</p>
<p><strong>A slice may be</strong> all pages or blocks of a given type. Or it may be all content created by the user. Or all content who's status is "ready to publish". Or...</p>
<p>All content in a slice is listed using "infinite" scrolling. Editors can filter it using free text search and sort it, by default either by name or by publish date.</p>
<p><img class="thumbnail-centered" src="/PageFiles/591/slices-from-alloy.png" alt="" width="271" height="230" /></p>
<p>When creating a slice the developer can also add one or several ways to create new content, typically within the slice. For instance if a slice lists all content of a number of page types used for articles the editor can use it to select one of those page types, enter a name and hit the Create button and a new page will be created at a predefined location in the page tree.</p>
<p><img class="thumbnail-centered" src="/PageFiles/591/creating-content-in-slice.png" alt="" width="379" height="153" /></p>
<p>Besides enabling new and improved workflows for editors (and developers) PowerSlice can also be used for exposing custom content types. That is, instances of custom types implementing IContent which won't be displayed in the page tree or blocks gadget.</p>
<h2>Download and documentation</h2>
<p>The source code for PowerSlice, which is a number of C# classes, JavaScript files and HTML-templates used by the JavaScript components is <a title="PowerSlice source code on GitHub" href="https://github.com/joelabrahamsson/PowerSlice">located on GitHub</a>. The module is also packaged as a NuGet package available on <a title="EPiServer's NuGet feed" href="http://nuget.episerver.com">EPiServer's NuGet feed</a>.</p>
<p>Creating a slice is easy. In it's simplest form all we need to do is create a class with a single string property returning the slice's name. Meanwhile, should we want to we can customize the slice to apply filtering, specify the default sort option, add additional sort options, add ways to create content etc.</p>
<p>Documentation as well as a video introducing what PowerSlice is can be found <a title="PowerSlice documentation and video" href="/link/c307dee82d384e9cbfa436f08a8b949d.aspx?id=509&epslanguage=en">here</a>.</p>
<p><strong>Happy slicing!</strong></p>
2013-03-27T05:00:00.0000000ZBlog postLocalization in widgets used as EPiServer gadgets or property editors<p>Given a language resource file like this:</p>
<pre class="language-csharp"><code><?xml version="1.0" encoding="utf-8" ?><br /><languages><br /> <language name="English" id="en"><br /> <mystuff><br /> <substuff><br /> <key>Value</key><br /> </substuff><br /> </mystuff><br /> </language><br /></languages></code></pre>
<p>The node "mystuff" can be accessed in a JavaScript UI-component such as a gadget or custom editor using require and the i18n module, like this:</p>
<pre class="language-csharp"><code>define([<br /> "epi/i18n!epi/cms/nls/mystuff"<br />], function (<br /> resources<br />) {<br /> return declare("", [], {<br /> resources: resources,<br /> });<br />});</code></pre>
<p>The resources variable will be an object like this:</p>
<pre class="language-csharp"><code>{<br /> substuff: {<br /> key: "value"<br /> }<br />}</code></pre>
<p>To instead retrieve only the "substuff" element the required module can be modified to epi/i18n!epi/cms/nls/mystuff.substuff.</p>
<p>To output a localized resource like "key" above in a template the following can be used:</p>
<pre class="language-csharp"><code>${resources.substuff.key}<br /></code></pre>
2013-03-24T20:45:03.0000000ZBlog postSpecifying drag-n-drop support in custom EPiServer editor descriptor<p>Editor descriptors can be used to change how a property, or properties of a given type, is edited. One such example is described in my article about <a href="/link/0ce0d801c6594c9c9384409475d388bd.aspx?id=281&epslanguage=en">how to let editors populate content reference properties using dropdowns</a>.</p>
<p>When using an editor that doesn't support drag-n-drop the drag-n-drop functionality can be restored by specifying a drop target type in the editor descriptor. Example:</p>
<pre class="language-csharp"><code>public override void ModifyMetadata(<br /> ExtendedMetadata metadata, <br /> IEnumerable<System.Attribute> attributes)<br />{<br /> base.ModifyMetadata(metadata, attributes);<br /> metadata.AdditionalValues["DropTargetType"] = new[] { "epi.cms.pagereference" };<br />} <br /></code></pre>
<p>Similarly for files the drop target type can be set to "fileurl":</p>
<pre class="language-csharp"><code>metadata.AdditionalValues["DropTargetType"] = new [] { "fileurl" };</code></pre>
<p>To restrict the type of content that can be dropped to pages the editor descriptors EditorConfiguration property can be used:</p>
<pre class="language-csharp"><code>EditorConfiguration["typeIdentifiers"] = "epi.cms.page";</code></pre>
<p>If the editor descriptor is for a block type used as a property what property in the block to map the dropped item to can be specified using:</p>
<pre class="language-csharp"><code>metadata.AdditionalValues["DropTargetChildProperty"] = "LinkedPage";</code></pre>
2013-03-18T21:45:07.0000000ZBlog postList of EPiServer content interfaces and properties<table class="table" border="0">
<thead>
<tr>
<th> Interface</th> <th>Member<br /></th> <th>Type <br /></th>
</tr>
</thead>
<tbody>
<tr>
<td>IContentData</td>
<td>Property <br /></td>
<td>PropertyDataCollection</td>
</tr>
<tr>
<td>IInitializableContent</td>
<td>SetDefaultValues(ContentType)</td>
<td> </td>
</tr>
<tr>
<td>IModifiedTrackable</td>
<td>ResetModified()</td>
<td> </td>
</tr>
<tr>
<td>IModifiedTrackable</td>
<td>IsModified</td>
<td>bool <br /></td>
</tr>
<tr>
<td>IReadOnly <br /></td>
<td>CreateWritableClone() <br /></td>
<td>object</td>
</tr>
<tr>
<td>IReadOnly</td>
<td>MakeReadOnly()</td>
<td> </td>
</tr>
<tr>
<td>IReadOnly</td>
<td>IsReadOnly</td>
<td>bool <br /></td>
</tr>
<tr>
<td>IReadOnly<T> <br /></td>
<td>CreateWritableClone<T> <br /></td>
<td>T <br /></td>
</tr>
<tr>
<td>IContentSecurable</td>
<td>GetContentSecurityDescriptor() <br /></td>
<td>IContentSecurityDescriptor</td>
</tr>
<tr>
<td>ISecurable</td>
<td>GetSecurityDescriptor() <br /></td>
<td>ISecurityDescriptor <br /></td>
</tr>
<tr>
<td>IContent <br /></td>
<td>ContentGuid</td>
<td>Guid <br /></td>
</tr>
<tr>
<td>IContent</td>
<td>ContentLink</td>
<td>ContentReference <br /></td>
</tr>
<tr>
<td>IContent <br /></td>
<td>ContentTypeID</td>
<td>int <br /></td>
</tr>
<tr>
<td>IContent</td>
<td>IsDeleted</td>
<td>bool <br /></td>
</tr>
<tr>
<td>IContent</td>
<td>Name</td>
<td>string <br /></td>
</tr>
<tr>
<td>IContent</td>
<td>ParentLink</td>
<td>ContentReference <br /></td>
</tr>
<tr>
<td>ILocalizable</td>
<td>ExistingLanguages</td>
<td>IEnumerable<CultureInfo> <br /></td>
</tr>
<tr>
<td>ILocalizable</td>
<td>Language</td>
<td>CultureInfo <br /></td>
</tr>
<tr>
<td>ILocalizable</td>
<td>MasterLanguage <br /></td>
<td>CultureInfo <br /></td>
</tr>
<tr>
<td>IVersionable</td>
<td>IsPendingPublish</td>
<td>bool</td>
</tr>
<tr>
<td>IVersionable</td>
<td>StartPublish</td>
<td>DateTime?</td>
</tr>
<tr>
<td>IVersionable</td>
<td>Status</td>
<td>VersionStatus</td>
</tr>
<tr>
<td>IVersionable</td>
<td>StopPublish</td>
<td>DateTime?</td>
</tr>
<tr>
<td>IResourceable</td>
<td>ContentFolderID</td>
<td>long</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>Changed</td>
<td>DateTime</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>ChangedBy</td>
<td>string</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>Created</td>
<td>DateTime</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>CreatedBy</td>
<td>string</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>Deleted</td>
<td>DateTime?</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>DeletedBy</td>
<td>string</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>Saved</td>
<td>DateTime</td>
</tr>
<tr>
<td>IChangeTrackable</td>
<td>SetChangedOnPublish</td>
<td>bool</td>
</tr>
<tr>
<td>IRoutable</td>
<td>RouteSegment</td>
<td>string</td>
</tr>
<tr>
<td>ICategorizable</td>
<td>Category</td>
<td>CategoryList</td>
</tr>
<tr>
<td>IExportable</td>
<td>ShouldBeImplicitlyExported</td>
<td>bool</td>
</tr>
</tbody>
</table>
2013-03-18T21:05:11.0000000ZBlog postEPiServer and MVC – What is the view model?Perhaps the most discussed and debated question of all when it comes to EPiServer and ASP.NET MVC development is “What is the view model?” Here's my thoughts on the subject and the reasoning behind the path chosen in the Alloy templates.
<p>In <a href="/link/4e3e6d68067b4c288327d2716ee0af70.aspx">my article</a> about the MVC templates for EPiServer 7 I wrote</p>
<blockquote>"<span>Perhaps the most discussed question of all when it comes to EPiServer and MVC development is 'What is the model?' This is a multifaceted question, which could easily make this article very long. Hence, I will leave the background discussion for a later article or blog post"</span></blockquote>
<p>In this article I'll follow up on that with both the background reasoning for what types of models are passed to views from controllers in the MVC templates, as well as general thoughs about (view) models when working with EPiServer CMS and ASP.NET MVC.</p>
<h2>To use view models or not to use view models</h2>
<p>Should we use a separate view model or simply pass PageData/BlockData to the view? In general ASP.NET MVC development it’s a well established best practice, at least in larger projects, to use separate view models. There are four commonly used arguments for this approach:</p>
<ol>
<li>By creating a model to the needs of the view we can keep the view simple and free from complex logic.</li>
<li>By creating a view model we can create unit tests for the logic that takes domain models or other data as arguments and returns the data needed by the view.</li>
<li>By using separate view models we can change the domain models without having to change the view models and vice versa.</li>
<li>Model binding in ASP.NET MVC is vulnerable to mass assignment attacks and using a separate view model can prevent that.</li>
</ol>
<p>All of the above arguments are of course valid but also context specific.</p>
<p><strong>For instance, a page</strong> type is often already designed with the needs of the view in mind. We’re after all using a content management system in which the domain objects represent content intended to be displayed using templates.</p>
<p>That is, in many, but not all, scenarios a view, no matter if it’s MVC or Web Forms, simply renders properties from a PageData or BlockData object. In such cases there’s also no logic to test meaning that the second argument doesn’t make much sense in this context.</p>
<p><strong>Using view models</strong> to be able to change domain models without having to update views, or vice versa, is an attractive idea from an architectural standpoint. It does come at a steep price however, as it requires a lot of code for mapping CMS content objects to view models.</p>
<p>While that can be handled by mapping frameworks such as AutoMapper we’d still be forced to write more code whenever we want to add a new property to a content type that should be displayed in the view, as we’d then have to update the page or block type as well as the view model.</p>
<p>Also, designing for future changes which <em>may</em> happen is a case of Big Design Up Front. Often the code that hasn’t been written yet is most easy to change.</p>
<p><strong>Finally, while mass</strong> assignment is a very real threat when using ASP.NET MVC the model binding of CMS content is handled by EPiServer and EPiServer sites rarely have code in which non-trusted users are allowed to create or modify pages or blocks.</p>
<p>For these reasons the MVC template does allow them selves to use pages and blocks as view models when doing so offers the path of least resistance.</p>
<p>There is however another aspect of the underlying “What is the model” question – how to handle data needed by the overall layout rather than the specific view.</p>
<h2>Framework components</h2>
<p>Let’s review one of the pages from the Alloy site below.</p>
<p>It’s pretty obvious that the headline, text and form is unique for this page and therefor something that the rendering view should handle. But what about the header and footer?</p>
<p>There’s clearly quite a lot of data being displayed there but hardly any of it is related to the specific page. As for the breadcrumb and sub navigation those are both tied to the current pages location in the page tree but we can probably all agree that we wouldn’t like each page type specific controller or view to have to care about them.</p>
<p><img class="thumbnail-centered" src="/PageFiles/551/Alloy_model_cropped.png" alt="" width="700" height="720" /></p>
<p>While handling such “framework” components is straightforward using master pages and user controls in Web Forms there’s no clear-cut solution when using ASP.NET MVC. There are however a number of possible solutions which each can be grouped into one of two general patterns:</p>
<ol>
<li>Use a base class for view models with properties needed by the sites framework. Such properties can then be rendered in layout files, optionally using partial views. </li>
<li>Use child actions in layouts to render framework components such as navigations. Each child action, invoked by the Action or RenderAction HTML helpers, can then figure out the current page by looking at the request context.</li>
</ol>
<p><strong>Coming from Web</strong> Forms development where user controls is frequently used the second approach is attractive. By using child actions we can compose each page by using a number of stand alone components without any dependencies between them.</p>
<p>However, each child action will spawn a full MVC cycle, which is costly performance wise. Each such action would also have to figure out the current page context, which is rather tedious and possibly error prone. </p>
<p><strong>The first approach</strong> requires that all actions responsible for pages populate common properties of the view model. While that can be handled by using a base class for controllers with such actions we would end up with, possibly complex, inheritance hierarchies not only for view models but also for controllers.</p>
<h2>View models in the MVC templates</h2>
<p>Based on the reasoning about the necessity, or lack of such, for separate view models and the need for almost the exact same context in layouts and navigation components used in most views the solution in the MVC templates is to pass the current page object to the view along side data needed by framework components. This is done using a base class, or rather an interface to utilize generic variance.</p>
<h3>IPageViewModel</h3>
<p><img class="thumbnail pull-right" src="/PageFiles/551/IPageViewModel.png" alt="" width="178" height="112" />All non-partial views and layouts in the MVC templates uses a model of type IPageViewModel<T>. The type parameter T has to be a descendent of PageData.</p>
<p>The interface defines a CurrentPage property of type T as well a couple of properties intended to provide context to layouts and framework components such as navigation elements.</p>
<p>The idea behind this solution is that all views, and especially their layout files, can rely on some common characteristics of the view model.</p>
<h3>Populating context properties</h3>
<p>To free controllers from having to populate these common properties of the view model an action filter named PageViewContextActionFilter is registered globally at start up. This filter inspects the view model which is about to be passed to the view and, given that it’s of type IPageViewModel, sets the common properties required by the sites framework.</p>
<p>By using this approach each action for a page can use it’s own specific view model as long as it implements IPageViewModel without having to care about populating common properties.</p>
<p><strong>At the same time</strong> the logic for populating such common properties have been moved out from the sites controllers into a specific class responsible for framework components, which can be modified and tested without having to deal with controllers.</p>
<p>Should a specific controller or action want to influence the common properties of the view model it can do so by populating them on the view model as the filter then won’t modify them. Alternatively a controller can implement an interface named IModifyLayout that tells the filter to pass the Layout property of the view model to the controller after having populated it with default values.</p>
<p><img class="thumbnail-centered" src="/PageFiles/551/alloy_view_model_handling.png" alt="" width="573" height="707" /></p>
<p><strong>Using an action</strong> filter instead of populating all properties of the view model in controllers makes the code less obvious and harder to follow. Clearly a bad thing. However, considering the alternative we'd either have to duplicate a lot of code or rely on inhertitance which would have almost the same negative effects while also tying controllers to a possibly complex inheritance hiearchy.</p>
<p>By taking the action filter route each controller can go on it's merry way focusing only on the specifics needed for the page type it handles.</p>
<h3>Models for partial views</h3>
<p>Partial views doesn't follow the pattern described above. Instead they either use a completely custom view model or the current content object is passed directly to the view.</p>
<p>The reason for not using a similar approach as for non-partial views is that the partial views don't have layouts and typically don't need to know about a broader context.</p>
<h2>Conclusion</h2>
<p>While the approach used in the MVC templates isn’t the most obvious and takes a while to wrap one’s head around it makes it easy to create new controller, models and views. As such I find it allows rapid development while maintaining decent separation of concerns.</p>
<p><strong>When working with</strong> a view one has access to both view specific properties as well as a broader context. While this may seem like it's violating "best practices" I think it's good to keep in mind that best practices is dependent on context. And in the case of many EPiServer sites the context is that a page type very much is a view model in it self.</p>
<p>I've also used the same approach as in the MVC templates in a few other projects since and found it working well. Software design and development is always about <em>context</em> though. I can imagine sites where completely view-specific view models may makes sense. Similarly I can imagine sites where simply passing the current PageData object to the view would be an attractive solution.</p>
<p><strong>Therefor I personally</strong> think that we can use the view model approach used in the MVC templates in most projects as a start. As with many other things we should however always look at the specific context of the project and think about how we can deliver most customer value and flexibility for evolving customer needs.</p>
2013-03-17T01:22:14.0000000ZBlog post