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/templatesin your module Magnolia deploys them to
/<CATALINA_HOME>/webapps/<contextPath>/templates/on the file system.
templatesworkspace. 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.
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:
JcrRepoTemplateLoaderloads templates from the repository. By default it loads templates from the
templatesworkspace 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.
LazyFileTemplateLoaderloads templates from an arbitrary location on the file system.
FreeMarker template loaders are configured in
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.
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.ftlscript is in a
/templating-kit/pagesfolder 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.