Clever Harold Template Authoring Guide
---------------------------------------

Outline
=======

- Introduction_
- `Layout Template`_
- `Default Template Functions`_
- `Kid Template Publisher`_
- `Cheetah Template Publisher`_
- `Named Template Functions`_

Introduction
=============

Clever Harold has the concept that a web site layout is defined in a
template and referenced in only in the project configuration file,
never in other templates.  This reduces repeating references to a
layout and makes your template code immediately portable to other
layouts.

Clever Harold also has the concept that some parts of your site are
repeated over and over and over.  In conjunction with the layout
template, the publishers allow for a set of templates that provide
default markup.  Your individual pages simply declare what portions of
the page to fill, and the template publisher renders your functions
with the layout.

In your templates, you write named template functions that take the
place of the default function in the layout.  In practice, this is as simple as::


    <html xmlns:py="http://purl.org/kid/ns#">
        <div py:def="main()">
        ... main markup specific to just this page
        </div>
    </html>



Layout Template
===============

The layout template is a Kid template that you write and reference in
your projects.  In it, you write functions that act as placeholders
for individual templates to override.  An example illustrates it best::


    <html xmlns:py="http://purl.org/kid/ns#">
        <div py:def="header()" />
        <div py:def="content()" />
        <div py:def="footer()" />
    </html>

With such a layout, the templates can define any of three named
template functions: ``header``, ``content`` and ``footer``.  


Default Template Functions
==========================

The default page content is separated from the layout and your views
by way of one or Kid templates, called *default templates*.  These
templates typically contain only named function definitions and the
default values for each.

Continuing the layout example above, we can provide default
implementations for each function::


    <html xmlns:py="http://purl.org/kid/ns#">
        <div py:def="header()">    Welcome to our site.  </div>
        <div py:def="content()">   This page is empty.   </div>
        <div py:def="footer()">    Thank you and please come again. </div>
    </html>


Kid Template Publisher
======================

The Kid template publisher renders templates from your file system
directories.  Within your templates, you define functions that are
include in your application layout. 

The default layout has functions like ``main``, ``sidebar``, and so
on.  On a template-by-template basis, you supply the functions you
want to replace.


Cheetah Template Publisher
==========================

Clever Harold has tried to focus on Kid templates without neglecting
other template types.  In the 0.1 release, both Kid and Cheetah
templates are supported, however, layouts and defaults must be Kid
templates.  Lifting this restriction and providing additional template
publishers is planned for the next release.

Cheetah templates are published from disk in the same manner as other
templates.  In your project directories, create files with the
extension ".tmlp", and the publisher will render them as part of the
final layout.


Named Template Functions
========================

The publisher also renders named template functions just like full
templates.  This applies to template functions in both Kid and Cheetah
templates.  For example, given this URL::

    /path/to/template/part_as_xml?part_id=14

We might implement it as a named template function with a Kid template::

    <html xmlns:py="http://purl.org/kid/ns#">
        <div py:def="part_as_xml(part_id)">
	... some part lookup producing xml elements
        </div>
    </html>

Or a Cheetah template::

    <html>
    # def part_as_xml(part_id) 
        <div>
        ... some part lookup producing xml elements
        </div>
    # end def
    </html>


Further Reading
---------------

- `Kid Template Language Specification`_
- `Cheetah Templates Documentation`_

.. _Kid Template Language Specification:  http://www.kid-templating.org/language.html
.. _Cheetah Templates Documentation:  http://cheetahtemplate.org/learn.html
