Hippo Site Developers

This Getting Started track is for experienced Cocoon website developers, who would like to build websites that publish content from a Hippo Repository. You will be taken through downloading and installing the Hippo Repository, the Hippo CMS, the Maven Hippo-Cocoon plugin and our Site Skeleton, which can act as a framework for your project.

More Getting Started Tracks

Introduction

The Hippo Site Skeleton is a Maven-based project that is useful for starting your own projects to publish sites from a Hippo Repository. It is used in conjunction with the Hippo-Cocoon Maven plugin, to run your project inside a pre-built version of Cocoon, that you choose by setting up Maven dependencies. We will show you how to do this below. You should also have at least Hippo Repository running, and preferably also Hippo CMS so you can create and edit some documents.

Installation

A full Hippo installation comes in three components, the Hippo Repository, where your content is kept, the Hippo CMS which you use to edit that content and your site that publishes the content. These components communicate using WebDAV and JMS.

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!

Installing Hippo CMS Binary

How to download, install and run Hippo CMS so you can edit the content of a Hippo Repository.

Hippo CMS

Download the latest build from http://repository.hippocms.org/hippo-cms/v6.x/

Unzip the build into a folder on your harddisk, for example ~/hippo/hippo-cms-v6.01.00

Warning
Windows Explorer's built-in "compressed folder" functionality is reported to incorrectly unzip the Hippo CMS 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-cms-v6.01.00/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 (only IE and Firefox are currently supported) and navigate to http://localhost:50000/
You should see the login window
Enter the username "root" and password "password"
Congratulations, your Hippo CMS is running!

Changing the Hippo CMS hostname

Great! But what about this localhost thing? I want other developers to connect to my CMS and repository, but where do I start?

Well it's not that hard. You will have to change 2 files within the Hippo CMS folder:

sites.xconf - hold the host configuration for the current CMS (located in the cocoon/WEB-INF/ folder)
localdevDomains.xml - The localdevDomains.xml is used by the Hippo CMS workflow (located in the cocoon/WEB-INF/configuration/projects/localdev/ folder)

sites.xconf

Your sites.xconf should look something like this:

<sites version="1.0">
  <site name="hippo-cms">
    <domain>localhost</domain>
    <directory>../sites/hippo-cms/</directory>
    <repository>default</repository>
    <model>context://types/types.xml</model>
    <workflow>default</workflow>
    <httpstate>session-attr:httpstate</httpstate>
  </site>
</sites>

As you might have noticed the domain is set to 'localhost'. Change this to the hostname you had in mind and your done with the sites.xconf.

localdevDomains.xml

Your localdevDomains.xml should look something like this:

<beans>
  <bean id="projectDomains" class="java.util.HashSet">
    <constructor-arg index="0" type="java.util.Collection">
      <list>
        <value>localhost</value>
      </list>
    </constructor-arg>
  </bean>
</beans>

Again the value is set to 'localhost'. Change it to the same url used in the sites.xconf.

Well that's it. There is only one more thing to do and that is restarting the CMS. Afterwards you will be able to reach Hippo CMS on http://yoururl:50000/.

In the future you might want to build the CMS from source. The 'localhost' value will then be a single build property. (for more information see: http://www.hippocms.org/display/CMS/Hippo+CMS+Developers)

Installing Hippo Cocoon Maven 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).

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 :

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.

Hippo CMS Home

About Hippo CMS

Downloads

Community

Support

Documentation

Open Source Projects

Page Operations

Browse Space

Introduction

Installation

Installing Hippo Repository Binary

Hippo Repository

Installing Hippo CMS Binary

Hippo CMS

Changing the Hippo CMS hostname

Installing Hippo Cocoon Maven plugin

Hippo Cocoon Maven plugin

Get Maven

Plugin Installation

Installed Blocks

The Site Skeleton

The Site Skeleton

Downloading the Skeleton

Building the Skeleton

Launching the Skeleton

How does it work

Public Pipelines

Modifying the Skeleton

Using a different version of Cocoon

Adding custom configuration

Viewing the live site

Further Reading