|
|||||||
Hierarchically organized web sites often employ structural hyperlinks (a.k.a. "navigation") to give users a sense of location and help them find their way around. These links are generally "persistent," appearing on many pages across a site. They may also vary slightly from page to page in order to highlight a user's current location -- a type of "you are here" indicator.
The process of creating and maintaining structural links can be tedious and error-prone; that's where the Nav module comes in. Web pages can dynamically invoke Nav's three public methods, (breadcrumbs, fisheye, and sitemap) to generate structural links on the fly. The methods can be called directly if ERuby is supported. Static documents can use SSI and CGI to obtain the same functionality. See the Usage section for details.
Please note: Nav was designed for sites where the document hierarchy closely mirrors the structure of the filesystem. That is, the contents of a page found at URL /foo/bar/baz.html should exist in a file named baz.html, which resides in subdirectory bar, in directory foo. A few exceptions to this rule can be handled gracefully, however: see the INSTALL file for details.
A breadcrumb trail is a path through a site's document hierarchy. It begins with a link to the site's home page and ends with a link to the page currently being viewed. To use an example borrowed from a college Math department's web site, a page devoted to "seminars on probability" might have the following breadcrumb trail:
Home -> Research Groups -> Probability -> Seminars
A fisheye view also shows a breadcrumb trail, but adds links for the immediate children of each page in the trail. The result is a set of nested lists that reveal increasing detail as we get closer in the hierarchy to the page being viewed. A fisheye view for our example "seminars" page might look like:
A sitemap gives an overview of the document hierarchy. It isn't tailored to a particular page, and -- unlike breadcrumbs and the fisheye view -- it does not emphasize a "current" page.
The sitemap for our example site would look much like the fisheye view, but it would include details from all branches of the document hierarchy, not just the ones leading to a particular page. Also, to keep things brief, the sitemap might not list pages below a certain depth threshold. (e.g., it might show the link for "probability", but exclude the deeper link for "seminars": see SITEMAP_DEPTH in nav.rb.)
document_root/research/probability/index.html
The children of this page ("seminars" and "faculty members") are childless: their files reside in the probability directory as well:
document_root/research/probability/seminars.html document_root/research/probability/faculty.html
If either of these pages might possibly gain children in the future, they should be given index files in their own separate subdirectories, e.g.,
document_root/research/probability/seminars/index.html document_root/research/probability/faculty/index.html
Use one of Nav.breadcrumbs, Nav.fisheye and/or Nav.sitemap in your documents like so:
% # Where to find nav.rb if it isn't already in ruby's include path
% $:.push '/usr/local/lib/www/nav'
%
% require 'nav'
...
<body>
You are here:
<div class="breadcrumbs">
<%= Nav.breadcrumbs %>
</div>
<h1>Everything you wanted to know about my lint collection</h1>
...
Use SSI and CGI. In your server-parsed HTML (SHTML) documents, add directives to invoke the nav.cgi script with an appropriate option, like this:
... <!--#include virtual="/cgi-bin/nav.cgi?option"--> ...
where option is one of breadcrumbs, fisheye or sitemap.
<% ENV['SITE_ROOT_URL'] = '/subsites/mysite' %>
<!--#set var="SITE_ROOT_URL" value="/subsites/mysite"-->
This step is optional, though strongly recommended. If author-supplied metadata for a given page cannot be found, the breadcrumbs and fisheye methods will try to guess a name for that page based on the corresponding file or directory name. Without this metadata the page and its descendants will be completely invisible to the sitemap method, however. See the Bugs section.
You can provide metadata for your pages in two ways:
We can provide metadata for an index file in a specially-named file in the same directory. By default this files is named nav.txt, but you can change this setting: see METADATA_FILENAME in nav.rb.
The nav.txt file follows a simple name = value syntax. Whitespace and comments (text following a '#') are ignored. Valid fields and values are:
For our sample "probability research group" page, the file
document_root/research/probability/nav.txt
might look like this:
name = Probability group child_url = seminars.html child_url = faculty.html collapsible = yes
These tags add metadata to non-index HTML files. They use the same name/value pairs as nav.txt, and they appear in the document header.
The tags in our "probability group seminars" page might look like:
<meta name="name" content="Probability group seminars"/> <meta name="hidden" content="yes"/>
Since non-index files should ideally lack children, there shouldn't be much point in using child_url or collapsible in them. But Nav checks for these values anyway, just in case.
As of June 2003, you can see Nav in action on the University of Rochester's Math Department website, <www.math.rochester.edu>.
The sitemap and fisheye methods rely heavily on author-supplied child_url lists. (See Usage.) Pages not explicitly listed as children will only sporadically appear in the fisheye view (i.e., when they happen to lie on the breadcrumb trail) and will be completely absent from the sitemap.
(While these methods could dynamically compile a list of children by walking the filesystem, such a solution solution would be messy and might reveal more about the site hierarchy than we'd like: there would be difficulty concealing backup copies, subdirectories not meant to be listed, etc.)
| Copyright: | 2004 Hoss Firooznia <hoss@lodestone.org> |
| License: | Creative Commons Attribution-NonCommercial-ShareAlike 2.0 license: creativecommons.org/licenses/by-nc-sa/2.0/ |
| Version: | 1.2 |
1.2: Added configurable FISHEYE_SHOW_CHILDREN: allows administrator
to decide whether to display child nodes of the current page in
a fisheye view; upgraded to version 2.0 of Creative Commons
license.
1.1: Regex that matches embedded meta tags is now slightly more flexible.