Resources

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.

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.

Examples of resources:

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:

JCR resources workspace
File system
Classpath (JARs)

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.

When you store resources in the resources workspace, organize them by module and type:

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`
Template model (JavaScript)	`/my-module/templates/pages/foo.js`

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.

When you store resources on the file system, organize them by module and type. See: Module structure

Type of resource	Path on the file system
App descriptor	`<magnolia.resources.dir>/my-module/apps/foobar.yaml`
Dialog definition	`<magnolia.resources.dir>/my-module/dialogs/pages/foo.yaml`
Static Web resource (CSS, JavaScript)	`<magnolia.resources.dir>/my-module/css/style.css`
Template definitions (YAML)	`<magnolia.resources.dir>/my-module/templates/pages/foo.yaml`
Template script (FreeMarker)	`<magnolia.resources.dir>/my-module/templates/pages/foo.ftl`
Template model (JavaScript)	`<magnolia.resources.dir>/my-module/templates/pages/foo.js`

magnolia.resources.dir is a property defining the directory from which resources are loaded in a Magnolia instance. This directory is used for file-based resources such as light modules and for overriding classpath resources. The property is configured in WEB-INF/config/default/magnolia.properties and has the default value $magnolia.home/modules. To see the current value of the property, go to the Config Info tab in the About Magnolia app.

You can use symbolic links (a.k.a symlinks or soft links) in the resources directory to include light modules located elsewhere on your system.

3. Classpath

A resource originating from classpath is a resource in a JAR file, exposed to the classloader of the Magnolia webapp (in WEB-INF/lib of the webapp). The jar file can be a Magnolia Maven module or any other jar file provided by Magnolia or by a third party.

Storing resources in a JAR and accessing them via the classpath is a best practice in the long term. It ensures that resource files are committed to source control, they participate in the software lifecycle like any other project artifact, and they are easier for large developer teams to work with.

When you store resources in the classpath, add them to the src/main/resources/<module-name>/resources folder of your (Magnolia) Maven module.

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`
Template model (JavaScript)	`src/main/resources/my-module/templates/pages/foo.js`

Where should I store my resources?

Best practice

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 resources to "override" an existing source or to add an additional resource within a running Magnolia system in production. This can be done in 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 in /server/filters/servlets/ResourcesServlet. The servlet looks for the resource in all three origins in the order described above.

Example: Referencing a CSS file in a FreeMarker script

<link rel="stylesheet" href="${ctx.contextPath}/.resources/my-module/css/style.css">

The ResourcesServlet checks the following origins:

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.

You can also use resfn templating functions to create links to CSS and JS resources in templates by a defined pattern or a list of patterns.

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.

Example: Including a FreeMarker script in another script

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

/<module-name>/dialogs
/<module-name>/apps
/<module-name>/templates/pages
and so on

Definitions configured in YAML files are also resources. You can include a YAML file in another YAML file in a similar way as including a template script.

Example: Including a YAML action definition in a YAML dialog definition.

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 resource files from classpath or from file system using an IDE or your 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. 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 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.

Go to Web Dev > Resource Files to open the app.

The app indicates the origin of the resource with icons:

Icon	Resource origin
	Classpath (JARs)
	File system
	JCR `resources` workspace

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.

To override a resource:

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.

Removing the hotfix
Please note that if you have an active receiver (subscriber), applying the Delete file action to the hotfixed resource will only mark the resource for deletion. It will not restore the original resource. To fully restore the function of the original resource, you need to publish it after deleting it.

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.

Select the resource /my-module/templates/foobar.yaml and trigger the action publish. Afterwards check the situation on the public instance:

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 Publish deletion or Restore previous version.

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

Resource processing functionality is 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