This Getting Started track is for experienced Cocoon Developers, who would like to add to, customise or otherwise work with the latest version of the Hippo CMS. We will take you through how to get and build the source code for the Hippo CMS.

More Getting Started Tracks

Installing Hippo Repository Binary

How to download, install and run the Hippo Repository, so you can serve content to a Hippo CMS or your own Hippo Site.

Hippo Repository

• Download the latest build from http://repository.hippocms.org/hippo-repository/v1.2.x/
• Unzip the build into a folder on your harddisk, for example ~/hippo/hippo-repository-1.2.x

  Warning Windows Explorer's built-in "compressed folder" functionality is reported to incorrectly unzip the Hippo Repository binary distribution. Windows users are adviced to use a third-party ZIP utility, e.g. 7-Zip.

• Then you need to change directory to where the startup scripts are, if this is your first run, make them executable, then run them. In a new console, type:

  cd ~/hippo/hippo-repository-[version]/bin
  chmod u+x fortress.sh wrapper.bin libwrapper.so
  ./fortress.sh start
  

NB. Windows Users, Linux Users, MacOSX Users.

Now you can see if it is working

• Open a webbrowser and navigate to http://localhost:60000/default
• You should get a popup asking for a username and password
• Enter the username "root" and password "password"
• Congratulations, your Hippo Repository is running!

Alternatively, you can Build Hippo Repository from Source.

Building Hippo CMS from Source

Here we describe how to get the Hippo CMS source code from our versioning system, and how you can build, install and run it.

If you would like to build a custom version of the Hippo CMS or review the code, you will need to checkout the sourcecode from our Subversion Repository.

Getting a Subversion Client

To be able to get the source code for the Hippo Projects, you will need a client for Subversion, the versionning system.

Subversion Clients

The official subversion site: http://subversion.tigris.org/

The windows client Tortoise: http://tortoisesvn.tigris.org/

The windows client RapidSVN http://rapidsvn.tigris.org/

The eclipse plugin: http://subclipse.tigris.org/

SVN Documentation

The official SVN Documentation : http://svnbook.red-bean.com/

Getting Code

How to get all of the Hippo Code

Subversion Repository

The public Hippo SVN repository is located at :

http://svn.hippocms.org/repos/hippo

Hippo Projects

Hippo's CMS System is made up of several projects kept separately in Hippo's Subversion Repository.

This includes tools to assist in doing builds and initialisation, sample sites, a wrapper for starting the different processes, a pre-built Cocoon and the main Hippo components themselves (Hippo Repository and Hippo CMS).

Here is how to check out a copy of the current code

Somewhere to put it (an example)

cd ~/
mkdir hippo
cd hippo

Build Tools

svn co http://svn.hippocms.org/repos/hippo/hippo-fortress/trunk hippo-fortress
svn co http://svn.hippocms.org/repos/hippo/hippo-tools/repository-initialization/trunk hippo-tools/repository-initialization

The main Hippo Components

svn co http://svn.hippocms.org/repos/hippo/hippo-repository/trunk hippo-repository
svn co http://svn.hippocms.org/repos/hippo/hippo-cms/trunk hippo-cms

Cocoon

svn co http://svn.hippocms.org/repos/hippo/hippo-cocoon/trunk hippo-cocoon

Samples

svn co http://svn.hippocms.org/repos/hippo/hippo-cms-site-sample/trunk hippo-cms-site-sample
svn co http://svn.hippocms.org/repos/hippo/hippo-site-skeleton/trunk/ hippo-site-skeleton

Installing Maven Hippo-Cocoon plugin

How to install the Hippo Cocoon Maven plugin, so you can build your own Hippo Site projects, made from the Hippo Site Skeleton.

Hippo Cocoon Maven plugin

The Hippo Cocoon plugin is a Maven plugin to assist you to build and deploy your Maven-based Hippo Site projects. It uses pre-built distributions of Cocoon to simplify development.

Get Maven

This plugin is designed for Maven 1.0.n, if you do not already have it, the latest version, currently 1.0.2, can be downloaded from http://maven.apache.org/maven-1.x/start/download.html. Decompress the archive to a suitable location. Add this location as MAVEN_HOME to your environment variables and for convenience, add it to the $PATH variable.

