<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>
WebMake: Documentation: The <sitemap> Tag
</title>
<meta name="generator" content="WebMake/2.2" />
<style>
body {
background-color: #ffffff;
color: #000000;
font-size: medium;
font-family: verdana,lucida,helvetica,sans-serif;
}
code, samp, pre {
font-family: Courier New,courier,fixed-width,monospace;
}
H1 { font-size: x-large; font-family: Garamond,Book Antiqua,Times,serif; background: #FFCC66; }
H2 { font-size: large; font-family: Garamond,Book Antiqua,Times,serif; background: #FFDD77; }
H3 { font-size: medium; font-family: Garamond,Book Antiqua,Times,serif; background: #FFEE88; }
H4 { font-size: small; font-family: Garamond,Book Antiqua,Times,serif; }
H5 { font-size: x-small; font-family: Garamond,Book Antiqua,Times,serif; }
H6 { font-size: xx-small; font-family: Garamond,Book Antiqua,Times,serif; }
A:link {
font-weight: bold;
color: #004000;
text-decoration: underline;
}
A:visited {
font-weight: normal;
color: #008000;
text-decoration: underline;
}
A:active {
font-weight: bold;
color: #800000;
text-decoration: underline;
}
dt {
font-size: medium;
font-weight: bold;
padding-top: 8px; padding-bottom: 8px;
}
dd {
padding-top: 8px; padding-bottom: 8px;
}
</style>
</head>
<body bgcolor="#ffffff" text="#000000" link="#3300cc" vlink="#660066">
<font face="lucida,verdana,sans-serif">
<div align="center">
<img src="images/WebMakeTitle.png" alt="WebMake" width="500" height="122" />
</div>
<table width="100%">
<tr>
<td valign="top">
<strong><a href="http://webmake.taint.org/">WebMake</a>
Documentation</strong> (version 2.2)
</td>
<td valign="top">
<div align="right">
[ <a href="out.html">Back</a> | <a href="navlinks.html">Forward</a> | <a href="index.html">Index</a>
| <a href="allinone.html">All In One</a> ]
</div>
</td>
</tr>
</table>
<!-- yes, it's that Mozilla black-border code again ;) -->
<!-- stolen from www.mozilla.org via rc3.org -->
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td bgcolor="#aaaaaa">
<table border="0" cellspacing="4" cellpadding="4" width="100%">
<tr>
<td bgcolor="#ffffff">
<table border="0" cellspacing="4" cellpadding="4" width="100%">
<tr>
<td>
<h1>The <sitemap> Tag</h1><p>
The <sitemap> tag is used to generate a content item containing a map,
in a tree structure, of the current site.
</p>
<p>
It does this by traversing every content item you have defined, looking for
one tagged with a <strong>isroot=true</strong> attribute. This will become the root of the
site map tree.
</p>
<p>
While traversing, it also searches for content items with a <a href="metadata.html">metadatum</a> called <strong>up</strong>. This is used to tie all the content together into a
tree structure.
</p>
<blockquote>
<p>
<em>Note:</em> content items that do not have an <strong>up</strong><a href="metadata.html">metadatum</a> are considered
children of the root by default. If you do not want to map a piece of
content, declare it with the attribute <strong>map=false</strong>.
</p>
</blockquote>
<p>
By default, the content items are arranged by their score and title <a href="metadata.html">metadata</a>
at each level. The sort criteria can be overridden by setting the
<em>sortorder</em> attribute.
</p>
<blockquote>
<p>
<em>Note:</em> if you wish to include external HTML pages into the sitemap, you
will need to load them as URL references using the <media> tag and use
the <metatable> tag to associate <a href="metadata.html">metadata</a> with them.
<em>t/data/sitemap_with_metatable.wmk</em> in the WebMake test suite demonstrates
this. This needs more documentation (TODO).
</p>
</blockquote>
<p>
The <sitemap> tag takes the following required attributes:
</p>
<dl>
<dt>
<em>name</em>
</dt>
<dd>
<p>
The name of the sitemap item, used to refer to it
later. Sitemaps are referred to, in other content items or in out
files, using the normal ${foo} style of <a href="content.html">content reference</a>.
</p>
</dd>
<dt>
<em>node</em>
</dt>
<dd>
<p>
The name of the template item to evaluate for each
node with children in the tree. See <strong>Processing</strong>, below.
</p>
</dd>
<dt>
<em>leaf</em>
</dt>
<dd>
<p>
The name of the template item to evaluate for each leaf
node, ie. a node with no children, in the tree. See <strong>Processing</strong>,
below.
</p>
</dd>
</dl>
<p>
And the following optional attributes:
</p>
<dl>
<dt>
<em>rootname</em>
</dt>
<dd>
<p>
The root content item to start traversing at. The
default root is whichever content item has the <strong>isroot</strong> attribute
set to <strong>true</strong>.
</p>
</dd>
<dt>
<em>all</em>
</dt>
<dd>
<p>
Whether or not all content items should be mapped.
Normally dynamic content, such as <a href="metadata.html">metadata</a> and perl-code-defined
content items, are not included. (default: false)
</p>
</dd>
<dt>
<em>dynamic</em>
</dt>
<dd>
<p>
The name of the template item to evaluate for
dynamic content items, required if the <em>all</em> attribute is set
to <strong>true</strong>.
</p>
</dd>
<dt>
<em>grep</em>
</dt>
<dd>
<p>
Perl code to evaluate at each step of the tree.
See the <em>Grep</em> section below.
</p>
</dd>
<dt>
<em>sortorder</em>
</dt>
<dd>
<p>
A <a href="sorting.html">sort string</a> specifying what <a href="metadata.html">metadata</a>
should be used to sort the items in the tree, for example "<em>section
score title</em>".
</p>
</dd>
</dl>
<p>
Note that the <em>root</em> attribute is deprecated; use <em>rootname</em> instead.
</p>
<p>
The sitemap can be declared either as an empty element, with <strong>/></strong> at the
end, or with a pair of starting and ending tags and text between. If the
sitemap is declared using the latter style, any text between the tags will be
prepended to the generated site map. It's typically only useful if you wish
to set <a href="metadata.html">metadata</a> on the map itself.
</p>
<a name="Processing"><h1>Processing</h1></a><p>
Here's the key to sitemap generation. Once the internal tree structure of the
site has been determined, WebMake will run through each node from the root
down up to 20 levels deep, and for each node, evaluate one of the 3 content
items named in the <sitemap> tag's attributes:
</p>
<ol>
<li>
<p>
<em>node</em>: For pages with pages beneath them;
</p>
</li>
<li>
<p>
<em>leaf</em>: For "leaf" pages with no pages beneath them;
</p>
</li>
<li>
<p>
<em>dynamic</em>: For dynamic content items, defined by perl code
or <a href="metadata.html">metadata</a>.
</p>
</li>
</ol>
<p>
By changing the template content items you name in the tag's attributes, you
have total control over the way the sitemap is rendered. For efficiency,
these should be declared using the <template> tag instead of the
<content> tag.
</p>
<p>
The following variables (ie. content items) are set for each node:
</p>
<dl>
<dt>
<em>name</em>
</dt>
<dd>
<p>
the content name
</p>
</dd>
<dt>
<em>title</em>
</dt>
<dd>
<p>
the content's <strong>Title</strong><a href="metadata.html">metadatum</a>, if set
</p>
</dd>
<dt>
<em>score</em>
</dt>
<dd>
<p>
the content's <strong>Score</strong><a href="metadata.html">metadatum</a>, if set
</p>
</dd>
<dt>
<em>list</em>
</dt>
<dd>
<p>
the text for all children of this node (<em>node</em>
items only)
</p>
</dd>
<dt>
<em>is_node</em>
</dt>
<dd>
<p>
whether the content is a node or a leaf (1 for
node, 0 for leaf)
</p>
</dd>
</dl>
<p>
In addition, the following <a href="url_refs.html">URL reference</a> is set:
</p>
<dl>
<dt>
<em>url</em>
</dt>
<dd>
<p>
the first URL listed in a WebMake <out> tag
to refer to the content item.
</p>
</dd>
</dl>
<p>
Confused? Don't worry, there's an example below.
</p>
<a name="Grep"><h1>Grep</h1></a><p>
The <em>grep</em> attribute is used to filter which content items are included in
the site map.
</p>
<p>
The "grep" code is evaluated once for every node in the sitemap, and <code>$_</code>
is the name of that node; you can then decide to display/not display it, as
follows.
</p>
<p>
<code>$_</code> is set to the current content item's name. If the perl code returns 0,
the node is skipped; if the perl code sets the variable <code>$PRUNE</code> to 1, all
nodes at this level and below are skipped.
</p>
<a name="Example"><h2>Example</h2></a><p>
If you're still not sure how it works, take a look at <em>examples/sitemap.wmk</em>
in the distribution. Here's the important bits from that file.
</p>
<p>
Firstly, two content items are necessary -- a template for a sitemap node, and
a template for a leaf. Note the use of <strong>$(url)</strong>,
<strong>${title}</strong>, etc., which are filled in by the sitemap code.
</p>
<p>
<pre>
<content name=sitemapnode map=false>
<li>
<a href=$(url)>${title}</a>: $[${name}.abstract]<br>
<!-- don't forget to list the sub-items -->
<ul> ${list} </ul>
</li>
</content>
</pre>
</p>
<p>
And the template for the leaf nodes. Note that the <strong>${list}</strong>
reference is not needed here.
</p>
<p>
<pre>
<content name=sitemapleaf map=false>
<li>
<a href=$(url)>${title}</a>: $[${name}.abstract]<br>
</li>
</li>
</content>
</pre>
</p>
<p>
Finally, the sitemap itself is declared.
</p>
<p>
<pre>
<sitemap name=mainsitemap node=sitemapnode leaf=sitemapleaf />
</pre>
</p>
<p>
From then on, it's just a matter of including the sitemap content item in
an output file:
</p>
<p>
<pre>
<out name=map file=sitemap_html/map.html>
${header}${mainsitemap}${footer}
</out>
</pre>
</p>
<p>
And that's it.
</p>
<p>
This documentation includes a sitemap, by the way. It's used to generate
the navigation links. Take a look <a href="docmap.html">here</a>.
</p>
<p>
</p>
</p>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td>
</tr>
</table>
<table width="100%">
<tr>
<td valign="top">
<strong><a href="http://webmake.taint.org/">WebMake</a>
Documentation</strong> (version 2.2)
</td>
<td valign="top">
<div align="right">
[ <a href="out.html">Back</a> | <a href="navlinks.html">Forward</a> | <a href="index.html">Index</a>
| <a href="allinone.html">All In One</a> ]
</div>
</td>
</tr>
</table>
<div align="right">
<a href="http://webmake.taint.org/"><img src="images/BuiltWithWebMake.png" alt="Built With WebMake" border="0" width="88" height="31" /></a>
</div>
</font>
</body>
</html>