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.

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

• Site module. You need to install the Site module and configure a site definition in order create a prototype.

Configuring a prototype in JCR

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

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:

Configuring a prototype in YAML

  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.

1. Edit <your-site>/templates in JCR configuration

1. Remove the  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.
2. Set the <your‑site>/templates@class property to info.magnolia.module.site.templates.ReferencingPrototypeTemplateSettings. This class allows you to use a prototype defined in YAML.
3. Set the <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.

2. Create a prototype YAML file

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

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.

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