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.

The Magnolia CLI offers the create-page and create-component commands that automatically create basic scripts, template definitions and dialog definitions.

Template properties

Magnolia natively supports template properties for rendering pages with FreeMarker or SPA. Some of the properties listed below are required or optional for both of these renderers, some are FreeMarker or SPA specific.

You can also configure Custom template properties.

Common template properties

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

Property Description

renderType

required for freemarker and optional for the SPA $type aliases (classes):

spa (info.magnolia.rendering.spa.renderer.SpaRenderableDefinition)
siteSpa (info.magnolia.rendering.spa.renderer.SiteAwareSpaRenderableDefinition)

The property specifies which renderer to use. Magnolia supports the freemarker, spa and site-spa renderers by default.

If you have the Site module, you can set renderType to site and define a common templateScript in the template prototype to use for all pages on the site. For site-aware SPA rendering, the value is site-spa.

You can also create a custom renderer.

dialog

optional

Dialog definition ID in <module-name>:<path to dialog definition> format. The ID has two parts separated by a colon:

<module-name>: name of the module that contains the dialog definition.
<path>: relative path to the dialog definition inside the dialogs root item. For example, the dialog ID my-module:pages/homePageProperties points to either the YAML file $magnolia.home/my-module/dialogs/homePageProperties.yaml or the JCR node /modules/my-module/dialogs/homePageProperties in the configuration workspace.

title

optional

Template title displayed to editors. The value can be literal or retrieved from a message bundle 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 a message bundle with a key. Use alphanumeric characters in literal values.

$type

required if class is not defined in template definition

Alias for the Java bean representing the definition data of this item. Use the following values:

page for a non-SPA template.
siteSpa for a site-aware SPA template.
spa for any other SPA template.

class

optional

Fully qualified class name for the Java bean representing the definition data of this item. The default class is info.magnolia.rendering.template.TemplateDefinition.

Only set the value when using a custom definition class (for example, com.example.templates.CustomTemplateDefinition).

For an externally hosted SPA, class is:

info.magnolia.rendering.spa.renderer.SpaRenderableDefinition if $type: spa is not in the template definition.
info.magnolia.rendering.spa.renderer.SiteAwareSpaRenderableDefinition if $type: siteSpa is not in the template definition.

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

Allows you to deliver the same content in different formats. This helps you optimize content for different channels (desktop, smartphone and tablet) and system parameters.

You can configure variations in the site definition as well as the template definition. Alternatively, you may want to use personalization to create content variants.

SPA-only template properties

Property Description

Property	Description
`baseUrl`	required In an external SPA configuration, an external URL which the page editor iFrame must point to. In an external SPA setup, multiple pages can have the same page definition but each page may need a different path or parameter to initialize. The format of this initialization element can be specified using the `routeTemplate` property.
`routeTemplate`	optional Format of a string appended to `baseUrl` to initialize a page in an external SPA configuration. Available properties Besides `language`, you can use any page node property (for example, `@name`, `@path`, `@id` or the prefixed `mgnl:` and `jcr:` properties). Double and single curly brackets Double curly brackets and single curly brackets are interpreted differently. The parameter inside double curly brackets `{{ }}` is not converted to the `application/x-www-form-urlencoded` MIME format. In case you need to use `@path`, other parameters with characters such as `space`, `+`, `"`, `%`, `<`, `>`, `\`, `^` or any HTML-unsafe characters, use the single curly brackets. Examples With `baseUrl: http://localhost:3000` and: `routeTemplate:'?title={{title}}'` Passing `The string ü@foo-bar` to `title` will result in a broken address: http://localhost:3000/?title=The string ü@foo-bar `routeTemplate:'?title={title}'` Passing `The string ü@foo-bar` will generate a URI-safe form: http://localhost:3000/?title=The+string+%C3%BC%40foo-bar
`spaRouterClass`	optional In an external SPA setup, the implementation class of your own custom router so you can resolve extra attributes that must be added to the URL.

baseUrl

required

In an external SPA configuration, an external URL which the page editor iFrame must point to.

In an external SPA setup, multiple pages can have the same page definition but each page may need a different path or parameter to initialize. The format of this initialization element can be specified using the routeTemplate property.

routeTemplate

optional

Format of a string appended to baseUrl to initialize a page in an external SPA configuration.

Available properties: Besides language, you can use any page node property (for example, @name, @path, @id or the prefixed mgnl:* and jcr:* properties).
Double and single curly brackets: Double curly brackets and single curly brackets are interpreted differently. The parameter inside double curly brackets {{ }} is not converted to the application/x-www-form-urlencoded MIME format. In case you need to use @path, other parameters with characters such as space, +, ", %, <, >, \, ^ or any HTML-unsafe characters, use the single curly brackets.

Examples

With baseUrl: http://localhost:3000 and:

routeTemplate:'?title={{title}}'
Passing The string ü@foo-bar to title will result in a broken address:

http://localhost:3000/?title=The string ü@foo-bar

routeTemplate:'?title={title}'
Passing The string ü@foo-bar will generate a URI-safe form:

