Navigation and Site Maps

HyperContent 1.4 introduces a new way of developing site navigation and site maps. Previously, navigation structures (such as the top and left hand navigation on this page) would be generated through a combination of XML Includes and XSL logic that sorts through the includes and decides how to order and label them. If you wanted to implement custom or ad-hoc ordering, you would have to build a custom data element into the data of XML files to store a sort key: for binary files, there was no way other than sorting on filename or title. Mixing links to external sites with automatically generated in-site navigation required maintenance of separate link files.

These concerns recurred across several of the larger and more complex sites built using HyperContent, so this new system was built to provide a better way to manage navigation. It also happens to dramatically reduce HyperContent's memory usage at build time, as it moves logic and data analysis out of XSL and into Java where it can be processed much more efficiently. There are three components to the new navigation system: a navigation templating language, a navigation editor, and a navigation resolution filter.

Navigation Templates

HyperContent provides a simple XML grammar for navigation templates. This grammar allows you to create nested navigation structures with custom labeling and sorting rules.

The URL for the navigation templates dtd is

http://hypercontent.sourceforge.net/dtd/navigation.dtd

< nav-template >

A navigation template embodies a rule for producing any number of navigation items, as well as rules for how its children should be sorted. It may contain any number of child nav-template elements, and may contain an overrides element which is used to override default labeling or sorting for instances of the specified pattern.

pattern =

A pattern describes the location of a navigation item. It may contain the path of a file in the filesystem, a pattern used to define an xml-doctype in the project definition, the URL of an external resource, or can be left blank to indicate a navigation item which is intended to be just a container or label for other items.

basedir =

The node in the filesystem from which the pattern should be resolved. A single forward slash indicates the root of the repository, while a blank value indicates that the basedir should be inherited. If this is the root template, the inherited value will be the directory in which the nav-template file is stored. Otherwise, the inherited value will reflect the resolved directory of the parent nav-template instance.

sortIndex =

This field can be used to specify an integer reflecting at what position this template should occur in the resolved list of navigation items which are its siblings.

labelWith = (title|vcard|filename|date|custom)

This defines how instances of the specified pattern should be labeled: according to the Dublin core title (metadata), vcard full name (metadata), filename, date saved, or the custom label specified in the next attribute.

customLabel

Holds the custom label value used when labelWith=custom.

maxChildren

Specifies the maximum number of navigation items that should be presented beneath this one when the templates are resolved. Child items will be sorted before the list is truncated.

sortChildren = (off|by-title|by-label|by-date|by-vcard|by-filename)
childSortOrder = (ascending|descending)

Specifies if and how sorting should be applied to navigation items which are resolved as children of an instance of this template.

suppress = (true|false)

Primarily used for override templates: indicates that items resolved to this template should NOT appear in the resolved navigation document.

target

A value passed through to the resolved navigation document, which can be used to specify target for generated links.

< overrides >

The overrides element may contain any number of nav-template children. Each of these nav-templates must represent a specific instance of the pattern of the nav-template which contains the overrides; in this way, a specific instance can be given a sortIndex of 0 to move to the top, or can have a custom label applied if, for example, the page title is too long to fit in a navigation area.

Navigation Filter

The navigation filter resolves a set of navigation templates into a navigation items document. This involves resolving instances of patterns, and processing these instances according to the templates' sorting and labeling rules. It is best to perform the resolution of navigation templates into items at build time to guarantee that any content which has been added, altered or removed since the templates were last updated is reflected appropriately in the site navigation. This type of filter is specified using the filter tag as a direct child of an xml-doc or xml-doctype tag; this way, the data is filtered once and can be included many times, by all the files that share navigation. The navigation filter is specified with a filter tag with key="navigation". Other files that include a navigation file that is configured with the filter as described will receive the filtered data with a root element of navigation, as follows.

< navigation >

The root element of a resolved navigation items document. Contains one or more nav-item elements.

< nav-item >

Represents one navigation item, and may contain additional nav-item elements.

directory =

The directory which contains this item, if applicable.

location =

The filesystem path or URL of this item, if applicable.

base =

The location of this item minus the file extension and preceding period. Handy for generating links to HTML output from xml sources.

pattern =

The pattern of this item in the project definition, if applicable. Useful for grouping like items.

label =

The label of this item.

target =

The target as specified in the item's template.

Navigation Editor

The navigation editor presents a user friendly view of a navigation templates document. What the user sees is actually a hierarchical representation of the filtered result of the templates. The editor allows the user to drag and drop to re-order items within a list, quickly add one-off templates (such as links to external sites), change the label and location of items, and suppress or remove items. These changes are then converted back into templates, such that the application of the filter will yield output identical to what the user entered on screen (assuming no other files have been added, altered or removed in the repository). You can configure the navigation editor to be used with nav-template files by configuring an editor tag with key="navigation" for the relevant xml-doc or xml-doctype. It is useful to combine it with the dublincore, xml and upload editors.