Static resources

This page explains the support for static resources activated by Across Web. On this page you will learn:

  • the embedded resource conventions for static resource files (css, js) and Thymeleaf templates

  • how to configure static resource (client-side) caching

  • how to configure static resource url versioning

See the chapter on web resources if you are looking for information on the WebResourceRegistry and programmatic registration of web resources.

Across Web automatically enables serving of static resources bundled with modules. With the default settings static resources will be configured with versioned urls and client-side caching.

Conventions

The default resources are contains in the /views folder on the classpath, and Across Web will serve resources from /views/static. Additional subfolders to serve can be configured with the acrossWebModule.resources.folders property.

By convention (and for best development mode support) module specific resources should be located in a subfolder with the resourcesKey of the module.

Example resources layout for MyModule
src/main/resources
   views/
     static/
       MyModule/
         js/controller.js
         css/my-module.css
         img/logo.png
     th/
       MyModule/
         controller.html
         user-profile.html

The relative path under which the static resources are available is determined by the acrossWebModule.resources.path property.

Client-side caching

By default static resources will be cached on the client-side for a period of 1 year. Disabling client-side caching is done with the acrossWebModule.resources.caching.enabled property. If client-side caching is disabled, no cache headers will be sent to the client.

Configuring the caching period is done separately with the acrossWebModule.resources.caching.period property. Setting the value to 0 with caching enabled will sent no-cache headers. This is also the default if development mode is active.

Resource URL versioning

By default AcrossWebModule enables Spring versioning of static resources. This will generate versioned URLs, create a ResourceUrlProvider bean and add a ResourceUrlEncodingFilter and ResourceUrlProviderExposingInterceptor to the request handlers.

Using versioned resource URLs is transparent:

  • in Thymeleaf all relative links added with @{/relative/path} will be rewritten if necessary

  • in JSP the equivalent is the <spring:url value="/relative/path" var="url"/> tag

Using these will work both with and without resource versioning.

If versioning is disabled, the ResourceUrlProvider will not be available on the request. Modules using accessing the ResourceUrlProvider directly should built-in support for this.

Fixed version strategy

AcrossWebModule supports automatic configuration of resource versioning using a single fixed version. When enabled this means that resources of the form /across/resources/static/mymodule/mymodule.css will get rewritten to /across/resources/static/VERSION/mymodule/mymodule.css.

The fixed version used is determined as follows:

  1. acrossWebModule.resources.versioning.version property

  2. build.number property

  3. version of the AcrossWebModule

Using the fixed version strategy works well for relative includes in both CSS and JS files, avoiding the need to rewrite URLs inside those files.

Customizing the version strategy

It is possible to keep configuration of the default resources active but only change the version strategy used. This can be done by injecting your own VersionResourceResolver bean named versionResourceResolver the AcrossWebModule context.

Example providing custom version strategy
@ModuleConfiguration(AcrossWebModule.NAME)
public static class CustomVersionResourceResolver
{
	@Bean
	public VersionResourceResolver versionResourceResolver() {
		return new VersionResourceResolver()
				.addVersionStrategy( new FixedVersionStrategy( "1.0" ), "/**/*.css" )
				.addVersionStrategy( new FixedVersionStrategy( "2.0" ), "/**" );
	}
}
Because of limitations of the CssLinkTransformer in combination with a fixed version strategy, AcrossWebModule does not rewrite links inside css files. If you absolutely need this in your application, you will have to disable the automatic resource versioning and configure it yourself.
« Building web pages Static resources Webjars support »