Quickstart

Let's take a look on how to use Naviwork with Apache Cocoon step by step. Please make sure that you have installed the Logabit WebTools as described in the installation section before you start.

Step 1: Create your naviwork.xml

In the first step you have to create the naviwork configuration file naviwork.xml in the location configured by the parameter navigation-def-path in cocoon.xconf. Add afterwards this content to that file:

<navigation version="1.0">
  <entry id="home" label="Home" default="true"/>
  <entry id="news" label="News"/>
</navigation>

Now you have already defined the structure of your website. There are two sections: Home and News. For a complete reference to the structure of the Naviwork configuration file please take a look into the configuration section.

Step 2: Register the NavigationAction

In order to tell Naviwork the currently selected navigation entry, you have to add the NavigationAction to your Cocoon sitemap. At first register it in the components section:

<map:actions>
  <map:action name="naviwork" src="com.logabit.webtools.navigation.acting.NavigationAction"/>
</map:actions>

Then create a pipeline that executes this action:

<map:match pattern="news">
  <map:generate src="templates/news.jxt"/>
  <map:act type="naviwork"/>
  <map:transform type="jx"/>
  <map:serializer type="html"/> 
</map:match>

If no parameter is given, Naviwork uses the current sitemap URI to determine the selected navigation entry. This means an navigation entry with that id will be searched within the the configuration. If no such entry was found, the default entry will be returned.

In some situations you probably don't want to react upon the sitemap URI or you want to pass explicitely the navigation entry id to the NavigationAction. For this you can set the action parameter entryId. The NavigationAction then will try to load a navigation entry with this id:

<map:match pattern="*">
  <map:generate src="templates/{1}.jxt"/>
  <map:act type="naviwork">
     <map:parameter name="entryId" value="{1}"/>
  </map:act>
  <map:transform type="jx"/>
  <map:serializer type="html"/> 
</map:match>

Step 4: Create your template

The NavigationAction places the navigation bean of type com.logabit.webtools.navigation.Navigation into the current session under the name navigation. Within your template you can access the session and retrieve this navigation bean from there, like the example below shows using JXTemplate:

<html xmlns:jx="http://apache.org/cocoon/templates/jx/1.0">
  <jx:set var="navi" value="${session.getAttribute('navigation')}" />

  <body>
  
    <ul>
    <jx:forEach var="entry" items="${navi.allEntries}">
      <li><a href="${entry.uri}">${entry}</a>
    </jx:forEach>
    </ul>

  </body>

</html>

Note that allEntries returns a flatten list of all navigation entries from the whole navigation configuration. If you only need the children, then use children. Please take a look into the Javadoc of the package com.logabit.navigation to get an overview of all available methods.

Breadcrumb

If you want to access the breadcrumb, simply call navi.breadCrumb. This will return a list of navigation entries that belong to the current selection path. In your template you can then simply iterate over this list:

<jx:forEach var="entry" items="${navi.breadCrumb}">
  <a href="${entry.uri}">/ ${entry.label}</a>
</jx:forEach>