In your user directory, create a build.properties file and add the following line

maven.repo.remote=http://repository.hippocms.org/maven/,http://repo1.maven.org/maven/

The Maven Hippo Cocoon plugin is currently incompatible with both Maven 1.1(-beta) and Maven 2.

Java 5 users need to place xalan-2.6.0.jar in the $MAVEN_HOME/lib/endorsed directory.

Plugin Installation

maven plugin:download -Dversion=2.01.01 -DartifactId=hippo-cocoon-plugin -DgroupId=hippo-cocoon

The current version is 2.01.01 (updated 2007-08-21). You can check in the Hippo public repository: http://repository.hippocms.org/maven/hippo-cocoon/plugins/ for updates.

The above command will download the plugin from the Hippo repository and store it in your local repository. This only needs doing once.

Windows users should also install Patch.

Sometimes maven refuses to download and install the new plugin. You'll need to delete the plugin on your computer in three places: Linux and MacOSX ~/dev/maven/plugins (or wherever you installed maven) ~/.maven/cache (change username) ~/.maven/repository/hippo-cocoon/plugins Windows C:\apache\maven\plugins (or where you installed maven) C:\Documents and Settings\username\.maven\cache C:\Documents and Settings\username\.maven\repository\hippo-cocoon\plugins

Installed Blocks

The pre-built distributions of Cocoon have a certain set of blocks built in.
You can see the list by looking at the project.xml file in the SVN repository for the plugin. http://svn.hippocms.org/repos/hippo/hippo-cocoon/trunk/server/project.xml.

If your project needs more blocks, add the new dependencies for these blocks to the project.xml of the Site Skeleton (see below).

Configuring Hippo CMS

The Hippo CMS is very configurable, here are some of the settings.

Jetty Properties

Cocoon properties

Site properties

Repository properties

Global cocoon memory settings

Please take extreme care when setting the build.properties of your Cocoon project.

