resfn
resfn templating functions allow you to create links to CSS and JS
resources in templates by a defined pattern or a list of patterns. The
following methods are available:
-
#css -
#cachedCss -
#js -
#cachedJs
The functions originate in a project called neat-resources, hosted on GitHub, developed by rah003 and integrated in the magnolia-resources module. If you have already used neat-resources, please read From hcmcfn to resfn below.
Overview
The purpose of resfn functions is to generate HTML elements that link
to CSS and JS resource files in your project. You would typically use
the functions in a FreeMarker template script. The functions create
<script> and <link> elements for you depending on the file pattern
(.*js, .*css) you provide and the resources that are available.
Example: In a FreeMarker template script, the following code…
${resfn.css("/foobar.*css")} ${resfn.js("/foobar.*js")}
renders links to all CSS and JS files in the foobar module if the
module is part of your bundle:
<script src="/foobar-module/webresources/js/a.js"></script>
<script src="/foobar-module/webresources/js/b.js"></script>
<link rel="stylesheet" type="text/css" href="/foobar-module/webresources/css/style.css" />
<link rel="stylesheet" type="text/css" href="/foobar-module/webresources/css/style2.css" />Available resources
The links are created only for resources which are a part of your
bundle. This includes all resources visible to the magnolia-resources
module: resources from the file system, from
the classpath, JCR-based, and in-memory.
Pattern argument
Each of the main methods, #css, #cachedCss, #js and #cachedJs,
can take a single pattern or a pattern list as its argument:
${resfn.css("/foobar/webresources.*css")}
${resfn.js(["/foobar.*js", "/travel-demo/.*js"])}-
Line 1: A single pattern to match all CSS files in the
webresourcessubfolder of thefoobarmodule. -
Line 2: A list of patterns matching all JS files from the
foobarandtravel-demomodules. The list must be in the following format:[$pattern1, $pattern2, …].
Cached or not cached
For CSS and JS you can use resfn to create links for webresources
which will be served from cache (use #cachedCss and #cachedJs) or
directly via the resources loading mechanism (via #css and #js). The
former methods will generate links with ~$timestamp~cache appended to
the link name, for example a.css will become
a~2016-12-08-02-56-06-000~cache.css.
Methods
css
Creates <link> tags for CSS files.
Method signatures
String css(String pattern)
String css(String pattern, String otherAttributes)
String css(List<String> patterns)
String css(List<String> patterns, String otherAttributes)
Arguments
| Argument | Description |
|---|---|
|
required A single pattern or a list of patterns to match the desired resource(s). |
|
optional Other attributes to be added to the generated Examples:
|
cachedCss
Creates <link> tags for CSS files which will be served from cache.
Method signatures
String cachedCss(String pattern)
String cachedCss(String pattern, String otherAttributes)
String cachedCss(List<String> patterns)
String cachedCss(List<String> patterns, String otherAttributes)
Arguments
| Argument | Description |
|---|---|
|
required A single pattern or a list of patterns to match the desired resource(s). |
|
optional Other attributes to be added to the generated Examples:
|
From hcmcfn to resfn
Version 2.5.1 of the
magnolia-resources
module adds the templating functions, originally called hcmcfn, from
neat-resources into a new
submodule called magnolia-resources-templating. With this move the
resources templating functions have become an official part of Magnolia.
If you have already been using
neat-resources, you can still
use them.
resfn, provided by magnolia-resources-templating (version 2.5.1),
contains exactly the same methods as neat-resources (version 1.0.1).
However, magnolia-resources-templating may undergo further
development, whereas the development of neat-resources is pending.
There is only one difference: the context attribute registered on the FreeMarker renderer has a different name:
Module
Context attribute
Call example
neat-resources
hcmcfn
${hcmcfn.css("/foobar-module.*css")}
magnolia-resources-templating
resfn
${resfn.css("/foobar-module.*css")}
To switch from neat-resources to magnolia-resources-templating,
modify the existing FreeMarker scripts by replacing hcmcfn with
resfn.
Excluding resfn from your bundle
resfn resides in magnolia-resources-templating, which was added to
magnolia-empty-webapp with version 5.5.1 of Magnolia. Since
magnolia-empty-webapp itself is the base app of every Magnolia webapp
and bundle, your bundle will most probably contain also
magnolia-resources-templating, if your bundle is based on Magnolia
5.5.1 or higher. However, you may always exclude resfn from your
bundle by adding the following section to the POM file of your webapp:
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-empty-webapp</artifactId>
<type>war</type>
<exclusions>
<exclusion>
<groupId>info.magnolia.resources</groupId>
<artifactId>magnolia-resources-templating</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-empty-webapp</artifactId>
<type>pom</type>
<exclusions>
<exclusion>
<groupId>info.magnolia.resources</groupId>
<artifactId>magnolia-resources-templating</artifactId>
</exclusion>
</exclusions>
</dependency>The above snippet is for a webapp which is based directly on
magnolia-empty-webapp.