image

RubyFrontier Documentation

The Page Table

When RubyFrontier starts to render a page object, it walks up the hierarchy from the page object gathering directives. Some of these directives will be directive objects; others will be scalar directives. But I’ve already told you all that.

What I have not yet made clear is what RubyFrontier is doing with all these directives. Here’s the answer: RubyFrontier is gathering all these directives into a single hash. This hash is called the page table. The page table, clearly, is tremendously important; indeed, the whole rendering process revolves around it. As a page is processed, all important information is read from, or written into, the page table. This is partly for RubyFrontier’s own convenience (a single hash to pass around and consult) and partly for your convenience, since your own customization scripts have a single, consistent place to go to fetch (and, if you know what you’re doing, modify) values that affect the outcome of the rendering process. There are several points in the rendering process (such as the four filter scripts, macro processing, and outline rendering) where the page table is directly available to you, and are free to examine it and (at your own risk) to alter it.

The Structure of the Page Table

Non-folded directive objects encountered as the page table is being built are stored at the top level of the page table as Pathname objects, keyed by their simple string name (meaning that the initial “#” and the file extension, if any, are stripped). So, for example, if your customization script is treating the page table as a variable called pt, you can learn the Pathname of the first #javascripts folder encountered on the way up the hierarchy by asking for pt["javascripts"].

Scalar directives are also written into the top level of the page table. Thus, for example, if your customization script is treating the page table as a variable called pt, then to learn the current :bgcolor setting you would ask for pt[:bgcolor].

Folded values other than scalar directives — namely, pathnames and name-value pairs drawn from inside any #tools, #glossary, and #images folders — go into subhashes of their own. So, for example, if your customization script is treating the page table as a variable called pt, you could access these hashes as pt["tools"], pt["glossary"], pt["snippets"], and pt["images"]. (The fact that the keys here are strings, not symbols, is deliberate.)

Stuff in the Page Table Other Than Directives

RubyFrontier works out and stores in the page table some key pieces of information of its own (i.e. these are not values supplied to RubyFrontier as directives). It is well to be aware of these, since they can be useful to your scripts, and also because you should not accidentally tromp on them.

NOTE on the names: These names are pretty terrible, but they are mostly inherited from Frontier, and I have left them unchanged (except for making them lowercase) to ease migration.

Next: How a Page Object Gets Rendered

This documentation prepared by Matt Neuburg, phd = matt at tidbits dot com (http://www.apeth.net/matt/), using RubyFrontier.
Download RubyFrontier from GitHub.