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

Develop with Eclipse

Introduction

Goal

Use the Eclipse IDE to work on Hippo implementation projects.

Background

Eclipse integrates with Maven to enable creating, building, running and debugging projects within the IDE.

This documentation has been verified using Eclipse Java EE IDE for Web Developers, version Neon Release (4.6.0).

Eclipse Plugins

Maven Integration for Eclipse

Maven Integration for Eclipse is required to work with Hippo projects in Eclipse. It comes pre-installed with the Eclipse for Java EE Developers package, which we recommend you use.

Freemarker Plugin for Eclipse

A Freemarker Plugin for Eclipse is available as part of the JBoss Tools Project and can be installed separately.

  1. Choose Help > Eclipse Marketplace.
  2. Search for "JBoss Tools".
  3. Choose Install.
  4. A tree of checkboxes will appear, uncheck all (by unchecking the root) except FreeMarker IDE.
The version of the Freemarker plugin for Eclipse Luna is rather buggy. If you use Eclipse Mars you can work with a beta version of the JBoss tools that is much more stable.

Create a New Hippo Project

  1. Choose File > New > Maven Project.
  2. Optionally specify a non-default project location and/or a working set.
  3. Choose Next.
    If this is the first time you create a Hippo project in Eclipse, you must first choose Configure..., then Add Remote Catalog and add the Hippo Maven repository:
    Catalog File: http://maven.onehippo.com/maven2
    Description: Hippo
  4. At Catalog choose Hippo.
  5. Choose the archetype with Group Id org.onehippo.cms7 and Artifact Id hippo-project-archetype.

    The latest version of the archetype is automatically selected. To select an earlier version, uncheck Show the last version of Archetype only.
  6. Choose Next.

  7. Enter a Group Id, Artifact Id, Version and Package for the new project.

    In Eclipse Mars you may also need to manually override the default values for the groupId, artifactId, version and projectName properties in the list under Properties available from archetype. This appears to be a bug in Maven Integration for Eclipse.
  8. Choose Finish to generate the project.

Import an Existing Hippo Project

  1. Choose File > Import....
  2. Select Maven > Existing Maven Projects.
  3. Choose Next.
  4. Browse to the root directory of your project.
  5. Optionally add the project to a working set.
  6. Choose Finish to import the project.

Run or Debug a Hippo Project on a Tomcat Server within Eclipse

  1. First prepare a local Tomcat 8 installation:
    1. Download and Tomcat 8 and install it on your development machine. Do not run it yet, you will do this from within Eclipse later on.
    2. Build and run your Hippo project from the command line. Once it is running, stop it by pressing Ctrl+C.
    3. Copy the following files from your project's target/tomcat8x folder to your Tomcat installation (use the exact same folder hierarchy and replace existing files):
      1. common/lib/*.jar
      2. shared/lib/*.jar except your project's bootstrap-content jar (e.g. myhippoproject-bootstrap-content-1.0.0.jar).
      3. conf/context.xml
      4. conf/catalina.properties
  2. Configure the Tomcat Server in Eclipse:
    1. Choose File > New > Other, select Server > Server and choose Next.
    2. Select Apache > Tomcat v8.0 Server and choose Next.
    3. Set Tomcat installation directory to the location of your local Tomcat installation prepared in step 1, and choose Next.
    4. Select the cms, essentials and site modules of your project in the Available column and add them to the Configured column, and choose Finish.
    5. Choose Window > Show View > Servers.
    6. Double-click to open Tomcat v8.0 Server at localhost.
    7. Under General Information click on Open launch configuration.
    8. Select the Arguments tab and add the following arguments to those already there in the VM arguments box (use the appropriate paths for your situation):

      -Dderby.stream.error.file=”/Users/hippo/apache-tomcat-8.0.23/logs/derby.log”
      -Dlog4j.configuration=file:/Users/hippo/workspace/myhippoproject/conf/log4j-dev.xml
      -Dproject.basedir=/Users/hippo/workspace/myhippoproject
      -Drepo.path=/Users/hippo/workspace/myhippoproject/storage
      -Xms256m -Xmx1024m
    9. Under Server Locations select the option Use Tomcat installation (takes control of Tomcat installation).
    10. Under Timeouts raise the Start timeout to 200.
    11. Choose File > Save to save the server configuration.
  3. Configure the cms application to include the bootstrap-content module in its deployment assembly:
    1. Right click on your project's cms module (e.g. myhippoproject-cms) and select Properties.
    2. Select Deployment Assembly.
    3. Click on Add.
    4. Select Project and click on Next.
    5. Select your project's bootstrap-content module (e.g. myhippoproject-bootstrap-content) and click on Finish.
    6. Click OK.
  4. Configure the bootstrap-webfiles module not to be auto-redeployed by Eclipse (web files are automatically synchronized by the Hippo application):
    1. Right click on your project's bootstrap-webfiles module (e.g. myhippoproject-bootstrap-webfiles) and select Properties.
    2. Select Deployment Assembly.
    3. There should be two entries: src/main/java and src/main/resources. Remove both entries so the list is empty.
    4. Click OK.
  5. To run your Hippo project on the Tomcat server click on the Run icon in the Servers view.
  6. To debug your Hippo project on the Tomcat server click on the Debug icon in the Servers view.
Running your Hippo project this way enables all IDE features including automatic compilation and redeployment of your code!
The above instructions are based on 'Tutorial: setup Eclipse workspace for Hippo CMS' by Bart Vreeken.

Troubleshooting

If Tomcat won't start because of:

java.lang.NoClassDefFoundError: Lorg/slf4j/Logger

Then you either did not copy the shared folder correctly, or you did not copy the conf/catalina.properties correctly.

Debug a Hippo Project Running Outside Eclipse

If you choose to run your Hippo project from the command line, you can still use Eclipse for debugging by attaching its debugger to the running application.

  1. Choose Run > Debug Configurations...
  2. Select Remote Java Application and click on the New launch configuration icon in the top left corner of the dialog.
  3. Enter a Name for this debug configuration.
  4. On the Connect tab, at Project browse to the project you want to debug. Typically this is the site module, e.g. myhippoproject-site.
  5. Make sure Port is set to 8000.
  6. Choose Apply to save the debug configuration.
  7. Choose Debug to attach de Eclipse debugger to the running application.

If you now set breakpoints in your code Eclipse will open the debug perspective when your application executes that code.