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:
      hst:description:
      hst:contentRoot:
      /hst:configuration:
        /hst:pages:
        /...:
        /...:
        /hst:workspace:
          /...:
          /hst:channel:
            /hst:channelinfo:
      /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.
  Note the hst:channel node can also be a sibling (instead of child) of the hst:workspace node. Regardless of whether the hst:channel is a sibling or child of the hst:workspace, when the blueprint is used to create a new channel, the hst:channel node of the configuration of the new channel will always be below the hst:workspace! Next to that, if the blueprint does not have a hst:channel node, when the blueprint is used, below the hst:workspace still an hst:channel node is created (and even if the blueprint did not define an hst:workspace node at all). Thus:
  Always an hst:channel below the hst:workspace is created for the newly created channel, regardless of where the hst:channel is in the blueprint and regardless of whether the blueprint has an hst:channel node at all.

• 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/myproject), 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/myproject). All channels created from this blueprint will then inherit that HST configuration via the hst:inheritsfrom property.

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:configuration:
        hst:inheritsfrom: [../common-subsite]
        /hst:sitemap:
        /hst:sitemenus:
        /hst:pages:
        /hst:workspace:
          /hst:channel:
            hst:channelinfoclass: org.example.channels.SubsiteInfo

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 YAML source definition for the subsite would look something like:

definitions:
  config:
    /hippo:configuration/hippo:queries/hippo:templates/new-subsite/hippostd:templates/example-subsite:
      jcr:primaryType: hippostd:folder
      jcr:mixinTypes: ['hippo:harddocument']
      hippostd:foldertype: [new-document, new-folder]
      # add more bootstrap content here

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:configuration:
        hst:inheritsfrom: ../common-website
        /hst:sitemap:
        /hst:sitemenus:
        /hst:pages:
        /hst:workspace:
          /hst:channel:
            hst:channelinfoclass: org.example.channels.WebsiteInfo
      /hst:site:
         hst:content: absolute path content root of an existing website

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.