<commit_before># 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 Locations

`Resources` will be served via the `StaticFileMiddleware` from either a module or themes `wwwroot` folder.
When defining a resource the naming convention is `~/ThemeName/scripts/path-to-file.js` or `~/Module.Name/styles/path-to-file.css`

The tilde (~) is a convention used to indicate a relative path, for example a tenant base path.
All script or stylesheet resources should be prefixed with the `~` character.

## Resource Settings

Resource Settings are configured through the site admin.

### AppendVersion

Enabling `AppendVersion` or Resources cache busting will automatically append a version hash to all local scripts and style sheets.
This is turned on by default.

### 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 or theme.  
They have a name, a type (script, stylesheet) and optionally a version.  
The `OrchardCore.Resources` module provides some commonly used ones:

| Name                  | Type   | Versions      | Dependencies   |
| --------------------- | ------ | ------------- | -------------- |
| jQuery                | Script | 3.6.0         | -              |
| jQuery.slim           | Script | 3.6.0         | -              |
| jQuery-ui             | Script | 1.12.1        | jQuery         |
| jQuery-ui-i18n        | Script | 1.7.2         | jQuery-ui      |
| jquery.easing         | Script | 1.4.1         | -              |
| jquery-resizable-dom  | Script | 0.35.0        | -              |
| js-cookie             | Script | 2.2.1         | jQuery         |
| popper                | Script | 1.16.1        | -              |
| popperjs              | Script | 2.9.3         | -              |
| bootstrap             | Script | 4.6.0         | popper         |
| bootstrap             | Script | 5.1.0         | popperjs       |
| bootstrap             | Style  | 4.6.0, 5.1.0  | -              |
| bootstrap-select      | Script | 1.13.18       | -              |
| bootstrap-select      | Style  | 1.13.18       | -              |
| bootstrap-slider      | Script | 11.0.2        | -              |
| bootstrap-slider      | Style  | 11.0.2        | -              |
| codemirror            | Script | 5.62.2        | -              |
| codemirror            | Style  | 5.62.2        | -              |
| font-awesome          | Style  | 5.15.4        | -              |
| font-awesome          | Script | 5.15.4        | -              |
| font-awesome-v4-shims | Script | 5.15.4        | -              |
| Sortable              | Script | 1.10.2        | -              |
| trumbowyg             | Script | 2.25.1        | -              |
| vue-multiselect       | Script | 2.1.6         | -              |
| vuedraggable          | Script | 2.24.3        | Sortable       |
| monaco-loader         | Script | 0.26.1        | -              |
| monaco                | Script | 0.26.1        | monaco-loader  |

### Registering a Resource Manifest

Named resources are registered by configuring the `ResourceManagementOptions` options.

This example is provided from `TheBlogTheme` to demonstrate.

```csharp
public class ResourceManagementOptionsConfiguration : IConfigureOptions<ResourceManagementOptions>
{
    private static ResourceManifest _manifest;

    static ResourceManagementOptionsConfiguration()
    {
        _manifest = new ResourceManifest();

        _manifest
            .DefineScript("TheBlogTheme-vendor-jQuery")
            .SetUrl("~/TheBlogTheme/vendor/jquery/jquery.min.js", "~/TheBlogTheme/vendor/jquery/jquery.js")
            .SetCdn("https://code.jquery.com/jquery-3.4.1.min.js", "https://code.jquery.com/jquery-3.4.1.js")
            .SetCdnIntegrity("<KEY>", "<KEY>")
            .SetVersion("3.4.1");
    }

    public void Configure(ResourceManagementOptions options)
    {
        options.ResourceManifests.Add(_manifest);
    }
}

```

In this example we define a script with the unique name `TheBlogTheme-vendor-jQuery`. 
We use a name that is unique to `TheBlogTheme` to prevent collisions when multiple themes are active. 

We set a url for the minified version, and the unminified version, which will be used in `ResourceDebugMode`.
For the same reason we define two CDN Url's, which will be preferred over the local urls if the `UseCdn` setting in the site admin is set. 
We set the Cdn Integrity Hashes and the version to `3.4.1`

This script will then be available for the tag helper or API to register by name. 

!!! note "Registration"
    Make sure to register this `IConfigureOptions<ResourceManagementOptions>` in the `Startup` or your theme or module.
    `serviceCollection.AddTransient<IConfigureOptions<ResourceManagementOptions>, ResourceManagementOptionsConfiguration>();`

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

