
Ucampas house-style template files
----------------------------------

The "style=template" attribute of a node in the ucampas navigation
tree identifies which house-style template shall be applied to a page.

Each style has template.html file, possibly with <?perl ... ?>
processing instructions embedded. There can also be a separate
template.pl file, with additional code to adjust and transform the
template. These Perl processing instructions are executed after the
navigation tree has been built and the SGML parser has already
converted both the *-b.html source document as well as the style
template HTML file into a PlexTree parse tree.

The PlexTree and NavTree API used is (unfortunately still very
incompletely!) documented at

  perldoc perl-PlexTree/PlexTree.pm
  perldoc NavTree.pm

Ucampas will process the template as follows:

  - Adjust any relative URLs that it finds in template.html according
    to the stylesheets_url, javascript_url, images_url, or style_url
    parameters.

  - Merge <head> fields from both the source and the template files,
    and add some more, as controlled by parameters such as
    discard_style and google_analytics.

  - Call the adjust($t, $out, $cur, $src) subroutine defined in
    template.pl, which has access to

      $t     a cloned template object

      $out   the (cursor to the root of the) HTML parse tree of the
             template file (and eventual output file)

      $cur   a curser to the node in the navigation tree that represents
             the current web page

      $src   the (cursor to the root of the) HTML parse tree of the
             *-b.html source file

  - Execute any Perl processing instructions in template.html, which
    also have access to the above variables (minus $t), as well as to

      $c     a cursor to the node that represents the <?perl ... ?>
             processing instruction in the HTML parse tree of the template
             ($c->top is $out)

    They can, for example, insert new text or elements using
    $c->insert(...) right before the location of the respective <?perl
    ... ?> processing instruction. After the execution of each such
    <?perl ... ?> processing instruction, ucampas will automatically
    remove it from $out (i.e. there is an implicit call to $c->cut at
    the end of each).

    Either adjust() or one of the processing instructions has to copy
    the body of the web page from $src into $out. They also may add
    navigation menus, breadcrumbs, page titles and other features,
    based on the structure and parameters found via $cur in the
    navigation tree. Ucampas provides some subroutines to do much of
    the work (e.g., navbar() to build a navigation menu, etc.).

  - Go over any <div class="ucampas-..."> elements in $out to make the
    requested substitutions.

  - Finally serialize $out back into the output XHTML file.

Unfortunately, there exists no detailed documentation yet for writing
new housestyle templates, and the existing PlexTree API is likely to
be extended in future (and hopefully become much simpler). Therefore,
at the moment, best contact the author of ucampas if you want to write
a new housestyle.

The provided *.html and *.pl example housestyles in this directory are
those actually used by the Computer Laboratory (also suitable for
other University of Cambridge departments).
