Page History

In Magnolia, all resource files are loaded the same way. This page explains where resources are loaded from, their loading order, and how you can reference resources.

Table of Contents

What is a resource file?

Resource files are static Web resources (CSS, JavaScript), definition files for apps, dialogs and templates (YAML), and template scripts (FreeMarker). A resource file or its JCR node representation typically defines something or influences how content is rendered in Magnolia.

...

Web resources: CSS, JavaScript
Template scripts: FreeMarker
Definition files (YAML): template definition, dialog definition, app descriptor ...

Origins and loading order

Resource files can be loaded from three origins:

...

Magnolia looks for a resource in this order. As soon as it finds the resource it stops looking. For example, if a resource is not found in the JCR resources workspace then Magnolia checks the file system. If the resource is found on the file system, Magnolia does not check the classpath.

1. JCR `resources` workspace

Storing resource files in the JCR resources workspace is useful for hotfixes and patches. An administrator can make an urgent fix and publish it in the Resource Files app. Long term, we recommend that you keep resource files in the classpath of your module. This way they get into source control and are easier for large developer teams to work with.

...

Type of resource	Node path in the `resources` workspace
App descriptor	`/my-module/apps/foobar.yaml`
Dialog definition	`/my-module/dialogs/pages/foo.yaml`
Static Web resource (CSS, JavaScript)	`/my-module/css/style.css`
Template definition (YAML)	`/my-module/templates/pages/foo.yaml`
Template script (FreeMarker)	`/my-module/templates/pages/foo.ftl`

2. File system

Storing resource files in the file system is a good option for front-end developers. You can edit CSS and JavaScript files with your favorite tools without Magnolia getting in the way.

...

Include Page

	_What is magnolia.resources.dir
	_What is magnolia.resources.dir

3. Classpath

Include Page

	_What is a classpath-originated resource
	_What is a classpath-originated resource

...

Type of resource	Path in a Maven module
App descriptor	`src/main/resources/my-module/apps/foobar.yaml`
Dialog definition	`src/main/resources/my-module/dialogs/pages/foo.yaml`
Static Web resource (CSS, JavaScript)	`src/main/resources/my-module/css/style.css`
Template definitions (YAML)	`src/main/resources/my-module/templates/pages/foo.yaml`
Template script (FreeMarker)	`src/main/resources/my-module/templates/pages/foo.ftl`

Where should I store my resources?

To have different types of origin sounds cumbersome at first sight - but actually it is a very handy feature. Let's give you some recommendations which resource type to use in which case.

Bestpractice

During development - use file based or classpath based resources. These files are easier to create, maintain and diff when you work within a team.

Use JCR based resource to "override" an existing source or to add an additional resource within a running Magnolia system in production. This can be done with the Resource Files app.

Referencing resources

Web resources

Use the /.resources servlet path to reference Web resources such as CSS and JavaScript files. The path is mapped to a

Javadoc

0	info.magnolia.module.resources.ResourcesServlet

in /server/filters/servlets/ResourcesServlet. The servlet looks for the resource in all three origins in the order described above.

...

JCR: /my-module/css/style.css node in the resources workspace.
File system: <magnolia.resources.dir>/my-module/css/style.css path.
Classpath: src/main/resources/my-module/css/style.css path within a Magnolia Maven module

Template scripts

Use /<module-name>/templates to reference template scripts such as FreeMarker scripts (.ftl). A template script is a resource file too. You may need to reference one script from another using the FreeMarker include directive.

...

Code Block

language	xml

<head>
    <title>Templating examples</title>
    [#include "/my-module/templates/pages/header-include.ftl"]
	[@cms.init /]
</head>

Definition files

Use /<module-name>/<definition-type>/ to reference definition files, where <definition-type> is a folder where you keep such definitions such as:

...

Code Block

language	js

form:
  label: Simple content page properties
  tabs:
    - name: tabText
      label: Texts
      fields:
        - name: title
          class: info.magnolia.ui.form.field.definition.TextFieldDefinition
          label: Title and categories
          i18n: true
actions: !include /my-module/dialogs/common/actions-block.yaml

Editing resource files

While developing you may edit most probably resources files from classpath or from file system using an IDE or you favorite text editor. If you want to modify resource files within a running Magnolia instance - you may not have access to the file system and least of all to classpath originating files. Anyway editing resources on a running Magnolia instance is possible with the Resource Files app, see overriding resources.

Watching changes of resources

If you change resources which are used to define items - Magnolia will notice it and reload definitions items if required.

Changes on JCR based resources are detected by Observation module.
Changes on file based resources are deteced by
Javadoc
0 info.magnolia.dirwatch.DirectoryWatcherService
.
Changes on classpath originating resources are only relevant during development. Watching changes in classpath resources must be enabled by setting the Magnolia property magnolia.develop to true (see defining properties and Classpath resources in development mode too).

Resource Files app

The Resource Files app displays resources (CSS, JavaScript, template scripts, YAML configuration files) from all origins and allows you to edit JCR resources.

...

You can use the app to add, preview, edit, delete and publish resources.

Overriding resources

Overriding classpath and file system resources is useful for hot fixing. You may need to change a resource urgently and don't have opportunity to commit the change to source control until later.

Edit a classpath or files system resource in the Resource Files app. This creates a JCR node representation of the file in the resources workspace. Since Magnolia loads JCR resources first, the copy will override corresponding files on the file system and classpath. You can publish the copy to public instances without stopping or redeploying Magnolia.

...

Select a classpath or file system resource and click Edit file.
Edit the resource file and save.
The file is now JCR based and can be published.

A check mark in the Overrides column indicates that the new JCR file overrides another resource on the file system or classpath.

Publishing resources

JCR based resources can be published. When publishing such a resource - its parent folder (actually all ancestor folders) are published automatically as well.

...

Note that the parent folders have been published but no other files within the parent folders beside the one which was selected originally.

Deleting JCR based resources

JCR based resources can be deleted. As known from other JCR content app (e.g. Pages app) - when triggering the delete action, the resource is marked as deleted. Afterwards you can execute publish deletion or restore.

The special thing compared to other JCR content apps: When deleting a JCR based resource which is the only resource in the folder, then the folder itself is deleted too. This is true for all ancestor folders.

Restricting access to resources

Access to resources is defined in the /modules/resources/config/resourceFilter filter. By default, the filter allows access to resources as follows:

byType
- css, map, js, htm(l), ico, woff(2), ttf, svg, gif, jp(e)g, tiff, bmp
byLocation
- when located in the 'webresources' directory

Processed resources

Magnolia 5.4+ resource processing was removed from the standard Resources module. For users who rely on it, this functionality is now provided by the Processed Resources app module that installs the Processed Resources app. Note that this module is not part of the preconfigured Magnolia bundles and needs to be installed separately.

Using a dedicated CSS pre-processor

Info

icon	false
title	Best practice

Multiexcerpt

MultiExcerptName	Use a dedicated CSS pre-processor

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.

Notes to legacy users

Magnolia 5.4 harmonized the loading and referencing of resources. You should start using the new origins and loading order.

New resource file types

In Magnolia 5.3 and earlier, resource had a narrower meaning. Only nodes in the resources workspace or files with the same path in the classpath were considered resources. However, resource loading changed in Magnolia 5.4 and now all the items listed in What is a resource file? above are considered resources.

Stop storing resources in `mgnl-resources` and `docroot`

We recommend you stop using these directories:

...

Old projects can still rely on these legacy resource folders and Magnolia 5.4 serves resources from them. But you should start using the new origins.

Page tree

Versions Compared

Old Version 2

New Version 3

Key

What is a resource file?