KidKit User's Guide

KidKit version 1.1.1

Created by Winston Wolff, January 2005.
Improved version by Christoph Zwerschke, October 2005.
Last changes by Christoph Zwerschke, March 2007.

Synopsis

KidKit is a Webware plug-in which makes Webware understand "Kid" templates.
By using this kit you can write Kid template files, and Webware will compile and
render them automatically when they are addressed via Webware's application server.
This is very similar to the concept of Python Server Pages (PSP), but Kid provides some
unique features making it an amazing modern alternative to PSP.

Requirements

Contrary to PSP, Kid itself is not included in Webware. You need to install
the Kid package separately.

The current KidKit has been tested with Kid versions from 0.6 up to 0.9.6.
Other versions may work as well.

Feedback

You can e-mail webware-discuss@lists.sourceforge.net to give feedback,
discuss features and get help using KidKit.
For Kid specific questions, use kid-template-discuss@lists.sourceforge.net
instead.

Differences between Kid and PHP

The main differences between Kid and PHP are the following:

Kid documents must be well-formed XML. This requires more discipline or
using the right tools for writing templates, but has the big advantage that
output is guaranteed to be well-formed XML as well.

You can chose how output is serialized, for instance following the rules
of sloppy HTML or strict XHTML.

Kid is an attribute language, very similar to TAL which is used
by Zope Page Templates. It takes advantage of XML namespaces in order to embed
Python code into HTML and XML as tag attributes which are not recognized by
HTML tools or browsers. So you can preview a template design and work on it
using ordinary HTML tools without interfering with the Python code.

Kid also provides a feature called "Match Templates" that can
be used to insert content dynamically based on patterns in template expansion
or to provide "custom tag" functionality similar to that found in
JSP taglibs or XSLT.

Configuring KidKit

There are some configuration parameters in Application.config
which control the behavior of KidKit.

CacheKidTemplates
Set this to False if you do not want compiled Kid templates (i.e. the
.py or .pyc files) to be cached on disk. Otherwise,
Kid templates will be cached (this is the default). Please note that if
you set this to False, Webware still caches servlets in memory.
Use the parameters CacheServletClasses and CacheServletInstances
to control this behavior (set them to False for debugging).

UseKidKitCache
Set this to True if you want to use a separate KidKit file cache subdirectory
Cache/KidKit to be used for storing the compiled Kid templates. The
following two options are only applicable if this is set to True. If this is
set to False, Kid will cache the compiled modules along with the templates
(this is the default).

CacheKidSource
Set this to True if you want to store the source code of the compiled templates
(i.e. the .py files) in the cache directory as well. Otherwise, only
the compiled Python modules (i.e. the .pyc files) will be stored on disk
(this is the default).

ClearKidCacheOnStart
Set this to True in order to clear the Kid cache on disk every time the
AppServer starts. Otherwise the Kid cache directory will persist,
which can give a speedup when templates are called for the first time
(this is the default).

Writing Kid templates

In the simplest case, you can just take a Kid template file with the
extension .kid and place it into a directory that is a valid Webware
context. For instance, you will find the following file with the name
Time2.kid in the KidKit/Examples context:

You can address this template as any other page in Webware; you
don't need to type in the .kid extension in the URL.

KidKit automatically compiles the template to a Python module and
creates a servlet class that will write the serialized template back
as a response. As base servlet class WebKit.Page will be used,
and the output will be written by replacing the method respond.
You can configure this response "hook" by setting a variable
named hook in the Kid template on the global level, i.e.
before the root element is opened. For instance, if you want to have
the Kid template replace the method writeContent of the servlet
class KidExamplePage, you would add the following lines to the
top of your Kid template:

Since the html tag has already been written when writeContent
is called, you must use some other tag for the root element or
add py:strip="" to the tag so that it will be stripped away.

Note that Python code that has been placed at the global level of the
template will be executed only once when the template is loaded for the
first time. The servlet factory of KidKit will then create an appropriate
servlet class that will be cached in memory by Webware from then on.
Every time the servlet is instantiated, the "hook" method would
serialize the template and write the result to the response.

In order to get access to the servlet from code that has been placed
at the local level of the Kid template, you can access the servlet
variable which gives you full access to the servlet instance. From here,
you can get all other information associated with the servlet. For instance,
you can get the form fields as servlet.request().fields().

Here is a simple example that reads the input from a form input field
and writes it back on the screen as a greeting:

Please note that though the template is written as strict XML, the output
will be serialized as HTML, because it has been configured as the default
output method. So the output of the servlet will look like this:

However, you can change the default output method with the
KidOutputMethod parameter mentioned above, or you can change
the output method for an individual template by setting the variable
output at the global level. For instance, you could add
the following line as first line (before the html tag) to the
Kid template above:

More examples

You will find some more examples in the KidKit/Examples context.

Credits

Kid has been developed by Ryan Tomayko (rtomayko<at>gmail.com).

KidKit was contributed to Webware in January 2005
by Winston Wolff (winstonw<at>stratolab.com).
The first version was based on the Cheetah servlet factory
and did not support caching or configurable servlet hooks.

Improved version contributed to Webware in October 2005
by Christoph Zwerschke (cito<at>online.de).
The new version is based on the PSP servlet factory.
KidKit now supports caching and several configuration parameters
for controlling caching, servlet hooks and output methods.

Support for newer Kid versions, particularly output formatting,
added by Christoph Zwerschke in March 2007.