<!--
=head1 NAME
sitetree.wmk - WebMake tag to generate a per-page sitemap
=head1 LOADING
< use plugin="sitetree" />
=head1 WEBMAKE TAGS
< sitetree name=... sitemap=...
opennode=... closednode=...
thispage=... leaf=... />
=head1 DESCRIPTION
This WebMake Perl library provides the C<sitetree> tag.
C<Sitetree> operates similarly to the built-in C<sitemap> tag, but, displays
only a subset of all the site's nodes; it will map all of the top-level nodes
of the site, and then only the parent nodes of the current page. The effect is
similar to a tree-view-based file browser, like Windows Explorer.
In terms of differences in usage, where C<sitemap> creates a single map which
includes every page in the site, C<sitetree> maps only the pages up to and
including the current page, and generates a map for each individual output
page.
So, for a site like this:
=over 4
=item + Section 1
=over 4
=item + Section 1 Subsection 1
=item + Section 1 Subsection 2
=back
=item + Section 2
=over 4
=item + Section 2 Subsection 1
=item + Section 2 Subsection 2
=back
=back
A reference to the site tree on page C<Section 1 Subsection 1> would result in
a site tree like this:
=over 4
=item - Section 1
=over 4
=item - Section 1 Subsection 1
=back
=item + Section 2
=back
Display of each page's entry in the tree is performed by expanding one of the 4
template content items named in the tag's attributes: C<closednode>,
C<opennode>, C<thispage>, or C<leaf>. See the C<sitemap> tag documentation for
more details on how to use these (note however that the I<is_node> variable
is not available for sitetrees).
=head1 ATTRIBUTES
=over 4
=item name
The name of the sitetree object. To include a sitetree in a page, refer to it
using this name, as a deferred reference.
=item sitemap
The name of the sitemap. The sitetree requires a sitemap, as the sitemap is
responsible for mapping out the site and defining which pages and content items
are included.
=item closednode
A content item which is evaluated to display a ''closed'' node, ie. a node
which is not on the path to the current page.
=item opennode
A content item which is evaluated to display an ''open'' node, one which is on
the path to the current page. As for the C<sitemap> tag's C<node> attribute,
this content item must include a reference to the B<list> variable, which will
contain all the entries for the pages beneath it in the hierarchy.
=item thispage
A content item which is evaluated to display the current page.
=item leaf
A content item which is evaluated to display a leaf-node page, one which has no
pages beneath it in the hierarchy.
=back
=head1 THANKS
Thanks go to Alex Canady, who came up with the idea for this one.
=cut
<wmmeta name="Title" value="sitetree.wmk" />
<wmmeta name="Abstract" value="WebMake tag to generate a per-page sitemap" />
-->
<{perl
use HTML::WebMake::PerlLib::SiteTree;
$self->define_empty_wmk_tag ("sitetree",
\&HTML::WebMake::PerlLib::SiteTree::handle_sitetree_tag,
qw(name sitemap closednode opennode thispage leaf));
'';
}>