experimental/hippo-navigation-cocoon/documentation.txt


If a HippoCMS based application wants to use a navigation which is decoupled from the structure how content is stored in the CMS, the Hippo navigation model comes into play. It uses a seperate folder structure in the WebDav repository (files/[site]/navigation) to create this object model.

In order to make this navigation model useable from within Cocoon, there are several components:

 * NavigationModelHolder
 * NavigationEventAwareJMSEventListener 
 * NavigationEventAwareManager
 * NavigationGenerator
 * NavigationIdLinkRewriterTransformer
 * NavigationPathMatcher
 * UID2RepositoryPathInputModule
 
The Avalon component configurations for the Cocoon 2.1 patching mechanism can be found in src/avalon of this module. Just add them to your project and make sure that the jar file (+ all dependencies - see project.xml for this purpose) are available in the classpath.

NavigationModelHolder
*********************
The NavigationModelHolder is the central component and has to be available in order to use any of the related sitemap components.

HOW DOES IT WORK
It is a singleton that contains the navigation model. The first time when it is accessed, it performs a Dasl query to get the navigation structure from the repository. Then it uses the class NavigationModelWebdavLoader. It parses the result document and fills a WebdavRootNode which is a tree containing all folders with their metadata.

The NavigationModelHolder implements the interface NavigationEventAware. By implementing this interface (+ adding it as lookup component to NavigationEventAwareManager) it gets notified by all changes in the navigation structure. These notifications are evaluated and the navigation model is updated accordingly by adding, updating or deleting nodes.

USAGE
This component comes with a single externally available method #getRootNavigationNode() which returns a WebdavRootNode object.

NavigationEventAwareJMSEventListener
************************************
The NavigationEventAwareJMSEventListener listens to notifications sent out by the Hippo repository via JMS.

HOW DOES IT WORK
It investiges the content of the message and distinguishes between changes in the content and changes in the navigation structure. In the latter case it sends out special NavigationEvents, otherwise it delegates to its parent class SlideJMSEventListener which sends out the normal events.

USAGE
The configuration contains information how to connect to the JMS provider. Additionally the role of the eventcache has to be set which is usually the org.apache.cocoon.caching.EventAwareManager. Don't confuse it with the NavigationEventAwareManager which does pretty much the same but specifically for NavigationEvents. The dependency to the NavigationEventAwareManager is hardcoded in the component.

NavigationEventAwareManager
***************************
With the help of the NavigationEventAwareManager components can subscribe to NavigationEvents in Cocoon.

HOW DOES IT WORK
The NavigationEventAwareManager is notified by the NavigationEventAwareJMSEventListener of any changes in the navigation structure. It passes all those events to all subscribed components. Those subscribers have to implement the interface NavigationEventAware.

USAGE
Just add the configuration with all "lookup components" to your Cocoon application.

NavigationGenerator
*******************
The NavigationGenerator provides a view to the navigation structure. The starting point is always a particular navigation node.

HOW DOES IT WORK
Based on a navigation id and a language, this generator creates all relevant
navigation entries for a document. This contains

 - the current nodes children</li>
 - the previous and the next document (if available)</li>
 - the current nodes parents and their siblings</li>
 - breadcrumb info (the labels and names of the current node and its  ancestors)

USAGE
It requires two pieces of information: The id of the navigation node for which the navigation structure should be created and the language.

    <map:generate src="[navigation-node-id]" type="navigation">
      <map:parameter name="lang" value="[language]"/>
    </map:generate>

NavigationIdLinkRewriterTransformer
***********************************
The NavigationPathLinkRewriterTransformer rewrites all links to other documents if they use a navigation path to point to them.

HOW DOES IT WORK
It scans for all occurencies of navigation ids in links and replaces them with navigation paths which are available from external. In particular, it scans for <nav:a xmlns:nav="http://hippo.nl/navigation/1.0" href="fr:7897987897">link text</a> nd replaces the language:navigationId value with the path pointing to the element.

USAGE
There is no special configuration necessary. Only add the transformer to your pipeline.

NavigationPathMatcher
*********************
The NavigationPathMatcher finds out, if a particular, language-specific path exists in the navigation model.

HOW DOES IT WORK
This matcher uses the navigation model to check, if a path is valid. If yes, it returns 
 - the contentId (aka as UID) of the document linked to the it using the key {contentId} and
 - the navigationId of the node using the key {navigationId}
to the sitemap.

USAGE
The matcher matches for the language specific navigation path. For that purpose it also requires the language  which it should test for:

        <map:match pattern="/some/language-specific/path/in/the/navigation/model" type="navigation-path">
          <map:parameter name="lang" value="fr"/>
          ... [here you can use {navigationId} and {contentId}]
        </map>

UID2RepositoryPathInputModule
*****************************
The UID2RepositoryPathInputModule translates a UID (aka contentId) to a repository path which can be used with the repository protocol.

USAGE
The shortname used in the configuration snippets is 'uid2path'. As value add the contentId:

  {uid2path:83274983749827}
