Portal Navigation (Proposal Stage)
Summary
This proposal strives to do develop an easy yet robust way to navigate Jetspeed 2's folder/node structure. You can view the most current version here: http://www.mail-archive.com/jetspeed-dev@jakarta.apache.org/msg14579.html
Prosposal
Summarized by Ate Douma
Wikified by Scott Weaver
Folder
A Folder is an aggregate of Pages, Folders and Links. It is not viewable or renderable but only used to group its elements in an ordered manner. Its elements all have a parent reference to their containing Folder. The Folder structure and hierarchy is the basis for Page navigation, layout, decoration and Menu rendering. There is only one root Folder without parent. That simplifies the definition of default Decorators and Decorations.
Folder elements
A Folder element (Page, Folder, Link) is defined within it or may be a reference to a element defined in another Folder (like Unix symbolic links), which may be a reference in itself.
Deleting an element will result in references defined to become invalid.
Elements which are a reference to another Element defined in another Folder will have as parent the Folder containing them. For referenced Folder elements though, its elements will still have as parent the referenced Folder itself, not the Folder reference. This means that navigating to an element within a referenced Folder will result in a change of the parent hierarchy.
Page
A Page is an aggregate of Fragments and Page configuration. A Page is always used for rendering the end result to the user. The Page used is determined by the Profiler based on the client capabilities, navigation parameters and/or request parameters.
When a Page is rendered all of its Fragments are rendered for as far as allowed based on possible security constraints. It is not possible to reference a single Fragment on a Page for rendering (or possibly using a different pipeline).
Fragment
A Fragment is a markup definition for content to be rendered by a portlet. Two types are supported:
layout and portlet. A layout Fragment definition contains nested Fragments to be layout by it 'layout' portlet. A portlet Fragment cannot contain nested Fragments.
Instead of a concrete Fragment definition it is possible to reference another Fragment defined within the Page or from another Page. External Fragment references are 'included' during rendering and become part of the Page including them and only the decoration and layout configurations from this Page apply.
Link
A Link is a reference to an external url to be displayed in a menu.
Page Decorator
A Page Decorator renders the border (including header and footer) and possibly one or more menus around the Page content as well as the layout of the Fragments output from a Page (e.g. column or row wise, single/maximized). Menu rendering (if supported) is delegated by the Page Decorator to a Menu Decorator. If more than one menu is supported a Menu Decorator must be defined for each. Also, explicitly suppressing the rendering of one or more menus must be possible.
Menu Decorator
A Menu Decorator is used by a Page Decorator to do the actual rendering of a menu. Depending on the Page Decorator capabilities, zero, one or more menus may be rendered on a Page. A Page Decorator could support a top tab menu and a left tree menu for instance.
A menu displays Folder elements as navigation links from the current Page. Normally, the current Page, or its first parent within the menu will be marked.
Two root Folder relative parameters control which Folder elements are to be displayed in the menu: depth and level. The level parameter specifies from which level down in the Folder hierarchy the menu rendering should start. Minimum value: 1. The depth parameter specifies how many levels the menu rendering may continue. Minimum value: 0, indicating all remaining levels (useful for tree menus).
Optionally, each Folder element can be configured to be excluded from menu rendering.
Additionally, a Folder can be configured to be skipped for current level determination. Those Folders are traversed for menu rendering but not included by it (nor its non-Folder elements). For instance the Folders used by the Profiler to find a matching Page (e.g. client capability Folders as wml or html, language Folders as en, fr, nl) could be skipped.
Portlet Decorator
A Portlet Decorator is used for rendering the markup around a portlet Fragment output.
Decorator Resolution
Each of the above decorators can be defined within a Page definition, be inherited from the containing Folder or even from higher up in the Folder hierarchy. A Portlet Decorator may also be defined on a portlet Fragment within a Page. The nearest definition will be used. As fallback the root Folder shall have a default configuration for each of these (including default menu parameters).
Page Decoration (or Skin)
A Page Decoration supplies a css style and optionally image references to be used by a Page Decorator. Furthermore, a Page Decoration can supply default css styles and optionally image references to be used by Menu Decorators and Portlet Decorators.
Menu Decoration (or Skin)
A Menu Decoration supplies a css style and optionally image references to be used by a Menu Decorator.
Portlet Decoration (or Skin)
A Portlet Decoration supplies a css style and optionally image references to be used by a Portlet Decorator.