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.
Common template properties
renderType: freemarker
templateScript: /my-module/templates/pages/home.ftl
dialog: my-module:pages/homePageProperties
class: com.example.templates.CustomTemplateDefinition
modelClass: com.example.templates.HomePageModel
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 Example
You can also create a custom renderer. |
||
|
required Path to the template script as
|
||
|
required In an external SPA configuration, an external URL which the page editor iFrame must point to. Example
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 Example
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. |
||
|
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 Model class that contains business logic for the template. The
class needs to implement the
RenderingModel interface.
The renderer creates a bean based on A Groovy model class can be referenced from a YAML template definition.
|
||
|
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. sitemap/templates/pages/sitemap.yaml
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. |
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.
- Example
-
A
main
area definition referencing the MTK’stextImage
andlinkList
components in theavailableComponents
node.
templateScript: /my-module/templates/pages/my-template.ftl
renderType: freemarker
areas:
main:
availableComponents:
textImage:
id: mtk2:components/textImage
linkList:
id: mtk2:components/linkList
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.