Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
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")}
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 and JCR-based resources.
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
webresources
subfolder of thefoobar
module. - Line 2: A list of patterns matching all JS files from the
foobar
andtravel-demo
modules. 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
pattern | required A single pattern or a list of patterns to match the desired resource(s). |
otherAttributes | optional Other attributes to be added to the generated Examples:
|
Returns
String
Zero to many <link/>
tags, divided by a line separator.
Usage
${resfn.css("/foobar-module.*css")} ${resfn.css("/foobar-module.*css", "media='all'")} ${resfn.css(["/foobar.*css", ".*magnolia.*css"])} ${resfn.css(["/foobar.*css", ".*magnolia.*css"], "media='all'")}
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
pattern | required A single pattern or a list of patterns to match the desired resource(s). |
otherAttributes | optional Other attributes to be added to the generated Examples:
|
Returns
String
Zero to many <link/>
tags, divided by a line separator.
Usage
${resfn.cachedCss("/foobar-module.*css")} ${resfn.cachedCss("/foobar-module.*css", "media='all'")} ${resfn.cachedCss(["/foobar.*css", ".*magnolia.*css"])} ${resfn.cachedCss(["/foobar.*css", ".*magnolia.*css"], "media='all'")}
js
Creates <script>
tags for JS files.
Method signatures
String js(String pattern)
String js(List<String> patterns)
Argument
pattern | required A single pattern or a list of patterns to match the desired resource(s). |
Returns
String
Zero to many <script/> tags divided by line line separator.
Usage
${resfn.js("/foobar-module.*js")} ${resfn.js(["/foobar.*css", ".*magnolia.*js"])}
cachedJs
Creates <script>
tags for JS files which will be served from cache.
Method signatures
String cachedJs(String pattern)
String cachedJs(List<String> patterns)
Argument
pattern | required A single pattern or a list of patterns to match the desired resource(s). |
Returns
String
Zero to many <script/>
tags divided by a line separator.
Usage
${resfn.cachedJs("/foobar-module.*js")} ${resfn.cachedJs(["/foobar.*css", ".*magnolia.*js"])}
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>
magnolia-empty-webapp
.
1 Comment
Joerg von Frantzius
Hi,
the rendered example links like href="/foobar-module/webresources/css/style.css" do not seem to refer to the Resources servlet, which would have "/.resources" as prefix (see also Resources#Webresources)
Is this on purpose, or maybe a mistake in the documentation?
Regards,
Jörg