```csharp
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

```csharp
settings.AtHead();
```

##### Place the resource at the end of the HTML document
<commit_msg>Document dependency version selection in ResourceManagementOptionsConfiguration class (#10128)<commit_after># 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 Locations

`Resources` will be served via the `StaticFileMiddleware` from either a module or themes `wwwroot` folder.
When defining a resource the naming convention is `~/ThemeName/scripts/path-to-file.js` or `~/Module.Name/styles/path-to-file.css`

The tilde (~) is a convention used to indicate a relative path, for example a tenant base path.
All script or stylesheet resources should be prefixed with the `~` character.

## Resource Settings

Resource Settings are configured through the site admin.

### AppendVersion

Enabling `AppendVersion` or Resources cache busting will automatically append a version hash to all local scripts and style sheets.
This is turned on by default.

### 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 or theme.  
They have a name, a type (script, stylesheet) and optionally a version.  
The `OrchardCore.Resources` module provides some commonly used ones:

| Name                  | Type   | Versions      | Dependencies   |
| --------------------- | ------ | ------------- | -------------- |
| jQuery                | Script | 3.6.0         | -              |
| jQuery.slim           | Script | 3.6.0         | -              |
| jQuery-ui             | Script | 1.12.1        | jQuery         |
| jQuery-ui-i18n        | Script | 1.7.2         | jQuery-ui      |
| jquery.easing         | Script | 1.4.1         | -              |
| jquery-resizable-dom  | Script | 0.35.0        | -              |
| js-cookie             | Script | 2.2.1         | jQuery         |
| popper                | Script | 1.16.1        | -              |
| popperjs              | Script | 2.9.3         | -              |
| bootstrap             | Script | 4.6.0         | popper         |
| bootstrap             | Script | 5.1.0         | popperjs       |
| bootstrap             | Style  | 4.6.0, 5.1.0  | -              |
| bootstrap-select      | Script | 1.13.18       | -              |
| bootstrap-select      | Style  | 1.13.18       | -              |
| bootstrap-slider      | Script | 11.0.2        | -              |
| bootstrap-slider      | Style  | 11.0.2        | -              |
| codemirror            | Script | 5.62.2        | -              |
| codemirror            | Style  | 5.62.2        | -              |
| font-awesome          | Style  | 5.15.4        | -              |
| font-awesome          | Script | 5.15.4        | -              |
| font-awesome-v4-shims | Script | 5.15.4        | -              |
| Sortable              | Script | 1.10.2        | -              |
| trumbowyg             | Script | 2.25.1        | -              |
| vue-multiselect       | Script | 2.1.6         | -              |
| vuedraggable          | Script | 2.24.3        | Sortable       |
| monaco-loader         | Script | 0.26.1        | -              |
| monaco                | Script | 0.26.1        | monaco-loader  |

### Registering a Resource Manifest

Named resources are registered by configuring the `ResourceManagementOptions` options.

This example is provided from `TheBlogTheme` to demonstrate.

```csharp
public class ResourceManagementOptionsConfiguration : IConfigureOptions<ResourceManagementOptions>
{
    private static ResourceManifest _manifest;

    static ResourceManagementOptionsConfiguration()
    {
        _manifest = new ResourceManifest();

        _manifest
            .DefineScript("TheBlogTheme-vendor-jQuery")
            .SetUrl("~/TheBlogTheme/vendor/jquery/jquery.min.js", "~/TheBlogTheme/vendor/jquery/jquery.js")
            .SetCdn("https://code.jquery.com/jquery-3.4.1.min.js", "https://code.jquery.com/jquery-3.4.1.js")
            .SetCdnIntegrity("<KEY>", "<KEY>")
            .SetVersion("3.4.1");
    }

    public void Configure(ResourceManagementOptions options)
    {
        options.ResourceManifests.Add(_manifest);
    }
}

```

In this example we define a script with the unique name `TheBlogTheme-vendor-jQuery`. 
We use a name that is unique to `TheBlogTheme` to prevent collisions when multiple themes are active. 

We set a url for the minified version, and the unminified version, which will be used in `ResourceDebugMode`.
For the same reason we define two CDN Url's, which will be preferred over the local urls if the `UseCdn` setting in the site admin is set. 
We set the Cdn Integrity Hashes and the version to `3.4.1`

This script will then be available for the tag helper or API to register by name. 

Additionally, we can use the `SetDependencies` method to ensure the script or style is loaded after their dependency. 

```csharp
public class ResourceManagementOptionsConfiguration : IConfigureOptions<ResourceManagementOptions>
{
    private static ResourceManifest _manifest;

    static ResourceManagementOptionsConfiguration()
    {
        _manifest = new ResourceManifest();

        _manifest
            .DefineStyle("ModuleName-Bootstrap-Select")
            .SetUrl("~/ModuleName/bootstrap-select.min.css", "~/ModuleName/bootstrap-select.css")
            .SetDependencies("bootstrap:4");
    }

    public void Configure(ResourceManagementOptions options)
    {
        options.ResourceManifests.Add(_manifest);
    }
}

```

In this example, we define a style that depends on Bootstrap version 4. In this case, the latest available minor version of bootstrap version 4 will be added. Alternatively, you can set a specific version of your choice or the latest version available. [See Inline definition](#inline-definition) for more details about versioning usage.

!!! note "Registration"
    Make sure to register this `IConfigureOptions<ResourceManagementOptions>` in the `Startup` or your theme or module.
    `serviceCollection.AddTransient<IConfigureOptions<ResourceManagementOptions>, ResourceManagementOptionsConfiguration>();`
  

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

```csharp
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

```csharp
settings.AtHead();
```

##### Place the resource at the end of the HTML document

{'fraction_non_alphanumeric': 0.09416978257859022, 'fraction_numerical': 0.01689516687439413, 'mean_word_length': 2.3294144767173814, 'pattern_counts': {'":': 0, '<': 22, '<?xml version=': 0, '>': 22, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7383278', 'n_tokens_mistral': 3992, 'n_tokens_neox': 3753, 'n_words': 1415}