path: root/docs/src/customizing.tex

\section{Customizing and extending Cheetah}
\label{customizing}

To extend and customize Cheetah you can create a {\bf subclass} of Template that
reimplements some of its methods, you can use {\bf settings}, or you can use
{\bf plugins}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Subclasses of the Template class}

This is an advanced topic that is difficult to explain without full code
examples.  It's best to learn how to do this by looking at existing subclasses
of the \code{Template} class.  The Cheetah.Servlet module and the
Cheetah.Templates package contain examples.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Settings}

\code{Template} objects have a \code{\_settings} attribute. This is a dictionary of
configuration settings that control most of Cheetah's core behaviour.  The
Template object's constructor method has a keyword argument 'settings' that
accepts a dictionary to override the default settings.  Many of these settings
are for internal use and are of little interest to end-users.  Some, however,
can be quite useful.  This section explains how to use them.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Using tokens other than dollar sign and hash}

It is possible to use any character sequence to signal the start of a
\$placeholder or \#directive.  The ``\code{placeholderStartToken}'' and
``\code{directiveStartToken}'' settings control this.

\begin{verbatim}
myTemplateDef = "Here's my @@adj template."
myNamespace = {'adj': 'silly'}
from Cheetah.Template import Template
templateObj = Template(myTemplateDef, myNamespace, 
                 settings={'placeholderStartToken':'@@'})
\end{verbatim}

\code{placeholderStartToken} can be any character sequence of any length
provided that it doesn't end or start with \code{\#} as this is used by the
\#directives.  You can't use a sequence of spaces as the token, although you can
have spaces mixed with other characters.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Alternate comment tokens}

It is possible to use any character sequence to signal the start of a single
line comment and the start/end of a multiline comment.  The
``\code{singleLineComment}'' and ``\code{multiLineComment}'' settings control
this.  ``\code{singleLineComment}'' should be a string and
``\code{multiLineComment}'' should be a tuple of two strings.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Disabling 'auto-calling'}

Cheetah's auto-calling behaviour (see section
\ref{TDL.placeholders.autocalling}) can be disabled via the
``\code{useAutocalling}'' setting.

\begin{verbatim}
from Cheetah.Template import Template
templateObj = Template(myTemplateDef, myNamespace, 
                 settings={'useAutocalling':0,})
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Delayed Compilation}

The \code{Cheetah.Template.Template} class usually compiles its template
definition as soon as it is initialized (e.g. \code{Template(templateDef,NS)}).
There are some situations where you may want to delay the compilation until
later. See section \ref{webware.containment.includes} for one such situation.
The ``\code{delayedCompile}'' setting and the \code{.compileTemplate()} method
are used for this purpose.

\begin{verbatim}
from Cheetah.Template import Template
templateObj = Template(myTemplateDef, myNamespace, 
                 settings={'delayedCompile':1,})
...
templateObj.compile()
\end{verbatim}

\code{Template.recompile()} is a synonym for \code{Template.compile()}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Error checking of placeholder tags}

[{\bf This description is a copy of an email.  It will be tidied up later.}]

I've replaced varNotFound_handler with a new feature/framework called
'errorChecker'.  This is a debugging tool similar to, but more powerful than,
varNotFound_handler.  Cheetah now comes with a Cheetah.ErrorCheckers module that
contains various classes.  You can enable one of the classes by doing this:

\begin{verbatim}
templObj = Template(templDef, NS, 
              settings={'errorChecker':NAME_OF_CLASS })
or 
templObj = Template(templDef, NS, 
              settings={'errorCheckerClass': CLASS })
\end{verbatim}

where NAME_OF_CLASS is a string referring to one of the classes in
Cheetah.ErrorCheckers.  The current options are 'Echo', 'BigEcho', 'KeyError',
'ListErrors'.

These clases can catch any exception that occurs in a \$placeholderTag, not just
NameMapper.NotFound.  They don't work with \$vars inside \#directives.

If you used 'ListErrors' you can generate a list of errors and when they
occurred:

\begin{verbatim}
print TO.errorChecker().listErrors()
[('${aoeu}', 'Tue Aug 14 14:54:37 2001'), 
  ('${a4}', 'Tue Aug 14 14:54:37 2001')]