Revision:	8327
Committed:	Thu Sep 27 11:24:34 2007 UTC (13 years, 6 months ago) by asavory
Content type:	text/plain
File size:	5999 byte(s)
Log Message:	HCN-1: New import of Reinhard's hippo-navigation code
#	Content
1
2	If a HippoCMS based application wants to use a navigation which is decoupled from the structure how content is stored in the CMS, the Hippo navigation model comes into play. It uses a seperate folder structure in the WebDav repository (files/[site]/navigation) to create this object model.
3
4	In order to make this navigation model useable from within Cocoon, there are several components:
5
6	* NavigationModelHolder
7	* NavigationEventAwareJMSEventListener
8	* NavigationEventAwareManager
9	* NavigationGenerator
10	* NavigationIdLinkRewriterTransformer
11	* NavigationPathMatcher
12	* UID2RepositoryPathInputModule
13
14	The Avalon component configurations for the Cocoon 2.1 patching mechanism can be found in src/avalon of this module. Just add them to your project and make sure that the jar file (+ all dependencies - see project.xml for this purpose) are available in the classpath.
15
16	NavigationModelHolder
17	*********************
18	The NavigationModelHolder is the central component and has to be available in order to use any of the related sitemap components.
19
20	HOW DOES IT WORK
21	It is a singleton that contains the navigation model. The first time when it is accessed, it performs a Dasl query to get the navigation structure from the repository. Then it uses the class NavigationModelWebdavLoader. It parses the result document and fills a WebdavRootNode which is a tree containing all folders with their metadata.
22
23	The NavigationModelHolder implements the interface NavigationEventAware. By implementing this interface (+ adding it as lookup component to NavigationEventAwareManager) it gets notified by all changes in the navigation structure. These notifications are evaluated and the navigation model is updated accordingly by adding, updating or deleting nodes.
24
25	USAGE
26	This component comes with a single externally available method #getRootNavigationNode() which returns a WebdavRootNode object.
27
28	NavigationEventAwareJMSEventListener
29	************************************
30	The NavigationEventAwareJMSEventListener listens to notifications sent out by the Hippo repository via JMS.
31
32	HOW DOES IT WORK
33	It investiges the content of the message and distinguishes between changes in the content and changes in the navigation structure. In the latter case it sends out special NavigationEvents, otherwise it delegates to its parent class SlideJMSEventListener which sends out the normal events.
34
35	USAGE
36	The configuration contains information how to connect to the JMS provider. Additionally the role of the eventcache has to be set which is usually the org.apache.cocoon.caching.EventAwareManager. Don't confuse it with the NavigationEventAwareManager which does pretty much the same but specifically for NavigationEvents. The dependency to the NavigationEventAwareManager is hardcoded in the component.
37
38	NavigationEventAwareManager
39	***************************
40	With the help of the NavigationEventAwareManager components can subscribe to NavigationEvents in Cocoon.
41
42	HOW DOES IT WORK
43	The NavigationEventAwareManager is notified by the NavigationEventAwareJMSEventListener of any changes in the navigation structure. It passes all those events to all subscribed components. Those subscribers have to implement the interface NavigationEventAware.
44
45	USAGE
46	Just add the configuration with all "lookup components" to your Cocoon application.
47
48	NavigationGenerator
49	*******************
50	The NavigationGenerator provides a view to the navigation structure. The starting point is always a particular navigation node.
51
52	HOW DOES IT WORK
53	Based on a navigation id and a language, this generator creates all relevant
54	navigation entries for a document. This contains
55
56	- the current nodes children</li>
57	- the previous and the next document (if available)</li>
58	- the current nodes parents and their siblings</li>
59	- breadcrumb info (the labels and names of the current node and its ancestors)
60
61	USAGE
62	It requires two pieces of information: The id of the navigation node for which the navigation structure should be created and the language.
63
64	<map:generate src="[navigation-node-id]" type="navigation">
65	<map:parameter name="lang" value="[language]"/>
66	</map:generate>
67
68	NavigationIdLinkRewriterTransformer
69	***********************************
70	The NavigationPathLinkRewriterTransformer rewrites all links to other documents if they use a navigation path to point to them.
71
72	HOW DOES IT WORK
73	It scans for all occurencies of navigation ids in links and replaces them with navigation paths which are available from external. In particular, it scans for <nav:a xmlns:nav="http://hippo.nl/navigation/1.0" href="fr:7897987897">link text</a> nd replaces the language:navigationId value with the path pointing to the element.
74
75	USAGE
76	There is no special configuration necessary. Only add the transformer to your pipeline.
77
78	NavigationPathMatcher
79	*********************
80	The NavigationPathMatcher finds out, if a particular, language-specific path exists in the navigation model.
81
82	HOW DOES IT WORK
83	This matcher uses the navigation model to check, if a path is valid. If yes, it returns
84	- the contentId (aka as UID) of the document linked to the it using the key {contentId} and
85	- the navigationId of the node using the key {navigationId}
86	to the sitemap.
87
88	USAGE
89	The matcher matches for the language specific navigation path. For that purpose it also requires the language which it should test for:
90
91	<map:match pattern="/some/language-specific/path/in/the/navigation/model" type="navigation-path">
92	<map:parameter name="lang" value="fr"/>
93	... [here you can use {navigationId} and {contentId}]
94	</map>
95
96	UID2RepositoryPathInputModule
97	*****************************
98	The UID2RepositoryPathInputModule translates a UID (aka contentId) to a repository path which can be used with the repository protocol.
99
100	USAGE
101	The shortname used in the configuration snippets is 'uid2path'. As value add the contentId:
102
103	{uid2path:83274983749827}