resfn

FreeMarker development only

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

Argument Description

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 <link/> tag. If the value of this parameter requires quotes, use single quotes (') or escaped double quotes (\").

Examples:

  • "title='Basic' media='all'"

  • "title=\"Basic\" media=\"all\""

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

Argument Description

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 <link/> tag. If the value of this parameter requires quotes, use single quotes (') or escaped double quotes (\").

Examples:

  • "title='Basic' media='all'"

  • "title=\"Basic\" media=\"all\""

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

Argument Description

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>

The above snippet is for a webapp which is based directly on magnolia-empty-webapp.

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules