Template definition

A template definition gives a template a name and makes it available to the system.

At a minimum, a SPA template definition must specify a renderer type ($type property) and base URL (baseUrl).

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.

Template properties

Property Description

$type

required

Alias representing the definition data of this item.

Use the following values:

  • siteSpa for a site-aware SPA template.

  • spa for any other SPA template.

baseUrl

required

An external URL which the page editor iFrame must point to.

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, @sitePath, @id or the prefixed mgnl:* and jcr:* properties).

  • @id

  • @name

  • @path

  • @sitePath

  • id

  • language

  • lastModified

  • path

  • sitePath

  • slug

  • and custom properties

    • slug is an alias of @name.

    • @name is different from name:

      • @name is a node name.

      • name is a content property.

    • @path and path are the same property.

    • @sitePath and sitePath are the same property.

      Returns a path without the handlePrefix defined in site definition.

      For example, if the site is /path/to/site, then @sitePath only returns /sub/path from /path/to/site/sub/path.

    • @id and id are the same property.

    • lastModified returns the last modified date, and the value is java.time.Instant#toString.

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

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 the YAML file /my-module/dialogs/homePageProperties.yaml.

renderType

optional

Defines which renderer to use. Magnolia SaaS supports the spa and site-spa renderers by default.

For site-aware SPA rendering, the value is site-spa.

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.

parameters

optional

Custom template properties that you can access (reference and use) in routeTemplate.

extends

optional

Inherits the configuration from another template definition. The value is a valid Magnolia path.

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.

parameters:
  example: my-value

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 the YAML file $magnolia.resources.dir/my-module/templates/pages/home.yaml.

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

You can use the following mechanisms to reuse a configuration:

  • Include mechanism, used in YAML definitions to include a referenced file. The Magnolia-specific !include directive uses the absolute path to reference the file.

  • Definition decoration, allowing you to alter the existing configured items, such as apps, dialogs, fields, templates and more.

Configuration examples

With baseUrl property

$type: spa
title: 'React: Contact'
baseUrl: http://example.com
dialog: spa-lm:pages/basic

With baseUrl and routeTemplate properties

$type: spa
title: 'React: Contact'
baseUrl: http://localhost:3000
routeTemplate: '{{path}}?lang={language}'
dialog: spa-lm:pages/basic

Site SPA render type

$type: siteSpa
visible: true
dialog: mte:pages/pageProperties
baseUrl: http://localhost:3100/magnoliaAuthor
routeTemplate: '{{@path}}'

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
Related topics
Feedback

SaaS

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Magnolia SaaS docs.

Main doc sections

DX Core Headless SaaS PaaS Legacy Cloud Incubator modules