Client resources

This topic explains how to define and configure available client resources. You can do this through the EPiServer.Framework.Web.Resources.ClientResource class and interfaces, to render or inject client resources into content without modifying the templates. 

Defining client resource definitions in module.config

The client resource provider finds and returns definitions of client resources, which are defined in manifests of public and protected modules and add-ons. You can request the definition by name and add it to the page. You do not need a custom client resource provider if you define the resources in module.config. The following example shows client resource definitions in a module manifest:

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

 Implementing the custom client resource provider

The client provider class must implement the EPiServer.Framework.Web.Resources.IClientResourceProvider interface and it should be decorated with EPiServer.Framework.Web.Resources.ClientResourceProviderAttribute to register this implementation automatically. In the following example, the sample client resource provider returns one script resource that depends on another client resource provider. The provider resolves the full path to the script file in module directory by module name.

[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" }
            }
        };
    }
}

Requiring client resources

You can require client resources (often when developing an add-on or plug-in) to render on the page without accessing and changing page templates.

Implementing client resource register

Episerver CMS provides base class EPiServer.Web.Resources.PageClientResourceRegister that you can inherit when implementing client resource register for CMS pages. The EPiServer.Framework.Web.Resources.IClientResourceRegister interface requires client resources for specific rendering area and depends on the current context.

You must execute client resource registers before rendering a page. The code calls registers automatically, if templates inherit base classes for page and controller that are defined in Episerver CMS (EPiServer.PageBase and EPiServer.Web.Mvc.PageController). Also, when you request resources for CMS page templates, the resources can inherit the base register class. You should decorate the register implementation class with EPiServer.Framework.Web.Resources.ClientResourceRegisterAttribute to make it discoverable automatically.

In the following example, 

• RegisterResources method takes two arguments: the list of required client resources and current HTTP context.
• Information from current HTTP context can 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.
• You can require a client resource by name if the resource is known and it was defined in any module manifest, or it is returned by custom resource provider. The example register requires two resources by name; these resources were defined in sample module manifest and sample client resource provider.

[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();
    }
}

Note: The third resource was not defined in module.config or provider and this resource is required using its URL in sample register implementation.

You can require JavaScript, CSS, or HTML resource by specifying its URL or inline content that you should inject on the page.

See also: EPiServer.Framework.Web.Resources.IRequiredClientResourceList members.

Client resource settings

Each Require method returns settings for required client resource to specify an area where you render a resource and filter resources by type.

Rendering area

This is a string that identifies the place in templates where you render a resource.

Episerver requires two default rendering areas for all templates:

• Header: for resources that you should add inside the <head> tag. You should require styles for this area.
• Footer: for resources that you should add in the bottom of the page, before closing </body> tag. You should put scripts in this area.

You can set rendering area for resource by using AtArea(areaName), AtHeader(), AtFooter() methods of client resource settings.

If you do not explicitly specify rendering area, the Header is the default option. Sample register requires a style resource without setting the area, so this style is going to be rendered in Header area. Footer area explicitly requires two other script resources.

Filter Resources by Type

Sometimes several resources of different types are grouped and have the same name. You can request only resources of certain type when you request resources by name. For example, you can define jQuery UI scripts and CSS files using the one name jquery.ui. Then require jQuery UI style resource in the Header area and require scripts in the Footer:

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

Requesting client resources using ClientResources class

Client resource register requires implementation typically when you develop a module and add-on that needs injections.

You can require client resource by using EPiServer.Framework.Web.Resources.ClientResources static class, which provides Require methods with the same signatures as methods in IRequiredClientResourceList interface, if you need to request client resources in code behind or directly in templates. Request resource before you render required resources for corresponding area.

Rendering the required client resources

Use web control or HTML helper to render required client resources for a corresponding area. A template must render required client resources at least for two default areas. Render resources for Header area inside <head> tag. Render resources for Footer area in the bottom of the page, before closing </body> tag.

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:

<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:

<html>
    ...
    <%= Html.RequiredClientResources(RenderingArea.Footerbody>
</html>