Repository Initialization Instructions

Introduction

Goal

Create repository initialization instructions

Summary

During startup of a repository, when it is started for the first time or with the system property repo.bootstrap=true, preconfigured initialization actions are performed if they were not performed before or if they are scheduled to be reloaded. The initialization actions are declared in files named hippoecm-extension.xml. Any jar included in the CMS application may contain such a file in its root directory.

hippoecm-extension.xml

The file hippoecm-extension.xml itself is written in JCR System View XML and consists of a list of node declarations of type hippo:initializeitem. Each node configures an initialization action that is performed during the bootstrap phase of a repository startup.

The repository keeps a record of which initialization items it has run. If an initialization action was already performed on that repository during a previous initialization phase, it is not performed again, except for repository resource bundles which are always and automatically reloaded. This allows you to use the hippoecm-extension.xml to add custom content to an existing repository, without overwriting existing content.

<?xml version="1.0" encoding="UTF-8"?>
<sv:node xmlns:sv="http://www.jcp.org/jcr/sv/1.0"
         xmlns:ae="http://www.onehippo.org/jcr/autoexport/1.0"
    sv:name="hippo:initialize" ae:id="gettingstarted">
  <sv:property sv:name="jcr:primaryType" sv:type="Name">
    <sv:value>hippo:initializefolder</sv:value>
  </sv:property>

  <!-- Document types -->
  <sv:node sv:name="gettingstarted">
    <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>30050</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:namespace" sv:type="String">
      <sv:value>http://www.onehippo.org/gettingstarted/nt/1.0</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:nodetypesresource" sv:type="String">
      <sv:value>namespaces/gettingstarted.cnd</sv:value>
    </sv:property>
  </sv:node>

  ...

</sv:node>

Initialization Nodes

The example shows one node of type hippo:initializeitem, but the file may contain any number of such nodes. The node shown happens to be named 'gettingstarted'. This name must uniquely identify the initialization action. If there are multiple initialize items with the same name, only one of them will get executed. If the name of the item is changed to a new unique name, the initialization action is performed again on the next startup of the same repository. Except when registering a namespace, this name has no additional meaning. 

Various Initialization Actions

Different kinds of initialization actions have their own specific properties to be specified.  In short you are able to:

• Register a namespace;
• Import node type definitions (CNDs);
• Import resource bundles;
• Import content and configuration (nodes and properties) from (enhanced) system view XML;
• Change content and configuration (nodes and properties);
• Set individual properties;
• Delete existing content and configuration.

Initialize item ordering

Initialize items are execured in three groups: first all namespaces registration actions are performed, then all node type definition import actions, and finally all other actions. Within these groups, initialize items are ordered using their sequence property. The sequence numbers control the order in which the initialization actions are performed. Actions with lower numbers are performed before actions with higher numbers.

In case two initialize items have the same sequence number their initialization is ordered according to the following rules:

1. (Repository 4.0.4+) standard initialize items (not using Enhanced XML Import delta-merge)  are ordered before delta-merge contentresource items
2. standard initialize items are ordered on their  upstream-downstream relationship (if applicable)
3. if still equal (which includes two delta-merge initialize items) the items are ordered using their name (alphabetically).

Sequence Numbers Dependencies

The value of a sequence number can be important if an initialization action assumes other parts to be loaded first. For example, loading a custom namespace should always occur after the 'hippo' namespace has loaded because custom document type normally extend hippo:document.

A general guideline for sequence number values is this:

• CMS core: < 5000
• CMS plugins and add-ons: 5000 - 20000
• Hippo Forge plugins: 20000 - 30000
• Implementation projects > 30000

Register a Namespace

This is done by defining the property hippo:namespace and give it the namespace uri as its value. The name of the initialize item node is used as the namespace prefix. The following example registers the namespace uri   http://www.onehippo.org/jcr/myhippoproject/2.0 with the prefix  myhippoproject.

  <sv:node sv:name="myhippoproject">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hippo:initializeitem</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:namespace" sv:type="String">
      <sv:value>http://www.onehippo.org/jcr/myhippoproject/2.0</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:sequence" sv:type="Double">
      <sv:value>31050.0</sv:value>
    </sv:property>
  </sv:node>

Import a Node Type Definition

