View File | Revision Log | Show Annotations | Download File | View Changeset
/hippo/experimental/hippo-navigation-cocoon/documentation.txt
Revision: 8327
Committed: Thu Sep 27 11:24:34 2007 UTC (12 years, 8 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

File Contents

# 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}

Properties

Name Value
svn:executable