Template definition
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 | ||
---|---|---|---|
|
required for
The property specifies which renderer to use. Magnolia supports the
If you have the Site module,
you can set You can also create a custom renderer. |
||
|
optional Dialog definition ID in
|
||
|
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:
|
||
|
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. |
||
|
required if Alias for the Java bean representing the definition data of this item. Use the following values:
|
||
|
optional Fully qualified class name for the Java bean representing the
definition data of this item. The default class is
Only set the value when using a custom definition class (for example,
|
||
|
optional Custom template properties that you can access from a script without having to write a class. |
||
|
optional (in JCR node configuration only) Inherits the configuration from another template definition. The value is a valid Magnolia path. See Reusing configuration. |
||
|
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 |
---|---|
|
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 |
|
optional Format of a string appended to
Examples With
http://localhost:3000/?title=The string ü@foo-bar
http://localhost:3000/?title=The+string+%C3%BC%40foo-bar |
|
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 | ||
---|---|---|---|
|
required Path to the template script (in
|
||
|
optional Model class that contains business logic for the template. The
class needs to implement the
info.magnolia.rendering.model.RenderingModel interface.
The renderer creates a bean based on A Groovy model class can be referenced from a YAML template definition.
|
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 | ||
---|---|---|---|
|
required ID of the template definition in
You can reference templates from any module.
|
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
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