Patch Proposal: Read Templates From User Topics
The ability to store templates in user topics has long been requested. This patch adds this capability to the current store module without removing any existing capabilities.
Motivation
It is generally agreed that templates should be stored in user topics instead of the templates directory. However a move to this as the only mechanism has major impact. This patch provides the capability to read templates from user topics without damaging the existing template mechanisms. The intention is primarily to provide a means to %INCLUDing user topics into templates.
Description
The patch works by extending the definition of a template "name" to encompass a topic name. In the following examples I use perl syntax variable references to compose the example name strings. Today, if I specify the template in variable
$name
and with the skin in variable
$skin
, current web
$web
, then the search (type 1) order is:
templates/$web/$name.$skin.tmpl
templates/$web/$name.tmpl
templates/$name.$skin.tmpl
templates/$name.tmpl
To read a user topic, the patch extends this chain as follows.
$Name
and
$Skin
are just
$name
and
$skin
with the first character capitalised.
templates/$web/$name.$skin.tmpl
templates/$web/$name.tmpl
templates/$name.$skin.tmpl
templates/$name.tmpl
data/$web/${Skin}Skin${Name}Template.txt - if a skin is specified
data/$web/${Name}Template.txt - if no skin specified
data/$twikiWebname/${Skin}Skin${Name}Template.txt - if a skin is specified
data/$twikiWebname/${Name}Template.txt - if no skin is specified
Additionally (and primarily for use in %INCLUDE) the template name may be a wiki topic name, specified as "$Web.$Topic", in which case the search (type 2) is:
templates/$web/$Web.$Topic.$skin.tmpl
templates/$web/$Web.$Topic.tmpl
templates/$Web.$Topic.$skin.tmpl
templates/$Web.$Topic.tmpl
data/$Web/$Topic.txt - whether or not a skin is specified
If $Web is not specified, it defaults to $TWiki::twikiWebname, and the search to type 1.
Meta-data found in the topic is discarded. Only the topic text is used.
The patch also documents the functions involved in templates.
Documentation
TWikiVariables needs to be re-worked to document skins. When it is, then it should be updated to reflect the description above.
Examples
%TMPL:INCLUDE{view}%
%TMPL:INCLUDE{ChicSkin.View}%
Implementation
The template handling code would be better off abstracting off into a separate module, and the side-effecting and global variable referencing tidied up.
Note: Patch is attached as patch.dat. The patch is against Store.pm r1.77.
Discussion:
Don't be alarmed if your comments disappear as I refactor this page; I'm aiming to keep it to a reasonable length, and will chop corrections/clarifications as they are embedded in the proposal.
Patch is committed to CVS. Oh, and btw, in the future context or unified diffs are
much nicer to deal with than ed-script style diffs. They actually fail when applied to an improper version of a file instead of applying blindly and causing no end of trouble. They can also adapt to certain types of changes and still work, which ed-diffs are completely incapable of. See the
PatchGuidelines.
--
WalterMundt - 01 Mar 2004
Added documentation to
TWikiTemplates
--
CrawfordCurrie - 30 Jun 2004