Client Resources

Table of Contents

• Introduction
• Client Resource Providers
• Default Client Resource Provider for Modules
• Implementing the Custom Client Resource Provider
• Requiring Client Resources
• Implementing Client Resource Register
• Client Resource Register for CMS Pages
• Client Resource Settings
• Rendering Areas
• Filter Resources by Type
• Requesting Client Resources Using ClientResources Class
• Rendering the required client resources
• Web Forms control
• MVC helper

Introduction

EPiServer Framework provides the number of classes and interfaces that can be used to define available client resources, to require client resource depending on the current context and to render client resources on the page. This information will be interesting mostly for module and add-on developers who need to render or inject client resources on the pages without modifying the page templates.

EPiServer.Framework.Web.Resources.ClientResource class defines client resource that can be used on site pages. Please see class reference for more information.

Client Resource Providers

Client resource provider returns definitions of available client resources that can be requested by name and added on the page.

Default Client Resource Provider for Modules

There is client resource provider that finds and returns all client resources that are defined in manifests of public and protected modules and add-ons. So there is no need to implement custom client resource provider if your resources are defined in module.config files.

The following example shows client resource definitions in a module manifest:

CopyXML

<?xml version="1.0" encoding="utf-8" ?>
<module>
  <clientResources>
    <add name="epi.samples.Module.Styles" path="ClientResources/Styles.css" resourceType="Style"/>
  </clientResources> 
</module>

See Configuring module.config document for detailed information.

Implementing the Custom Client Resource Provider

The provider class must implement EPiServer.Framework.Web.Resources.IClientResourceProvider interface. Also it should be decorated with EPiServer.Framework.Web.Resources.ClientResourceProviderAttribute to register this implementation automatically.

Example:

CopyC#

[ClientResourceProvider]
public class ClientResourceProvider : IClientResourceProvider
{
    public IEnumerable<ClientResource> GetClientResources()
    {
        return new[] 
        {
            new ClientResource
            {
                Name = "epi.samples.Module.FormHandler",
                Path = Paths.ToClientResource("SampleModuleName", "ClientResources/FormHandler.js"),
                ResourceType = ClientResourceType.Script,
                Dependencies = new List<string> { "OtherResourceName" }
            }
        };
    }
}

This sample provider returns one script resource which depends on another client resource. Note that the full path to the script file in module directory is resolved by module name.

Requiring Client Resources

There is a couple of ways how developer can require certain client resource to be rendered on the page without accessing and changing page templates. Often it is required when developing some kind of add-on or plug-in.

Implementing Client Resource Register

One way is implementing EPiServer.Framework.Web.Resources.IClientResourceRegister interface. Client resource register requires client resources for specific rendering area and depending on the current context.

Client resource registers must be executed before page rendering. Registers are called automatically if templates inherit base classes for page and controller that are defined in EPiServer CMS (EPiServer.PageBase and EPiServer.Web.Mvc.PageController). Also there is base register class that can be inherited when requesting resources for CMS page templates. See CMS SDK documentation for more information.

Register implementation class should be decorated with EPiServer.Framework.Web.Resources.ClientResourceRegisterAttribute to make it discoverable automatically.

CopyC#

[ClientResourceRegister]
public class ClientResourceRegister : IClientResourceRegister
{
    public void RegisterResources(IRequiredClientResourceList requiredResources, HttpContextBase context)
    {
        requiredResources.Require("epi.samples.Module.Styles");
        requiredResources.Require("epi.samples.Module.FormHandler").AtFooter();
        requiredResources.RequireScript("http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.8.0.min.js").AtFooter();
    }
}

RegisterResources method takes 2 arguments: the list of required client resources and current HTTP context.

Information from current HTTP context can be used to decide which resources are required for this context.

The list of required client resources provides the number of Require methods to register required client resources.

Client resource can be required by name if this resource is known and it was defined in any module manifest or it is returned by custom resource provider. Note that sample register requires 2 resources by name; these resources were defined in sample module manifest and sample client resource provider.

Also it is possible to require JavaScript, CSS or HTML resource by specifying its URL or inline content that should be injected on the page. Please see EPiServer.Framework.Web.Resources.IRequiredClientResourceList members for more information.

Client resource register for CMS pages

EPiServer CMS provides base class EPiServer.Web.Resources.PageClientResourceRegister that you can inherit when implementing client resource register for CMS pages. See “Managing Client Resources when working with EPiServer CMS” section in EPiServer CMS SDK documentation for more details.

Client resource settings

Each Require method returns settings for required client resource that can be used to specify area where resource should be rendered and filter resources by type. See ClientResourceSettings reference for more information.

Rendering Areas

Rendering area is a string that identifies the place in templates where resource should be rendered.

There are 2 default rendering areas that are required for all templates:

• Header: for resources that should be added inside the <head> tag. Styles preferably should be required for this area.
• Footer: for resources that should be added in the bottom of the page, before closing </body> tag. Scripts preferably should be put in this area.

Rendering area can be set for resource by using AtArea("areaName"), AtHeader(), AtFooter() methods of client resource settings. Header is default option if rendering area is not specified explicitly.

Sample register requires style resource without setting the area, so this style is going to be rendered in Header area. Two other script resources are required for Footer area explicitly.

Filter Resources by Type

Sometimes several resources of different types are grouped and have the same name. It is possible to request only resources of certain type when requesting resources by name.

For example, all jQuery UI scripts and CSS files can be defined using the one name jquery.ui. Then jQuery UI style resource can be required in Header area and scripts can be required in Footer:

CopyC#

requiredResources.Require("jquery.ui").StylesOnly().AtHeader();
requiredResources.Require("jquery.ui").ScriptsOnly().AtFooter();

Requesting Client Resources Using ClientResources Class

Client resource register implementation is required mostly when developing module and add-on that needs some injections.

It is also possible to require client resource by using EPiServer.Framework.Web.Resources.ClientResources static class. It provides Require methods with the same signatures as methods in IRequiredClientResourceList interface.

This is more handy way if you need to request client resources in code behind or directly in templates. Make sure that resource is requested before rendering of required resources for corresponding area.

Rendering the Required Client Resources

Required client resources can be rendered for corresponding area by using web control or HTML helper.

Web Forms Control

Use EPiServer.Framework.Web.WebControls.RequiredClientResources control to render required resources in Web Forms templates. The following code renders client resources required for Header area:

CopyXML

<head runat="server">
    ...
    <EPiServer:RequiredClientResources RenderingArea="Header" ID="RequiredResourcesHeader" runat="server" />
</head>

MVC Helper

Use HTML helper extension to render required resources in MVC templates. The following code renders client resources required for the Footer area:

CopyXML

...
    <%= Html.RequiredClientResources(RenderingTags.Footer)%>
</body>
</html>