Node type definitions are written in Compact Node Notation in compact node type definition files. These files can be imported using an initialize item that has a property  hippo:nodetypesresource with the relative path to this file as its value. The following example imports the node type definitions of the example myhippoproject:

  <sv:node sv:name="myhippoproject-types">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
      <sv:value>hippo:initializeitem</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:nodetypesresource" sv:type="String">
      <sv:value>hippo-namespaces/myhippoproject.cnd</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:sequence" sv:type="Double">
      <sv:value>31050.1</sv:value>
    </sv:property>
  </sv:node> 

hippo:nodetypesresource instructions are reloadable.

Import Nodes and Properties

Hippo Repository uses the JCR system view XML files to import nodes and properties. To import such files an initialize item must define the following two properties:

1. a   hippo:contentroot property defines the parent node under which the new node should be added.
2. a   hippo:contentresource property defines the path to the XML file.

The XML file imported is in enhanced system view xml, an extension of the standard system view import format as specified by the JSR-170 and JSR-283 documents.

hippo:contentresource instructions are reloadable.

Import resource bundles

Resource bundles can be imported by specifying a hippo:resourcebundles property with as value the json file containing the resource bundle(s) that should be imported. The content of the file is always loaded into the repository at the path /hippo:configuration/hippo:translations. The following example can be used to import the translations for the node types of the example myhippoproject.

  <sv:node sv:name="myhippoproject-translations">
    <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>31050.2</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:resourcebundles" sv:type="String">
      <sv:value>translations.json</sv:value>
    </sv:property>
  </sv:node>

Note: hippo:resourcebundles instructions are automatically reloaded, without a need for specifying a hippo:version or even a hippo:reloadonstartup property (which are ignored).  

Set a Single Property

It is sometimes necessary to set a single existing property to a custom value. An example is to influence the number of options available in rich text fields.

This is achieved by creating an  hippo:initializeitem with two properties, one indicating the path to the property to be set and one with the new value the property should get, as such:

  <sv:node sv:name="myproject-setproperty">
    <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>32000</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:contentroot" sv:type="String">
      <sv:value>/path/to/property</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:contentpropset" sv:type="String">
      <sv:value>one</sv:value>
    </sv:property> 
  </sv:node> 

The   hippo:contentroot property specifies the absolute path to the property to be set. The   hippo:contentpropset specifies the value or values the property should be set to.

If the property exists, the existing value or values will be overwritten. It is illegal to try to set a single-values property with multiple values or with no value at all. Only properties of type string can modified in this manner.

Add Values to an Existing Property.

Instead of overwriting a multi-valued with the  hippo:contentpropset instruction with a new set of values, it is also possible to append values to the existing list of values. Use the  hippo:contentpropadd instruction to achieve this.

  <sv:node sv:name="myproject-setproperty">
    <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>32100</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:contentroot" sv:type="String">
      <sv:value>/path/to/property</sv:value>
    </sv:property>
    <sv:property sv:name="hippo:contentpropadd" sv:type="String">
      <sv:value>two</sv:value>
      <sv:value>three</sv:value>
    </sv:property>
  </sv:node>

The   hippo:contentroot property specifies the absolute path to the property to be changed. The   hippo:contentpropadd lists the values to append. Only properties of type  string can modified in this manner.

Delete a Node

Existing nodes can deleted via the contentdelete instruction. For example:

<sv:node sv:name="myproject-deletenode">
  <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>31000</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentdelete" sv:type="String">
    <sv:value>/path/to/node</sv:value>
  </sv:property>
</sv:node>

It is also possible to combine  contentdelete with  contentroot +   contentresource. The typical use case for such a combination is deleting a node and directly replacing it with a newly imported structure. In that case, the  contentroot path should be the parent of the  contentdelete path. For example:

<sv:node sv:name="myproject-replacenode">
  <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>31000</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentdelete" sv:type="String">
    <sv:value>/path/to/node</sv:value>
  </sv:property> 
  <sv:property sv:name="hippo:contentroot" sv:type="String">
    <sv:value>/path/to</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentresource" sv:type="String">
    <sv:value>new-node.xml</sv:value>
  </sv:property>
</sv:node>

In this example, the root element of 'new-node.xml' would again be the node  <node>.

Delete a Property

Individual properties can also be deleted using the  hippo:contentpropdelete instruction:

<sv:node sv:name="myproject-deleteproperty">
  <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>31000</sv:value>
  </sv:property>
  <sv:property sv:name="hippo:contentpropdelete" sv:type="String">
    <sv:value>/path/to/property</sv:value>
  </sv:property>
</sv:node>