Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.

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 a special class:  . You can use all the page template properties.

You can configure a prototype in:

 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.

Configuring a prototype in JCR

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

Example: Prototype in the site definition in the Site app.

Node nameDescription

 templates

 

 prototype

 

 areas

 

 navigation

 

 footer

 

 main

 

 htmlHeader

 

 class

info.magnolia.my-module.definition.PageTemplateDefinition

 templateScript

/my-module/templates/pages/main.ftl

 renderType

site

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 in /<site name>/templates :
    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.

    Exampletravel site definition in the Site app.

    Node nameValue

     travel

     

     templates

     

     availability

     

     class

    info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings

     prototypeId

    travel-demo:pages/prototype

     theme

     

     i18n

     
  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).


     # When using 'renderType=site' all pages inherit their 'templateScript' value from the site definition which is
    # globally defined for whole the site. This is the reason no page YAML definition defines an explicit 'templateScript'
    # to use. The value inherited and currently used is:
    # templateScript: /travel-demo/templates/pages/main.ftl
    # This might be replaced with the template from 'travel-demo-marketing-tags':
    # templateScript: /travel-demo-marketing-tags/templates/pages/main-marketing-tags.ftl
    
    dialog: mtk2:pages/basic
    class: info.magnolia.module.site.templates.PrototypeTemplateDefinition
    
    templateScript: /travel-demo/templates/pages/main.ftl
    renderType: site
    type: feature
    
    jsFiles:
      - link: /.resources/travel-demo-theme/libs/twitterbootstrap/js/bootstrap.min.js
        addFingerPrint: true
      - link: /.resources/travel-demo-theme/libs/twitterbootstrap-extras/ie10-viewport-bug-workaround.js
        addFingerPrint: true
      - link: /.resources/travel-demo-theme/js/viewport-units-buggyfill.js
        addFingerPrint: true
    
    areas:
      htmlHeader:
        createAreaNode: false
        renderType: freemarker
        templateScript: /travel-demo/templates/pages/areas/htmlHeader.ftl
        type: noComponent
      main:
        type: list
      footer:
        editable: false
        templateScript: /travel-demo/templates/pages/areas/footer.ftl
        type: noComponent
        parameters:
          columns: 4
        areas:
          footer1: &footer1
            type: list
            templateScript: /travel-demo/templates/pages/areas/contentContainer.ftl
            parameters:
              cssClass: col-md-3
            inheritance:
              components: all
              enabled: true
            availableComponents:
              textImage:
                id: travel-demo:components/textImage
              linkList:
                id: travel-demo:components/linkList
          footer2: *footer1
          footer3: *footer1
          footer4: *footer1
      navigation:
        class: info.magnolia.demo.travel.definition.NavigationAreaDefinition
        createAreaNode: false
        modelClass: info.magnolia.demo.travel.model.NavigationAreaModel
        renderType: freemarker
        templateScript: /travel-demo/templates/pages/areas/navigation.ftl
        type: noComponent
        userLinksResolvers:
          public-user-registration:
            class: info.magnolia.demo.travel.user.DefaultUserLinksResolver
            loginPageTemplateId: public-user-registration:components/login
            profilePageTemplateId: public-user-registration:components/userUpdate
            registrationPageTemplateId: public-user-registration:components/registration
    

Prototype template properties

Prototype is a  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:

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 in the Travel Demo.

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 templateScript property. The page definitions set renderType=site to inherit the script from the prototype, see home.yaml for example.

class

optional

A custom definition class which extends , an implementation of . 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: (Git) 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.

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.


Before mergeAfter merge

Prototype:

Node nameDescription

  prototype

 

  areas

 

  footer

 

  availableComponents

 

  textImage

 

  id

mtk:components/textImage

  linkList

 

  id

mtk:components/linkList

  editable

false

  type

list

  main

 

  type

list

  templateScript

/example/templates/pages/main.ftl

