# KidKit User's Guide

KidKit version 0.9

First version created by Winston Wolff, January 2005.
Improved version by Christoph Zwerschke, October 2005.

## 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.

Kid and KidKit are currently under development, so consider KidKit still alpha at the moment (October 2005). If you use Kid a lot, feel free to improve this component.

## Requirements

Contrary to PSP, Kid itself is not included in Webware. You need to install the Kid package separately which in turn needs the ElementTree package and optionally makes use of the cElementTree package.

You can download Kid from kid.lesscode.org, and ElementTree from effbot.org/downloads/#elementtree.

The current KidKit was tested with Kid versions from 0.6 up to 0.7.1, and Element Tree 1.2.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.

- KidOutputMethod
  The default output method for Kid. Possible values are: 'xml', 'html', 'html-strict', 'xhtml' and 'xhtml-strict'.
- 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. Please note that 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.
- 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.
- 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.

## 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 KidKitExamples context:

    <?xml version='1.0' encoding='utf-8'?>
    <?python
    import time
    title = "A Kid Template"
    ?>
    <html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:py="http://purl.org/kid/ns#">
      <head>
      <title py:content="title">
        This is replaced with the value of the title variable.
      </title>
      </head>
      <body style="color:black;background-color:white">
        <div style="font-family:sans-serif;text-align:center">
          <h2>
            Time Example 2
          </h2>
          <p>
            <i>
              This page is a stand-alone page.
            </i>
          </p>
          <p>
            The current time is ${time.strftime('%C %c')}.
          </p>
        </div>
      </body>
    </html>

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:

    <?xml version='1.0' encoding='utf-8'?>
    <?python
    from KidKit.Examples.KidExamplePage import KidExamplePage
    hook = KidExamplePage.writeContent
    ?>
    <root>...</root>

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:

    <html xmlns:py="http://purl.org/kid/ns#">
    <head><title>Form Example</title></head>
    <body>
    <?python fields = servlet.request().fields()
    name = fields.get('name') or 'stranger' ?>
    <h1>Kid Form Example</h1>
    <p>Hello <strong py:content="name" />, how are you?</p>
    <form>
    Enter your name here: <input type="text" name="name" />
    <input type="submit" name="Submit" value="Submit" />
    </form>
    </body>
    </html>

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:

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
    "http://www.w3.org/TR/html4/loose.dtd">
    <HTML>
    <HEAD><META CONTENT="text/html; charset=utf-8" HTTP-EQUIV="Content-Type">
    <TITLE>Form Example</TITLE></HEAD>
    <BODY>
    <H1>Kid Form Example</H1>
    <P>Hello <STRONG>stranger</STRONG>, how are you?</P>
    <FORM>
    Enter your name here: <INPUT TYPE="text" NAME="name">
    <INPUT TYPE="submit" NAME="Submit" VALUE="Submit">
    </FORM>
    </BODY>
    </HTML>

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:

    <?python output='xhtml-strict' ?>

In this case, the template would be serialized like that:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html>
    <head>
    <title>Form Example</title></head>
    <body>
    <h1>Kid Form Example</h1>
    <p>Hello <strong>stranger</strong>, how are you?</p>
    <form>
    Enter your name here: <input type="text" name="name" />
    <input type="submit" name="Submit" value="Submit" />
    </form>
    </body>
    </html>

## More examples

You will find some more examples in the KidKitExamples context.

## Credits

- Kid has been developed by Ryan Tomayko (http://lesscode.org).
- ElementTree has been developed by Fredrik Lundh (http://effbot.org).
- 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.