Client resources

Client resources let you inject CSS, JavaScript, and HTML into rendered pages without modifying templates. The EPiServer.Framework.Web.Resources.ClientResource class and its companion interfaces provide a declarative pipeline for defining, requiring, and rendering these resources.

Define client resources in module.config

The client resource provider finds and returns client resource definitions from the manifests of public and protected modules and add-ons. Request a definition by name and add it to the page. A custom client resource provider is unnecessary if the resources are defined 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>

Implement the custom client resource provider

The client provider class must implement the EPiServer.Framework.Web.Resources.IClientResourceProvider interface. Decorate the class with EPiServer.Framework.Web.Resources.ClientResourceProviderAttribute to register the 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 the 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"
          }
      }
    };
  }
}

Require client resources

Require client resources to render on the page without modifying page templates. This is especially useful when developing an add-on or plug-in.

Implement client resource register

Optimizely Content Management System (CMS) provides the EPiServer.Framework.Web.Resources.IClientResourceRegistrator interface. Implement this interface to register client resources for specific rendering areas based on the current context.

Execute client resource registers before rendering a page. The registration runs automatically when templates inherit CMS base classes for Razor pages or controllers (EPiServer.Web.Mvc.RazorPageModel and EPiServer.Web.Mvc.ContentController). When requesting resources for CMS page templates, the resources can inherit the base register class. Decorate the register implementation class with EPiServer.Framework.Web.Resources.ClientResourceRegistratorAttribute for automatic discovery.

The following code example demonstrates how RegisterResources works:

• RegisterResources method takes one argument: the list of required client resources.
• Information from the current HTTP context can decide which resources are required for this context. An implementation that needs access to the current HTTP context should take a dependency on Microsoft.AspNetCore.Http.IHttpContextAccessor.
• 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 it is known and defined in any module manifest, or a custom resource provider returns it. The example register requires two resources by name, defined in the sample module manifest and sample client resource provider.

[ClientResourceRegistrator]
public class ClientResourceRegister: IClientResourceRegistrator {
  public void RegisterResources(IRequiredClientResourceList requiredResources) {
    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.

Require JavaScript, CSS, or HTML resources by specifying the URL or inline content to inject on the page.

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

Client resource settings

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

Render area

A render area is a named string that identifies the place in a template where a resource renders.

Optimizely requires two default rendering areas for all templates:

• Header – Add resources inside the <head> tag. Require styles for this area.
• Footer – Add resources at the bottom of the page, before the closing </body> tag. Place scripts in this area.

Set the rendering area for a resource with the AtArea(areaName), AtHeader(), or AtFooter() methods on client resource settings.

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

Filter resources by type

Sometimes several resources of different types share the same name. Request only resources of a certain type by name. For example, 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();

Request client resources using ClientResources class

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

The EPiServer.Framework.Web.Resources.ClientResources static class provides Require methods with the same signatures as IRequiredClientResourceList. Use this class to require client resources directly in code-behind or templates. Request resources before rendering the required resources for the corresponding area.

Render the required client resources

Use the tag 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 the Header area inside <head> tag. Render resources for Footer area at the bottom of the page, before closing </body> tag.

MVC Helper

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

<html>
  ...
  <head>
    ...
    <required-client-resources area="Header" />
  </head>
  <body>
    ...
    <required-client-resources area="Footer" />
  </body>
</html>