WebMake Documentation (version 2.4)

The <breadcrumbs> Tag

Another common site navigation strategy is to provide what Jakob Nielsen has called a "breadcrumb trail". The <breadcrumbs> tag supports this.

WTF Is A Breadcrumb Trail?

The "breadcrumb trail" is a piece of navigation text, displaying a list of the parent pages, from the top-level page right down to the current page. You've probably seen them before; take a look at this Yahoo category for an example.

To illustrate, here's an example. Let's say you're browsing the Man Bites Dog story in an issue of Dogbiting Monthly, which in turn is part of the Bizarre Periodicals site. Here's a hypothetical breadcrumb trail for that page:

Bizarre Periodicals : Dogbiting Monthly : Issue 24 : Man Bites Dog

Typically those would be links, of course, so the user can jump right back to the contents page for Issue 24 with one click.

If you have a site that contains pages that are more than 2 levels deep from the front page, you should consider using this to aid navigation.

How To Use It With WebMake

To use a breadcrumb trail, first define a sitemap. This tells WebMake how to order the page hierarchy, and which pages to include.

Next, define a template to be used for each entry in the trail. This should contain references to ${url} (note: not $(url)), which will be replaced with the URL for the page in question; and ${name}, which will be expanded to the name of the "main" content item on that page, allowing you to retrieve metadata for that content like so: $[${name}.title] .

Note: the "main" content item is defined as the first content item on the page which is not metadata, not perl-generated code, and has the map attribute set to "true", ie. not a template.

You can also define two more templates to be used at the top of the breadcrumb trail, ie. the root page, and at the tail of it, ie. the current page being viewed. These are optional though, and if not specified, the generic template detailed above will be used as a default.

Then add a <breadcrumbs> tag to the WebMake file as follows.

	<breadcrumbs name=mycrumbs map=sitemapname
		level=leveltemplatename />

The top and tail attributes are optional, as explained above. The level attribute, which names the "generic" breadcrumb template item to use for intermediate levels, is mandatory.

You can then add references to $[mycrumbs] in other content items, and the breadcrumb-trail text will be inserted. Note! be sure to use a deferred reference, or the links may not appear!

Attribute Reference

These are the attributes accepted by the <breadcrumbs> tag.

the name of the breadcrumb-trail content item. Required.
the name of the sitemap used to determine page hierarchy. Required.
the name of the template used to draw links at the intermediate levels of the trail. Required.
the name of the template used to draw the link to the top-most, or root, page. Optional -- level will be used as a fallback.

the name of the template used to draw the link to the bottom-most, currently-viewed page. Optional -- level will be used as a fallback.


This will generate an extremely simple set of <a href> links, no frills. The sitemap it uses isn't specified here; see the sitemap tag documentation for details on how to generate a site map.

  <template name=btop>
  	[ <a href=${url}>$[${name}.title]</a> /
  <template name=blevel>
  	<a href=${url}>$[${name}.title]</a> /
  <template name=btail>
  	<a href=${url}>$[${name}.title]</a> ]
  <breadcrumbs map=sitemapname name=crumbs
  	top=btop tail=btail level=blevel />

WebMake Documentation (version 2.4)
Built With WebMake