Magnolia 6.0 reached end of life on June 26, 2019. This branch is no longer supported, see End-of-life policy.
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.
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" />
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.
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"])}
webresources
subfolder of the foobar
module.foobar
and travel-demo
modules. The list must be in the following format: [$pattern1, $pattern2, ...]
.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
.
Creates <link>
tags for CSS files.
String css(String pattern)
String css(String pattern, String otherAttributes)
String css(List<String> patterns)
String css(List<String> patterns, String otherAttributes)
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:
|
String
Zero to many <link/>
tags, divided by a line separator.
${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'")}
Creates <link>
tags for CSS files which will be served from cache.
String cachedCss(String pattern)
String cachedCss(String pattern, String otherAttributes)
String cachedCss(List<String> patterns)
String cachedCss(List<String> patterns, String otherAttributes)
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:
|
String
Zero to many <link/>
tags, divided by a line separator.
${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'")}
Creates <script>
tags for JS files.
String js(String pattern)
String js(List<String> patterns)
pattern | required A single pattern or a list of patterns to match the desired resource(s). |
String
Zero to many <script/> tags divided by line line separator.
${resfn.js("/foobar-module.*js")} ${resfn.js(["/foobar.*css", ".*magnolia.*js"])}
Creates <script>
tags for JS files which will be served from cache.
String cachedJs(String pattern)
String cachedJs(List<String> patterns)
pattern | required A single pattern or a list of patterns to match the desired resource(s). |
String
Zero to many <script/>
tags divided by a line separator.
${resfn.cachedJs("/foobar-module.*js")} ${resfn.cachedJs(["/foobar.*css", ".*magnolia.*js"])}
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
.
resfn
from your bundleresfn
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
.