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

<h2>simpleTALUtils</h2>
This module holds optional classes and functions that might be of use while using SimpleTAL, but are not required by SimpleTAL directly.

<h3>def ExpandMacros (context, template, outputEncoding="ISO-8859-1")</h3>
This function can be used to expand a template which contains METAL macros, while leaving in place all the TAL and METAL commands.  Doing this makes editing a template which uses METAL macros easier, because the results of the macro can be seen immediately.

The macros referred to by the passed in template must be present in the context so that their contents can be referenced.  The outputEncoding determines the encoding of the returned string, which will contain the expanded macro.

<h3>FastStringOutput</h3>
This class implements a very restricted File type object that can return a string containing all data written into it.  Unlike StringIO, FastStringOutput only supports write operations, and so is faster.  Only two methods are supported: write and getvalue.

<h4>write (data)</h4>
Used by SimpleTAL to write the expanded template.

<h4>getvalue ()</h4>
Use this to retrieve a string with the resulting output.

<h3>TemplateCache</h3>
This class implements a cache for compiled templates which automatically invalidates entries when their template file changes.  The instance has one public method: getTemplate

<h4>getTemplate (name, inputEncoding="ISO-8859-1")</h4>

This method will return a compiled template from the file 'name'.  If the file ends in '.xml' it will be compiled using simpleTAL.compileXMLTemplate, otherwise it will be compiled as a HTML template.  If the method is called again it will check to see whether the file 'name' has changed since the last call, and if it has it will re-compile the template,otherwise it will return the cached version.

HTML Templates will be taken as being stored in the "inputEncoding", XML templates ignore this parameter.

<h4>getXMLTemplate (name)</h4>

This method will return a compiled XML template from the file 'name'.  This works identically to getTemplate as described above, except that it always treats the template as XML.

<h3>HTMLStructureCleaner</h3>
This class can be used to encode any stray special characters within a given string or file-like object.  Its intended use is in preparing data that will be placed into a Context object and then included in a template using the 'structure' keyword.  The class uses the Python SGML parser to determine what tags are present, so any HTML markup will be left intact.  As an example, take the content:

<pre>
<code>This is some &lt;b&gt;bad&lt;/b&gt; html that is &lt; than great!</code>
</pre>

If this was included in a template in its current state the result would be bad markup.  Once cleaned by this class, the result would be:

<pre>
<code>This is some &lt;b&gt;bad&lt;/b&gt; html that is &amp;lt; than great!</code>
</pre>

The class has one external method:

<pre>
<code>def clean (self, content, encoding=None)</code>
</pre>
The content should be either a string or a file-like object.  If the string is a unicode string (u"") it will be cleaned as is.  If the string is an ordinary string then the encoding must be supplied, and it will first be converted to unicode.  If the content object is a file-like object then it will be converted only if the encoding is supplied.

The call returns a unicode string that has the '&lt;', '&gt;' and '&amp;' characters encoded.

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