Always make sure to configure both maven.wrapper.maxmemory (in mb's) and maven.cocoon.heapsize (in bytes, 20 mb lower).

CMS properties

Project specific properties

Workflow properties

Workflow quartzscheduler configuration

Workflow store configuration

Lucene properties

Debug properties

Building Hippo CMS

Environment Variable

Make sure you have an environment variable set for COCOON_HOME, pointing to the location of your Cocoon installation.

Build the ant tasks:

cd hippo-cocoon/anttasks
maven

Extra dependencies

Before building the CMS, you will need to download some dependencies that may not be redistributed:
JTA 1.0.1B (Download Class Files 1.0.1B, unzip, then jar cvf jta-1.0.1B.jar javax, copy the jar to ~\.maven\repository\jta\jars)
JavaMail 1.3.2 (Download zip, copy mail.jar to ~\.maven\repository\javamail\jars\javamail-1.3.2.jar)
JavaBeans Activation Framework 1.0.2 (Download zip, copy activation.jar from zip to ~\.maven\repository\activation\jars\activation-1.0.2.jar)
JDO (download the Final Draft zipfile, and unzip jdo.jar to ~\.maven\repository\jdo\jars\jdo-1.0.1.jar)

If you are working on a Windows based machine you will need GNU Patch. Make sure that it's installed before you start installing the CMS. You will need to put GNU Patch in your environment variable 'PATH'.

Build Hippo CMS

$ cd hippo-cms/editor
$ maven clean cocoon:deploy

Launching Hippo CMS

If this is your first run, make the startup scripts executable, then execute them. In a new console, type:

cd ~/hippo/hippo-cms-[STAGING:version]/bin
chmod u+x fortress.sh wrapper.bin libwrapper.so
./fortress.sh start

NB. Windows Users, Linux Users, MacOSX Users.

Testing Hippo CMS

Now you can see if it is working

• Open a webbrowser and navigate to http://localhost:50000
• You should get a popup asking for a username and password
• Enter the username "root" and password "password"
• Congratulations, your Hippo CMS is running!

NB. The Hippo CMS is not currently usable in Safari on MacOSX.

The Site Skeleton

The Hippo Site Skeleton is a useful starting point from which you can build your own Hippo Site to publish content from the Hippo Repository.

The Site Skeleton

The Site Skeleton is a very simple project to help you get acquainted with Hippo and to act as a template to make your own projects from.

When hooked up to the Hippo Repository, it is able to retrieve and display documents and document listings from the repositories folder hierarchy.

Downloading the Skeleton

The Skeleton is kept in the HippoCMS Subversion Repository http://svn.hippocms.org/repos/hippo/hippo-site-skeleton/

• If you do not have one, install a Subversion client, you can get instructions for your platform here http://subversion.tigris.org/
• in a new console, type :

  cd ~/hippo
  svn co http://svn.hippocms.org/repos/hippo/hippo-site-skeleton/trunk/ hippo-site-skeleton
  

Building the Skeleton

• Install the Hippo-Cocoon Maven plugin if you have not already done so.
• Check that the skeleton will use the version of Cocoon you want to use
• In the same console, type:

  cd hippo-site-skeleton/
  maven cocoon:deploy
  

Launching the Skeleton

• In the same console, type:

  chmod u+x fortress.sh wrapper.bin libwrapper.so (give execute permissions)
  ./fortress.sh start (to start)
  
  ./fortress.sh stop (to stop)
  

NB. Windows Users, Linux Users, MacOSX Users.

Now you can see if it is working

• Open a webbrowser and navigate to http://localhost:55555/
• You should see a simple page containing a list of documents in the repository's preview section
• Congratulations, your Hippo Site Skeleton is running!

How does it work

Public Pipelines

The two most interesting public pipelines in the project: one for the home page (which only displays the document list) and one to handle the display of documents within the repository (which shows the document list and the requested document).

Here is the pipeline for the home page :

<!-- the home page -->
<map:match pattern="index.html">
  <map:aggregate element="root" label="source">
    <!-- call an internal pipeline to perform a DASL Query to return all documents -->
    <!-- this pipeline returns the list as a nested collection:collection -->
    <map:part element="documents" xsrc="cocoon:/dasl/documents/content"/>
  </map:aggregate>
  <!-- transforms the collection:collection into a display page -->
  <map:transform xsrc="transformers/templates/document.xsl"/>
  <!-- perform internationalisation -->
  <map:transform type="i18n">
    <map:parameter name="locale" value="en"/>
  </map:transform>
  <!-- re-write the links -->
  <map:transform type="linkrewriter"/>
  <!-- strip any namespaces from the output -->
  <map:transform xsrc="site://transformers/util/stripnamespaces.xsl"/>
  <!-- serialize to XHTML -->
  <map:serialize type="xhtml"/>
</map:match>

Here is the pipeline for all of the other pages :

<!-- all other content -->
<map:match pattern="**.html">
  <map:aggregate element="root" label="source">
  <!-- call an internal pipeline to perform a DASL Query to return all documents -->
  <!-- this pipeline returns the list as a nested collection:collection -->
    <map:part element="documents" xsrc="cocoon:/dasl/documents/content"/>
    <!-- call an internal pipeline to retiriev an individual document from the repository -->
    <map:part element="content" xsrc="repository://content/{1}.xml"/>
  </map:aggregate>
  <!-- transforms the collection:collection and the document into a display page -->
  <map:transform xsrc="transformers/templates/document.xsl"/>
  <!-- perform internationalisation -->
  <map:transform type="i18n">
    <map:parameter name="locale" value="en"/>
  </map:transform>
  <!-- re-write the links -->
  <map:transform type="linkrewriter"/>
  <!-- strip any namespaces from the output -->
  <map:transform xsrc="site://transformers/util/stripnamespaces.xsl"/>
  <!-- serialize to XHTML -->
  <map:serialize type="xhtml"/>
</map:match>

There is one internal pipeline in the sitemap, to provide the results of DASL Queries to the two public pipelines.

<!--
       caching dasl query
  {1} = dasl : id to retrieve the query file
  {2} = path : search path within the repository
-->
<map:match pattern="dasl/*/**">
 <!-- generate a dasl query document, using the hippojx generator
      which automatically uses the sitemap parameters to make a cache key -->
  <map:generate xsrc="site://jx/dasl-{1}.xml" type="hippojx">
  <!-- full webdav path to the repository directory
      where if changes occur, should force a cache refresh -->
    <map:parameter name="target" value="{repository:files}/{2}"/>
    <!-- path into the repository, from where you would like your listing -->
    <map:parameter name="path" value="{repository:rootPath}{repository:filesPath}/{2}"/>
    <!-- adding the name of the query to the cache, for accuracy -->
    <map:parameter name="query" value="{1}"/>
    <!-- how deep to search into the folder hierarchy -->
    <map:parameter name="depth" value="infinity"/>
    <!-- the maximum number of results to return -->
    <map:parameter name="nrOfResults" value="30"/>
  </map:generate>
  <!-- perform the DASL Query -->
       <map:transform type="webdav"/>
  <!-- transform the flat result set into a nested representation of the hierarchy
      in the standard cocoon collection:collection namespace -->
  <map:transform xsrc="site://transformers/util/dasl2collection.xsl">
    <map:parameter name="path" value="{repository:rootPath}{repository:filesPath}/{2}"/>
  </map:transform>
  <!-- send xml -->
  <map:serialize type="xml"/>
</map:match>

The remaining pipelines are for providing images, css, javascript, and binaries from the repository.

Modifying the Skeleton

Using a different version of Cocoon

As Cocoon develops, you might want to start using newer version than are pre-set in this project. Like any Maven project, these dependencies are configured in the project.xml file.

Here is the current dependency for Cocoon Core :

<!-- Hippo build of Cocoon Core -->
<dependency>
 <id>hippo-cocoon</id>
 <version>2.1.8.2</version>
 <type>zip</type>
</dependency>

There are also depencies declared for the other Cocoon blocks required in the Skeleton.

You can add the dependencies you need to support your own projects here as well. They will be retrieved when you next build.

The Hippo build of Cocoon includes everything needed to run a "normal" cocoon site, like Hippo Fortress, Jetty and a vanilla cocoon-core, plus extra jars like the Hippo Webdav and Siteutil block, the webapp directory layout, some standard xpatches that use standard variables from your build.properties (like maven.cocoon.site.*), and some code needed to read jms messages from hippo repository.

Since hippo-cocoon uses a vanilla Cocoon core, you need to explicitly add dependencies on Cocoon's blocks you want to use, like jms or forms. The Hippo Skeleton would not work if you used the standard distribution of Cocoon core because you would miss all this extra stuff.

Adding custom configuration

If you are adding your own code, or other blocks to your Cocoon site, you probably need to configure it.

The Hippo-Cocoon plugin takes care of applying XConf Patch files for you during the build process. Just place them in :

hippo-site-skeleton/src/config/

• *.xconf – apply the patch to cocoon.xconf
• *.xmap – apply the patch to the root sitemap.xmap
• *.xlog – apply the patch to the logging configuration

Viewing the live site

Typically, a site you create to publish out of a Hippo Repository, would serve the contents of the Live site, not the Preview site (as the Skeleton is currently setup to do).

Your Hippo Repository is currently set up with 2 sub-repositories :

• Preview http://localhost:60000/default/files/default.preview
• Live http://localhost:60000/default/files/default.www

The only real difference between the preview and live websites is the repository they retrieve their content from. The preview website uses the same repository as the CMS. Every change you make to a document in the CMS will be immediately visible on the preview website. The live website on the other hand, uses the repository to which document are published. Documents in the CMS will only be visible on the live website after they have been published.

When a document in Preview is 'published' is is merely copied from Preview to Live.

The Site Skeleton is designed to serve Preview and Live from the same port but on different domains. These are setup via the Skeleton's configuration (in project.properties, overridden by any build.properties file you have in place).

The Site Skeleton is setup to serve Preview from http://localhost:55555 and Live from http://www.skeleton.localhost:55555.

If you only need to serve Live, just swap the values around. If you need both, you will have to configure a local domain for one of them.

Further Reading

Configuration Properties Reference
Input Module Reference
Source Reference
DASL Reference
Hippo Cocoon Plugin Reference
HippoJXTemplate Reference