Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
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.
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:
Configure a prototype in a site definition, under the /templates/prototype
node. If you have the Multisite module (EE Pro) you can configure a different prototype for each site or use the same prototype for all sites.
Example: Prototype in the Travel Demo site (partial example).
Node name | Description |
---|---|
prototype | |
areas | |
navigation | |
footer | |
main | |
htmlHeader | |
class | info.magnolia.demo.travel.definition.PageTemplateDefinition |
templateScript | /travel-demo/templates/pages/main.ftl |
Prototype is a TemplateDefinition which means it supports the same properties as page definition, including common template properties. However, typically you don't use them all. Here are the typical use cases:
| 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. |
| optional The A page template script typically starts with an opening Example: The travel demo 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 |
| optional A custom definition class which extends ConfiguredTemplateDefinition , an implementation of 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
(Git) is a custom definition class used in the Travel Demo. It adds support for a |
Magnolia 5.4.8+
It is not possible to configure a site completely by YAML, but the prototype can be defined with YAML. You have to edit the JCR configuration of the site and create a YAML file.
<your-site>/templates
in JCR configuration
prototype
node from the JCR configuration of your site (<your-site>/templates/prototype
). You may want to keep the node until you have created the prototype YAML file.<your‑site>/templates@class
property to info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings
. This class allows you to use a prototype defined in YAML.<your‑site>/templates@prototypeId
property to the YAML file which actually defines the prototype. The syntax of the property value follows the template ID notation <module-name>:pages/<name>
, for instance travel-demo:pages/prototype
.Example: JCR site definition used together with a YAML defined prototype. This example is from the travel demo.
Node name | Value |
---|---|
travel | |
templates | |
availability | |
class | info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings |
prototypeId | travel-demo:pages/prototype |
theme | |
i18n |
Since a site prototype definition is a page template definition, the YAML file for the prototype is just a page template definition written in YAML. However it requires a special value for the class
property which must be info.magnolia.module.site.templates.PrototypeTemplateDefinition
(or a subclass).
class: info.magnolia.module.site.templates.PrototypeTemplateDefinition
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)
main
area type as list
. Page definition adds availableComponents
for the area. The result contains both.templateScript
. Page definition says nothing about script. The result is that the home page uses the script defined in the prototype.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: prototype areas footer availableComponents textImage id linkList id editable type main type templateScript Page template definition: Merged template definition: prototype areas footer availableComponents textImage id linkList id editable type main availableComponents textImage id teaser id type templateScriptBefore merge After merge Node name Description mtk:components/textImage mtk:components/linkList false list list /example/templates/pages/main.ftl renderType: site
areas:
footer:
editable: true
main:
availableComponents:
textImage:
id: mtk:components/textImage
teaserInternal:
id: mtk:components/teaser
Node name Description mtk:components/textImage mtk:components/linkList true list mtk:components/textImage mtk:components/teaser list /example/templates/pages/main.ftl