On Sat, Jun 08, 2002 at 03:51:54PM -0700, Bryce Harrington wrote:
> Has anyone developed a listing of standard macro-names (i.e., and API)
> for common template-toolkit snippets (i.e. "widgets")?
Kind of.
The HTML and Splash template libraries achieve something like this.
For example:
[% PROCESS splash/menu
buttons = [
{ link => 'buttons.html', text => 'Buttons' }
{ link => 'menus.html', text => 'Menus' }
{ link => 'tabs.html', text => 'Tabs' }
]
%]
Check out stonehenge.com which Randal has recently relaunched with a
Splash interface. Although it's an ad-hoc standard, it is at least
a reasonably well-defined interface to code against. When he wants
to change the look and feel, Randal can create a new set of widget
templates that conform to the same interface and shouldn't have to
touch any of his content pages.
> What I'm thinking of is a system where an end user can submit content in
> lightly-formatted plain text and instead of converting it directly to
> HTML (via ettext2html), runs it through one of a set of processors that
> can convert it to a standardish TT2 syntax, and then use template
> toolkit to render the HTML using a site-specific TT2-based style macro
> library.
The TT docs (in the 'docs' directory) are an (ugly) example of this.
They're built from a gnarly and knobbly mish-mash of Pod, XML, templates
and various other bits and pieces (in 'docsrc', a separate bundle available
from the web site). What you end up with in 'docs' are a set of templates
which get processed at 'make' time to build the final document set. You
can go and tweak the templates in docs/lib and build the documentation
in a different style if you like.
Final processing is done by ttree which simply walks the
directory and processes each page. All the navigation elements, menus,
etc., are implemented as templates. The source pages include directives
like this that get generated by some insidious code in the docsrc
processing script and generating templates:
[% WRAPPER ndx %]
[% WRAPPER ndxitem
link='Tutorial/index.html'
name='Tutorial'
title='Template Toolkit Tutorials'
-%]
This section includes tutorials on using the Template Toolkit..
[% END %]
[% WRAPPER ndxitem
link='Manual/index.html'
name='Manual'
title='User guide and reference manual for the Template Toolkit'
-%]
This is the comprehensive user guide and reference manual..
[% END %]
...etc...
[% END %]
The end result is that you get a nice table of contents, and you
can change your 'ndx' and 'ndxitem' templates and re-process to
get a different TOC style.
There are all sorts of useful widgets like this that should be part
of the HTML, Splash, or some other library, but aren't. It's easy to
add new widget templates, but we're starting to hit a complexity
barrier with the current approach. The Splash! templates, for example,
already contain way too many code-like directives that should really be
handled by a plugin, or better yet, a view.
The motivations for building the docs from templates were twofold.
First, and foremost, I wanted to reduce the vast number of places
where chunks of documentation were repeated (e.g. configuration
options which appear in each Template::* module and also in the
Template::Manual::* pages) or conformed to a similar, or even
identical format (e.g. the version, copyright, see also sections).
It also allows me to define all my metadata and document structure
information in one place (a <blech>XML</blech> file) and then process
this to build various index pages, navigation components, menus, etc.,
automagically. It constructs everything as complete POD documents,
adding standard headers and footers, and then Pod::POMs them for
generating the above HTML templates, complete with all the TOC
directives, etc.
There are downsides. The whole system is badly hacked together,
fragmented, fragile, difficult to understand and hard to maintain.
However, I think that's a limitation in this particular implementation,
not in the concept. And despite the limitations, it does make the
job of maintaining the TT documentation much easier (read: possible)
once you know you're way around it (and don't touch anything that
isn't broke :-)
Stas Bekman had taken the issue of building document sets a good few
steps further for the modperl 2 docs. He has built the DocSet module
which allows you to create a directory tree of documents along with
configuration files that specify the structure of each part of the
document system. They can also specify directories to be searched
for files, files to be copied and so on.
A script then walks the directory, examining the config files, scanning
directories, processing and copying files, and doing all sorts of other
magic to build a final document system, complete with navigation, menus,
etc. I've been playing with it a little in the last week or so and it's
very powerful. I haven't got the link at hand, but I'm sure Stas will
provide it...
It allows you to define sections, chapters, pages, and so on that give
a fairly generic structural outline of the site. You can tweak the
templates to change the presentation of different elements, but like
the TT docs, it's a little ad-hoc and you have to do a little digging
around to find out how the templates fit together.
> The motivation for this is probably pretty obvious: my content
> submitters don't know HTML and probably wouldn't be bothered to learn
> TT2 syntax either but do seem to groove on wiki-style syntaxes.
> Unfortunately, the site uses various stylistic elements for representing
> headers, data tables, etc. that I do as TT2 macros (marketing is talking
> about doing a sitewide redesign in the near future, so I need the
> abstraction).
I think that Stas's DocSet stuff provides a good start for a system
which scans directories, allows different text conversions, processing
rules, etc., to build a document system model. One of the key goals
is to allow people to write simple, clear documentation, and to put
it wherever is most convenient for them. Let the machine do the hard
work (with a little guidance and instruction, of course) of pulling it
all together into a coherent model.
Once you've got that abstract model, you can have many different ways
of presenting it via different template sets, or even different template
engines, or via Perl code.
Cheers
A
