php-web-doc/templates

Templates README
$Id$

This directory hierarchy contains very simple templates for the docweb
templating system.

The templating engine is equipped with a natural fallback procedure. This
procedure allows a developer to create templates in different languages,
and for different sub-projects, while maintaining a "default" language and
project when specific templates are not found.

The fallback procedure is as follows:
  - if the specified template, for the active language and project is
    available: use it.
  - if the specified template, for the active language is available, but
    there is no template for the active project, use the active language,
    default project template.
  - if the above two conditions are not met, use the default language and
    default project template.
  - if the above condition is not met (there is no default template, trigger
    a fatal error (coding problem).

For this reason, you will notice that the "en" tree is completely empty (this
is redundant, unless the default ever changes to another language), and the
[lang]/www trees are also empty (as www is the default project).

----

Templates & Rules

Currently, templates are just PHP source files. The DocWeb template engine is
simple enough that if there is ever a decision to move towards another engine,
this will be possible with minimal re-coding (by using DocWeb_Template as a
wrapper).

Using the native language (PHP) for templates presents certain dangers, in the
form of power. For this reason, whem creating/maintaining templates, the
following rules should be observed.
  - Templates are designed for DISPLAY LOGIC ONLY. That is, avoid performing
    any non-display logic inside the templates. For instance, it is acceptable
    to loop through an array of links to output their values. It is not,
    however, acceptable to loop through a list of files, and check readability.
    This type of logic should be performed outside of the template.
  - When rendering, templates are given their own scope (the $params
    argument). It is possible to use external values (such as $this (the
    template object), or $GLOBALS. Avoid this, and pass all required values
    as parameters.
  - As a convenience, templates may/should omit the PHP License header.