Page template definition:

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

Merged template definition:

Node nameDescription

  prototype

 

  areas

 

  footer

 

  availableComponents

 

  textImage

 

  id

mtk:components/textImage

  linkList

 

  id

mtk:components/linkList

  editable

true

  type

list

  main

 

  availableComponents

 

  textImage

 

  id

mtk:components/textImage

  teaser

 

  id

mtk:components/teaser

  type

list

  templateScript

/example/templates/pages/main.ftl

12 Comments

  1. I'm trying to use a yaml prototype with a page template definition but I'm missing something thus getting an error message on trying to edit the home page.

    Here are the related yaml files and the error messages: https://pastebin.com/4YYatYd5

    Here the site definition:

     

    1. Can you enlarge that screenshot in width?  I'd like to see the values of

      • /capitaly/templates@class
      • /capitaly/templates@prototypeId


      1. Christoph Meier, sure:

        • class: info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings
        • prototypeId: presentation:pages/main

        and actually there is a thing with which I"m not sure if is right in my prototype main.yaml file I have a `dialog: mte:pages/pageProperties` It is a CE bundle but until changing it to be in accordance with the samples here it has its own dialog file created with the cli. But both ways it gives the template error: No template script defined for the template definition 

        [info.magnolia.rendering.template.configured.ConfiguredTemplateDefinition@2ea44d02[id=presentation:pages/home,name=home,renderType=site,description=<null>,title=<null>,templateScript=<null>,autoGeneration=info.magnolia.rendering.template.configured.ConfiguredAutoGeneration@1558bcc4[content={},generatorClass=<null>]

        Have found a trace of others having this same issue, and Stef te Winkel 's proposed solution was: 

        - using class info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings in Site Module
             that's right

        - using enableAll true with availability and empty templates content node
             I don't have enableAll as neither has this documentation

        - using class: info.magnolia.module.site.templates.PrototypeTemplateDefinition and renderType:site in prototype template
             that's right

        - using class: info.magnolia.module.site.templates.PageTemplateDefinition in Page template definition with renderType: site
             I wasn't using class as the home.yaml here doesn't uses it neither, tried with it, didn't make difference
        - when switching from JCR setup to Yaml setup, don't forget to delete the Prototype node
             I wasn't using JCR setup, no prototype node

        So I still couldn't solve it.


        1. Obeliksz  - Note that you will have a bigger audience when asking questions at the Magnolia google groups

          1. Right, have posted there.

        2. I'm confused here. The CE bundle only allows for a single site definition. So having the node capitaly would be incorrect.

          1. Please see the comments on Site definition , where my question was if there is only one (the first) content node it will be considered to contain the site definition... So having a top node is error if not in multisite mode?

            1. Exactly, when the multisite module is not installed there is no need for that top node. This node config:/modules/site/config/site is your top level node. Configure off of that.

              1. first I tried to just move every node out of `capitaly` and delete the `capitaly` node, that way no template was found, then moved all the nodes inside a `site` content node, so no I have the same error as I had before. I guess it doesn't matter what name it has that single top content node - but it did cause some confusion for me too.

                1. If you are using CE it expects to find the site configuration off the site node. It must be called site. If you configure another node, such as capitaly, in between the site node and your configuration the system will not load the configuration. Have a look here. You can see the path is mentioned there.

                  If you are still having an issue, I would say it's related to template availability. 

                  1. Richard Gange I've moved the items from the config:/modules/site/config/site/capitaly cn into the config:/modules/site/config/site cn and this way it does not see any page definition: when going to the pages app it alerts that none are found. When putting them inside the cn config:/modules/site/config/site/capitaly or config:/modules/site/config/site/site it works. Revisiting the source code that you've linked it should be working from config:/modules/site/config/site as you said... weird issue.

                    In both case in the resource files app I see my light module and its template files to be registered.

                    1. Have started it all over from scratch and it works now...