title: SimpleTAL API: simpleTAL Module
subject: Documentation on how to use the simpleTAL Module.

<h2>simpleTAL</h2>
Two helper functions are provided for convenience, one for compiling HTML templates, and one for compiling XML templates.  If an error is encountered during compilation (for example mismatched TAL tags or bad syntax) an TemplateParseException will be thrown.

<h3>compileHTMLTemplate (template, inputEncoding="ISO-8859-1", minimizeBooleanAtts=0)</h3>
Compiles the passed in HTML template into an instance of the 'Template' class.  The template object should be either a string containing the template, or a file-like object.  The inputEncoding specifies the encoding that the template was written using and deafults to iso-8859-1.  The minimizeBooleanAtts flag controls whether HTML boolean attributes (e.g. &lt;img ismap&gt;) should be written out in minimized form.  See below for details of how to use the Template class.

<h3>compileXMLTemplate (template)</h3>
Compiles the passed in XML template into an instance of the 'Template' class.  The template object should be either a string containing the template, or a file-like object.  The XML template must be a well formed XML document.  The character set will be determined from the prolog of the template or be assumed to be utf-8.  See below for details of how to use the Template class.

<h3>compileDOMTemplate (dom)</h3>
Compiles an XML template that is stored as a DOM tree.  This requires PyXML to be installed to function.  

<h3>Template Instances</h3>
The compiled templates contain all of the logic required to be able to expand themselves for a given context.  They can be kept around and reused as often as required, there is no need or benefit to re-compiling them unless the underlying template changes.  They have one method of interest as part of the external API:

<pre>
<code>
def expand (self, context, outputFile[,outputEncoding] [,docType][,suppressXMLDeclaration])
</code>
</pre>

This method will expand the template, using the simpleTALES.Context object provided, and write the output into the given file-like object.  If the template is a HTML template then the result will, by default, be encoded in iso-8859-1.  If no outputEncoding is specified and the template is an XML template then it will default to utf-8.

The docType and suppressXMLDeclaration variables apply only to XML Templates.  

Python's support for XML does not currently extend to the LexicalHandler API, which is required for an application to be able to read an XML documents DOCTYPE.  If <a href="http://pyxml.sourceforge.net/">pyXML</a> is installed SimpleTAL will make use of it to determine the XML DOCTYPE, otherwise the doctype must be passed as a named variable to the expand method.

For example to produce a valid strict XHTML document without pyXML use:

<pre>
<code>
template.expand (context, outputFile, docType='&lt;!DOCTYPE html  PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;')
</code>
</pre>

If the suppressXMLDeclaration is set to true then the XML Declaration will not be included in the output (required for XHTML in IE6).

<a href="api.html">Back to SimpleTAL API</a>
