Template prototype

Template prototype is like a master page template. Anything you configure in the prototype is applied to all page templates. The prototype makes configuration efficient as you only need to do it once. For example, add an area to the prototype to make it available on all pages. You can override the prototype at the page definition level if needed.

Best practice

Put commonly used things in the template prototype. If most pages on your site have the same areas then define those areas in the prototype.

Do I need a prototype?

No, it is not necessary to use a prototype. You can configure a separate page definition for each page template instead. This works fine if you have a small number of templates that are very different from each other.

Prototype is an optional templating mechanism that offers a number of benefits:

  • Ensures uniformity across templates

  • Avoids repeating and duplicating configuration

  • Creates similar templates quickly

Prerequisites

Configuring a prototype

The prototype definition is a page template definition that must use the info.magnolia.module.site.templates.PrototypeTemplateDefinition class.

You can use all the page template properties.

You can configure a prototype in:

If you have the Multisite module (DX Core) you can configure a different prototype for each site or use the same prototype for all sites.

Configuring a prototype in JCR

In the site definition, configure the prototype in the /templates/prototype node.

Configuring a prototype in YAML

While it is not possible to configure a site definition completely in YAML, you can configure the prototype in YAML and reference it in the site definition. The prototype definition can reside in any module.

To configure the prototype in YAML:

  1. In the site definition:

    1. Set the:

      1. class property to info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings. This class allows you to use a prototype defined in YAML.

      2. prototypeId to the location of the YAML prototype definition in the <module name>:<relative path to definition> format, for example, travel-demo:pages/prototype.

  2. Remove the prototype node, if it exists.

    Example: travel site definition.

    /<module-name>/sites/travel.yaml
    templates:
  class: info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings
  prototypeId: travel-demo:pages/prototype
  availability:
    class: com.example.myModule.site.CustomTemplateAvailability
theme:
  name: travel-demo-theme
i18n:
  class: info.magnolia.cms.i18n.DefaultI18nContentSupport
  enabled: true
  fallbackLocale: en
  locales:
    en:
      enabled: true
      language: en
    de:
      enabled: true

  3. Create the prototype YAML file in the location defined in the prototypeId property and set the class property to info.magnolia.module.site.templates.PrototypeTemplateDefinition (or a subclass).

    https://bitbucket.org/magnolia-cms/travel-demo

Prototype template properties

Prototype is a info.magnolia.rendering.template.TemplateDefinition, which means it supports the same properties as page definition, including Template definition. However, typically you don’t use them all. Here are the typical use cases:

Property Description

areas

optional

Common areas such as footer or navigation that are used on most pages.

Each child node is an area definition. Define the areas in the prototype so you don’t have to repeat them in each page definition.

templateScript

optional

The templateScript property allows you to define a common page template script for the whole site. For a page to inherit its template script from the prototype you must also define renderType=site in the template definition.

A page template script typically starts with an opening <html> element and ends with the closing </html> element when rendering HTML output.

See main.ftl file in the Travel Demo.
Example

The Travel Demo defines a template script in the prototype. This common script is used for all pages.

It is also the reason why no YAML page definition in the demo has an explicit templateScript property. The page definitions set renderType=site to inherit the script from the prototype, see home.yaml for example in the travel demo repository.

$type

required, if the class property is not defined in the template definition.

An alias specifying the type of the prototype.

Use the following values:

  • prototype for ordinary prototypes.

  • spaPrototype for SPA-based prototypes.

class

optional

A custom definition class that extends info.magnolia.rendering.template.configured.ConfiguredTemplateDefinition (an implementation of info.magnolia.rendering.template.TemplateDefinition). You only need a custom class if you want to add your own nodes and properties in the prototype. Implement corresponding methods to operate on those properties in the definition class.

Example

PageTemplateDefinition is a custom definition class used in the Travel Demo. It adds support for a jsFiles node, which allows you to define JavaScript files in the prototype the same way a theme defines them.

See an overview of differences between FreeMarker and headless templating.

Merging a prototype with a page definition

When a user requests a page Magnolia merges the prototype with a page definition. The result is a merged template definition which is then used to render the page.

The merged definition is virtual. You won’t find its configuration anywhere. It is created dynamically at the time of rendering. However, you can access the merged definition in a template script using the def rendering context object.

Example: Merging a prototype (configured in JCR) with a home page definition (configured in YAML)

  1. Prototype defines the main area type as list. Page definition adds availableComponents for the area. The result contains both.

  2. Prototype defines a templateScript. Page definition says nothing about script. The result is that the home page uses the script defined in the prototype.

  3. Prototype defines the footer area as not editable. Page definition overrides this decision by allowing footer editing on the home page. The result is that the footer can be edited on the home page only.

  • Prototype

  • Page template definition

  • Merged template definition

Prototype definition

home.yaml
renderType: site
areas:
  footer:
    editable: true
  main:
    availableComponents:
      textImage:
        id: mtk2:components/textImage
      teaserInternal:
        id: mtk2:components/teaser

Merged template definition

Feedback

DX Core

×

Location

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

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules