Prototype Pages Configuration

Prototypes pages are configured below hst:prototypepages. When adding a new page through the Experience manager, a copy of the selected prototype page will be added to  hst:workspace/hst:pages. The hst:prototypepages node is of the exact same type as the  hst:pages node, hence the same node structure as for hst:pages is supported at CND level. The relevant CND part is:

[hst:pages] > nt:base, mix:referenceable orderable
+ * (hst:abstractcomponent)

[hst:configuration] > nt:base, mix:referenceable, mix:versionable
// snip
+ hst:pages (hst:pages) = hst:pages
+ hst:prototypepages (hst:pages) = hst:pages
// snip

However  hst:prototypepages have some more constraints with respect to what is allowed. 

hst:prototypepages configuration rules

For prototype pages exactly the same configuration rules apply as for any page below hst:pages except that a node of type  hst:containercomponentreference is not allowed to be a descendant. This means a prototype page can thus have child nodes of the following types:

1. hst:component
2. hst:containercomponent
3. hst:containeritemcomponent

There are however some best practices that in general hold for most prototype pages:

Allowed configuration for prototype pages

1. A prototype can have containers ( hst:containercomponent node) 
2. A prototype can have container items ( hst:containeritemcomponent nodes)
3. A prototype page, just like any other page, can (in general will) extend from an abstract page below hst:abstractpages. Any of its descendant components can also extend components below hst:components (technically also from pages below hst:pages but this is discouraged).

Prototype metadata

Above we saw already that a prototype is (apart from some edge cases) the same as a real page definition below hst:pages. However there is also prototype metadata that can include extra information for the prototype and how it is used. The following metadata mixin is supported on prototype page nodes:

[hst:prototypemeta] mixin
// the name to show for the prototype
- hst:displayname (string)
// the relative path to primary container
- hst:primarycontainer (string)

When the hst:displayname is set, this is the name for the prototype shown in the UI in  Page Management.

The hst:primarycontainer can be used in case of multiple containers to indicate which one gets leftover items when re-applying a prototype (see  Reshuffling of container items when changing page templates on the  Page Management page). When set, it must be the relative path from the page to the container. See below a configuration example

Note that the hst:prototypemeta mixin, when present, gets removed from the page that is created from a prototype. Thus also the displayname and primarycontainer properties.

Example prototype configuration

/hst:prototypepages:
  jcr:primaryType: hst:pages
  /two-columns:
    jcr:primaryType: hst:component
    jcr:mixinTypes: ['hst:prototypemeta']
    hst:displayname: Two columns
    hst:primarycontainer: main/content/right-container
    hst:referencecomponent: hst:abstractpages/base
    /main:
      jcr:primaryType: hst:component
      /content:
        jcr:primaryType: hst:component
        hst:template: two-columns.main.content
        /left-container:
          jcr:primaryType: hst:containercomponent
        /right-container:
          jcr:primaryType: hst:containercomponent

The hst:template  two-columns.main.content refers to a JSP or Freemarker template that includes the left and right containers, for example:

<div class="row-fluid">
  <div class="span6">
    <hst:include ref="left-container"/>
  </div>
  <div class="span6">
    <hst:include ref="right-container"/>
  </div>
</div> 

Prototype pages from inherited configuration

Prototype pages from inherited configurations are supported. When a page is created out of a prototype from inherited configuration, the created page is not stored in the inherited configuration of its workspace but in the workspace of the project. This is because the hst:workspace is not inherited from inherited configurations, as explained in  Workspace configuration.

Re-applying a prototype that has container items:

On the  Page Management page "reshuffling" of container items when changing page templates (prototypes) is explained. Technically we call this re-applying a prototype. There is however a subtlety with respect to re-applying a prototype to a page that already contains items in one or more of its containers. As explained in the section Allowed configuration for prototype pages above a prototype is allowed to have container items in its containers. When a new page is created out of such a prototype, the page directly holds some container items in its containers. Nothing subtle here, just a clone. However, what happens if an existing page is re-applied to the same or a different prototype? 

Re-applying a prototype (called template in the UI) is meant to change the layout of an existing page and not to add possible available container items from the prototype to an existing page. For this reason we implemented it as follows: