Blueprints Configuration

Blueprints for new channels

The channel manager can create new channels at runtime. A new channel is always created from a  blueprint, which defines the HST configuration and content to use for the new channel. When a new channel is created, various parts are added to the existing HST configuration (i.e. a new channel, mount, site, and configuration nodes). The names for those HST configuration parts are based on the name of the channel.

All blueprints are located in

/hst:hst/hst:blueprints

The structure of a blueprint node looks like:

+ hst:hst
    + hst:blueprints
        + example-blueprint
            - hst:name (string)
            - hst:description (string)
            - hst:contentRoot (string)
            + hst:configuration
            + hst:channel
            + hst:mount
            + hst:site

A blueprint can have the following properties:

• hst:name Name of the blueprint shown in the blueprint selection dialog in the CMS.

• hst:description Description of the blueprint shown in the blueprint selection dialog in the CMS.

• hst:contentRoot The node to copy bootstrap content of a blueprint to. The default is /content/documents. Only applicable to blueprints with content (see below).

A blueprint can contain the following child nodes:

• hst:configuration
  Contains all HST configuration needed for new channels created from this blueprint: sitemenus, sitemap, components, templates, etc. Which configuration parts are included depends on the use case.

• hst:channel
  The hst:channel node must have a string property hst:channelinfoclass that contains the fully qualified name of the ChannelInfo interface to use. Optionally, a child node hst:channelinfo can be added with the initial persisted values for the channel properties. If omitted, getters of the channel info interface will return the default values set in the @Parameter annotations.

• hst:mount
  Only needed when a mount of a channel created from this blueprint needs additional properties. If present, the mount node in the blueprint (including all its properties) is copied to the right location under hst:hosts when a new channel is created. If a blueprint does not contain an hst:mount node, a new one will be created from scratch. The hst:locale property of a new mount will always be set to the locale of the content root path of a new channel.

• hst:site
  Only needed when channels created from this blueprint reuse existing content and/or existing HST configuration. To reuse existing content, the hst:site node must contain a property hst:content of type String whose value is the path to the content root node to use (e.g. /content/documents/myhippoproject), just like regular hst:site nodes.
  It is also possible to refer to an existing HST configuration by setting the property hst:configurationpath of the hst:site node to the absolute path to that configuration (e.g. /hst:hst/hst:configurations/myhippoproject). All channels created from this blueprint will then reuse the same HST configuration.
  Reusing HST configuration is not recommended, because editing a channel created from this blueprint in the Channel Manager will then modify the configuration of  all channels created from this blueprint. It is only applicable when the reused HST configuration cannot be changed by end users.

A blueprint can be set up in various ways, depending on the type of channel. Some possible options are described below.

Blueprint with content ('subsite')

A blueprint with content is also referred to as a 'subsite'. It reuses the HST components that are in a particular (site) application, but has its own content tree. Such a blueprint typically has the following structure:

+ hst:hst
    + hst:blueprints
        + example-subsite
            - hst:contentRoot = /content/documents/subsites
            - hst:description = Create a new subsite
            - hst:name = Subsite
            + hst:channel
            |   - hst:channelinfoclass = org.example.channels.SubsiteInfo
            + hst:configuration
                - hst:inheritsfrom = ../common-subsite
                + hst:sitemap
                + hst:sitemenus
                + hst:pages

In system view XML:

<?xml version="1.0" encoding="UTF-8"?>
<sv:node sv:name="example-subsite" xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hst:blueprint</sv:value>
  </sv:property>
  <sv:property sv:name="hst:contentRoot" sv:type="String">
    <sv:value>/content/documents/subsites</sv:value>
  </sv:property>
  <sv:property sv:name="hst:description" sv:type="String">
    <sv:value>Create a new subsite</sv:value>
  </sv:property>
  <sv:property sv:name="hst:name" sv:type="String">
    <sv:value>Subsite</sv:value>
  </sv:property>
  <sv:node sv:name="hst:channel">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hst:channel</sv:value>
    </sv:property>
    <sv:property sv:name="hst:channelinfoclass" sv:type="String">
      <sv:value>org.example.channels.SubsiteInfo</sv:value>
    </sv:property>
  </sv:node>
  <sv:node sv:name="hst:configuration">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hst:configuration</sv:value>
    </sv:property>
    <sv:property sv:multiple="true" sv:name="hst:inheritsfrom"
                 sv:type="String">
      <sv:value>../common-subsite</sv:value>
    </sv:property>
    <sv:node sv:name="hst:sitemap">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hst:sitemap</sv:value>
      </sv:property>
    </sv:node>
    <sv:node sv:name="hst:sitemenus">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hst:sitemenus</sv:value>
      </sv:property>
    </sv:node>
    <sv:node sv:name="hst:pages">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hst:pages</sv:value>
      </sv:property>
    </sv:node>
  </sv:node>
</sv:node>

This example blueprint defines its own sitemap, sitemenus, and pages. It inherits the components, templates, and catalog items from an existing HST configuration called common-subsite.

Subsite bootstrap content

A subsite blueprint typically comes with a bootstrap content structure. Every time a new subsite channel is created, this content structure is copied to the path specified by the blueprint property hst:contentRoot.

The bootstrap content of a subsite is copied by the new-subsite query. For example, the blueprint

/hst:hst/hst:blueprints/example-subsite

can specify its bootstrap content tree under

/hippo:configuration/hippo:queries/hippo:templates/new-subsite/hippostd:templates/example-subsite

For example, a new channel my-subsite created from the example blueprint above would copy the node /hippo:configuration/hippo:queries/hippo:templates/new-subsite/hippostd:templates/example-subsite to /content/documents/subsites/my-subsite.

The XML import of the subsite bootstrap content would look something like:

<?xml version="1.0" encoding="UTF-8"?>
<sv:node sv:name="example-subsite" xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippostd:folder</sv:value>
  </sv:property>
  <sv:property sv:multiple="true" sv:name="jcr:mixinTypes" sv:type="Name">
    <sv:value>hippo:harddocument</sv:value>
  </sv:property>
  <sv:property sv:name="hippostd:foldertype" sv:type="String"
               sv:multiple="true">
    <sv:value>new-document</sv:value>
    <sv:value>new-folder</sv:value>
  </sv:property>
  <!-- add more bootstrap content here -->
</sv:node>

configured in the hippoecm-extension.xml as

<sv:node sv:name="myhippoproject-hippo-queries-new-subsite-template
                                                     -example-subsite">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:initializeitem</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:sequence" sv:type="Double">
    <sv:value>12000</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentresource" sv:type="String">
    <sv:value>configuration/queries/templates/new-subsite/example-subsite.xml
    </sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentroot" sv:type="String">
    <sv:value>
       /hippo:configuration/hippo:queries/hippo:templates
              /new-subsite/hippostd:templates</sv:value>
  </sv:property>
</sv:node>

Blueprint reusing existing content

A blueprint can also reuse existing content. This allows you to first create all the content for a new channel in the CMS (e.g. by translating or copying existing content). The created content tree can then be selected when creating a new channel. Such a blueprint typically has the following structure:

+ hst:hst
    + hst:blueprints
        + example-website
            - hst:description = Create a new website
            - hst:name = Website
            + hst:channel
            |   - hst:channelinfoclass = org.example.channels.WebsiteInfo
            + hst:configuration
            |   - hst:inheritsfrom = ../common-website
            |   + hst:sitemap
            |   + hst:sitemenus
            |   + hst:pages
            + hst:site
                - hst:content = absolute path content root of an existing website

In system view XML:

<?xml version="1.0" encoding="UTF-8"?>
<sv:node xmlns:sv="http://www.jcp.org/jcr/sv/1.0" sv:name="website">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hst:blueprint</sv:value>
  </sv:property>
  <sv:property sv:name="hst:description" sv:type="String">
    <sv:value>Create a new website</sv:value>
  </sv:property>
  <sv:property sv:name="hst:name" sv:type="String">
    <sv:value>Website</sv:value>
  </sv:property>
  <sv:node sv:name="hst:site">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hst:site</sv:value>
    </sv:property>
    <sv:property sv:name="hst:content" sv:type="String">
      <sv:value>
        <!-- TODO: enter path of existing content root node -->
      </sv:value>
    </sv:property>
  </sv:node>
  <sv:node sv:name="hst:channel">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hst:channel</sv:value>
    </sv:property>
    <sv:property sv:name="hst:channelinfoclass" sv:type="String">
      <sv:value>com.example.channels.WebsiteInfo</sv:value>
    </sv:property>
  </sv:node>
  <sv:node sv:name="hst:configuration">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hst:configuration</sv:value>
    </sv:property>
    <sv:property sv:multiple="true" sv:name="hst:inheritsfrom"
                 sv:type="String">
      <sv:value>../common-website</sv:value>
    </sv:property>
    <sv:node sv:name="hst:sitemap">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hst:sitemap</sv:value>
      </sv:property>
    </sv:node>
    <sv:node sv:name="hst:sitemenus">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hst:sitemenus</sv:value>
      </sv:property>
    </sv:node>
    <sv:node sv:name="hst:pages">
      <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hst:pages</sv:value>
      </sv:property>
    </sv:node>
  </sv:node>
</sv:node>

The hst:site node is only used for the initial value of the content root path of a channel in the 'add channel' dialog in the CMS. When no hst:site node is included, the initial value of the content root path of a channel will be empty.