<% header(name + " User's Guide") %>

<p><% name %> version <% versionString %></p>

<p>First version created by Winston Wolff, January 2005.<br>
Improved version by Christoph Zwerschke, October 2005.</p>

<h2>Synopsis</h2>

<p>KidKit is a Webware plug-in which makes Webware understand &quot;Kid&quot; 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.</p>

<p>Kid and KidKit are currently under development, so consider
KidKit still <em>alpha</em> at the moment (August 2006).
If you use Kid a lot, feel free to improve this component.</p>

<h2>Requirements</h2>

<p>Contrary to PSP, Kid itself is not included in Webware. You need to install
the Kid package separately. Note that Kid needs the ElementTree package and
optionally makes use of the cElementTree package (future versions of Kid may
also utilize the xml.etree package that comes shipped with Python 2.5).</p>

<p>You can download Kid from
<a href="http://kid.lesscode.org">kid.lesscode.org</a>,
and ElementTree from
<a href="http://effbot.org/downloads/#elementtree">effbot.org/downloads/#elementtree</a>.</p>

<p>The current KidKit has been tested with Kid versions from 0.6 up to 0.9.3,
and ElementTree version 1.2.6. Other versions may work as well.</p>

<h2>Feedback</h2>

<p>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.</p>

<h2>Differences between Kid and PHP</h2>

<p>The main differences between Kid and PHP are the following:</p>

<ul>
<li>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.</li>
<li>You can chose how output is serialized, for instance following the rules
of sloppy HTML or strict XHTML.</li>
<li>Kid is an <em>attribute language</em>, 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.</li>
<li>Kid also provides a feature called &quot;Match Templates&quot; that can
be used to insert content dynamically based on patterns in template expansion
or to provide &quot;custom tag&quot; functionality similar to that found in
JSP taglibs or XSLT.</li>
</ul>

<h2>Configuring KidKit</h2>

<p>There are some configuration parameters in <tt>Application.config</tt>
which control the behavior of KidKit.</p>

<ul>
<li><b>KidOutputMethod</b><br>
The default output method for Kid. Possible values are:
'xml', 'html', 'html-strict', 'xhtml' and 'xhtml-strict'.</li>
<li><b>CacheKidTemplates</b><br>
Set this to False if you do not want compiled Kid templates (i.e. the
<tt>.py</tt> or <tt>.pyc</tt> files) to be cached on disk.
Please note that Webware still caches servlets in memory.
Use the parameters <b>CacheServletClasses</b> and <b>CacheServletInstances</b>
to control this behavior (set them to False for debugging).
</li>
<li><b>UseKidKitCache</b><br>
Set this to True if you want to use a separate KidKit file cache subdirectory
<tt>Cache/KidKit</tt> 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.</li>
<li><b>CacheKidSource</b><br>
Set this to True if you want to store the source code of the compiled templates
(i.e. the <tt>.py</tt> files) in the cache directory as well. Otherwise, only
the compiled Python modules (i.e. the <tt>.pyc</tt> files) will be stored on disk.</li>
<li><b>ClearKidCacheOnStart</b><br>
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.</li>
</ul>

<h2>Writing Kid templates</h2>

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

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

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

<p>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 <tt>WebKit.Page</tt> will be used,
and the output will be written by replacing the method <tt>respond</tt>.
You can configure this response &quot;hook&quot; by setting a variable
named <tt>hook</tt> 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 <tt>writeContent</tt> of the servlet
class <tt>KidExamplePage</tt>, you would add the following lines to the
top of your Kid template:</p>

<pre class="py">
&lt;?xml version='1.0' encoding='utf-8'?&gt;
&lt;?python
from KidKit.Examples.KidExamplePage import KidExamplePage
hook = KidExamplePage.writeContent
?&gt;
&lt;root&gt;...&lt;/root&gt;
</pre>

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

<p>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 &quot;hook&quot; method would
serialize the template and write the result to the response.</p>

<p>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 <tt>servlet</tt>
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 <tt>servlet.request().fields()</tt>.</p>

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

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

<p>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:</p>

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

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

<pre class="py">
&lt;?python output='xhtml-strict' ?&gt;
</pre>

<p>In this case, the template would be serialized like that:</p>

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

<h2>More examples</h2>

<p>You will find some more examples in the <i>KidKitExamples</i> context.</p>

<h2>Credits</h2>

<ul>
<li>Kid has been developed by Ryan Tomayko (http://lesscode.org).</li>
<li>ElementTree has been developed by Fredrik Lundh (http://effbot.org).</li>
<li>KidKit was contributed to Webware in January 2005
by Winston Wolff (winstonw&lt;at&gt;stratolab.com).
The first version was based on the Cheetah servlet factory
and did not support caching or configurable servlet hooks.</li>
<li>Improved version contributed to Webware in October 2005
by Christoph Zwerschke (cito&lt;at&gt;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.</li>
</ul>

<% footer() %>