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
-
#link
-
#cachedLink
-
#links
-
#cachedLinks
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 Freemarker injections render links to all CSS and JS files in the foobar
module if the module is part of your bundle.
${resfn.css("/foobar.*css")}
${resfn.js("/foobar.*js")}
<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 list of patterns as its argument.
${resfn.css("/foobar/webresources.*css")} (1)
${resfn.js(["/foobar.*js", "/travel-demo/.*js"])} (2)
1 | A single pattern to match all CSS files in the webresources subfolder of the foobar module. |
2 | A list of patterns matching all JS files from the foobar and travel-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 $timestampcache
appended to the link name, for example a.css
will become a2016-12-08-02-56-06-000cache.css
.
Get resources links
Besides generating CSS/JS HTML elements, resfn
can be used to get resource links from the given pattern arguments.
Example: In a FreeMarker template script, the following code retrieves links to all resource files in the foobar
module if the module is part of your bundle.
<link rel="stylesheet" type="text/css" href="${resfn.link('/foobar.*css')}" />
${resfn.links("/foobar.*js")}
<link rel="stylesheet" type="text/css" href="/foobar-module/webresources/css/style.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:
|
js
Creates <script>
tags for JS files.
Method signatures
String js(String pattern)
String js(String pattern, String otherAttributes)
String js(List<String> patterns)
String js(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:
|
cachedJs
Creates <script>
tags for JS files which will be served from cache.
Method signatures
String cachedJs(String pattern)
String cachedJs(String pattern, String otherAttributes)
String cachedJs(List<String> patterns)
String cachedJs(List<String> patterns, String otherAttributes)
Argument
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:
|
links
This method gets links for one or more resources.
cachedLink
This method gets a resource’s cached link.
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, as shown in the table below.
Module | Context attribute | Example |
---|---|---|
|
|
|
|
|
|
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
.