Blueprints Configuration - Enterprise Java Content management system - Hippo CMS

Blueprints Configuration

When making changes to blueprints through the Console, to be able to see the changes in the CMS Channel Manager at 'Add Channel', you need to logout and login again to the CMS.

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

For more information about HST configuration inheritence see Adding a new (sub)site.

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.

If there is both a hst:site node with hst:content property pointing to a site  and a matching subsite node below  /hippo:configuration/hippo:queries/hippo:templates/new-subsite/hippostd:templates (in other words you have 'blueprint reusing existing content' and 'Subsite bootstrap content' both configured), then, the latter ('Subsite bootstrap content' has precedence).

Blueprints Configuration

When making changes to blueprints through the Console, to be able to see the changes in the CMS Channel Manager at 'Add Channel', you need to logout and login again to the CMS.

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

For more information about HST configuration inheritence see Adding a new (sub)site.

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.

If there is both a hst:site node with hst:content property pointing to a site  and a matching subsite node below  /hippo:configuration/hippo:queries/hippo:templates/new-subsite/hippostd:templates (in other words you have 'blueprint reusing existing content' and 'Subsite bootstrap content' both configured), then, the latter ('Subsite bootstrap content' has precedence).