Loading and editing template scripts

Best practice

Keep template scripts in your project module. This way you can store the scripts 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.

Template script loading

Magnolia loads template scripts from the following locations in this order. As soon as it finds a script, it stops looking.

Filesystem of the webapp. JSP scripts can only reside on the file system because they require pre-compiling by the server before they can be rendered. JSP scripts are extracted onto the file system during module installation or update. When you put JSP scripts in /mgnl-files/templates in your module Magnolia deploys them to /<CATALINA_HOME>/webapps/<contextPath>/templates/ on the file system.
templates workspace. The script needs to be enabled (box checked) to be considered for loading. You can load only Freemarker scripts from the repository.
Web application's classpath . This is best practice for Freemarker scripts. Keep them in the module JAR. A module JAR is always in the classpath so Magnolia finds the scripts.

Template loaders

The FreeMarker renderer can load template "files" through any object that implements the freemarker.cache.TemplateLoader interface. The templates need not be real files and can come from any kind of data source such as classpath, servlet context or database.

Magnolia provides three FreeMarker template loader implementations:

JcrRepoTemplateLoader loads templates from the repository. By default it loads templates from the templates workspace but you can configure another workspace. This loader is included in the In-place Templating module.
LazyWebappTemplateLoader loads templates from the webapp folder by default. If no matching template is found it will be loaded from the classpath.
LazyFileTemplateLoader loads templates from an arbitrary location on the file system.

FreeMarker template loaders are configured in /server/rendering/freemarker/templateLoaders.

Node name	Value
server
rendering
freemarker
templateLoaders
jcr
class	info.magnolia.module.inplacetemplating.JcrRepoTemplateLoader
extension	.ftl
workspace	templates
webapp
class	info.magnolia.freemarker.loaders.LazyWebappTemplateLoader

You can also write your own custom template loader if needed.

Installing scripts into the repository

Editing template scripts in the repository is not maintainable in the long run because the changes don't make their way into the module. You can use this approach for evaluation and prototyping but don't do it in a production environment. We strongly recommend that you store the scripts in a version control system and package them into a project module.

In order to edit template scripts in the repository, install them into the templates workspace. This is useful for prototyping or developing but it only works with FreeMarker scripts. The scripts become editable in the Templates app.

Add a TemplatesInstallTask into your module version handler. Here is an example from the Standard Templating Kit module ( Git ):

STKModuleVersionHandler.java

import info.magnolia.module.inplacetemplating.setup.TemplatesInstallTask;
 
// Install scripts when the module is installed for the first time.
@Override
protected List<Task> getExtraInstallTasks(InstallContext ctx) {
	final List<Task> tasks = new ArrayList<Task>();
	tasks.addAll(super.getExtraInstallTasks(ctx));
	tasks.add(new TemplatesInstallTask("/templating-kit/.*\\.ftl", true));@Override

// Reinstall scripts when the module is updated.
@Override
protected List<Task> getDefaultUpdateTasks(Version forVersion) {
	final List<Task> tasks = new ArrayList<Task>();
	tasks.addAll(super.getDefaultUpdateTasks(forVersion));
	tasks.add(new TemplatesInstallTask("/templating-kit/.*\\.ftl", true));
	return tasks;
	}

Editing scripts in the repository

To edit a template script in the repository:

Go to STK > Templates.
Create a template script or edit an existing one. To override a script that would normally be loaded from the classpath, replicate the folder hierarchy. For example, the STK main.ftl script is in a /templating-kit/pages folder inside the module JAR. Creating the matching folders in the repository allows the repository script override the classpath script.
Check the Enable template checkbox.
Optional: If you customize a default template script, such as one of the STK scripts, clear the Automatic update box. This ensures that your customizations are not lost when the module is updated. If the box is checked, the script will be replaced with a newer version during module update.

Installing scripts onto the file system

To install JSP scripts on to the file system put them in /mgnl-files/templates/<module-name> in your module. Magnolia deploys them to /<CATALINA_HOME>/webapps/<contextPath>/templates/ on the file system during module install and update.

Page tree