Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
New Web technologies such as Syntactically Awesome Style Sheets (Sass) and Less have largely replaced the need to do FreeMarker pre-processing for CSS files. You can now accomplish the same with a dedicated CSS pre-processor. We recommend that you start using such new technologies. Magnolia provides the /resources
path (without dot) as a legacy option to support older projects.
The Processed Resources app is configured in /modules/processed-resources-app
.
Node name |
---|
modules |
processed-resources-app |
dialogs |
apps |
When a resource (CSS or JavaScript) is "processed" its content is interpreted as a FreeMarker template. You can use FreeMarker constants, variables and expressions inside the resource text. Magnolia evaluates them before serving the resources to the client.
Go to Web Dev > Processed Resources to open the app.
You can process different types of files. Choose a template that matches the file type:
/resources
pathUse the /resources
path (without dot) to load processed resources.
Example: Referencing a processed CSS file
<link rel="stylesheet" href="${ctx.contextPath}/resources/my-module/css/all-styles.css">
The /resources
path is mapped to the resources
workspace in /server/URI2RepositoryMapping/mappings/resources
using URI to repository mapping. This ensures that resources are loaded correctly also in projects that are built on earlier versions of Magnolia which you may want to run on Magnolia 5.4.
When you reference a resource with the
/resources
path, the resource is not loaded by
When building large sites, authors often face a maintainability challenge. In such websites, the size of the CSS is quite large and a lot of information may be repeated in multiple places. For example, maintaining a coherent color scheme throughout a document implies reusing a few color values at numerous positions in the CSS files. Altering the scheme, whether tweaking a single color or completely rewriting it, therefore becomes a complex task requiring precision, as a single find and replace often isn't enough. – Mozilla Developer Network: Using CSS variables
You can create equivalent functionality that is equivalent to CSS variables with processed resources in Magnolia.
Example: This Processed CSS resource defines a Freemarker variable textColor
and assigns it a value. We reference the variable later in the same file.
[#assign textColor="#ff0099"] p { font-family: Verdana, sans-serif; font-size: 11px; color: ${textColor}; }
When the resource is processed, the Freemarker expressions are evaluated and the resulting CSS is served to the client.
p { font-family: Verdana, sans-serif; font-size: 11px; color: #ff0099; }
Merging several JavaScript files into one file makes sense if you load the same JavaScript everywhere. Consider creating packages of JavaScript files that always go together:
Example: Merging jQuery plugins
The parent resource is Processed JavaScript template. The child nodes are normal non-processed JavaScript templates.
In the parent resource, use a FreeMarker list
directive to iterate through the children and access their content:
[#list cmsfn.children(content) as child ] [@cms.component content=child /] [/#list]
When you request the parent resource you get one long file with all the child scripts appended.
Processing is not recursive. This means, FreeMarker expressions are only evaluated in the parent node, not in child nodes.
Third-party JavaScript libraries get versioned frequently. You may want the latest version of a library in your project but don't want to keep updating references in all template scripts every time the resource file name changes. Or you may want minified and pretty-print versions of the same JavaScript with friendly file names.
Example: Create a resource file jquery-1.12.0.min.js
using the JavaScript template. This is the complex file name that has a version number. Create a friendly resource jquery-min.js
using the Reference template. Reference the first from the second.
Now you can reference jQuery from template scripts with a stable, friendly resource name:
<script src="${ctx.contextPath}/resources/jquery-min.js"></script>
When the library is updated you only need to update the reference, no need to touch the templates.
You can implement a custom model class and access the model's methods from inside a CSS or JavaScript document. In the model class you can use any Java logic or Magnolia functionality.
Enter the fully-qualified class name of the model class in the Model Class box in the resource properties dialog.
3 Comments
Pierre Sandrin
Is this module compatible with 5.6? I get exceptions in the magnolia UI when i start the App. In the module descriptor the dependency to magnolia-core is 5.4.3/*
Christoph Meier
Hello Pierre
Dependency to magnolia-core is 5.4.3/* could/should be okay. The number followed by
/*
means that the module at least requires 5.4.3 or higher.Concerning the exception: Please add the relevant part of the log file which indicates the error to pastebin.com or a similar service and provide a link to that error.log snippet.
Pierre Sandrin
I will open an issue in Jira to report the problem. I was just wondering if the module is meant to be compatible with 5.6 since it is not in the preconfigured bundle. The module descriptor says it should be in that case.