Template Queries

Overview

This page explains template queries in Bloomreach Content, their purpose, and how they are stored and configured in the repository.

Purpose of Template Queries

When CMS users create new documents or subfolders within a content folder, they select from available "Add ..." options in the folder's context menu. Each option corresponds to a document or folder type. The system creates the new item by copying a template and substituting default property values as needed.

Template queries define:

Which "Add ..." options appear in the CMS UI
Which document or folder types are available for each option
How property values are substituted when creating new items

This page describes the configuration of template queries, including node types, properties, and their relationships. Examples illustrate these concepts.

For a step-by-step example of custom template queries, see Control Which Document Types Can Be Used in Which Folder.

You can generate template queries for custom document types using the Essentials development tools.

Folder Types and Template Queries

How Folder Types Reference Template Queries

Content folders (hippostd:folder nodes) have a multi-valued String property, hippostd:foldertype. Each value in this property references a template query. Each referenced template query appears as an "Add ..." option in the folder's context menu in the CMS UI.

Template queries are stored as nodes of type hippostd:templatequery at:

/hippo:configuration/hippo:queries/hippo:templates

The hippostd:templatequery node type extends the JCR node type nt:query and includes:

[nt:query] > nt:base
  - jcr:statement (string)
  - jcr:language (string)

jcr:statement contains the query statement.
jcr:language specifies the query language (xpath, sql, JCR-SQL2, or JCR-JQOM).

The query selects the template nodes for the document or folder types available for the corresponding "Add ..." option.

Document templates are stored as prototype documents within the document type definitions. Example:
```
/hippo:namespaces/myproject/newsdocument/hipposysedit:prototypes/hipposysedit:prototype
```

Folder templates are stored within the template query node structure. Example:

/hippo:configuration/hippo:queries/hippo:templates/new-translated-folder/hippostd:templates/hippostd:folder

Excluding Specific Primary Node Types

To exclude certain primary node types from a template query, add the hippostd:excludePrimaryTypes property to the hippostd:templatequery node.

By default, the new-document template query at /hippo:configuration/hippo:queries/hippo:templates/new-document has an empty hippostd:excludePrimaryTypes: []. You can add node types to exclude them from the query results. For example, to prevent the taxonomy document type (hippotaxonomy:taxonomy) from appearing as an option:

definitions:
  config:
    /hippo:configuration/hippo:queries/hippo:templates/new-document:
      hippostd:excludePrimaryTypes:
        operation: add
        value: [hippotaxonomy:taxonomy]

This configuration ensures that the new-document template query does not offer taxonomy documents as an option.

Example: Folder Types and Template Queries

Consider a project created using the Maven archetype with default settings. The content root folder /content/documents/myproject defines two folder types:

/content/documents/myproject:
  jcr:primaryType: hippostd:folder
  hippostd:foldertype: [new-translated-folder, new-document]

Each value in hippostd:foldertype references a template query under /hippo:configuration/hippo:queries/hippo:templates.

Localized labels for template queries are defined in resource bundles at /hippo:configuration/hippo:translations/hippo:templates:

/hippo:configuration/hippo:translations/hippo:templates:
  jcr:primaryType: hipposys:resourcebundles
  /en:
    jcr:primaryType: hipposys:resourcebundle
    new-document: new document
    new-translated-folder: new translated folder

In the CMS UI, the context menu for the myproject folder displays a localized menu option for each template query referenced in hippostd:foldertype:

Structure of a Folder Template Query

The new-translated-folder template query node has the following structure:

/hippo:configuration/hippo:queries/hippo:templates/new-translated-folder:
  jcr:primaryType: hippostd:templatequery
  /hippostd:templates:
    jcr:primaryType: hippostd:templates
    /hippostd:folder:
      jcr:primaryType: hippostd:folder
      hippostd:foldertype: [new-translated-folder, new-document]
  jcr:language: xpath
  jcr:statement: /jcr:root/hippo:configuration/hippo:queries/hippo:templates/new-translated-folder/hippostd:templates/node()

The folder template is defined within the template query node structure.
The template includes hippostd:foldertype values for the new folder created from this template.
The query statement selects template nodes within this structure.

When a user selects Add new translated folder in the CMS UI, a dialog appears for entering the folder name. Because this template query returns only one result, the dialog does not prompt for folder type selection.

New translated folder dialog with name and URL fields

Structure of a Document Template Query

The new-document template query node is defined as follows:

/hippo:configuration/hippo:queries/hippo:templates/new-document:
  jcr:primaryType: hippostd:templatequery
  jcr:language: xpath
  jcr:statement: //element(*,hipposysedit:namespacefolder)/element(*,mix:referenceable)/element(*,hipposysedit:templatetype)/hipposysedit:prototypes/element(hipposysedit:prototype,hippo:document)

The query statement selects all hipposysedit:prototype nodes of type hippo:document within the document type definitions in /hippo:namespaces.
Since all document types inherit from hippo:document, a folder with this template query allows users to create documents of any type in that folder.

When a user selects Add new document in the CMS UI, a dialog appears for entering the document name and selecting a document type from a dropdown list.

New document dialog with document type dropdown options

Value Substitution

How Value Substitution Works

When a user creates a new document or folder, the system copies the selected template to the target folder. Some property values in the new node may depend on context, such as the current date, the user, or values entered in the creation dialog.

Template query nodes support a multi-valued property, hippostd:modify, which specifies which properties to substitute and the values to use. The special _name pseudo property allows you to set the node name.

Each entry in hippostd:modify alternates between a relative property path and the value to substitute.
Paths are relative to the root of the selected template node.
The _node wildcard in paths matches any node.

The following table lists available substitution values:

Substitution Value	Description
`$name`	The URL name entered in the creation dialog.
`$holder`	The current user's ID.
`$now`	The current date and time in `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format.
`$inherited`	Copies the property value from the parent node.
`$uuid`	Generates a new UUID.

You can use math functions with $now. Supported time units:

Y (year)
M (month)
D (day)
H (hour)
MIN (minute)
SEC (second)
MIL (millisecond)

Examples:

$now/H: Start of the current hour
$now/D: Start of the current day
$now+2Y: Two years from now
$now-1D: One day before now
$now+6M+3D/D: Six months and three days from now, rounded down to the nearest day

Substitution only occurs if the specified property exists on the template node. If the property does not exist, it is ignored.

Example: Value Substitution in Template Queries

The new-translated-folder template query defines the following hippostd:modify values:

/hippo:configuration/hippo:queries/hippo:templates/new-translated-folder:
  jcr:primaryType: hippostd:templatequery
  hippostd:modify: [./_name,
                       $name,
                       ./hippotranslation:id,
                       $uuid,
                       ./hippotranslation:locale,
                       $inherited]

This configuration results in:

The new node's name is set to the URL name entered by the user.
The hippotranslation:id property is set to a newly generated UUID.
The hippotranslation:locale property is set to the value from the parent node.

The new-document template query uses additional hippostd:modify pairs, such as:

./hippostdpubwf:createdBy
$holder
Sets the hippostdpubwf:createdBy property to the username of the user creating the document.
./hippostdpubwf:creationDate
$now
Sets the hippostdpubwf:creationDate property to the current date and time.