Apache::Wyrd::Site::NavPull - Display a list of documents in a navigation-tree
<BASECLASS::NavPull root="/someplace/index.html" maxdepth="3"> <BASECLASS::Template name="list"> <blockquote>$:items</blockquote> </BASECLASS::Template> <BASECLASS::Template name="item"> <p><a href="$:name">$:title</a></p> </BASECLASS::Template> <BASECLASS::Template name="selected"> <p>$:title</p> </BASECLASS::Template> <BASECLASS::Template name="nearest"> <p><a href="$:name"><b>$:title</a><b></p> </BASECLASS::Template> </BASECLASS::NavPull>
NavPull is designed to make navigation bars self-managing. It does so by recursively building the hierarchy out of the stated "parent" attributes of indexed Pages. Beginning with a "root", which can be an arbitrary page or (the default) a section root, it builds the list using five templates:
"list" is the HTML which bounds the list itself: in one of the list tags, it represents the list tags themselves (e.g. <UL>...</UL>). Where the items of the list are to appear, the placemarker $:items should appear.
"item" is the HTML which represents an individual page. Whatever attributes of the Page you want to display in the list need to be given in placemarkers of this template.
Identical to "item", but used only if the document in the NavPull list is the document on which it appears. This template is kept separate from the item template to allow the document to be treated differently on the page on which it appears, for example, not at all, or unlinked, so that it is clear it can't be navigated to. (Not normally used, see "metoo" flag, below.)
Identical to "selected", but represents the closest parent node before the depth of the tree runs out. For example, if the NavPull is instructed to draw the tree only three nodes deep and the document on which the NavPull appears is five nodes down, the "nearest" template is used to draw the last ancestor which appears. Unless supplied, it defaults to the "item" template.
When the "tree" tag is in effect, the last page in a branch, i.e. the "leaf" is drawn using this template. Unless supplied, it defaults to the "item" template.
These templates can be extended down the depth of the tree by leaving as-is, or any depth level can be made different from the shallower ones by appending the depth level to the template name: list2, item2, selected2, list3, item3, selected3, etc. If templates for a depth level are not provided, they default to the next-shallower depth.
Very crude templates are supplied automatically if no level of the template is specified in the body of the NavPull.
NOTE: There is some support for multiple parentage. If a page declares two parents (separated by commas), the decision as to how to draw the tree depends on the referrer field of the HTTP request. If it indicates one of the ancestors of the page up one geneology, the navigation tree is drawn to reflect that branch, not the other(s). Multiple parents must belong in the same section, however, and there can be no circular relationships between parents.
The starting point, or "root" of the inverted-tree hierarchy. If not provided, the NavPull will seek through the sections of the site (the set of "section" attrubutes of pages) until it finds a document with a parent attribute which is the literal string "root" (signifying it has no parents other than the hierarchy root) and which belongs in the same section as the document on which the NavPull appears.
root can also be "self", in which case the NavPull will display its progeny rather than its ancestors.
How many nodes down the tree to display. If the tree does not have that many nodes, the display will stop at the deepest nodes it can find.
If provided, the document will sort within each group of equal-node siblings (siblings with a common parent) based on this token-list. As with TagPulls, the sorting is done in the order of the tags in either alphabetical or numerical order as appropriate, with those attributes designated "dates" by Apache::Wyrd::Site::Pull::_date_fields() in reverse chronological order.
Note that there is also support for arbitrary sort orders. Any set of siblings in a parentage-group may add a colon and numerical value to their parent attribute in order to indicate what order to be listed as siblings of the same node. For example, parent="/path_to/my/parent.html:2" indicates that this page should be the second page listed among its siblings. You may skip numbers in order to leave room for expansion among a sibling group, but any siblings missing these digits mixed in with siblings with these digits will appear before them in the list as if all numbered "0".
Normally, the expansion of the depth is along the selected document's branch. Only siblings of direct ancestors are shown, not those siblings children. This is in keeping with traditional navigation practice. This flag overrides this convention, expanding all parent nodes to the depth of the tree or the maxdepth attribute, whichever comes first. It is primarily of use in drawing site-maps.
Do not display end-documents, i.e. those Pages without children.
reverse the sort indicated in "sort" above.
Remove this page (the one the NavPull is on) from the list, and by extension, all its children.
Use "nearest" templates for all direct ancestors, instead of the normal templates for all ancestors except for the nearest on a tree on which this page does not appear due to its excessive depth.
Reserves the _format_output method. Support for multiple parentage has not proven very useful, since circular hierarchies cannot be tolerated, and any liberal application of multiple parentage quickly produces circular relationships.
Barry King <wyrd@nospam.wyrdwright.com>
General-purpose HTML-embeddable perl object
Abstract document-list Wyrd
Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.
See LICENSE under the documentation for Apache::Wyrd.
Apache::Wyrd
To install Apache::Wyrd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::Wyrd
CPAN shell
perl -MCPAN -e shell install Apache::Wyrd
For more information on module installation, please visit the detailed CPAN module installation guide.