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, 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 that returns strings.  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 a string or bytes object containing the template, or a file-like object that returns strings or bytes.  The XML template must be a well formed XML document.  See below for details of how to use the Template class.

<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 to re-compile 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='utf-8'] [,docType=None] [,suppressXMLDeclaration=False])
</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 outputFile is an instance of io.TextIOBase or codecs.StreamWriter then strings are written to the file, otherwise the output is encoded in outputEncoding.  XML Templates will output the appropriate XML declaration for the outputEncoding, independently of whether strings or bytes are written out.  

The docType and suppressXMLDeclaration arguments only apply 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.  The doctype must be passed as a named variable to the expand method.

For example to produce a valid strict XHTML document 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>