http://localhost:3000/?title=The+string+%C3%BC%40foo-bar

spaRouterClass

optional

In an external SPA setup, the implementation class of your own custom router so you can resolve extra attributes that must be added to the URL.

FreeMarker-only template properties

Property Description

templateScript

required

Path to the template script (in /<module>/templates/<type>/<file>.<ext> path format). See Resources for more about script storage locations.

Since Magnolia 6.2.30, the property has been deprecated for use with the SPA renderer. In SPA context, configure the definition with baseUrl and optionally routeTemplate. For more details, see above in SPA-only template properties.

modelClass

optional

Model class that contains business logic for the template. The class needs to implement the RenderingModel interface. The renderer creates a bean based on modelClass. The current content, definition and parent model are passed to the constructor. This object is instantiated for each rendering of a page or component.

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 (for example, com.example.templates.HomePageModel).
Groovy models: path to the model using dot notation such as myModule.templates.components.LinkModel.

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 Rendering context objects: def.

parameters:
  example: my-value

To access the example parameter in a FreeMarker script, use the following:

${def.parameters.example!}

Referencing templates

Other configuration nodes can reference templates. The property used in the referencing configuration depends on the mechanism used.

Referencing templates with `id` property

The template id property is used for:

Component availability in an area definition.
Template availability in a site definition.

Property Description

id

required

ID of the template definition in <module name>:<path to page definition> format. The ID has two parts separated by a colon:

<module-name>: name of the module that contains the template definition.
<path>: relative path to the template definition inside the templates folder. For example, the page ID my-module:pages/home points to either the YAML file $magnolia.resources.dir/my-module/templates/pages/home.yaml or the JCR node /modules/my-module/templates/pages/home in the config workspace.

You can reference templates from any module.

id is not a general property. It can only be used when it is supported by the referencing configuration.

Referencing templates using path

Various Magnolia mechanisms use the path to the template definition to reference templates. These mechanisms allow you to reuse configurations:

Include mechanism: used in YAML definitions to include a referenced file. The Magnolia-specific !include directive uses the absolute path to reference the file.
Extends mechanism: used in JCR node configuration to extend another configuration. The extends property references the source configuration by its path. The target configuration inherits everything from the source and adds its own exceptions.
Definition decoration mechanism: allows you to alter existing configured items, such as apps, dialogs, fields, templates and more.

Configuration examples

SPA render type

With `baseUrl` property

# Since Magnolia 6.2.18, SPA $type aliases are available and the renderType property is optional.
# class: info.magnolia.rendering.spa.renderer.SpaRenderableDefinition
# renderType: spa

$type: spa
title: 'React: Contact'
# templateScript: /react-minimal-lm/webresources/build/index.html
# Since version 6.2.26 of the Pages module, the templateScript property is deprecated for use with the SPA renderer.
baseUrl: http://example.com
dialog: spa-lm:pages/basic

With `baseUrl` and `routeTemplate` properties

# Since Magnolia 6.2.18, SPA $type aliases are available and the renderType property is optional.
# class: info.magnolia.rendering.spa.renderer.SpaRenderableDefinition
# renderType: spa

$type: spa
title: 'React: Contact'
# templateScript: /react-minimal-lm/webresources/build/index.html
# Since version 6.2.26 of the Pages module, the templateScript property is deprecated for use with the SPA renderer.
baseUrl: http://localhost:3000
routeTemplate: '{{path}}?lang={language}'
dialog: spa-lm:pages/basic

Site SPA render type

# Since Magnolia 6.2.18, SPA $type aliases are available and the parent renderType property is optional.
# class: info.magnolia.rendering.spa.renderer.SiteAwareSpaRenderableDefinition
# renderType: site-spa

$type: siteSpa
visible: true
dialog: mte:pages/pageProperties
baseUrl: http://localhost:3100/magnoliaAuthor
routeTemplate: '{{@path}}'
# templateScript: /vue-lm/webresources/dist/index.html
# Since version 6.2.26 of the Pages module, the templateScript property is deprecated for use with the SPA renderer.

areas:
  header:
    renderType: spa
    title: Header
    type: single
    availableComponents:
      navigation:
        id: vue-lm:components/navigation
  main:
    renderType: spa
    title: Main
    availableComponents:
      title:
        id: vue-lm:components/title
      text-image:
        id: vue-lm:components/text-image
      component-with-area:
        id: vue-lm:components/component-with-area

FreeMarker render type

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

With `variations` property

title: 'Sitemap'
renderType: freemarker
templateScript: /sitemap-magnolia/templates/pages/sitemap.ftl
visible: true
variations:
  xml:
    templateScript: /sitemap-magnolia/templates/pages/sitemap-xml.ftl

Referencing templates with the `id` property

A main area definition referencing the MTK’s textImage and linkList components in the availableComponents node.

templateScript: /my-module/templates/pages/my-template.ftl
renderType: freemarker
areas:
  main:
    availableComponents:
      textImage:
        id: mtk2:components/textImage
      linkList:
        id: mtk2:components/linkList

Template definition