This article covers a Bloomreach Experience Manager version 11. There's an updated version available that covers our most recent release.

Add the Essentials Setup Application to your Project

Warning

The Essentials setup application has been built with a 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 Essentials plugins are interacting with this structure. Therefore, Essentials 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 Essentials.

When adding the Essentials 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 Essentials to your project.

Please use Essential's feedback mechanism to tell us about your experiences using it 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 Essentials 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 tutorial 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 Essential'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 Essentials setup application. Copy it into the root directory of your existing Hippo project, keeping the name 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 Essential'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>

Step 6: Add support for Essentials to the site module

To add support for Essentials 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 standard delivery tier components available to your project. This is something you can take advantage of even if you don't install the Essentials setup application with your existing Hippo project.

Step 7: Initialize the Essentials 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: Prevent the Beanwriter from Modifying Custom Content Beans

The Essentials setup application includes the Beanwriter tool which can auto-generated content bean classes for your document types. Most likely your project contains custom content bean classes that you don't want the Beanwriter to modify. However, you may still want to auto-generate bean classes for new document types. Therefore, annotate all methods in your existing content bean classes with @HippoEssentialsGenerated and set its allowModifications parameter to false.

Example:

@HippoEssentialsGenerated(internalName = "myhippoproject:title", allowModifications = false)
public String getTitle() {
    // custom content bean method implementation goes here
}

For more information, see Creating Content Beans (section "Prevent the Beanwriter from Modifying Custom Content Beans").

Step 9: 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 Essentials 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 Essentials 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 Essentials, you install new files into your project sources and you create new configurations, stored in the Hippo repository. When Essentials 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 Essentials 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?