Adding the setup application to your Project - BloomReach Experience - Open Source CMS

This article covers a Hippo CMS version 10. There's an updated version available that covers our most recent release.

12-05-2015

Adding the setup application to your Project

Warning

The setup application has been built with focus on easing and speeding up the initial steps of creating a new Hippo project. It sets up a certain structure in new Hippo projects, and the setup dashboard plugins are interacting with this structure. Therefore, the setup application does not guarantee that all interactions with an existing Hippo project will work smoothly. The structure of the existing Hippo project may, to some extent, conflict with the structure expected by the setup application.

When adding the setup application to an existing Hippo project, you should be aware of the above caveat. We recommend you use your VCS to detect and revert undesired changes by the setup application to your project.

Please use the setup application's feedback mechanism to tell us about your experiences using the setup application with an existing Hippo project. This may lead to better support of this scenario in the future.

Overview

The "installation" process works roughly like this: Create a new Hippo project from the archetype, move the setup application into your existing Hippo project, hook it into your build and deploy process and initialize it.

Upon completion of the process, you should be able to access the setup dashboard locally, browse the Library and access the pre-installed Tools.

Step 1: Create a new, empty Hippo project

The Getting Started Trail specifies how to create a new Hippo project from the (most recent) Hippo project archetype. Execute the mvn archetype:generate command in a separate directory to temporarily create a new, empty Hippo project. When prompted for the project parameters, make sure they are as close to the parameters of your existing Hippo project as possible.

Step 2: Match your project settings

In the generated, empty Hippo project, examine the root POM (pom.xml). Compare the parent version with that of your existing Hippo project. If the parent version of your existing Hippo project is lower than the parent version of the empty project, update the parent version of your existing project.

Updating the parent version of your existing Hippo project should happen regularly, and will require that you execute some regression testing on your project. If you find that the minor parent version number of your project is lower than the minor parent version number of the generated project, you should either upgrade your existing Hippo project, or check the setup application's release notes for the most recent version with the same minor parent version number as your project currently has.

Step 3: Copy the Essentials module

The generated Hippo project contains an essentials module / directory, which represents the setup application. Copy it into the root directory of your existing Hippo project and keep naming it essentials. Then, check in essentials/pom.xml that the parent parameters (groupId, artifactId and version) correctly refer to the root POM of your existing Hippo project. If not, update these values.

Step 4: Link the essentials module into your project

Open the root POM (pom.xml) of your existing Hippo project. Add the essentials module as a new module in your modules section

<module>essentials</module>

and add the essentials WAR as a deployable, besides the site and cms WARs.

<deployable>
  <location>${project.basedir}/essentials/target/essentials.war</location>
  <type>war</type>
  <properties>
    <context>/essentials</context>
  </properties>
</deployable>

Step 5: Prepare Essentials usage in CMS and site

In order to make some of the setup application's libraries available to the CMS and site modules, we manage a few dependencies centrally in the root POM. For this, add the property

<essentials.version>ESSENTIALS_VERSION</essentials.version>

(replace "ESSENTIALS_VERSION" with the version found in the same name property of the root POM of the generated Hippo project), and add the following dependencies to the dependencyManagement section:

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-essentials-plugin-sdk-api</artifactId>
  <version>${essentials.version}</version>
</dependency>
<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-essentials-components-cms</artifactId>
  <version>${essentials.version}</version>
</dependency>
<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-essentials-components-hst</artifactId>
  <version>${essentials.version}</version>
</dependency>

Step 6: Add support for the setup application to the site module

To add support for the setup application to the site module of your existing Hippo project, add the following dependencies to your site/pom.xml file.

<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-essentials-plugin-sdk-api</artifactId>
</dependency>
<dependency>
  <groupId>org.onehippo.cms7</groupId>
  <artifactId>hippo-essentials-components-hst</artifactId>
</dependency>
Note that the plugin-sdk-api dependency makes a Java annotation available to the site's content beans, which is used to make the setup application's BeanWriter tool work.
Note that the components-hst dependency makes the library of generic HST components available to your project. This is something you can take advantage of even if you don't install the setup application with your existing Hippo project. Installing only this library is documented here. The library of generic HST components is documented here.

Step 7: Initialize the setup application

Now, open the file essentials/src/main/resources/project-settings.xml, and initialize the project settings:

  • projectNamespace the main namespace prefix used in your existing project. By default, this can be determined by looking for the file bootstrap/configuration/src/main/resources/namespaces/*.cnd. The asterisk ('*') represents your project Namespace.
  • selectedBeansPackage the Java package that contains your HST beans, e.g. 'org.example.beans'.
  • selectedComponentsPackage the Java package that contains your HST components, e.g. 'org.example.components'.
  • selectedRestPackage the Java package where HST REST classes are located, e.g. 'org.example.rest'.
  • cmsModule add this tag if the Maven module containing your CMS web application is named different from "cms". E.g. if your existing project uses "backend" as the name of the CMS WAR root folder, specify <cmsModule>backend</cmsModule>.
  • siteModule add this tag if the Maven module containing your site web application is named different from "site". E.g. if your existing project uses "website" as the name of the site WAR root folder, specify <siteModule>website</siteModule>.
  • bootstrapModule add this tag if the Maven module containing your bootstrap modules is named different from "bootstrap". E.g. if your existing project uses "initialization" as the name of the bootstrap modules root folder, specify <bootstrapModule>initialization</bootstrapModule>.
  • webfilesSubModule add this tag if the Maven sub-module containing your webfiles (inside the bootstrap folder) is named different from "webfiles". E.g. if your existing project uses "webresources" as the name of the webfiles root folder, specify <webfilesSubModule>webresources</webfilesSubModule>. 
  • beansFolder add this tag if the folder containing your HST beans is outside of "site" project. The specified value represents the path relative to the project root folder, for example <beansFolder>bootstrap/beans/src/main/java</beansFolder>

Step 8: Clean up

You may have been using the generated, empty Hippo project throughout these steps as a reference. By now, you no longer need it, and may want to delete it.

Try it out

You should now be able to use the setup dashboard with your existing Hippo project. To build and run your project, you'd typically issue the command

mvn verify && mvn -P cargo.run -Drepo.path=storage

If all is well, you can now access the setup dashboard at http://localhost:8080/essentials.

More Disclaimers

As explained above, some parts of the setup application may not interact nicely with your existing Hippo project in case of conflicts between the existing project's structure and the structure expected by the setup application.

In particular, what might happen is the following: Using the setup appliation, you install new files into your project sources and you create new configuration, stored in the Hippo repository. When the setup application tries to install such a resource and finds that it already exists, it will not touch it. Like that, only a part of a set of coherent resources may be installed, leaving the project in an unpredictable state. It is therefore essential(!) that you operate the setup application carefully, and monitor the sanity of the changes made.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?