Client Resources

Introduction
Requirements for Page Templates
Executing Client Resource Registers Before Rendering the Page
Rendering Resources for the Header and Footer Default Areas
Client Resource Register for CMS Pages

Introduction

This document describes how to manage client resources in EPiServer CMS. It is possible to require certain client resources to be rendered on the page in a specific area. Usually this approach is used by modules, add-ons and various plug-ins when client resources cannot be added directly by modifying the templates. Please refer to Framework SDK for more information.

Consider the following requirements to support this functionality.

Requirements for Page Templates

Client Resource Registers Must be Executed Before Rendering the Page

Client resource registers are executed automatically if template page/controller inherits one of the following base classes for Web Forms and MVC templates:

TemplatePage<T>
TemplatePage
EditPage
SamplePage
PageBase<T>
PageBase
PageController<T>

Make sure that you call base.OnPreRenderComplete(e) method if it is overridden in your page class.

You have to call client resource registers in your code if your template does not inherit these base classes.

Web Forms Example

Add following code to the method that is raised on OnPreRenderComplete page event the template does not inherit page base classes:

protected override void OnPreRenderComplete(EventArgs e)
{
    base.OnPreRenderComplete(e);

    // Register required client resources for page
    Locate.Advanced.GetInstance<IClientResourceService>().RegisterRequiredResources(new HttpContextWrapper(Context));
}

MVC Example

Decorate your custom page controller with EPiServer.Framework.Web.Mvc.RequireClientResourcesAttribute if this controller does not inherit PageController<T>:

[RequireClientResources]
public class CustomPageController
{
    ...
}

Page Templates Must Render Required Client Resources for the Header and Footer Default Areas

Required client resources for Header area should be rendered inside <head> tag. Required resources for Footer area should be rendered in the bottom of the page, before closing </body> tag. Usually it can be in master pages.

Web Forms Example

XML

<%@ Master Language="C#" AutoEventWireup="False" CodeBehind="MasterPage.master.cs"
    Inherits="Sample.MasterPage" %>
<html>
<head runat="server">
    ...
    <EPiServer:RequiredClientResources RenderingArea="Header" ID="RequiredResourcesHeader" runat="server" />
</head>
<body runat="server" id="Body">
    ...
    <EPiServer:RequiredClientResources RenderingArea="Footer" ID="RequiredResourcesFooter" runat="server" />
</body>
</html>

MVC Example

<%@ Master Language="C#" Inherits="System.Web.Mvc.ViewMasterPage" %>
<%@ Import Namespace="EPiServer.Framework.Web" %>
<%@ Import Namespace="EPiServer.Framework.Web.Mvc.Html" %>
<html>
<head runat="server">
    ...
    <%= Html.RequiredClientResources(RenderingTags.Header) %>
</head>
<body>
    ...
    <%= Html.RequiredClientResources(RenderingTags.Footer)%>
</body>
</html>

The developer of templates can define any other rendering areas and render resources for these areas in templates.

For example, you can define areas like BeforeMainBody and AfterMainBody and render resources for these areas before your main content and after your main content to provide extension points where some client resources can be injected on the page. Standard Twitter button injection can be required for AfterMainBody area to add Twitter button just after the main page text.

Client Resource Register for CMS Pages

EPiServer CMS provides base class EPiServer.Web.PageClientResourceRegister that you can inherit when implementing client resource register for CMS pages. You should implement abstract protected method that takes PageData of the current page as additional argument. This method will not be called if PageData is null for the current context.

[ClientResourceRegister]
public class ClientResourceRegister : PageClientResourceRegister
{
    protected override void RegisterResources(IRequiredClientResourceList requiredResources, HttpContextBase context, PageData pageData)
    {
        if (pageData.PageTypeName.Equals("XFormPage", StringComparison.OrdinalIgnoreCase))
        {
            requiredResources.Require("epi.samples.Module.FormHandler").AtFooter();
        }
    }
}

Client Resource Management

Table of Contents

Introduction

Requirements for Page Templates

Client Resource Registers Must be Executed Before Rendering the Page

Web Forms Example

MVC Example

Page Templates Must Render Required Client Resources for the Header and Footer Default Areas

Web Forms Example

MVC Example

Client Resource Register for CMS Pages