Magnolia 4.5 reached end of life on June 30, 2016. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

STK resources are accessible in Templating Kit > Resources and can be changed in AdminCentral. This functionality relies on the Resources module. Resources used in the STK include CSS sheets, JavaScripts and template images.

Referencing resources

In the STK resources are referenced in the Theme configuration. Resources can also be added at a  site definition and template definition level.

It is not necessary to store resources in the resources workspace. You can link to any valid internal or external URL.

See Themes for more information about how resources are used in the STK.

Resource types

The following resource types can be created in Resources:

  • Binary: Image files in all formats. In the STK the template images used by the CSS sheets are accessible in /templating-kit/themes/pop/img/bgs and /icons.
  • CSS: Standard CSS sheets.
  • Javascript: Standard JavaScript files.
  • Processed CSS: The content of the sheet is interpreted as a FreeMarker template. The CSS sheets used in the STK are type Processed CSS.
  • Processed Javascript: The content of the file is interpreted as a FreeMarker template. The JavaScripts used in the STK are type Processed Javascript.
  • Reference: Individual Javascripts referenced by aggregator scripts.

Processed resources

When a resource (CSS or JavaScript) is of type Processed, its content is interpreted as a FreeMarker template. You can use FreeMarker constants, variables and expressions inside the resource. You can also implement a custom model class and access the model's methods from inside the CSS or JavaScript document. The model class is defined in the resource's properties dialog. You can use any Java logic or Magnolia functionality. See Advanced tab below for more information.

Creating new resource files

To create a new resource item:

  1. Click New Item.
  2. Name the item and select the resource type.
  3. Click Edit Item or double-click on the file icon.
  4. Fill fields in the dialog.
  5. Save.

Dialogs

Depending on the resource type selection, Edit Item opens one of three dialogs:

  • JavaScript and CSS files (both processed and non-processed): The Content field uses the editCode control for entry of CSS or JavaScript code.

  • Aggregator JavaScripts: Child JavaScripts are added to the parent script in the Reference Resource field. See Aggregator scripts for more information.

  • Binary files such as images are uploaded in the File field.

Advanced tab

In the Advanced tab:

  • Bypass: If checked, the resource is loaded by the standard mechanism which loads from the file system or classpath resources. If unchecked, the resource is loaded from the repository. The first is the recommended best practice while the latter is useful during learning and development.
  • Extension: The script extension is added to the path if Bypass is selected.
  • Model Class: Allows for the use of a model class other than that in the template definition, which is overridden.

Resources loading

Resources are typically CSS files, JavaScript, images that rarely change (for example, logos). A resource can be either rendered as is or it can be pre-processed. Most resources are files sent to the browser. The resource loading logic is based on URI mapping. Where you store the resources should be determined by how those resources will be used.

Loading from the class path

By default, the classpath of a Magnolia webapp contains the JAR files in /WEB-INF/lib and any classes and resources in /WEB-INF/classes. The advantage of storing resources in the module itself is that the resources become part of the software lifecycle and follow the same release process as the code. As these resources are not editable in AdminCentral, this approach works best for items such as background graphics and logos. For example, the icons used in the AdminCentral are stored inside the AdminCentral module jar. See: /.resources/icons/24/cubes.gif.

The path for files served from classpath is http://<domain>/<contextPath>/.resources/<path to file>. The URI mapping configuration that resolves resources from a location that starts with /.resources (note the dot) is in Configuration > /server/filters/servlets/ClasspathSpoolServlet.

The dot naming convention for this resources in classpath was chosen to avoid confusion with file location names assigned by developers. This is a convention that is used in other file locations too such as .magnolia.

Loading from a custom file system

For loading bypassed and non-processed resources you can add custom resource loaders that implement the info.magnolia.module.resources.loaders.ResourceLoader interface. The FileSystemResourceLoader is an example of such a loader. It allows you to load resources from a custom file system path. You can define one path in the loader's configuration. The order of the loaders can be changed by moving the loader node up or down the tree.

Loading resources from the workspace

You can make resources visible and editable via AdminCentral by storing them in the resources workspace. This is a useful strategy for development and testing purposes since it makes changing resources quick and allows you to override a resource in the classpath. However, generally this is not the best practice for production. The path for files served from the resources workspace is http://<domain>/<contextPath>/resources/<path to file>. For example: /resources/templating-kit/themes/pop/css/styles.css.

The URI mapping configuration that resolves resources from a location that starts with /resources (note the absence of the dot) is in Configuration > /server/URI2RepositoryMapping/mappings/resources. Note that if a resource is marked as bypassed in the workspace, the system looks for the resource in the classpath.

Other loading options

You can also access resources using the WebDav module or the CMIS module.

  • No labels

3 Comments

  1. In the section "Loading from the class path" where URLs of the form http://<domain>/<contextPath>/.resources/<path to file> are talked about as a way to address resource files stored in the module itself, it may be helpful to know that the resource files in the module are those stored under the module-resources folder of the module.

    For example, if you have a module named training-stk-website, and in the module project folder you have the file training-stk-website/src/main/resources/mgnl-resources/training-stk-website/logo.gif, then you can access this file by the URL http://<domain>/<contextPath>/.resources/training-stk-website/logo.gif.

    This illustrates how a .resources URL is mapped to a file in a module jar.

  2. Typo: FileSystemReosourceLoader => FileSystemResourceLoader