Extensions and helpers library for EPiServer

Frederik Vig 14.02.2014 04.17.00

The library is easily installed through EPiServer's NuGet feed and enchances your development flow by filling the gap between the methods and helpers provided by EPiServer, and those that we've found to be missing in our EPiServer projects.

The methods range from helpers that make it easy to create navigations with full control over the markup, to extensions for the UrlHelper to easily work with EPiServer URLs in your Razor view.

You can find all the source code, API reference and some examples on the projects GitHub page: https://github.com/Geta/EPi.Extensions/

When creating this library (which is used on several production sites, including this one), we have attentionally not bloated it by adding many methods and helpers, but tried to keep everything as clean as possible and done thorough reviews before adding new functionality to the API. The reason for this is that in our experience there are quite a lot of existing helper/util/extension libraries out there that try to do too much and end up just getting in the way and over complicating things. We've also tried to make it very enjoyable and easy to use. 

Some examples below.

Filters

You can use FilterForDisplay to easily filter out pages that the user shouldn't see. Here is an example of how to filter child pages of start page (we have of course a generic overload of the GetChildren method as well).

var childPages = ContentReference.StartPage.GetChildren().FilterForDisplay();

MenuList extension for HtmlHelper

MenuList extension method helps to build menus. Extension method requires two parameters - ContentReference of the menu root page and @helper which generates menu item. MenuList uses FilterForDisplay extension method to filter out pages that the user doesn't have access to, are not published, are not visible in menu and that don't have a template.

MenuList has three optional parameters:

  • includeRoot - flag which indicates if root page should be included in menu (default is false)
  • requireVisibleInMenu - flag which indicates if pages should be included only when their property VisibleInMenu is true (default is true)
  • requirePageTemplate - flag which indicates if pages should have templates<

Below is an example how menu can be created for pages under start page.

@helper MenuItemTemplate(MenuItem item)
{
    <li class="@(item.Selected ? "active" : null)">
        @Html.PageLink(item.Page)
    </li>
}

<nav id="main-nav" class="navigation" role="navigation">
    <ul class="nav">
        @Html.MenuList(ContentReference.StartPage, MenuItemTemplate)
    </ul>
</nav>

XFormHelper

Example of a custom DisplayTemplate for XForm using the XFormHelper to clean up the markup.

@using EPiServer.HtmlParsing
@using EPiServer.Web.Mvc.Html
@using Geta.EPi.Cms.Helpers
@model EPiServer.XForms.XForm
@if (ViewData["XFormActionResult"] is EPiServer.Web.Mvc.XForms.XFormSuccessActionResult)
{
    <strong>Form posted.</strong>
}
else
{
    using (Html.BeginXForm(Model, htmlAttributes: new { @class = "form xform" }))
    {
        if (Model != null)
        {
            foreach (HtmlFragment fragment in (IEnumerable<HtmlFragment>)ViewData["XFormFragments"] ?? Model.CreateHtmlFragments())
            {
                @Html.Fragment(XFormHelper.CleanupXFormHtmlMarkup(fragment))
            }
        }
    }
}

The markup will look something like this:

<form action="" class="form xform" method="post">
    <div id="id_matrix" class="xform-table">
        <div class="xform-body">
            <div class="xform-row">
                <div class="xform-col">
                    <label for="Input_54330581">
                        Navn
                    </label>
                    <input id="Input_54330581" name="Navn" size="70" type="text" value="" />
                </div>
            </div><div class="xform-row">
                <div class="xform-col">
                    <label for="Input_54330581">
                        Epost
                    </label>
                    <input id="Input_54330581" name="Epost" size="70" type="text" value="" />

                </div>
            </div>
        </div>
    </div>
</form>

QueryStringBuilder

Here we have an example of using QueryStringBuilder to build a filter URL. This can be useful for lists that have filter functionality or sort functionality. To instantiate QueryStringBuilder UrlHelper extensions are used.

<a href="@Url.QueryBuilder(Request.RawUrl).Toggle("sort", "alphabet")">A-Å</a>

Output when URL is: /list

<a href="/list?sort=alphabet">A-Å</a>

Output when URL is: /list?sort=alphabet

<a href="/list">A-Å</a>

There are many other methods and helpers - for a complete overview either take a look at the code or check out the API reference.

We appreciate any feedback - for questions, bugs, feature requests, please use the projects issue list.