view release on metacpan or  search on metacpan

Wyrd/Site/NavPull.pm  view on Meta::CPAN

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.

=head2 HTML ATTRIBUTES

=over

=item root

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.

=item maxdepth

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.

=item sort

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...

=back

=head2 FLAGS

=over

=item tree

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.

=item onlynodes

Do not display end-documents, i.e. those Pages without children.

=item reverse

reverse the sort indicated in "sort" above.

=item noself

Remove this page (the one the NavPull is on) from the list, and by
extension, all its children.

=item light_path

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.

=back

=head1 BUGS/CAVEATS

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.

=cut

sub _format_output {
	my ($self) = @_;
	my $root = $self->{'root'};
	$self->{'sort'} ||= 'rank,shorttitle';
	my $id = undef;
	#list, item, nearest, selected = default templates
	$self->{list} ||= '<ul>$:items</ul>';
	$self->{item} ||= '<li><a href="$:name">$:shorttitle</a></li>';
	$self->{leaf} ||= $self->{item};
	$self->{selected} ||= '<li><b>$:shorttitle</b></li>';
	$self->{nearest} ||= $self->{selected};
	my $index = $self->{'index'};
	if (not($root)) {
		$id =  $self->_get_section_root;
		$self->_debug("$$id{name} is the root of this section");
		unless ($id->{name}) {
			$self->_data("<!-- no root exists for this section -->");
		}
		$id = $id->{name};
	} elsif ($root eq 'self') {
		$self->_debug('using self as the root');
		$id = $self->dbl->self_path;
	} else {
		#assume the user knows what they're doing.  Make no checks on suitability.
		$self->_debug('using supplied root:' . $root);
		$id = $root;
	}