Configuration File Format
To follow the configuration file, you need to think of your Web site as a tree structure. Typically, the site starts at a home page or some sort of index, then from there you can select a category, then refine the topic you're interested in by selecting specific branches further into the tree structure.
The configuration file for a site could look like this:
type=page file=index.shtml caption=Home type=box_title caption="First section" type=page file=f1.shtml caption="Entry A" type=page file=f2.shtml caption="Entry B" type=page file=f3.shtml caption="Entry C" type=page file=f3-1.shtml caption="Entry C1" type=page file=f3-2.shtml caption="Entry C2" type=page file=f3-3.shtml caption="Entry C3" type=page file=f4.shtml caption="Entry D" type=box_title caption="Second section" type=page file=f2.shtml caption="Entry B" type=page file=f3.shtml caption="Entry C" type=link caption="Go somewhere else" file=f3-2.shtml
Each line represents an entry in the tree. Indentation indicates the relationship between pages: the user will need to enter f3.shtml to see f3-1.shtml, f3-2.shtml and f3-3.shtml. Similarly, the tree structure introduces a notion of locality: only the main headlines above the current page will be displayed, much like in crumbtrail navigation. For example, a user currently viewing f3-2.shtml will be presented with a link to index.shtml, f3.shtml and all the f3-*.shtml pages.
The levels of indentation must be marked using actual tabulation characters. Each line represents a link in the tree, usually this corresponds to a page in the site. The lines are composed of key/value pairs, where the key must be just one word (composed of letters and/or digits) and the value can be anything, but must be surrounded by double quotes if it contains spaces.
The following keys are available:
- type: This indicates the type of the node.
Values for this key are:
- page: this is an actual page. When the user is viewing a page with the URL corresponding to this entry, this is the one that shall be used. Consequently, only one page entry per file can exist in the whole tree structure.
- link: this entry will link to the specified page, that may be present somewhere else in the tree. This lets you create links between different branches in the tree. This has to be used with care, as it breaks the crumb trail paradigm. You'll often want to use this with the headline setting to fix up a crumb trail.
- box_title: This creates a new box, and uses this entry as the title for the box. It may or may not be a link (depending on whether a file setting is specified).
- text: this creates plain text that isn't a link.
- file: this attribute indicates the target of the link, or the location of the page corresponding to that entry.
- caption: this is the name of the entry as it appears to the user. It's used for the plain text, as well as for the title attribute of the link and the alt attribute of the image, if necessary.
- class: this defines the class attribute for this entry. No class will be set if this attribute isn't defined.
- img: if defined, includes the image specified as part of the link.
- headline: this attribute adds a link to the specified page, in the crumb trail, one level before the current level. See the Photojournal's Wallpaper pages to see what this can be used for. (I feel like this feature isn't abstracted in the right way. I'll be happy to receive comments on how it can be improved.)