Resources

STK resources are accessible in STK > Resources and can be changed inline. 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 in STK > Themes. Resources can also be added in the template prototype or a template definition.

Node name	Value
pop
cssFiles
jsFiles
init-libraries
farFutureCaching	true
link	/resources/templating-kit/js/scriptloader-libraries.js
init-plugin
init-theme

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

Click New Item.
Name the item and select the resource type.
Click Edit Item or double-click on the file icon.
Fill fields in the dialog.
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

Best practice

The best practice is to load resources by the standard Magnolia mechanism which loads from the file system or classpath resources. This way you can store the resources in a version control system and they become part of a controlled software development lifecycle automatically. You can edit them in an IDE or your favorite editor.

In the Advanced tab:

Model Class: Allows for the use of a model class other than that in the template definition, which is overridden.
Bypass: When checked, the resource is loaded from the file system or classpath (best practice). When cleared, the resource is loaded from the repository, which is useful for learning and development.
Extension: The script extension is added to the path if Bypass is selected.

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

Classpath is a parameter that tells the Java Virtual Machine or the Java compiler where to look for user-defined classes and packages. The classpath of a Magnolia webapp includes any JAR files in /WEB-INF/lib and any classes and resources in /WEB-INF/classes.

The advantage of storing resources in a module JAR is that the resources become part of the software lifecycle and follow the same release process as code. Since such resources are not editable inline, this approach works for items you don't need to edit often such as template scripts, background graphics and logos.

The path for resources 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 the Configuration app > /server/filters/servlets/ClasspathSpoolServlet.

Magnolia uses the dot naming convention for resources in the classpath 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 FileSystemReosourceLoader 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.

Node name	Value
modules
resources
config
resourceLoaders
classpathLoader
class	info.magnolia.module.resources.loaders.ClasspathResourceLoader
fileSystemLoader
class	info.magnolia.module.resources.loaders.FileSystemResourceLoader
path	/home/jsmith

Loading resources from the workspace

You can make resources visible and editable inline 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 the Configuration app > /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.

Page tree