Added by Jeremy Quinn, last edited by Niels van Kampenhout on Oct 02, 2006  (view change)

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.

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.

Further Reading

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