Template definition

A template definition gives a template a name and makes it available to the system. At a minimum a template definition must specify a script and a renderer. You can configure a template in a YAML file or a JCR node.

Template definition types

Magnolia has three types of template definitions:

Page definition defines a page template. Pages are divided into areas.
Area definition defines an area template. An area is configured in a page definition. Areas typically contain components.
Component definition defines a component template.

Common template properties

Simple template definition:

/my-module/templates/pages/home.yaml

renderType: freemarker 
templateScript: /my-module/templates/pages/home.ftl
dialog: my-module:pages/homePageProperties
class: com.example.templates.CustomTemplateDefinition
modelClass: com.example.templates.HomePageModel

Node name	Value
home
class	com.example.templates.CustomTemplateDefinition
dialog	my-module:pages/homePageProperties
modelClass	com.example.templates.HomePageModel
renderType	freemarker
templateScript	/my-module/templates/pages/home.ftl

You can use common template properties in page, area and component definitions. Each template type has its own specific properties too.

`renderType`	required Renderer to use. Magnolia supports `freemarker` and `jsp` renderers by default. If you have the Site module you can set `renderType=site`, then define a common `templateScript` in the template prototype to use on all pages of the site. You can also create a custom renderer.
`templateScript`	required Path to the template script as `/<module>/templates/<type>/<file>.<ext>` format. See Resources for more about script storage locations.
`dialog`	optional Dialog definition ID in `<module-name>:<path to dialog definition>` format. The ID has two parts, separated by a colon: `<module-name>` : The name of the module which contains the dialog definition. `<path>`: Relative path to the dialog definition inside `dialogs` root item. For example the dialog ID `my-module:pages/homePageProperties` either points to the YAML file `$magnolia.home/my-module/dialogs/homePageProperties.yaml` or to the JCR node `/modules/my-module/dialogs/homePageProperties` in the configuration workspace.
`i18nBasename`	optional Message bundle such as `com.example.templates.messages`. You don't need to set this property if your message bundle is in the `i18n` directory (the `mgnl-i18n` directory in Magnolia 5.4.5 and earlier) inside the module. Magnolia will find the bundle automatically. Only set the property if you put the bundle somewhere else.
`title`	optional Title of the template displayed to editors. The value can be literal or retrieved from a message bundle (which is defined in i18nBasename) with a key. Use alphanumeric characters in literal values. Displayed in: Pages: Template dropdown in the Pages app. Areas: Area toolbar in the page editor. Components: Component toolbar in the page editor.
`description`	optional Template description displayed to editors. The value can be literal or retrieved from the message bundle (specified by `i18nBasename`) with a key.
`class`	optional The fully-qualified class name for the Java bean representing the definition data of this item. The default class is TemplateDefinition . Only set the value when using custom definition class. Example: `com.example.templates.CustomTemplateDefinition`.
`modelClass`	optional A model class that contains business logic for the template. The model class needs to implement the RenderingModel interface. The renderer creates a bean based on the `modelClass`. Current content, definition and the parent model are passed to the constructor. This object is instantiated for each rendering of a page or component. Magnolia 5.4.5+ A Groovy model class can be referenced from a YAML template definition. Current limitations: A Groovy model cannot be supplied as a file, you can only reference a Groovy model stored in JCR. (See the Groovy module.) The reference path cannot include the hyphen character. Value: Java models: Fully-qualified class name. Example: `com.example.templates.HomePageModel`. Groovy models: Path to the model using dot notation such as `myModule.templates.components.LinkModel.`
`parameters`	optional Custom template properties that you can access from a script without having to write a class.
`extends`	optional, in JCR node configuration only Inherits the configuration from another template definition. The value is a valid Magnolia path. See Reusing configuration.
`variations`	optional Merges template definition with the variation having the same name of the channel - if available.

Custom template properties

Use a parameters item in any template definition to add custom properties without having to write a custom class. Access the properties from your script using the def.parameters.<parameter-name> notation. See def.

parameters:
  example: my-value

Node name	Value
<template name>
parameters
example	my-value

To access the example parameter in a Freemarker script, use:

${def.parameters.example!}

Reusing configuration

Magnolia provides mechanisms to reuse configuration items such as template definitions or dialogs. Read Reusing configuration and Extend JCR node based template definition for further information.

Page tree

Template definition