

Resources (OrchardCore.Resources)

Purpose

The Resources module provides commonly used resources like JavaScript libraries and CSS files. It also enables the Resource Manager so any module can describe what resources are necessary on any page or component. When the full page is rendered all the required resources are computed and custom <script> and <link> tags are rendered accordingly. You can also register custom <meta> tags.

Resource Settings

Resource Settings are configured through the site admin.

UseCdn

Enabling UseCdn will configure the IResourceManager to provide any scripts or styles, such as jQuery, from the configured CDN.

ResourceDebugMode

When enabled will serve scripts or styles, that have a CDN configured, or a debug-src, from the local server in non minified format.
This will also disabled the CdnBaseUrl prepending.

CdnBaseUrl

When supplied this will prepend local resources served via the IResourceManager or Tag Helpers with the absolute url provided. This will be disabled in ResourceDebugMode

Named Resources

Named resources are well-known scripts and stylesheets that are described in a module.
They have a name, a type (script, stylesheet) and optionally a version.
The OrchardCore.Resources modules provides some commonly used ones:

Name	Type	Versions	Dependencies
jQuery	Script	3.4.1	-
jQuery.slim	Script	3.4.1	-
jQuery-ui	Script	1.12.1	jQuery
jQuery-ui-i18n	Script	1.7.2	jQuery-ui
popper	Script	1.14.7	-
bootstrap	Script	3.4.0, 4.3.1	jQuery, Popper
bootstrap	Style	3.4.0, 4.3.1	-
codemirror	Script	5.48.4	-
codemirror	Style	5.48.4	-
font-awesome	Style	4.7.0, 5.10.2	-
font-awesome	Script	5.10.2	-
font-awesome-v4-shims	Script	5.10.2	-

Usage

There are two ways to invoke a resource: either by using the IResourceManager API or a Tag Helper.
The API is necessary if you need to inject a resource from code. However it is recommended to use a Tag Helper when inside a view.

Using the API

From your module, add a reference to the OrchardCore.Resources.Abstractions project.
From the class you want to use the API in, inject the OrchardCore.ResourceManagement.IResourceManager interface.

Register a named resource

var settings = resourceManager.RegisterResource("script", "bootstrap")

The result of this call is an object of type RequireSettings that is used to pass more parameters to the required resource.

Place the resource at the beginning of the HTML document

settings.AtHead();

Place the resource at the end of the HTML document

settings.AtFoot();

Set the version to use

settings.UseVersion("3.3");

This will use the latest available version between 3.3 and 3.4. If the version is not available an exception is thrown.

Append a version

settings.UseAppendVersion(true);

This will append a version string that is calculated at runtime as an SHA256 hash of the file, the calculation cached, and appended to the url as part of the query string, e.g. my-script.js?v=eER9OO6zWGKaIq1RlNjImsrWN9y2oTgQKg2TrJnDUWk

Register custom script

At the beginning of the HTML document:

resourceManager.RegisterHeadScript(new HtmlString("<script>alert('Hello')</script>"));

At the end of the HTML document:

resourceManager.RegisterFootScript(new HtmlString("<script>alert('Hello')</script>"));

Add custom meta tag

resourceManager.RegisterMeta(new MetaEntry { Content = "Orchard", Name = "generator" });

You can also add more content to an existing tag like this:

resourceManager.AppendMeta(new MetaEntry { Name = "keywords", Content = "orchard" }, ",");

Using the Tag Helpers

From your module, in the _ViewImports.cshtml or your view, add @addTagHelper *, OrchardCore.ResourceManagement.

Register a named script

This example registers the script named bootstrap and all its dependencies (jquery).

Liquid

{% script name:"bootstrap" %}

Razor

<script asp-name="bootstrap"></script>

And for a stylesheet:

Razor

<style asp-name="bootstrap"></style>

Force the CDN

You can force a resource to be used from its CDN. By default the behavior is defined by configuration.

Liquid

{% script name:"bootstrap", use_cdn:"true" %}

Razor

<script asp-name="bootstrap" use-cdn="true"></script>

Use specific version

This example will use the latest available version with a Major version of 3, like 3.4.0. If the version is not specified the latest one is always used.

Liquid

{% script name:"bootstrap", version:"4" %}

Razor

<script asp-name="bootstrap" version="3"></script>

Append a Version Hash

You can append a version hash that will be calculated, and calculation cached, and appended in the format ?v=eER9OO6zWGKaIq1RlNjImsrWN9y2oTgQKg2TrJnDUWk

Liquid

{% script name:"bootstrap", append_version:"true" %}

Razor

<script asp-name="bootstrap" asp-append-version="true"></script>

Specify location

By default all scripts are rendered in the footer. You can override it like this:

Liquid

{% script name:"bootstrap", at:"Foot" %}

Razor

<script asp-name="bootstrap" at="Foot"></script>

Styles, however, are always injected in the header section of the HTML document.

Inline definition

You can declare a new resource directly from a view, and it will be injected only once even if the view is called multiple time.

Liquid

{% script src:"/TheTheme/js/foo.min.js", debug_src:"/TheTheme/js/foo.js" %}

Razor

<script asp-name="foo" asp-src="~/TheTheme/js/foo.min.js?v=1.0" debug-src="~/TheTheme/js/foo.js?v=1.0" depends-on="baz:1.0" version="1.0"></script>

In this example we also define a dependency on the script named baz with the version 1.0. If the version was not set the one with the highest number will be used.

You can also do the same for a stylesheet:

Liquid

{% style src:"/TheTheme/css/bar.min.css", debug_src:"/TheTheme/css/bar.css" %}

Razor

<style asp-src="~/TheTheme/css/bar.min.css" debug-src="~/TheTheme/css/bar.css"></style>

Custom scripts

The following example demonstrates how to inject a custom script in the footer section.

Liquid

{% scriptblock at: "Foot" %}
    document.write('<!-- some script -->');
{% endscriptblock %}

Razor

<script at="Foot">
    document.write('<!-- some script -->');
</script>

Meta tags

Liquid

{% meta name:"description", content:"This is a website" %}

Razor

<meta asp-name="description" content="This is a website" />

These properties are available:

Name	Description
name (asp-name in Razor)	The name attribute of the tag
content	The content attribute of the tag
httpequiv	The http-equiv attribute of the tag
charset	The charset attribute of the tag
separator	The separator to use when multiple tags are defined for the same name