Templates & Languages

Hello all, I've been busy again. This time, it's templates & i18n (partial) language support. I fully intend to add "real" functionality to docweb at some point in the near future, but I feel really hindered building on the foundation that is currently there -- this patch removes my biggest block to adding new functionality. So, here are my two latest additions. They go hand-in-hand, so they are in the same patch. 1) Template engine. The README sums this up, so I'll include that here: ---- 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. - As an additional convenience, short open tags are permitted in templates,

     but only in "echo-shortcut" form (<?=$outputThis?>). This applies to
     templates only.

---- 2) Language Sometimes we need language snippets (that are not internal to a template). These are basically language-specific entities. See the DocWeb_Language class (as well as include/Language/*). This procedure also contains a natural fallback procedure. Additional implementation details can be seen in lib_general.inc.php:site_header(...) and the nav_links template. If there are any questions, I'll be happy to answer. Also, if I've done anything completely stupidly, I'm open to hearing that, too. I'm open to suggestions. See patch. http://www.phpdoc.info/docweb_template_language_patch.txt (too large to attach) S --