How to extend Hippo CMS

When you need customizations of the Hippo CMS code for a specific project, you can wrap the Hippo CMS core system into your custom project and extend it's behaviour.

Table of contents

Goal

As Hippo CMS is in rapid development, it could be useful to 'include' a stable core system and have your custom code outside of the standard Hippo CMS SVN codebase, so you can safely update the Hippo CMS core without losing your changes. This document describes how to use the "svn:externals" option of SVN to wrap an out-of-the-box Hippo CMS into your custom project and mount your custom pipelines into it.

Setting up a custom SVN project

It's advisable to setup a custom SVN project, but it's not necessary for this method to work.

Folder structure of your project

Setup your folder structure as displayed in the following diagram:

+ HippoCMS-customized-project-name
    |
    +-- extensions
    |    |
    |    +-- sitemap.xmap
    |    +-- some-folder
    |         |
    |         +- code....
    |
    +-- project.properties
    +-- common-project.xml

You're free to organize the "extensions" folder to your likings. This is where you add your custom sitemap, which possibly mounts others, etc.
Please note that the project.properties file in the root folder is critical for this method to work.

Any dependencies specified in common-project.xml will be overridden by dependencies specified within the Hippo CMS editor. See the Maven documentation for more details.

Linking the Hippo CMS 'editor' folder

From the commandline (or your favorite SVN client), edit the svn:externals property by firing the following command from within the root of your custom project:

$ svn propedit svn:externals .

If SVN complains that you do not have an editor in your environment variables, please refer to the SVN docs to set it up.

You should now be able to edit the property's value.
Add the following line:

editor     http://svn.hippocms.org/repos/hippo/hippo-cms/branches/Branch_v6.03.xx/editor

In this example, we're linking to the v6.03 branch version of Hippo CMS, but you could use any Tag, Branch or the Trunk. Find the correct path by browsing the public SVN repository at http://svn.hippocms.org/repos/hippo/hippo-cms/.

Please note that you're only linking the "editor" folder of the Hippo CMS core code to your personal "editor" folder; not the other folders or files in the Hippo CMS root folder.

After doing an svn update, SVN should now automatically checkout the "editor" folder from the external Hippo SVN repository for you.
The folder structure on your filesystem should now look like this:

+ HippoCMS-customized-project-name
    |
    +-- editor (svn:external to hippo-cms/editor)
    |    |
    |    +-- (editor code....)
    |    |
    |    ....
    |
    +-- extensions
    |    |
    |    +-- sitemap.xmap
    |    +-- some-folder
    |         |
    |         +- code....
    |
    +-- project.properties
    +-- common-project.xml

Make Hippo CMS use your extensions folder

Next, tell Hippo CMS that you want to use your own extensions folder. Inside the main project.properties (the one in the root folder of your custom project), add

#----- /PROJECT.PROPERTIES -----#

# Extensions directory relative to "editor" folder
maven.extensions.dir=../extensions

maven.cocoon.extensions.version=v1.01.00
maven.cocoon.extensions.name=My-customized-Hippo-CMS-project
maven.cocoon.extensions.displayname=-[${maven.cocoon.extensions.name}-${maven.cocoon.extensions.version}]

Add the following code to common-project.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <pomVersion>1</pomVersion>
    <groupId>hippo-cms</groupId>
    <logo>/images/cmslogo.gif</logo>
    <name>${maven.cocoon.site.displayname}</name>
    <currentVersion>${maven.cocoon.site.version}</currentVersion>
    <organization>
        <name>Hippo</name>
        <url>http://www.hippocms.org/</url>
    </organization>
    <mailingLists>
        <mailingList>
            <name>hippocms-dev</name>
            <subscribe>hippocms-dev-subscribe@lists.hippocms.org</subscribe>
            <unsubscribe>hippocms-dev-unsubscribe@lists.hippocms.org</unsubscribe>
            <post>hippocms-dev@lists.hippocms.org</post>
            <archive>http://lists.hippo.nl/mailman/private/hippocms-dev/</archive>
        </mailingList>
    </mailingLists>
    <developers>
        <developer>
            <name>Hippo</name>
            <id>hippo</id>
            <email>info@hippo.nl</email>
            <organization>Hippo</organization>
            <roles>
                <role>Developer</role>
            </roles>
        </developer>
    </developers>
</project>

Make sure you have the hippo-cocoon plugin version 2.0.8 or up

Then, build the CMS by doing

$ cd editor
$ maven clean cocoon:deploy

Your extensions sitemap is now mounted under the /extensions URI space of Hippo CMS.

Adding patches

You can add (x)patches to automatically patch the standard Hippo CMS code to your liking. Add a maven.xml file in your root folder and add the following goal:

<project xmlns:ant="jelly:ant" xmlns:j="jelly:core">
    <postGoal name="cocoon:patch">
      <!-- Add your patches here -->
    </postGoal>
  </project>

This postGoal will run after the main cocoon:patch has run.
Please see the Maven 1.0 documentation about how to write Maven goals.

Overriding / adding i18n translations

This feature is added in Hippo CMS version 6.04

You can override default i18n labels and add your own. This is configured in the sitemaps that use catalogs called messages.
Create in the extensions folder a folder called translations. Put the messages_LOCALE.xml files in that folder (e.g. messages_en_US.xml, messages_nl.xml).

+ HippoCMS-customized-project-name
    |
    +-- extensions
    |    |
    |    +-- translations
    |         |
    |         +- sitemap.xmap
    |         +- messages_en_US.xml
    |         +- messages_nl.xml
    |         +- ....

Create a sitemap.xmap file like this:

<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
  <map:pipelines>
    <map:pipeline>
	<map:match pattern="*.xml">
	  <map:generate src="{1}.xml"/>
	  <map:serialize type="xml"/>
        </map:match>
    </map:pipeline>
  </map:pipelines>
</map:sitemap>

Further reference

Please see the SVN documentation on External Definitions for more information and some important remarks ("Subversion still only truly operates on non-disjoint working copies").