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")}

<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 the foobar module.
• Line 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  ~$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

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

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

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

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. 

There is only one difference: the context attribute registered on the FreeMarker renderer has a different name: 

${hcmcfn.css("/foobar-module.*css")}

${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>