\end{verbatim}


[\bf The ErrorCheckers framework is intended to be used as testing and debugging
tool only.  They are relatively slow and should not be used in production
systems with high loads.  Furthermore, when they are used the caching framework
is disabled. See Cheetah.ErrorCheckers if you want more on the ErrorChecker API.
}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Output filtering}

[{\bf This description is a copy of an email.  It will be tidied up later.}]

Cheetah now has an extended output filtering framework. It involves the
``formatter'' setting, the Cheetah.Formatters module, and the new \#formatter
directive.  This framework allows you to check and re-format your \$placeholder
tag output as it is interpolated into the template output: doing such things as
replacing None with an empty string, doing string translations, truncating the
output at a max length, or even paging through the output dynamically when
Cheetah is used with Webware.

Cheetah.Formatters contains a number of classes that are ready made formatters.
To use one do this
\begin{verbatim}
templObj = Template(templDef, NS, 
              settings={'formatter':NAME_OF_CLASS })
or 
templObj = Template(templDef, NS, 
              settings={'formatterClass': CLASS })

\end{verbatim}

where NAME_OF_CLASS is a string referring to one of the classes and CLASS is a
ref to some other class that subclasses Cheetah.Formatters.BaseClass. The
current options are 'ReplaceNone' and 'MaxLen'.

If the 'formatter' settings is None, as is the default, then the formatter is
str().

You can use the \#formatter directive to change the 
formatter at any point in your template.  Usage:

\begin{verbatim}
#formatter None   ---> set it back to str()
#formatter 'MaxLen'  ---> use the class name in the quotes
#formatter $myFormatterClass  ---> use this class (must be 
available at compile time)
\end{verbatim}

Formatters can accept keyword args like this (note the commas!):
\begin{verbatim}
${c, maxlen=$x, dummyKW='1234'}
${c, maxlen=7}
${*c, maxlen=7}
${*15*c, maxlen=7}
\end{verbatim}

The first example is translated to: 
\begin{verbatim}
format(valueFromSearchList(searchList, "c", 1), 
           dummyKW=7, trans=trans),
\end{verbatim}

If you use keyword args then you must be using a formatter - using them with
'formatter':None will raise an exception.

Note the 'trans' arg (aka 'transaction') that is automatically fed to the
formatter.  When Cheetah is used with Webware, this will allow the formatters to
provide output paging and other interactive features, such as showing the full
output of a truncated \$placeholder (overriding the 'maxlen' arg).



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Plugins}

Plugins are objects that are scripted to automatically configure and extend the
Template object.  They are used to make it easy to complex modifications of
Cheetah's behaviour that would be awkward or too repetitive to do with {\bf
  settings} alone. This section explains how to use pre-built plugins. If you
want to build your own plugin please read the documented source code in the
Cheetah.Plugins package.

Cheetah's ``\code{plugins}'' argument setting accepts a list of plugins. To use
a plugin import its class from the module that contains it and feed
\code{Template()} a list containing an instance of the class. Here's an example:

\begin{verbatim}
from Cheetah.Template import Template
from Cheetah.Plugins.MyPlugin import MyPlugin
...
TO = Template(templateDef, namespace, settings={'plugins':[MyPlugin(),]})
\end{verbatim}


\subsubsection{The PSP plugin}
Cheetah ships with a plugin that enables pure PSP-style code to be used along
with Cheetah \$placeholders and \#directives.  PSP syntax can also be used
alone without \$placeholders and \#directives.

Here's a trivial example of how to use it:
\begin{verbatim}
from Cheetah.Template import Template
from Cheetah.Plugins.PSP import PSPplugin

templateDef = """
Testing Cheetah's PSP plugin:
 
$testVar
<% pspVar = 'X' %>
#set $list = [1,2,3]
 
#for $i in map(lambda x: x*x*x, $list)
$i
<%for j in range(15):%> <%=j*15%><%=pspVar%><%end%>
#end for
"""
print Template(templateDef, {'testVar':1234}, plugins=[PSPplugin()])

\end{verbatim}

% Local Variables:
% TeX-master: "users_guide"
% End: