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.

• :adrsiteroottable. Pathname of the source folder (discovered by looking for #ftpSite.yaml).

• :adrobject. Pathname of the page object being rendered.

• :subdirectorypath: Relative Pathname from the :adrsiteroottable to the folder containing :adrobject.

• :siterootfolder. Pathname of the Web site folder into which rendering will be performed. It is derived from the value of the :folder key in the hash represented by #ftpSite.yaml. As I’ve already mentioned, you must set this value in order for RubyFrontier to know where to save your Web site!

• :fname. Name of the Web page file to be created. For a renderable, this is calculated based on the name of the page object in accordance with certain scalar directives (or their default values). (For a non-renderable, it is identical to the filename of the page object.)

• :f. Pathname of the Web page file to be created; derived by applying :subdirectorypath to the :siterootfolder and adding :fname.

• :bodytext. Temporary holding tank for the contents of the page object, stripped of any internal directives, before insertion into the template. In general it should be left untouched, but your pageFilter, if implemented, is expected to modify it.

• :postmacrotext. Temporary holding tank for the contents of the page object, after insertion into the template and after macro processing. In general it should be left untouched, but your postMacroFilter, if implemented, is expected to modify it.

• :renderedtext. Ultimate text to be written to :f. In general it should be left untouched, but your finalFilter, if implemented, is expected to modify it.

• :autoglossary. The contents of the #autoglossary.yaml file, loaded as a hash. Used when forming links between pages within the site.