Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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.
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:
Resource files can be loaded from three origins:
resources
workspaceMagnolia 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.
resources
workspaceStoring 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) |
|
Template script (FreeMarker) |
|
Template model (JavaScript) | /my-module/templates/pages/foo.js |
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) |
|
Template script (FreeMarker) |
|
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. 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) |
|
Template script (FreeMarker) |
|
Template model (JavaScript) | src/main/resources/my-module/templates/pages/foo.js |
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:
/my-module/css/style.css
node in the resources
workspace.<magnolia.resources.dir>/my-module/css/style.css
path.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.
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>
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
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
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.
If you change resources which are used to define items - Magnolia will notice it and reload definitions items if required.
magnolia.develop
to true (see defining properties and Classpath resources in development mode too).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 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:
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.
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.
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.
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
webresources
' directoryResource 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.