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
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
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 should be used. Magnolia supports
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 external SPA setups) 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 (in external SPA setups) A format of a string appended to the Example:
Available properties In addition to Double brackets vs single brackets Double curly brackets and single curly brackets are interpreted differently. The parameter inside double curly brackets +
In case you need to use path as a parameter or other parameters with characters such as
|
||
|
optional (in external SPA setups) 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 The ID has two parts, separated by a colon:
|
||
|
optional Message
bundle such as |
||
|
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:
|
||
|
optional Template description displayed to editors. The value can be literal or
retrieved from the message bundle (specified by |
||
|
required if the An alias for the Java bean representing the definition data of this item. Use the following values:
|
||
|
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:
|
||
|
optional A model class that contains business logic for the template. The
class needs to implement the
RenderingModel interface.
The renderer creates a bean based on the A Groovy model class can be referenced from a YAML template definition. Current limitations:
Value:
|
||
|
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 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
To access the example
parameter in a Freemarker script, use:
${def.parameters.example!}
Referencing templates
Other configuration nodes can reference templates. The property used in the referencing configuration depends on the mechanism that is 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: main
area definition referencing the
MTK’s textImage
and linkList
components in the availableComponents
node.
my-module/templates/pages/myTemplate
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
The ID has two parts separated by a colon:
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: Is used in YAML definitions to include a referenced file. The Magnolia-specific
!include
directive uses the absolute path to reference the file. -
Extends mechanism: Is 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, field types, templates and more.