Lombiq Helpful Libraries - Orchard Core Libraries - Resource Management for Orchard Core

Resource Filter

Makes it possible to include resources automatically based on the current context, e.g. allows only injecting home page styling when the home page is being loaded.

Usage

Activate the resource filter middleware by adding app.UseResourceFilters() to the Configure() method of the Startup file located in a common module or the web project:

public override void Configure(IApplicationBuilder app, IEndpointRouteBuilder routes, IServiceProvider serviceProvider)
{
    app.UseResourceFilters();
}

To add resource filters, the IResourceFilterProvider interface needs to be implemented first:

Example

public class ResourceFilters : IResourceFilterProvider
{
    public void AddResourceFilter(ResourceFilterBuilder builder)
    {
        builder.WhenHomePage().RegisterHeadScript("HomePageStyle");
        builder.WhenPath("/my-page").RegisterHeadScript("MyPageScript");
    }
}

Then the registration needs to be added to the service collection as well:

public override void ConfigureServices(IServiceCollection services)
{
    services.AddResourceFilter<ResourceFilters>();
}

In case the service is simple and doesn't depend on additional services, you can forego the custom class and declare the rules directly in the Startup file:

public override void ConfigureServices(IServiceCollection services)
{
    services.AddResourceFilter(builder =>
    {
        builder.WhenHomePage().RegisterHeadScript("HomePageStyle");
        builder.WhenPath("/my-page").RegisterHeadScript("MyPageScript");
    });
}

Extensibility

You can register services that implement the IResourceFilterThemeResolver interface. These are used to resolve targets for the required theme configuration. It can be necessary if the theme depends on resources other than what's defined in the ThemeAttribute.BaseTheme. For example, our Media Theme loads a selected theme dynamically from the media library, so that has to be added to the list separately using such a service.

JavaScript Module Support

The ScriptModuleResourceFilter makes it possible to register JS modules in a way that they can be imported by name, so no bundling or importing by URL is necessary. Once you've added it to your service collection (services.AddAsyncResultFilter<ScriptModuleResourceFilter>();) you can register modules with the ResourceManifest.DefineScriptModule(resourceName) extension method and require them using the IResourceManager.RegisterScriptModule(resourceName) extension method.

You don't even have to register dependencies, because thanks to the importmap script generated by the ScriptModuleResourceFilter, you can import any resource using the import * from 'resourceName' syntax. You can see an example in Lombiq.VueJs.Resources where Vue.js 3 support is added ahead of Orchard Core.

Extensions

• ApplicationBuilderExtensions: Shortcut extensions for application setup, such as UseResourceFilters() (see above).
• ResourceFilterProviderExtensions: Extension methods for the IResourceFilterProvider interface.
• ResourceManifestExtensions: Extensions for building the resource manifest, such as SetDependenciesRecursively() which helps registering multi-level dependencies.
• ResourceManagerExtensions: Extensions for resource usage, such as RegisterStyle() which registers a stylesheet resource by name without having to use the error-prone "stylesheet" literal.
• ServiceCollectionExtensions: Extensions for registering resource filter providers.

Abstractions

ResourceManagementOptionsConfiguratorBase

You can reduce the boilerplate when configuring the resource manager by inheriting from this class instead of IConfigureOptions<ResourceManagementOptions>. First, place your static assets inside one of these locations (the filename can contain subdirectories):

• ~/{Area}/css/{filename}
• ~/{Area}/js/{filename}
• ~/{Area}/vendors/{filename}

Then implement the Configure method. Inside, you can access methods of the provided ResourceManagementContext to make defining resources easier, for example:

context.DefineStyle(ResourceNames.NativeVariables, "native-variables.css");
context.DefineStyle(ResourceNames.Helpers, "helpers.css");
context.DefineStyle(ResourceNames.General, "general.css", ResourceNames.NativeVariables, ResourceNames.Helpers);

Finally, you can register it with an extension method:

services.AddResourceManagementConfiguration<ResourceManagementOptionsConfiguration>();