diff options
Diffstat (limited to 'docs/users_guide_src')
25 files changed, 6144 insertions, 0 deletions
diff --git a/docs/users_guide_src/Makefile b/docs/users_guide_src/Makefile new file mode 100755 index 0000000..8b8e977 --- /dev/null +++ b/docs/users_guide_src/Makefile @@ -0,0 +1,39 @@ +# You must change PYTHONSRC to the path of your Python source distributon. +# OR just create a symlink that matches this path. +PYTHONSRC=/usr/local/src/Python-source +DOCNAME=users_guide +MKHOWTO=$(PYTHONSRC)/Doc/tools/mkhowto +MAIN_TEX_FILE= users_guide.tex + +all: ps pdf html htmlMultiPage text + +almost-all: ps html htmlMultiPage text + +pdf: + $(MKHOWTO) --pdf $(MAIN_TEX_FILE) + mv $(DOCNAME).pdf ../ + +ps: + $(MKHOWTO) --ps $(MAIN_TEX_FILE) + mv $(DOCNAME).ps ../ +html: + -rm -rf $(DOCNAME) + $(MKHOWTO) --html --split 1 --iconserver . $(MAIN_TEX_FILE) + -rm -rf ../$(DOCNAME)_html + mv $(DOCNAME) ../$(DOCNAME)_html + +htmlMultiPage: + -rm -rf $(DOCNAME) + $(MKHOWTO) --html --iconserver . $(MAIN_TEX_FILE) + -rm -rf ../$(DOCNAME)_html_multipage + mv $(DOCNAME) ../$(DOCNAME)_html_multipage + +text: + $(MKHOWTO) --text $(MAIN_TEX_FILE) + mv $(DOCNAME).txt ../ + +clean: + -rm -rf $(DOCNAME) + -rm -f *.aux *.l2h *~ *.log *.ind *.bkm *.how *.toc + -rm -rf ../html + diff --git a/docs/users_guide_src/README b/docs/users_guide_src/README new file mode 100755 index 0000000..3b45564 --- /dev/null +++ b/docs/users_guide_src/README @@ -0,0 +1,9 @@ +To build the Cheetah documentation, you need the 'mkhowto' program from +the Python source distribution. So: + +1) Get the Python source distribution and unpack it in some directory. + +2) Edit the Cheetah documentation's Makefile and change PYTHONSRC to +point to the top-level directory of your Python source distribution. + +3) Run 'make'. diff --git a/docs/users_guide_src/comments.tex b/docs/users_guide_src/comments.tex new file mode 100755 index 0000000..36323cf --- /dev/null +++ b/docs/users_guide_src/comments.tex @@ -0,0 +1,99 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Comments} +\label{comments} + +Comments are used to mark notes, explanations, and decorative text that should +not appear in the output. Cheetah maintains the comments in the Python module +it generates from the Cheetah source code. There are two forms of the comment +directive: single-line and multi-line. + +All text in a template definition that lies between two hash characters +(\code{\#\#}) and the end of the line is treated as a single-line comment and +will not show up in the output, unless the two hash characters are escaped with +a backslash. +\begin{verbatim} +##============================= this is a decorative comment-bar +$var ## this is an end-of-line comment +##============================= +\end{verbatim} + +Any text between \code{\#*} and \code{*\#} will be treated as a multi-line +comment. +\begin{verbatim} +#* + Here is some multiline + comment text +*# +\end{verbatim} + +If you put blank lines around method definitions or loops to separate them, +be aware that the blank lines will be output as is. To avoid this, make sure +the blank lines are enclosed in a comment. Since you normally have a +comment before the next method definition (right?), you can just extend that +comment to include the blank lines after the previous method definition, like +so: +\begin{verbatim} +#def method1 +... lines ... +#end def +#* + + + Description of method2. + $arg1, string, a phrase. +*# +#def method2($arg1) +... lines ... +#end def +\end{verbatim} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Docstring Comments} +\label{comments.docstring} + +Python modules, classes, and methods can be documented with inline +'documentation strings' (aka 'docstrings'). Docstrings, unlike comments, are +accesible at run-time. Thus, they provide a useful hook for interactive help +utilities. + +Cheetah comments can be transformed into doctrings by adding one of the +following prefixes: + +\begin{verbatim} +##doc: This text will be added to the method docstring +#*doc: If your template file is MyTemplate.tmpl, running "cheetah compile" + on it will produce MyTemplate.py, with a class MyTemplate in it, + containing a method .respond(). This text will be in the .respond() + method's docstring. *# + +##doc-method: This text will also be added to .respond()'s docstring +#*doc-method: This text will also be added to .respond()'s docstring *# + +##doc-class: This text will be added to the MyTemplate class docstring +#*doc-class: This text will be added to the MyTemplate class docstring *# + +##doc-module: This text will be added to the module docstring MyTemplate.py +#*doc-module: This text will be added to the module docstring MyTemplate.py*# +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Header Comments} +\label{comments.headers} +Cheetah comments can also be transformed into module header comments using the +following syntax: + +\begin{verbatim} +##header: This text will be added to the module header comment +#*header: This text will be added to the module header comment *# +\end{verbatim} + +Note the difference between \code{\#\#doc-module: } and \code{header: }: +``cheetah-compile'' puts \code{\#\#doc-module: } text inside the module +docstring. \code{header: } makes the text go {\em above} the docstring, as a +set of \#-prefixed comment lines. + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/comparisons.tex b/docs/users_guide_src/comparisons.tex new file mode 100755 index 0000000..56a0fb3 --- /dev/null +++ b/docs/users_guide_src/comparisons.tex @@ -0,0 +1,451 @@ +\section{Cheetah vs. Other Template Engines} +\label{comparisons} + +This appendix compares Cheetah with various other template/emdedded scripting +languages and Internet development frameworks. As Cheetah is similar to +Velocity at a superficial level, you may also wish to read comparisons between +Velocity and other languages at +\url{http://jakarta.apache.org/velocity/ymtd/ymtd.html}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Which features are unique to Cheetah} +\label{comparisons.unique} + +\begin{itemize} +\item The {\bf block framework} (section \ref{inheritanceEtc.block}) +\item Cheetah's powerful yet simple {\bf caching framework} (section + \ref{output.caching}) +\item Cheetah's {\bf Unified Dotted Notation} and {\bf autocalling} + (sections \ref{language.namemapper.dict} and + \ref{language.namemapper.autocalling}) +\item Cheetah's searchList (section \ref{language.searchList}) + information. +\item Cheetah's \code{\#raw} directive (section \ref{output.raw}) +\item Cheetah's \code{\#slurp} directive (section \ref{output.slurp}) +\item Cheetah's tight integration with Webware for Python (section + \ref{webware}) +\item Cheetah's {\bf SkeletonPage framework} (section + \ref{libraries.templates.skeletonPage}) +\item Cheetah's ability to mix PSP-style code with Cheetah + Language syntax (section \ref{tips.PSP}) + Because of Cheetah's design and Python's flexibility it is + relatively easy to extend Cheetah's syntax with syntax elements from almost + any other template or embedded scripting language. +\end{itemize} + +%% @@MO: What about the new features we've been adding? + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. Velocity} +\label{comparisons.velocity} + +For a basic introduction to Velocity, visit +\url{http://jakarta.apache.org/velocity}. + +Velocity is a Java template engine. It's older than Cheetah, has a larger user +base, and has better examples and docs at the moment. Cheetah, however, has a +number of advantages over Velocity: +\begin{itemize} +\item Cheetah is written in Python. Thus, it's easier to use and extend. +\item Cheetah's syntax is closer to Python's syntax than Velocity's is to +Java's. +\item Cheetah has a powerful caching mechanism. Velocity has no equivalent. +\item It's far easier to add data/objects into the namespace where \$placeholder + values are extracted from in Cheetah. Velocity calls this namespace a 'context'. + Contexts are dictionaries/hashtables. You can put anything you want into a + context, BUT you have to use the .put() method to populate the context; + e.g., + +\begin{verbatim} +VelocityContext context1 = new VelocityContext(); +context1.put("name","Velocity"); +context1.put("project", "Jakarta"); +context1.put("duplicate", "I am in context1"); +\end{verbatim} + + Cheetah takes a different approach. Rather than require you to manually + populate the 'namespace' like Velocity, Cheetah will accept any existing + Python object or dictionary AS the 'namespace'. Furthermore, Cheetah + allows you to specify a list namespaces that will be searched in sequence + to find a varname-to-value mapping. This searchList can be extended at + run-time. + + If you add a `foo' object to the searchList and the `foo' has an attribute + called 'bar', you can simply type \code{\$bar} in the template. If the + second item in the searchList is dictionary 'foofoo' containing + \code{\{'spam':1234, 'parrot':666\}}, Cheetah will first look in the `foo' + object for a `spam' attribute. Not finding it, Cheetah will then go to + `foofoo' (the second element in the searchList) and look among its + dictionary keys for `spam'. Finding it, Cheetah will select + \code{foofoo['spam']} as \code{\$spam}'s value. + +\item In Cheetah, the tokens that are used to signal the start of + \$placeholders and \#directives are configurable. You can set them to any + character sequences, not just \$ and \#. +\end{itemize} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. WebMacro} +\label{comparisons.webmacro} + +For a basic introduction to WebMacro, visit +\url{http://webmacro.org}. + +The points discussed in section \ref{comparisons.velocity} also apply to the +comparison between Cheetah and WebMacro. For further differences please refer +to \url{http://jakarta.apache.org/velocity/differences.html}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. Zope's DTML} +\label{comparisons.dtml} + +For a basic introduction to DTML, visit +\url{http://www.zope.org/Members/michel/ZB/DTML.dtml}. + +\begin{itemize} +\item Cheetah is faster than DTML. +\item Cheetah does not use HTML-style tags; DTML does. Thus, Cheetah tags are + visible in rendered HTML output if something goes wrong. +\item DTML can only be used with ZOPE for web development; Cheetah can be + used as a standalone tool for any purpose. +\item Cheetah's documentation is more complete than DTML's. +\item Cheetah's learning curve is shorter than DTML's. +\item DTML has no equivalent of Cheetah's blocks, caching framework, + unified dotted notation, and \code{\#raw} directive. +\end{itemize} + +Here are some examples of syntax differences between DTML and Cheetah: +\begin{verbatim} +<ul> +<dtml-in frogQuery> + <li><dtml-var animal_name></li> +</dtml-in> +</ul> +\end{verbatim} + +\begin{verbatim} +<ul> +#for $animal_name in $frogQuery + <li>$animal_name</li> +#end for +</ul> +\end{verbatim} + +\begin{verbatim} +<dtml-if expr="monkeys > monkey_limit"> + <p>There are too many monkeys!</p> +<dtml-elif expr="monkeys < minimum_monkeys"> + <p>There aren't enough monkeys!</p> +<dtml-else> + <p>There are just enough monkeys.</p> +</dtml-if> +\end{verbatim} + +\begin{verbatim} +#if $monkeys > $monkey_limit + <p>There are too many monkeys!</p> +#else if $monkeys < $minimum_monkeys + <p>There aren't enough monkeys!</p> +#else + <p>There are just enough monkeys.</p> +#end if +\end{verbatim} + +\begin{verbatim} +<table> +<dtml-in expr="objectValues('File')"> + <dtml-if sequence-even> + <tr bgcolor="grey"> + <dtml-else> + <tr> + </dtml-if> + <td> + <a href="&dtml-absolute_url;"><dtml-var title_or_id></a> + </td></tr> +</dtml-in> +</table> +\end{verbatim} + +\begin{verbatim} +<table> +#set $evenRow = 0 +#for $file in $files('File') + #if $evenRow + <tr bgcolor="grey"> + #set $evenRow = 0 + #else + <tr> + #set $evenRow = 1 + #end if + <td> + <a href="$file.absolute_url">$file.title_or_id</a> + </td></tr> +#end for +</table> +\end{verbatim} + +The last example changed the name of \code{\$objectValues} to +\code{\$files} because that's what a Cheetah developer would write. +The developer would be responsible for ensuring \code{\$files} returned a +list (or tuple) of objects (or dictionaries) containing the attributes (or +methods or dictionary keys) `absolute\_url' and `title\_or\_id'. All these +names (`objectValues', `absolute\_url' and `title\_or\_id') are standard parts +of Zope, but in Cheetah the developer is in charge of writing them and giving +them a reasonable behaviour. + +Some of DTML's features are being ported to Cheetah, such as +\code{Cheetah.Tools.MondoReport}, which is based on the +\code{<dtml-in>} tag. We are also planning an output filter as flexible as +the \code{<dtml-var>} formatting options. However, neither of these are +complete yet. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. Zope Page Templates} +\label{comparisons.zpt} + +For a basic introduction to Zope Page Templates, please visit +\url{http://www.zope.org/Documentation/Articles/ZPT2}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. PHP's Smarty templates} +\label{comparisons.smarty} + +PHP (\url{http://www.php.net/}) is one of the few scripting languages +expressly designed for web servlets. However, it's also a full-fledged +programming language with libraries similar to Python's and Perl's. The +syntax and functions are like a cross between Perl and C plus some original +ideas (e.g.; a single array type serves as both a list and a dictionary, +\verb+$arr[]="value";+ appends to an array). + +Smarty (\url{http://smarty.php.net/}) is an advanced template engine for +PHP. ({\em Note:} this comparision is based on Smarty's on-line documentation. +The author has not used Smarty. Please send corrections or ommissions to the +Cheetah mailing list.) Like Cheetah, Smarty: + +\begin{itemize} +\item compiles to the target programming language (PHP). +\item has configurable delimeters. +\item passes if-blocks directly to PHP, so you can use any PHP expression in +them. +\item allows you to embed PHP code in a template. +\item has a caching framework (although it works quite differently). +\item can read the template definition from any arbitrary source. +\end{itemize} + +Features Smarty has that Cheetah lacks: +\begin{itemize} +\item Preprocessors, postprocessors and output filters. You can emulate a +preprocessor in Cheetah by running your template definition through a filter +program or function before Cheetah sees it. To emulate a postprocessor, run a +.py template module through a filter program/function. To emulate a Smarty +output filter, run the template output through a filter program/function. If +you want to use ``cheetah compile'' or ``cheetah fill'' in a pipeline, use +\code{-} as the input file name and \code{--stdout} to send the result to +standard output. Note that Cheetah uses the term ``output filter'' differently +than Smarty: Cheetah output filters (\code{\#filter}) operate on placeholders, +while Smarty output filters operate on the entire template output. There has +been a proposed \code{\#sed} directive that would operate on the entire output +line by line, but it has not been implemented. +\item Variable modifiers. In some cases, Python has equivalent string +methods (\code{.strip}, \code{.capitalize}, \code{.replace(SEARCH, REPL)}), +but in other cases you must wrap the result in a function call or write +a custom output filter (\code{\#filter}). +\item Certain web-specific functions, which can be emulated with +third-party functions. +\item The ability to ``plug in'' new directives in a modular way. Cheetah +directives are tightly bound to the compiler. However, third-party +{\em functions} can be freely imported and called from placeholders, and +{\em methods} can be mixed in via \code{\#extends}. Part of this is +because Cheetah distinguishes between functions and directives, while +Smarty treats them all as ``functions''. Cheetah's design does not +allow functions to have flow control effect outside the function +(e.g., \code{\#if} and \code{\#for}, which operate on template body lines), +so directives like these cannot be encoded as functions. +\item Configuration variables read from an .ini-style file. The +\code{Cheetah.SettingsManager} module can parse such a file, but you'd +have to invoke it manually. (See the docstrings in the module for +details.) In Smarty, this feature is used for +multilingual applications. In Cheetah, the developers maintain that everybody +has their own preferred way to do this (such as using Python's \code{gettext} +module), and it's not worth blessing one particular strategy in Cheetah since +it's easy enough to integrate third-party code around the template, or to add +the resulting values to the searchList. +\end{itemize} + +Features Cheetah has that Smarty lacks: +\begin{itemize} +\item Saving the compilation result in a Python (PHP) module for quick +reading later. +\item Caching individual placeholders or portions of a template. Smarty +caches only the entire template output as a unit. +\end{itemize} + +Comparisions of various Smarty constructs: +\begin{verbatim} +{assign var="name" value="Bob"} (#set has better syntax in the author's opinion) +counter (looks like equivalent to #for) +eval (same as #include with variable) +fetch: insert file content into output (#include raw) +fetch: insert URL content into output (no euqivalent, user can write + function calling urllib, call as $fetchURL('URL') ) +fetch: read file into variable (no equivalent, user can write function + based on the 'open/file' builtin, or on .getFileContents() in + Template.) +fetch: read URL content into variable (no equivalent, use above + function and call as: #set $var = $fetchURL('URL') +html_options: output an HTML option list (no equivalent, user can + write custom function. Maybe FunFormKit can help.) +html_select_date: output three dropdown controls to specify a date + (no equivalent, user can write custom function) +html_select_time: output four dropdown controls to specify a time + (no equvalent, user can write custom function) +math: eval calculation and output result (same as #echo) +math: eval calculation and assign to variable (same as #set) +popup_init: library for popup windows (no equivalent, user can write + custom method outputting Javascript) + + +Other commands: +capture (no equivalent, collects output into variable. A Python + program would create a StringIO instance, set sys.stdout to + it temporarily, print the output, set sys.stdout back, then use + .getvalue() to get the result.) +config_load (roughly analagous to #settings, which was removed + from Cheetah. Use Cheetah.SettingsManager manually or write + a custom function.) +include (same as #include, but can include into variable. + Variables are apparently shared between parent and child.) +include_php: include a PHP script (e.g., functions) + (use #extends or #import instead) +insert (same as #include not in a #cache region) +{ldelim}{rdelim} (escape literal $ and # with a backslash, + use #compiler-settings to change the delimeters) +literal (#raw) +php (``<% %>'' tags) +section (#for $i in $range(...) ) +foreach (#for) +strip (like the #sed tag which was never implemented. Strips + leading/trailing whitespace from lines, joins several lines + together.) + + +Variable modifiers: +capitalize ( $STRING.capitalize() ) +count_characters ( $len(STRING) ) +count_paragraphs/sentances/words (no equivalent, user can write function) +date_format (use 'time' module or download Egenix's mx.DateTime) +default ($getVar('varName', 'default value') ) +escape: html encode ($cgi.escape(VALUE) ) +escape: url encode ($urllib.quote_plus(VALUE) ) +escape: hex encode (no equivalent? user can write function) +escape: hex entity encode (no equivalent? user can write function) +indent: indent all lines of a var's output (may be part of future + #indent directive) +lower ($STRING.lower() ) +regex_replace ('re' module) +replace ($STRING.replace(OLD, NEW, MAXSPLIT) ) +spacify (#echo "SEPARATOR".join(SEQUENCE) ) +string_format (#echo "%.2f" % FLOAT , etc.) +strip_tags (no equivalent, user can write function to strip HTML tags, + or customize the WebSafe filter) +truncate (no equivalent, user can write function) +upper ($STRING.upper() ) +wordwrap ('writer' module, or a new module coming in Python 2.3) +\end{verbatim} + +Some of these modifiers could be added to the super output filter we +want to write someday. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. PHPLib's Template class} +\label{comparisons.php} + +PHPLib (\url(http://phplib.netuse.de/) is a collection of classes for various +web objects (authentication, shopping cart, sessions, etc), but what we're +interested in is the \code{Template} object. It's much more primitive than +Smarty, and was based on an old Perl template class. In fact, one of the +precursors to Cheetah was based on it too. Differences from Cheetah: + +\begin{itemize} +\item Templates consist of text with \code{\{placeholders\}} in braces. +\item Instead of a searchList, there is one flat namespace. Every variable + must be assigned via the \code{set\_var} method. However, you can pass + this method an array (dictionary) of several variables at once. +\item You cannot embed lookups or calculations into the template. Every + placeholder must be an exact variable name. +\item There are no directives. You must do all display logic (if, for, etc) + in the calling routine. +\item There is, however, a ``block'' construct. A block is a portion of text + between the comment markers \code{<!-- BEGIN blockName --> \ldots + <!-- END blockName>}. The \code{set\_block} method extracts this text + into a namespace variable and puts a placeholder referring to it in the + template. This has a few parallels with Cheetah's \code{\#block} + directive but is overall quite different. +\item To do the equivalent of \code{\#if}, extract the block. Then if true, do + nothing. If false, assign the empty string to the namespace variable. +\item To do the equivalent of \code{\#for}, extract the block. Set any + namespace variables needed inside the loop. To parse one iteration, use + the \code{parse} method to fill the block variable (a mini-template) into + another namespace variable, appending to it. Refresh the namespace + variables needed inside the loop and parse again; repeat for each + iteration. You'll end up with a mini-result that will be plugged into the + main template's placeholder. +\item To read a template definition from a file, use the \code{set\_file} + method. This places the file's content in a namespace variable. + To read a template definition from a string, assign it to a namespace + variable. +\item Thus, for complicated templates, you are doing a lot of recursive block + filling and file reading and parsing mini-templates all into one flat + namespace as you finally build up values for the main template. In + Cheetah, all this display logic can be embedded into the template using + directives, calling out to Python methods for the more complicated tasks. +\item Although you can nest blocks in the template, it becomes tedious and + arguably hard to read, because all blocks have identical syntax. Unless + you choose your block names carefully and put comments around them, it's + hard to tell which blocks are if-blocks and which are for-blocks, or what + their nesting order is. +\item PHPLib templates do not have caching, output filters, etc. +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. PSP, PHP, ASP, JSP, Embperl, etc.} +\label{comparisons.pspEtc} + +\begin{description} +\item[Webware's PSP Component] -- \url{http://webware.sourceforge.net/Webware/PSP/Docs/} +\item[Tomcat JSP Information] -- \url{http://jakarta.apache.org/tomcat/index.html} +\item[ASP Information at ASP101] -- \url{http://www.asp101.com/} +\item[Embperl] -- \url{http://perl.apache.org/embperl/} +\end{description} + + +Here's a basic Cheetah example: +\begin{verbatim} +<TABLE> +#for $client in $service.clients +<TR> +<TD>$client.surname, $client.firstname</TD> +<TD><A HREF="mailto:$client.email" >$client.email</A></TD> +</TR> +#end for +</TABLE> +\end{verbatim} + +Compare this with PSP: + +\begin{verbatim} +<TABLE> +<% for client in service.clients(): %> +<TR> +<TD><%=client.surname()%>, <%=client.firstname()%></TD> +<TD><A HREF="mailto:<%=client.email()%>"><%=client.email()%></A></TD> +</TR> +<%end%> +</TABLE> +\end{verbatim} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/editors.tex b/docs/users_guide_src/editors.tex new file mode 100755 index 0000000..84c8f03 --- /dev/null +++ b/docs/users_guide_src/editors.tex @@ -0,0 +1,39 @@ +\section{Visual Editors} +\label{visualEditors} + +This chapter is about maintaining Cheetah templates with visual editors, +and the tradeoffs between making it friendly to both text editors and visual +editors. + +Cheetah's main developers do not use visual editors. Tavis uses \code{emacs}; +Mike uses \code{vim}. So our first priority is to make templates easy to +maintain in text editors. In particular, we don't want to add features +like Zope Page Template's +placeholder-value-with-mock-text-for-visual-editors-all-in-an-XML-tag. +The syntax is so verbose it makes for a whole lotta typing just to insert a +simple placeholder, for the benefit of editors we never use. However, as users +identify features which would help their visual editing without making it +harder to maintain templates in a text editor, we're all for it. + +As it said in the introduction, Cheetah purposely does not use HTML/XML +tags for \$placeholders or \#directives. That way, when you preview the +template in an editor that interprets HTML tags, you'll still see the +placeholder and directive source definitions, which provides some ``mock text'' +even if it's not the size the final values will be, and allows you to use +your imagination to translate how the directive output will look visually in +the final. + +If your editor has syntax highlighting, turn it on. That makes a big +difference in terms of making the template easier to edit. Since no +``Cheetah mode'' has been invented yet, set your highlighting to Perl +mode, and at least the directives/placeholders will show up in different +colors, although the editor won't reliably guess where the +directive/placeholder ends and normal text begins. + +% Local Variables: +% TeX-master: "users_guide" +% End: + + + + diff --git a/docs/users_guide_src/errorHandling.tex b/docs/users_guide_src/errorHandling.tex new file mode 100755 index 0000000..28eee3a --- /dev/null +++ b/docs/users_guide_src/errorHandling.tex @@ -0,0 +1,145 @@ +\section{Error Handling} +\label{errorHandling} + +There are two ways to handle runtime errors (exceptions) in Cheetah. The first +is with the Cheetah directives that mirror Python's structured exception +handling statements. The second is with Cheetah's \code{ErrorCatcher} +framework. These are described below. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#try ... \#except ... \#end try, \#finally, and \#assert} +\label{errorHandling.directives} + +Cheetah's exception-handling directives are exact mirrors Python's +exception-handling statements. See Python's documentation for details. The +following Cheetah code demonstrates their use: + + +\begin{verbatim} +#try + $mightFail() +#except + It failed +#end try + +#try + #assert $x == $y +#except AssertionError + They're not the same! +#end try + +#try + #raise ValueError +#except ValueError + #pass +#end try + + +#try + $mightFail() +#except ValueError + Hey, it raised a ValueError! +#except NameMapper.NotFound + Hey, it raised a NameMapper.NotFound! +#else + It didn't raise anything! +#end try + +#try + $mightFail() +#finally + $cleanup() +#end try +\end{verbatim} + +Like Python, \code{\#except} and \code{\#finally} cannot appear in the same +try-block, but can appear in nested try-blocks. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#errorCatcher and ErrorCatcher objects} +\label{errorHandling.errorCatcher} + +Syntax: +\begin{verbatim} +#errorCatcher CLASS +#errorCatcher $PLACEHOLDER_TO_AN_ERROR_CATCHER_INSTANCE +\end{verbatim} + + +\code{ErrorCatcher} is a debugging tool that catches exceptions that occur +inside \code{\$placeholder} tags and provides a customizable warning to the +developer. Normally, the first missing namespace value raises a +\code{NameMapper.NotFound} error and halts the filling of the template. This +requires the developer to resolve the exceptions in order without seeing the +subsequent output. When an \code{ErrorCatcher} is enabled, the developer can +see all the exceptions at once as well as the template output around them. + +The \code{Cheetah.ErrorCatchers} module defines the base class for +ErrorCatchers: + +\begin{verbatim} +class ErrorCatcher: + _exceptionsToCatch = (NameMapper.NotFound,) + + def __init__(self, templateObj): + pass + + def exceptions(self): + return self._exceptionsToCatch + + def warn(self, exc_val, code, rawCode, lineCol): + return rawCode +\end{verbatim} + +This ErrorCatcher catches \code{NameMapper.NotFound} exceptions and leaves the +offending placeholder visible in its raw form in the template output. If the +following template is executed: +\begin{verbatim} +#errorCatcher Echo +#set $iExist = 'Here I am!' +Here's a good placeholder: $iExist +Here's bad placeholder: $iDontExist +\end{verbatim} + +the output will be: +\begin{verbatim} +Here's a good placeholder: Here I am! +Here's bad placeholder: $iDontExist +\end{verbatim} + +The base class shown above is also accessible under the alias +\code{Cheetah.ErrorCatchers.Echo}. \code{Cheetah.ErrorCatchers} also provides a +number of specialized subclasses that warn about exceptions in different ways. +\code{Cheetah.ErrorCatchers.BigEcho} will output + +\begin{verbatim} +Here's a good placeholder: Here I am! +Here's bad placeholder: ===============<$iDontExist could not be found>=============== +\end{verbatim} + +ErrorCatcher has a significant performance impact and is turned off by default. +It can also be turned on with the \code{Template} class' \code{'errorCatcher'} +keyword argument. The value of this argument should either be a string +specifying which of the classes in \code{Cheetah.ErrorCatchers} to use, or a +class that subclasses \code{Cheetah.ErrorCatchers.ErrorCatcher}. The +\code{\#errorCatcher} directive can also be used to change the errorCatcher part +way through a template. + +\code{Cheetah.ErrorCatchers.ListErrors} will produce the same ouput as +\code{Echo} while maintaining a list of the errors that can be retrieved later. +To retrieve the list, use the \code{Template} class' \code{'errorCatcher'} +method to retrieve the errorCatcher and then call its \code{listErrors} method. + +ErrorCatcher doesn't catch exceptions raised inside directives. + +% @@MO: How do you turn ErrorCatcher off after turn it on. +% '#ErrorCatcher None'? + +% Local Variables: +% TeX-master: "users_guide" +% End: + + + + diff --git a/docs/users_guide_src/examples.tex b/docs/users_guide_src/examples.tex new file mode 100755 index 0000000..6c394fb --- /dev/null +++ b/docs/users_guide_src/examples.tex @@ -0,0 +1,24 @@ +\section{Examples} +\label{examples} + +The Cheetah distribution comes with an 'examples' directory. Browse the +files in this directory and its subdirectories for examples of how +Cheetah can be used. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Syntax examples} +The \code{Cheetah.Tests} module contains a large number of test cases that can +double as examples of how the Cheetah Language works. To view these cases go +to the base directory of your Cheetah distribution and open the file +\code{Cheetah/Tests/SyntaxAndOutput.py} in a text editor. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Webware Examples} +For examples of Cheetah in use with Webware visit the Cheetah and Webware wikis +or use google. We used to have more examples in the cheetah source tarball, but +they were out of date and confused people. + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/flowControl.tex b/docs/users_guide_src/flowControl.tex new file mode 100755 index 0000000..75a5845 --- /dev/null +++ b/docs/users_guide_src/flowControl.tex @@ -0,0 +1,414 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Flow Control} +\label{flowControl} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#for ... \#end for} +\label{flowControl.for} + +Syntax: +\begin{verbatim} +#for $var in EXPR +#end for +\end{verbatim} + + +The \code{\#for} directive iterates through a sequence. The syntax is the same +as Python, but remember the \code{\$} before variables. + +Here's a simple client listing: +\begin{verbatim} +<TABLE> +#for $client in $service.clients +<TR> +<TD>$client.surname, $client.firstname</TD> +<TD><A HREF="mailto:$client.email" >$client.email</A></TD> +</TR> +#end for +</TABLE> +\end{verbatim} + +Here's how to loop through the keys and values of a dictionary: +\begin{verbatim} +<PRE> +#for $key, $value in $dict.items() +$key: $value +#end for +</PRE> +\end{verbatim} + +Here's how to create list of numbers separated by hyphens. This ``\#end for'' +tag shares the last line to avoid introducing a newline character after each +hyphen. +\begin{verbatim} +#for $i in range(15) +$i - #end for +\end{verbatim} + +If the location of the \code{\#end for} offends your sense of indentational +propriety, you can do this instead: +\begin{verbatim} +#for $i in $range(15) +$i - #slurp +#end for +\end{verbatim} + +The previous two examples will put an extra hyphen after last number. Here's +how to get around that problem, using the \code{\#set} directive, which will be +dealt with in more detail below. +\begin{verbatim} +#set $sep = '' +#for $name in $names +$sep$name +#set $sep = ', ' +#end for +\end{verbatim} + +Although to just put a separator between strings, you don't need a for loop: +\begin{verbatim} +#echo ', '.join($names) +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#repeat ... \#end repeat} +\label{flowControl.repeat} + +Syntax: +\begin{verbatim} +#repeat EXPR +#end repeat +\end{verbatim} + + +Do something a certain number of times. +The argument may be any numeric expression. +If it's zero or negative, the loop will execute zero times. +\begin{verbatim} +#repeat $times + 3 +She loves me, she loves me not. +#repeat +She loves me. +\end{verbatim} + + +Inside the loop, there's no way to tell which iteration you're on. If you +need a counter variable, use \code{\#for} instead with Python's \code{range} +function. Since Python's ranges are base 0 by default, there are two ways +to start counting at 1. Say we want to count from 1 to 5, and that +\code{\$count} is 5. +\begin{verbatim} +#for $i in $range($count) +#set $step = $i + 1 +$step. Counting from 1 to $count. +#end for + + +#for $i in $range(1, $count + 1) +$i. Counting from 1 to $count. +#end for +\end{verbatim} + + +A previous implementation used a local variable \code{\$i} as the repeat +counter. However, this prevented instances of \code{\#repeat} from +being nested. The current implementation does not have this problem as it +uses a new local variable for every instance of \code{\#repeat}. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#while ... \#end while} +\label{flowControl.while} + +Syntax: +\begin{verbatim} +#while EXPR +#end while +\end{verbatim} + + +\code{\#while} is the same as Python's \code{while} statement. It may be +followed by any boolean expression: +\begin{verbatim} +#while $someCondition('arg1', $arg2) +The condition is true. +#end while +\end{verbatim} + +Be careful not to create an infinite loop. \code{\#while 1} will loop until +the computer runs out of memory. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#if ... \#else if ... \#else ... \#end if} +\label{flowControl.if} + +Syntax: +\begin{verbatim} +#if EXPR +#else if EXPR +#elif EXPR +#else +#end if +\end{verbatim} + + +The \code{\#if} directive and its kin are used to display a portion of text +conditionally. \code{\#if} and \code{\#else if} should be followed by a +true/false expression, while \code{\#else} should not. Any valid Python +expression is allowed. As in Python, the expression is true unless it evaluates +to 0, '', None, an empty list, or an empty dictionary. In deference to Python, +\code{\#elif} is accepted as a synonym for \code{\#else if}. + +Here are some examples: +\begin{verbatim} +#if $size >= 1500 +It's big +#else if $size < 1500 and $size > 0 +It's small +#else +It's not there +#end if +\end{verbatim} + +\begin{verbatim} +#if $testItem($item) +The item $item.name is OK. +#end if +\end{verbatim} + +Here's an example that combines an \code{\#if} tag with a \code{\#for} tag. +\begin{verbatim} +#if $people +<table> +<tr> +<th>Name</th> +<th>Address</th> +<th>Phone</th> +</tr> +#for $p in $people +<tr> +<td>$p.name</td> +<td>$p.address</td> +<td>$p.phone</td> +</tr> +#end for +</table> +#else +<p> Sorry, the search did not find any people. </p> +#end if +\end{verbatim} + +See section \ref{output.oneLineIf} for the one-line \code{\#if} directive, +which is equivalent to Perl's and C's \code{?:} operator. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#unless ... \#end unless} +\label{flowControl.unless} + +Syntax: +\begin{verbatim} +#unless EXPR +#end unless +\end{verbatim} + + +\code{\#unless} is the opposite of \code{\#if}: the text is executed if the +condition is {\bf false}. Sometimes this is more convenient. +\code{\#unless EXPR} is equivalent to \code{\#if not (EXPR)}. + +\begin{verbatim} +#unless $alive +This parrot is no more! He has ceased to be! +'E's expired and gone to meet 'is maker! ... +THIS IS AN EX-PARROT!! +#end unless +\end{verbatim} + +You cannot use \code{\#else if} or \code{\#else} inside an \code{\#unless} +construct. If you need those, use \code{\#if} instead. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#break and \#continue} +\label{flowControl.break} + +Syntax: +\begin{verbatim} +#break +#continue +\end{verbatim} + + +These directives are used as in Python. \code{\#break} will +exit a \code{\#for} loop prematurely, while \code{\#continue} will immediately +jump to the next iteration in the \code{\#for} loop. + +In this example the output list will not contain ``10 - ''. +\begin{verbatim} +#for $i in range(15) +#if $i == 10 + #continue +#end if +$i - #slurp +#end for +\end{verbatim} + +In this example the loop will exit if it finds a name that equals 'Joe': +\begin{verbatim} +#for $name in $names +#if $name == 'Joe' + #break +#end if +$name - #slurp +#end for +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#pass} +\label{flowControl.pass} + +Syntax: +\begin{verbatim} +#pass +\end{verbatim} + + +The \code{\#pass} directive is identical to Python \code{pass} statement: it +does nothing. It can be used when a statement is required syntactically but the +program requires no action. + +The following example does nothing if only \$A is true +\begin{verbatim} +#if $A and $B + do something +#elif $A + #pass +#elif $B + do something +#else + do something +#end if +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#stop} +\label{flowControl.stop} + +Syntax: +\begin{verbatim} +#stop +\end{verbatim} + + +The \code{\#stop} directive is used to stop processing of a template at a +certain point. The output will show {\em only} what has been processed up to +that point. + +When \code{\#stop} is called inside an \code{\#include} it skips the rest of +the included code and continues on from after the \code{\#include} directive. +stop the processing of the included code. Likewise, when \code{\#stop} is +called inside a \code{\#def} or \code{\#block}, it stops only the \code{\#def} +or \code{\#block}. + +\begin{verbatim} +A cat +#if 1 + sat on a mat + #stop + watching a rat +#end if +in a flat. +\end{verbatim} + +will print +\begin{verbatim} +A cat + sat on a mat +\end{verbatim} + +And +\begin{verbatim} +A cat +#block action + sat on a mat + #stop + watching a rat +#end block +in a flat. +\end{verbatim} + +will print + +\begin{verbatim} +A cat + sat on a mat +in a flat. +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#return} +\label{flowControl.return} + +Syntax: +\begin{verbatim} +#return +\end{verbatim} + + +This is used as in Python. \code{\#return} will exit the current method with a +default return value of \code{None} or the value specified. It may be used +only inside a \code{\#def} or a \code{\#block}. + +Note that \code{\#return} is different from the \code{\#stop} directive, +which returns the sum of all text output from the method in which it is called. +The following examples illustrate this point: + +\begin{verbatim} +1 +$test[1] +3 +#def test +1.5 +#if 1 +#return '123' +#else +99999 +#end if +#end def +\end{verbatim} + +will produce +\begin{verbatim} +1 +2 +3 +\end{verbatim} + +while +\begin{verbatim} +1 +$test +3 +#def test +1.5 +#if 1 +#stop +#else +99999 +#end if +#end def +\end{verbatim} + +will produce +\begin{verbatim} +1 +1.5 +3 +\end{verbatim} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/gettingStarted.tex b/docs/users_guide_src/gettingStarted.tex new file mode 100755 index 0000000..69a3136 --- /dev/null +++ b/docs/users_guide_src/gettingStarted.tex @@ -0,0 +1,266 @@ +\section{Getting Started} +\label{gettingStarted} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Requirements} +\label{gettingStarted.requirements} + +Cheetah requires Python release 2.0 or greater, and has been tested with Python +2.0, 2.1 and 2.2. It is known to run on Linux, Windows NT/98/XP, FreeBSD and +Solaris, and should run anywhere Python runs. + +99\% of Cheetah is written in Python. There is one small C module +(\code{\_namemapper.so}) for speed, but Cheetah automatically falls back to a +Python equivalent (\code{NameMapper.py}) if the C module is not available. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Installation} +\label{gettingStarted.install} + +To install Cheetah in your system-wide Python library: +\begin{enumerate} +\item Login as a user with privileges to install system-wide Python packages. + On POSIX systems (AIX, Solaris, Linux, IRIX, etc.), the command is normally + 'su root'. On non-POSIX systems such as Windows NT, login as an + administrator. + +\item Run \code{python setup.py install} at the command prompt. + +\item The setup program will install the wrapper script {\bf cheetah} to + wherever it usually puts Python binaries ("/usr/bin/", "bin/" in the + Python install directory, etc.) +\end{enumerate} + +Cheetah's installation is managed by Python's Distribution Utilities +('distutils'). There are many options for customization. Type \code{``python + setup.py help''} for more information. + +To install Cheetah in an alternate location -- someplace outside Python's +\code{site-packages/} directory, use one of these options: +\begin{verbatim} + python setup.py install --home /home/tavis + python setup.py install --install-lib /home/tavis/lib/python +\end{verbatim} +Either way installs to /home/tavis/lib/python/Cheetah/ . Of course, +/home/tavis/lib/python must be in your Python path in order for Python to +find Cheetah. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Files} +\label{gettingstarted.files} + +If you do the systemwide install, all Cheetah modules are installed in the +{\bf site-packages/Cheetah/} subdirectory of your standard library +directory; e.g., /opt/Python2.2/lib/python2.2/site-packages/Cheetah. + +Two commands are installed in Python's \code{bin/} directory or a system +bin directory: \code{cheetah} (section \ref{gettingStarted.cheetah}) and +\code{cheetah-compile} (section \ref{howWorks.cheetah-compile}). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Uninstalling} +\label{gettingstarted.uninstalling} + +% @@MO: When 'python setup.py uninstall' is implemented, mention it here. + +To uninstall Cheetah, merely delete the site-packages/Cheetah/ directory. +Then delete the ``cheetah'' and ``cheetah-compile'' commands from whichever +bin/ directory they were put in. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{The 'cheetah' command} +\label{gettingStarted.cheetah} + +Cheetah comes with a utility \code{cheetah} that provides a command-line +interface to various housekeeping tasks. The command's first argument is +the name of the task. The following commands are currently supported: + +\begin{verbatim} +cheetah compile [options] [FILES ...] : Compile template definitions +cheetah fill [options] [FILES ...] : Fill template definitions +cheetah help : Print this help message +cheetah options : Print options help message +cheetah test : Run Cheetah's regression tests +cheetah version : Print Cheetah version number +\end{verbatim} + +You only have to type the first letter of the command: +\code{cheetah c} is the same as \code{cheetah compile}. + +The test suite is described in the next section. The \code{compile} +command will be described in section \ref{howWorks.cheetah-compile}, +and the \code{fill} command in section \ref{howWorks.cheetah-fill}. + +The depreciated \code{cheetah-compile} program does the same thing as +\code{cheetah compile}. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Testing your installation} +\label{gettingStarted.test} + +After installing Cheetah, you can run its self-test routine to verify it's +working properly on your system. Change directory to any directory you have +write permission in (the tests write temporary files). Do not run the tests +in the directory you installed Cheetah from, or you'll get unnecessary errors. +Type the following at the command prompt: +\begin{verbatim} +cheetah test +\end{verbatim} + +The tests will run for about three minutes and print a success/failure +message. If the tests pass, start Python in interactive mode and try the +example in the next section. + +Certain test failures are insignificant: +\begin{description} +\item{{\bf AssertionError: Template output mismatch: Expected Output = 0(end) +Actual Output = False(end)}} Python 2.3 changed the string representation of +booleans, and the tests haven't yet been updated to reflect this. +\item{{\bf AssertionError: subcommand exit status 127}} Certain tests run +``cheetah'' as a subcommand. The failure may mean the command wasn't found +in your system path. (What happens if you run ``cheetah'' on the command line?) +The failure also happens on some Windows systems for unknown reasons. This +failure has never been observed outside the test suite. Long term, we plan to +rewrite the tests to do a function call rather than a subcommand, which will +also make the tests run significantly faster. +\item{{\bf ImportError: No module named SampleBaseClass}} The test tried to +write a temporary module in the current directory and \code{import} it. Reread +the first paragraph in this section about the current directory. +\item{{\bf ImportError: No module named tmp}} May be the same problem as +SampleBaseClass; let us know if changing the current directory doesn't work. +\end{description} + +If any other tests fail, please send a message to the e-mail list with a copy +of the test output and the following details about your installation: + +\begin{enumerate} +\item your version of Cheetah +\item your version of Python +\item your operating system +\item whether you have changed anything in the Cheetah installation +\end{enumerate} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Quickstart tutorial} +\label{gettingStarted.tutorial} + +This tutorial briefly introduces how to use Cheetah from the Python prompt. +The following chapters will discuss other ways to use templates and more of +Cheetah's features. + +The core of Cheetah is the \code{Template} class in the \code{Cheetah.Template} +module. The following example shows how to use the \code{Template} class in an +interactive Python session. \code{t} is the Template instance. Lines prefixed +with \code{>>>} and \code{...} are user input. The remaining lines are Python +output. + +\begin{verbatim} +>>> from Cheetah.Template import Template +>>> templateDef = """ +... <HTML> +... <HEAD><TITLE>$title</TITLE></HEAD> +... <BODY> +... $contents +... ## this is a single-line Cheetah comment and won't appear in the output +... #* This is a multi-line comment and won't appear in the output +... blah, blah, blah +... *# +... </BODY> +... </HTML>""" +>>> nameSpace = {'title': 'Hello World Example', 'contents': 'Hello World!'} +>>> t = Template(templateDef, searchList=[nameSpace]) +>>> print t + +<HTML> +<HEAD><TITLE>Hello World Example</TITLE></HEAD> +<BODY> +Hello World! +</BODY> +</HTML> +>>> print t # print it as many times as you want + [ ... same output as above ... ] +>>> nameSpace['title'] = 'Example #2' +>>> nameSpace['contents'] = 'Hiya Planet Earth!' +>>> print t # Now with different plug-in values. +<HTML> +<HEAD><TITLE>Example #2</TITLE></HEAD> +<BODY> +Hiya Planet Earth! +</BODY> +</HTML> + +\end{verbatim} + +Since Cheetah is extremely flexible, you can achieve the same result this +way: + +\begin{verbatim} +>>> t2 = Template(templateDef) +>>> t2.title = 'Hello World Example!' +>>> t2.contents = 'Hello World' +>>> print t2 + [ ... same output as the first example above ... ] +>>> t2.title = 'Example #2' +>>> t2.contents = 'Hello World!' +>>> print t2 + [ ... same as Example #2 above ... ] +\end{verbatim} + +Or this way: + +\begin{verbatim} +>>> class Template3(Template): +>>> title = 'Hello World Example!' +>>> contents = 'Hello World!' +>>> t3 = Template3(templateDef) +>>> print t3 + [ ... you get the picture ... ] +\end{verbatim} + +The template definition can also come from a file instead of a string, +as we will see in section \ref{howWorks.constructing}. + +The above is all fine for short templates, but for long templates or +for an application that depends on many templates in a hierarchy, it's +easier to store the templates in separate *.tmpl files and use the +{\bf cheetah compile} program to convert them into Python classes in +their own modules. This will be covered in section +\ref{howWorks.cheetah-compile}. + +As an appetizer, we'll just briefly mention that you can store constant values +{\em inside} the template definition, and they will be converted to attributes +in the generated class. You can also create methods the same way. +You can even use inheritance to arrange your templates in a hierarchy, +with more specific templates overriding certain parts of more general +templates (e.g., a "page" template overriding a sidebar in a "section" +template). + +For the minimalists out there, here's a template definition, +instantiation and filling all in one Python statement: + +\begin{verbatim} +>>> print Template("Templates are pretty useless without placeholders.") +Templates are pretty useless without placeholders. +\end{verbatim} + +You use a precompiled template the same way, except you don't provide +a template definition since it was already established: + +\begin{verbatim} +from MyPrecompiledTemplate import MyPrecompiledTemplate +t = MyPrecompiledTemplate() +t.name = "Fred Flintstone" +t.city = "Bedrock City" +print t +\end{verbatim} + + +% Local Variables: +% TeX-master: "users_guide" +% End: + diff --git a/docs/users_guide_src/glossary.tex b/docs/users_guide_src/glossary.tex new file mode 100644 index 0000000..4ee2d9b --- /dev/null +++ b/docs/users_guide_src/glossary.tex @@ -0,0 +1,96 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Vocabulary} +\label{glossary} +\label{vocabulary} + +{\bf Template} is an informal term meaning a template definition, a +template instance or a template class. A {\bf template definition} is what +the human {\bf template maintainer} writes: a string consisting of text, +placeholders and directives. {\bf Placeholders} are variables that will be +looked up when the template is filled. {\bf Directives} are commands to be +executed when the template is filled, or instructions to the Cheetah compiler. +The conventional suffix for a file containing a template definition is +{\bf .tmpl}. + +There are two things you can do with a template: compile it or fill it. +{\bf Filling} is the reason you have a template in the first place: +to get a finished string out of it. Compiling is a necessary prerequisite: the +{\bf Cheetah compiler} takes a template definition and produces Python code +to create the finished string. Cheetah provides several ways to compile +and fill templates, either as one step or two. + +Cheetah's compiler produces a subclass of \code{Cheetah.Template} +specific to that template definition; this is called the {\bf generated +class}. A {\bf template instance} is an instance of a generated class. + +If the user calls the \code{Template} constructor directly (rather than a +subclass constructor), s/he will get what appears to be an instance of +\code{Template} but is actually a subclass created on-the-fly. + +The user can make the subclass explicit by using the ``cheetah compile'' +command to write the template class to a Python module. Such a module is +called a {\bf .py template module}. + +The {\bf Template Definition Language} -- or the ``Cheetah language'' for short +-- is the syntax rules governing placeholders and directives. These are +discussed in sections \ref{language} and following in this Guide. + +To fill a template, you call its {\bf main method}. This is normally +\code{.respond()}, but it may be something else, and you can use the +\code{\#implements} directive to choose the method name. (Section +\ref{inheritanceEtc.implements}. + +A {\bf template-servlet} is a .py template module in a Webware servlet +directory. Such templates can be filled directly through the web by requesting +the URL. ``Template-servlet'' can also refer to the instance being filled by +a particular web request. If a Webware servlet that is not a +template-servlet invokes a template, that template is not a template-servlet +either. + +A {\bf placeholder tag} is the substring in the template +definition that is the placeholder, including the start and end delimeters (if +there is an end delimeter). The {\bf placeholder name} is the same but without +the delimeters. + +Placeholders consist of one or more {\bf identifiers} separated by periods +(e.g., \code{a.b}). Each identifier must follow the same rules as Python +identifiers; that is, a letter or underscore followed by one or more letters, +digits or underscores. (This is the regular expression +\verb+[A-Za-z_][A-Za-z0-9_]*+.) + +The first (or only) identifier of a placeholder name represents a {\bf +variable} to be looked up. Cheetah looks up variables in various {\bf +namespaces}: the searchList, local variables, and certain other places. The +searchList is a list of objects ({\bf containers}) with attributes +and/or keys: each container is a namespace. Every template instance has +exactly one searchList. Identifiers after the first are looked up only in +the parent object. The final value after all lookups have been performed is +the {\bf placeholder value}. + +Placeholders may occur in three positions: top-level, expression and LVALUE. +{\bf Top-level} placeholders are those in ordinary text (``top-level text''). +{\bf Expression} placeholders are those in Python expressions. +{\bf LVALUE} placeholders are those naming a variable to receive a value. +(LVALUE is computerese for ``the left side of the equal sign''.) Section +\ref{language.placeholders.positions} explains the differences between these +three positions. + +The routine that does the placeholder lookups is called the {\bf NameMapper}. +Cheetah's NameMapper supports universal dotted notation and autocalling. +{\bf Universal dotted notation} means that keys may be written as if they were +attributes: \code{a.b} instead of \code{a['b']}. {\bf Autocalling} means that +if any identifier's value is found to be a function or method, Cheetah will +call it without arguments if there is no \verb+()+ following. More about the +NameMapper is in section \ref{language.namemapper}. + +Some directives are multi-line, meaning they have a matching {\bf \#end} tag. +The lines of text between the start and end tags is the {\bf body} of the +directive. Arguments on the same line as the start tag, in contrast, are +considered part of the directive tag. More details are in section +\ref{language.directives.syntax} (Directive Syntax Rules). + +% Local Variables: +% TeX-master: "users_guide" +% End: + +% # vim: sw=4 ts=4 expandtab diff --git a/docs/users_guide_src/howItWorks.tex b/docs/users_guide_src/howItWorks.tex new file mode 100755 index 0000000..4efa22f --- /dev/null +++ b/docs/users_guide_src/howItWorks.tex @@ -0,0 +1,420 @@ +\section{How Cheetah Works} +\label{howWorks} + +As mentioned before, you can do two things with templates: compile them and +fill them. (Actually you can query them too, to see their attributes and +method values.) Using templates in a Python program was shown in section +\ref{gettingStarted.tutorial} (Quickstart tutorial). Here we'll focus on +compiling and filling templates from the shell command line, and how to make +.py template modules. The compiling information here is also important for +template-servlets, which will be otherwise covered in chapter \ref{webware} +(Webware). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Constructing Template Objects} +\label{howWorks.templateClass} +\label{howWorks.constructing} + +The heart of Cheetah is the \code{Template} class in the +\code{Cheetah.Template} module. You can use it directly if you have a +template definition in hand, or indirectly through a precompiled template, +which is a subclass. The constructor accepts the following keyword +arguments. (If you're a beginner, learn the first three arguments now; +the others are much less frequent.) + +\begin{description} +\item{{\bf source}} + The template definition as a string. You may omit the \code{source=} + prefix {\em if it's the first argument}, as in all the examples below. + The source can be a string literal in your module, or perhaps a string + you read from a database or other data structure. +\item{{\bf file}} + A filename or file object containing the template definition. + A filename must be a string, and a file object must be open for reading. + By convention, template definition files have the extension + {\bf .tmpl}. +\item{{\bf searchList}} + A list of objects to add to the searchList. The attributes/keys of these + objects will be consulted for \code{\$placeholder} lookup. +\item{{\bf filter}} + A class that will format every \code{\$placeholder} value. You may + specify a class object or string. If a class object, + it must be a subclass of \code{Cheetah.Filters.Filter}. If a string, it + must be the name of one of the filters in filtersLib module (see next + item). + (You may also use the \code{\#filter} directive (section + \ref{output.filter}) to switch filters at runtime.) +\item{{\bf filtersLib}} + A module containing the filters Cheetah should look up by name. The + default is \code{Cheetah.Filters}. All classes in this module that are + subclasses of \code{Cheetah.Filters.Filter} are considered filters. +\item{{\bf errorCatcher}} + A class to handle \code{\$placeholder} errors. You may + specify a class object or string. If a class object, + it must be a subclass of \code{Cheetah.ErrorCatchers.ErrorCatcher}. + If a string, it must be the name of one of the error catchers in + \code{Cheetah.ErrorCatchers}. This is similar to the + \code{\#errorCatcher} directive + (section \ref{errorHandling.errorCatcher}). +\item{{\bf compilerSettings}} + A dictionary (or dictionary hierarchy) of settings that change Cheetah's + behavior. Not yet documented. +\end{description} + +To use \code{Template} directly, you {\em must} specify either \code{source} +or \code{file}, but not both. To use a precompiled template, you +{\em must not} specify either one, because the template definition is already +built into the class. The other arguments, however, may be used in either case. +Here are typical ways to create a template instance: +\begin{description} +\item{\code{t = Template("The king is a \$placeholder1.")}} + \\ Pass the template definition as a string. +\item{\code{t = Template(file="fink.tmpl")}} + \\ Read the template definition from a file named "fink.tmpl". +\item{\code{t = Template(file=f)}} + \\ Read the template definition from file-like object 'f'. +\item{\code{t = Template("The king is a \$placeholder1.", searchList=[dict, obj])}} + \\ Pass the template definition as a string. Also pass two namespaces for + the searchList: a dictionary 'dict' and an instance 'obj'. +\item{\code{t = Template(file="fink.txt", searchList=[dict, obj])}} + \\ Same, but pass a filename instead of a string. +\item{\code{t = Template(file=f, searchList=[dict, obj])}} + \\ Same with a file object. +\end{description} + +If you use \code{Template} directly, the template definition will be compiled +the first time it's filled. Compilation creates a template-specific class +called the {\bf generated class}, which is a subclass of \code{Template}. It +then dynamically switches the instance so it's now an instance of this class. +Don't worry if you don't understand this; it works. + +% By convention, you give a file containing a template definition the extension +% {\bf .tmpl}. + +When you precompile a template using the ``cheetah compile'' command, it +writes the generated class to a file. Actually, what it writes is the source +code for a Python module that contains the generated class. Again, the +generated class is a subclass of \code{Template}. We call the generated +module a {\bf .py template module}. Thus, if you always use +precompiled templates (as many people do), you can view Cheetah as a +convenient front-end for writing certain kinds of Python modules, the way +you might use a graphical dialog builder to make a dialog module. + +Precompiled templates provide a slight performance boost because the +compilation happens only once rather than every time it's instantiated. +Also, once you import the .py template module and allow Python to create a +.pyc or .pyo file, you skip the Python compiler too. The speed advantage +of all this is negligable, but it may make a difference in programs that +use templates many times a second. + +\code{Template} subclasses Webware's \code{Servlet} class when available, +so the generated class can be used as a Webware servlet. This is practical +only with precompiled templates. + +To fill a template, you call its {\bf main method}. This is normally +\code{.respond()}, but under certain circumstances it's \code{.writeBody()} or +a user-defined name. (Section \ref{inheritanceEtc.implements} explains why +the method name is not always the same.) However, \code{.\/\_\_str\_\_()} is +always an alias for the main method, so you can always use +\code{print\ myTemplateInstance} or \code{str(myTempateInstance)} to fill it. +You can also call any \code{\#def} or \code{\#block} method and it will fill +just that portion of the template, although this feature is not often used. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{``cheetah compile'' and .py template modules} +\label{howWorks.cheetah-compile} + +To create a .py template module, do either of these: + +\begin{verbatim} +cheetah compile [options] [FILES ...] +cheetah c [options] [FILES ...] +\end{verbatim} + +The following options are supported: +\begin{verbatim} + --idir DIR, --odir DIR : input/output directories (default: current dir) + --iext EXT, --oext EXT : input/output filename extensions + (default input: tmpl, default output: py) + -R : recurse subdirectories looking for input files + --debug : print lots of diagnostic output to standard error + --flat : no destination subdirectories + --nobackup : don't make backups + --stdout, -p : output to standard output (pipe) +\end{verbatim} + +{\em Note:} If Cheetah can't find your input files, or if it puts output files +in the wrong place, use the \code{--debug} option to see what Cheetah thinks +of your command line. + +The most basic usage is: +\begin{verbatim} +cheetah compile a.tmpl : writes a.py +cheetah compile a.tmpl b.tmpl : writes a.py and b.py +\end{verbatim} + +Cheetah will automatically add the default input extension (.tmpl) if the +file is not found. So the following two examples are the same as above +(provided files ``a'' and ``b'' don't exist): +\begin{verbatim} +cheetah compile a : writes a.py (from a.tmpl) +cheetah compile a b : writes a.py and b.py +\end{verbatim} + +You can override the default input extension and output extension +(\code{py}) using \code{--iext} and \code{--oext}, although there's +little reason to do so. Cheetah assumes the extension has a leading dot +(.) even if you don't specify it. + +Use the \code{-R} option to recurse subdirectories: +\begin{verbatim} +cheetah compile dir1 : error, file is a directory +cheetah compile -R dir1 : look in `dir1' for files to compile +cheetah compile : error, no file specified +cheetah compile -R : look in current directory for files + to compile +cheetah compile -R a b dir1 : compile files and recurse +\end{verbatim} +When recursing, only regular files that end in the input extension (.tmpl) are +considered source files. All other filenames are ignored. + +The options \code{--idir} and \code{--odir} allow you to specify that +the source (and/or destination) paths are relative to a certain directory +rather than to the current directory. This is useful if you keep your +*.tmpl and *.py files in separate directory hierarchies. After editing a +source file, just run one of these (or put the command in a script or +Makefile): +\begin{verbatim} +cheetah compile --odir /var/webware a.tmpl +cheetah compile -R --odir /var/webware +cheetah c --odir /var/webware sub/a.tmpl + : writes /var/webware/sub/a.py +\end{verbatim} + +``cheetah compile'' overwrites any existing \code{.py} file it finds, after +backing it up to FILENAME.py\_bak (unless you specify \code{--nobackup}). For +this reason, you should make changes to the \code{.tmpl} version of the +template rather than to the \code{.py} version. + +For the same reason, if your template requires custom Python methods or +other Python code, don't put it in the \code{FILENAME.py} file. Instead, put +it in a separate base class and use the \code{\#extends} directive to +inherit from it. + +Because FILENAME will be used as a class and module name, it must be a valid +Python identifier. For instance, \code{cheetah compile spam-eggs.tmpl} is +illegal because of the hyphen ("-"). This is sometimes inconvenient when +converting a site of HTML files into Webware servlets. Fortunately, the +{\em directory} it's in does not have to be an identifier. ({\em Hint:} for +date-specific files, try converting 2002/04/12.html to 2002/04/12/index.tmpl. +This also gives you a directory to store images or supplemental files.) + +Occasionally you may want output files put directly into the output directory +(or current directory), rather than into a subdirectory parallel to the input +file. The \code{--flat} option does this. Note that this introduces the +possibility that several input files might map to one output file. Cheetah +checks for output file collisions before writing any files, and aborts if there +are any collisions. +\begin{verbatim} +cheetah c sub/a.py : writes sub/a.py +cheetah c --flat sub/a.py : writes a.py +cheetah c --odir DEST sub/a.tmpl + : writes DEST/sub/a.py +cheetah c --flat --odir DEST sub/a.tmpl + : writes DEST/a.py +cheetah c --idir /home/henry sub/rollins.tmpl + : writes sub/rollins.py +cheetah c --flat --idir /home/henry sub/rollins.tmpl + : writes rollins.py +cheetah c --idir /home/henry --odir /home/henry sub/rollins.tmpl + : writes /home/henry/sub/rollins.py +cheetah c --flat --idir /home/henry --odir /home/henry sub/rollins.tmpl + : writes /home/henry/rollins.py +\end{verbatim} + +Whenever ``cheetah compile'' has to create an output directory or subdirectory, it +also creates an \_\_init\_\_.py file in it. This file is necessary +in order to make Python treat the directory as a Python package. + +One of the advantages of .py template modules is that you don't lose any +flexibility. The generated class contains all \code{\#attr} values and +\code{\#def}/\code{\#block} values as ordinary attributes and methods, so you +can read the values individually from other Python tools for any kind of custom +processing you want. For instance, you can extract the titles of all +your templates into a database, or find all the servlets with a certain +\code{\$author} value. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{``cheetah fill''} +\label{howWorks.cheetah-fill} + +You can compile and fill a large number of template definitions from the +command line in one step using \code{cheetah fill}. This compiles the template +in memory; it does {\em not} save the .py template module to disk. Instead it +writes a finished output file, which has the extension \code{.html} by default. +All the options to \code{cheetah compile} work the same way here, and there are +also a couple additional options: +\begin{verbatim} + --env : put the environment in the searchList + --pickle FILE : unpickle FILE and put that object in the searchList +\end{verbatim} + +Because you can't provide a searchList on the command line, the +templates must either contain or inherit all the variables it needs, +or use the \code{--env} and \code{--pickle} options to +provide additional variables. + +Examples: +\begin{verbatim} +cheetah fill a.tmpl : writes a.html +cheetah fill a.tmpl b.tmpl : writes a.html and b.html +cheetah f --oext txt a : writes a.txt (from a.tmpl) +\end{verbatim} + +Using \code{--env} may have security or reliability implications because the +environment normally contains lots of variables you inherited rather than +defining yourself. If any of these variables override any of yours (say a +\code{\#def}), you will get incorrect output, may reveal private information, +and may get an exception due to the variable being an unexpected type +(environmental variables are always strings). Your calling program may wish +to clear out the environment before setting environmental variables for the +template. + +There are two other differences between ``cheetah compile'' and ``cheetah fill''. +Cheetah doesn't create \_\_init\_\_.py files when creating directories in +fill mode. Also, the source filenames don't have to be identifiers. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Some trivia about .py template modules} +\label{howWorks.pyTrivia} + +We won't look inside .py template modules in this Guide except to note that +they are very different from template definitions. The following template +definition fragment: + +\begin{verbatim} +The number is $Test.unittest.main. +\end{verbatim} + +compiles to this: + +\begin{verbatim} +write("The number is ") +write(filter(VFN(VFS(SL,"Test.unittest",1),"main",0) +write(".") +\end{verbatim} + +The Cheetah Developers' Guide looks at .py template +modules in depth, and shows what the various directives compile to. +But you are welcome to take a peek at some .py template modules yourself +if you're curious about what Cheetah does under the hood. It's all +regular Python code: writing strings and function calls to a file-like +object. + +Looking at a .py template module may also help you see why something +doesn't work, by seeing what Cheetah thought you meant. It also helps +discourage you from modifying the .py file yourself, because who wants to +keep all those function calls and arguments straight? Let the computer +do the drudgery work. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Running a .py template module as a standalone program} +\label{howWorks.standalone} + +In addition to importing your .py template module file into a Python +script or using it as a Webware servlet, you can also run it from the +command line as a standalone program. The program will print the filled +template on standard output. This is useful while debugging the template, +and for producing formatted output in shell scripts. + +When running the template as a program, you cannot provide a searchList or +set \code{self.} attributes in the normal way, so you must take +alternative measures to ensure that every placeholder has a value. +Otherwise, you will get the usual \code{NameMapper.NotFound} exception at +the first missing value. You can either set default values in the template +itself (via the \code{\#attr} or \code{\#def} directives) or in a Python +superclass, or use the \code{--env} or \code{--pickle} command-line options, +which work just like their ``cheetah fill'' counterparts. + +Run \code{python FILENAME.py --help} to see all the command-line +options your .py template module accepts. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Object-Oriented Documents} +\label{howWorks.objoriented} + +Because Cheetah documents are actually class definitions, templates may inherit +from one another in a natural way, using regular Python semantics. For +instance, consider this template, FrogBase.tmpl: + +\begin{verbatim} +#def title +This document has not defined its title +#end def +#def htTitle +$title +#end def +<HTML><HEAD> +<TITLE>$title</TITLE> +</HEAD><BODY> +<H1>$htTitle</H1> +$body +</BODY></HTML> +\end{verbatim} + +And its subclassed document, Frog1.tmpl: +\begin{verbatim} +#from FrogBase import FrogBase +#extends FrogBase +#def title +The Frog Page +#end def +#def htTitle +The <IMG SRC="Frog.png"> page +#end def +#def body +... lots of info about frogs ... +#end def +\end{verbatim} + +This is a classic use of inheritance. The parent ``template'' is simply an +abstract superclass. Each document specializes the output of its parent. + For instance, here the parent defines +\code{\$htTitle} so that by default it's identical to whatever the +\code{\$title} is, but it can also be customized. + +In many other templating systems, you'd have to use case statements or +if-elseif blocks of some sort, repeated in many different sections of code. + +While we show another Cheetah document inheriting from this parent, a Python +class can inherit from it just as easily. This Python class could define its +programmatically-driven value for \code{\$body} and \code{\$title}, simply by +defining body() and title() methods that return a string. (Actually they +can return anything, but we'll get into that later.) + +\begin{verbatim} +from FrogBase import FrogBase +class Frog2(FrogBase): + def title(self): + return "Frog 2 Page" + # We don't override .htTitle, so it defaults to "Frog 2 Page" too. + def body(self): + return " ... more info about frogs ..." +\end{verbatim} + +Similarly, the Cheetah document can inherit from an arbitrary class. That's +how Cheetah makes templates usable as Webware servlets, by subclassing +\code{Servlet}. This technique should be possible for non-Webware systems +too. + +({\em Note:}\ \code{FrogBase.tmpl} could be improved by using the +\code{\#block} directive, section \ref{inheritanceEtc.block}.) + +% Local Variables: +% TeX-master: "users_guide" +% End: + diff --git a/docs/users_guide_src/inheritanceEtc.tex b/docs/users_guide_src/inheritanceEtc.tex new file mode 100755 index 0000000..019b042 --- /dev/null +++ b/docs/users_guide_src/inheritanceEtc.tex @@ -0,0 +1,492 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Import, Inheritance, Declaration and Assignment} +\label{inheritanceEtc} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#import and \#from directives} +\label{inheritanceEtc.import} + +Syntax: +\begin{verbatim} +#import MODULE_OR_OBJECT [as NAME] [, ...] +#from MODULE import MODULE_OR_OBJECT [as NAME] [, ...] +\end{verbatim} + + +The \code{\#import} and \code{\#from} directives are used to make external +Python modules or objects available to placeholders. The syntax is identical +to the import syntax in Python. Imported modules are visible globally to all +methods in the generated Python class. + +\begin{verbatim} +#import math +#import math as mathModule +#from math import sin, cos +#from math import sin as _sin +#import random, re +#from mx import DateTime # ## Part of Egenix's mx package. +\end{verbatim} + +After the above imports, \code{\$math}, \code{\$mathModule}, +\code{\$sin}, \code{\$cos} and \code{\$\_sin}, \code{\$random}, \code{\$re} +and \code{\$DateTime} may be used in \code{\$placeholders} and expressions. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#extends} +\label{inheritanceEtc.extends} + +Syntax: +\begin{verbatim} +#extends CLASS +\end{verbatim} + + +All templates are subclasses of \code{Cheetah.Template.Template}. However, +it's possible for a template to subclass another template or a pure Python +class. This is where \code{\#extends} steps in: it +specifies the parent class. It's equivalent to PSP's \code{``@page extends=''} +directive. + +Cheetah imports the class mentioned in an \code{\#extends} directive +automatically if you haven't imported it yet. The implicit importing works +like this: + +\begin{verbatim} +#extends Superclass +## Implicitly does '#from Superclass import Superclass'. + +#extends Cheetah.Templates.SkeletonPage +## Implicitly does '#from Cheetah.Templates.SkeletonPage import SkeletonPage'. +\end{verbatim} + +If your superclass is in an unusual location or in a module named +differently than the class, you must import it explicitly. There is no +support for extending from a class that is not imported; e.g., from a template +dynamically created from a string. Since the most practical way to +get a parent template into a module is to precompile it, all parent templates +essentially have to be precompiled. + +There can be only one \code{\#extends} directive in a template and it +may list only one class. In other words, templates don't do multiple +inheritance. This is intentional: it's too hard to initialize multiple +base classes correctly from inside a template. However, you can do +multiple inheritance in your pure Python classes. + +If your pure Python class overrides any of the standard \code{Template} +methods such as \code{.\_\_init\_\_} or \code{.awake}, be sure to call +the superclass method in your method or things will break. Examples of calling +the superclass method are in section \ref{tips.callingSuperclassMethods}. +A list of all superclass methods is in section +\ref{tips.allMethods}. + +In all cases, the root superclass must be \code{Template}. If your +bottommost class is a template, simply omit the \code{\#extends} in it and it +will automatically inherit from \code{Template}. {\em If your bottommost class +is a pure Python class, it must inherit from \code{Template} explicitly: } +\begin{verbatim} +from Cheetah.Template import Template +class MyPurePythonClass(Template): +\end{verbatim} + +If you're not keen about having your Python classes inherit from +\code{Template}, create a tiny glue class that inherits both from your +class and from \code{Template}. + +Before giving any examples we'll stress that Cheetah does {\em not} +dictate how you should structure your inheritance tree. As long as +you follow the rules above, many structures are possible. + +Here's an example for a large web site that has not only a general site +template, but also a template for this section of the site, and then a +specific template-servlet for each URL. (This is the ``inheritance +approach'' discussed in the Webware chapter.) Each template inherits from a +pure Python class that contains methods/attributes used by the template. We'll +begin with the bottommost superclass and end with the specific +template-servlet: + +\begin{verbatim} +1. SiteLogic.py (pure Python class containing methods for the site) + from Cheetah.Template import Template + class SiteLogic(Template): + +2. Site.tmpl/py (template containing the general site framework; + this is the template that controls the output, + the one that contains "<HTML><HEAD>...", the one + that contains text outside any #def/#block.) + #from SiteLogic import SiteLogic + #extends SiteLogic + #implements respond + +3. SectionLogic.py (pure Python class with helper code for the section) + from Site import Site + class SectionLogic(Site) + +4. Section.tmpl/py (template with '#def' overrides etc. for the section) + #from SectionLogic import SectionLogic + #extends SectionLogic + +5. page1Logic.py (pure Python class with helper code for the template-servlet) + from Section import Section + class indexLogic(Section): + +6. page1.tmpl/py (template-servlet for a certain page on the site) + #from page1Logic import page1Logic + #extends page1Logic +\end{verbatim} + +A pure Python classes might also contain methods/attributes that aren't used by +their immediate child template, but are available for any descendant +template to use if it wishes. For instance, the site template might have +attributes for the name and e-mail address of the site administrator, +ready to use as \$placeholders in any template that wants it. + +{\em Whenever you use \code{\#extends}, you often need \code{\#implements} +too,} as in step 2 above. Read the next section to understand what +\code{\#implements} is and when to use it. + +% @@MO: Edmund suggests making some diagrams of inheritance chains. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#implements} +\label{inheritanceEtc.implements} + +Syntax: +\begin{verbatim} +#implements METHOD +\end{verbatim} + +You can call any \code{\#def} or \code{\#block} method directly and get its +outpt. The top-level content -- all the text/placeholders/directives outside any +\code{\#def}/\code{\#block} -- gets concatenated and wrapped in a ``main +method'', by default \code{.respond()}. So if you call \code{.respond()}, you +get the ``whole template output''. When Webware calls \code{.respond()}, +that's what it's doing. And when you do 'print t' or 'str(t)' on a template +instance, you're taking advantage of the fact that Cheetah makes +\code{.\_\_str\_\_()} an alias for the main method. + +That's all fine and dandy, but what if your application prefers to call another +method name rather than \code{.respond()}? What if it wants to call, say, +\code{.send\_output()} instead? That's where \code{\#implements} steps in. It +lets you choose the name for the main method. Just put this in your template +definition: +\begin{verbatim} +#implements send_output +\end{verbatim} + +When one template extends another, every template in the inheritance chain +has its own main method. To fill the template, you invoke exactly one of +these methods and the others are ignored. The method you call may be in any of +the templates in the inheritance chain: the base template, the leaf template, +or any in between, depending on how you structure your application. So you +have two problems: (1) calling the right method name, and (2) preventing an +undesired same-name subclass method from overriding the one you want to call. + +Cheetah assumes the method you will call is \code{.respond()} because +that's what Webware calls. It further assumes the desired main method is the +one in the lowest-level base template, because that works well with +\code{\#block} as described in the Inheritance Approach for building Webware +servlets (section \ref{webware.inheritance}), which was originally the +principal use for Cheetah. So when you use \code{\#extends}, Cheetah changes +that template's main method to \code{.writeBody()} to get it out of the way and +prevent it from overriding the base template's \code{.respond()}. + +Unfortunately this assumption breaks down if the template is used in other +ways. For instance, you may want to use the main method in the highest-level +leaf template, and treat the base template(s) as merely a library of +methods/attributes. In that case, the leaf template needs \code{\#implements +respond} to change its main method name back to \code{.respond()} (or whatever +your application desires to call). Likewise, if your main method is in one of the +intermediate templates in an inheritance chain, that template needs +\code{\#implements respond}. + +The other way the assumption breaks down is if the main method {\em is} in +the base template but that template extends a pure Python class. Cheetah sees +the \code{\#extends} and dutifully but incorrectly renames the method to +\code{.writeBody()}, so you have to use \code{\#implements respond} to change +it back. Otherwise the dummy \code{.respond()} in \code{Cheetah.Template} +is found, which outputs... nothing. {\bf So if you're using \code{\#extends} +and get no output, the {\em first} thing you should think is, ``Do I need to +add \code{\#implements respond} somewhere?'' } + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#set} +\label{inheritanceEtc.set} + +Syntax: +\begin{verbatim} +#set [global] $var = EXPR +\end{verbatim} + +\code{\#set} is used to create and update local variables at run time. +The expression may be any Python expression. +Remember to preface variable names with \$ unless they're part of an +intermediate result in a list comprehension. + +Here are some examples: +\begin{verbatim} +#set $size = $length * 1096 +#set $buffer = $size + 1096 +#set $area = $length * $width +#set $namesList = ['Moe','Larry','Curly'] +#set $prettyCountry = $country.replace(' ', ' ') +\end{verbatim} + +\code{\#set} variables are useful to assign a short name to a +\code{\$deeply.nested.value}, to a calculation, or to a printable version of +a value. The last example above converts any spaces in the 'country' value +into HTML non-breakable-space entities, to ensure the entire value appears on +one line in the browser. + +\code{\#set} variables are also useful in \code{\#if} expressions, but +remember that complex logical routines should be coded in Python, not in +Cheetah! +\begin{verbatim} +#if $size > 1500 + #set $adj = 'large' +#else + #set $adj = 'small' +#end if +\end{verbatim} +Or Python's one-line equivalent, "A and B or C". Remember that in this case, +B must be a true value (not None, '', 0, [] or {}). +\begin{verbatim} +#set $adj = $size > 1500 and 'large' or 'small' +\end{verbatim} +(Note: Cheetah's one-line \code{\#if} will not work for this, since it +produces output rather than setting a variable. + +You can also use the augmented assignment operators: +\begin{verbatim} +## Increment $a by 5. +#set $a += 5 +\end{verbatim} + +By default, \code{\#set} variables are not visible in method calls or include +files unless you use the \code{global} attribute: \code{\#set global \$var = +EXPRESSION}. Global variables are visible in all methods, nested templates and +included files. Use this feature with care to prevent surprises. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#del} +\label{inheritanceEtc.del} + +Syntax: +\begin{verbatim} +#del $var +\end{verbatim} + +\code{\#del} is the opposite of \code{\#set}. It deletes a {\em local} +variable. Its usage is just like Python's \code{del} statement: +\begin{verbatim} +#del $myVar +#del $myVar, $myArray[5] +\end{verbatim} + +Only local variables can be deleted. There is no directive to delete a +\code{\#set global} variable, a searchList variable, or any other type of +variable. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#attr} +\label{inheritanceEtc.attr} + +Syntax: +\begin{verbatim} +#attr $var = EXPR +\end{verbatim} + +The \code{\#attr} directive creates class attributes in the generated Python +class. It should be used to assign simple Python literals such as numbers or +strings. In particular, the expression must {\em not} depend on searchList +values or \code{\#set} variables since those are not known at compile time. + +\begin{verbatim} +#attr $title = "Rob Roy" +#attr $author = "Sir Walter Scott" +#attr $version = 123.4 +\end{verbatim} + +This template or any child template can output the value thus: +\begin{verbatim} +$title, by $author, version $version +\end{verbatim} + +If you have a library of templates derived from etexts +(\url{http://www.gutenberg.org/}), you can extract the titles and authors +and put them in a database (assuming the templates have been compiled into +.py template modules): + +%\begin{verbatim} +%import glob +% +%\end{verbatim} +% +% @@MO: Finish this example. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#def} +\label{inheritanceEtc.def} + +Syntax: +\begin{verbatim} +#def METHOD[(ARGUMENTS)] +#end def +\end{verbatim} + +Or the one-line variation: +\begin{verbatim} +#def METHOD[(ARGUMENTS)] : TEXT_AND_PLACEHOLDERS +\end{verbatim} + + +The \code{\#def} directive is used to define new methods in the generated +Python class, or to override superclass methods. It is analogous to Python's +\code{def} statement. The directive is silent, meaning it does not itself +produce any output. However, the content of the method will be inserted into +the output (and the directives executed) whenever the method is later called by +a \$placeholder. + +\begin{verbatim} +#def myMeth() +This is the text in my method +$a $b $c(123) ## these placeholder names have been defined elsewhere +#end def + +## and now use it... +$myMeth() +\end{verbatim} + +The arglist and parentheses can be omitted: +\begin{verbatim} +#def myMeth +This is the text in my method +$a $b $c(123) +#end def + +## and now use it... +$myMeth +\end{verbatim} + +Methods can have arguments and have defaults for those arguments, just like +in Python. Remember the \code{\$} before variable names: +\begin{verbatim} +#def myMeth($a, $b=1234) +This is the text in my method +$a - $b +#end def + +## and now use it... +$myMeth(1) +\end{verbatim} + +The output from this last example will be: + +\begin{verbatim} +This is the text in my method +1 - 1234 +\end{verbatim} + +There is also a single line version of the \code{\#def} directive. +{\bf Unlike the multi-line directives, it uses a colon (:) to delimit the method +signature and body}: +\begin{verbatim} +#attr $adj = 'trivial' +#def myMeth: This is the $adj method +$myMeth +\end{verbatim} +Leading and trailing whitespace is stripped from the method. This is in +contrast to: +\begin{verbatim} +#def myMeth2 +This is the $adj method +#end def +\end{verbatim} +where the method includes a newline after "method". If you don't want the +newline, add \code{\#slurp}: +\begin{verbatim} +#def myMeth3 +This is the $adj method#slurp +#end def +\end{verbatim} + +Because \code{\#def} is handled at compile time, it can appear above or +below the placeholders that call it. And if a superclass placeholder +calls a method that's overridden in a subclass, it's the subclass method +that will be called. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#block ... \#end block} +\label{inheritanceEtc.block} + + +The \code{\#block} directive allows you to mark a section of your template that +can be selectively reimplemented in a subclass. It is very useful for +changing part of a template without having to copy-paste-and-edit +the entire thing. The output from a template definition that uses blocks will +be identical to the output from the same template with the \code{\#block \ldots +\#end block} tags removed. + +({\em Note:} don't be confused by the generic word `block'' in this Guide, +which means a section of code inside {\em any} \code{\#TAG \ldots \#end TAG} +pair. Thus, an if-block, for-block, def-block, block-block etc. In this +section we are talking only of block-blocks.) + +To reimplement the block, use the \code{\#def} directive. The magical effect +is that it appears to go back and change the output text {\em at the point the +original block was defined} rather than at the location of the +reimplementation. + +\begin{verbatim} +#block testBlock +Text in the contents +area of the block directive +#if $testIt +$getFoo() +#end if +#end block testBlock +\end{verbatim} + +You can repeat the block name in the \code{\#end block} directive or not, as +you wish. + +\code{\#block} directives can be nested to any depth. + +\begin{verbatim} +#block outerBlock +Outer block contents + +#block innerBlock1 +inner block1 contents +#end block innerBlock1 + +#block innerBlock2 +inner block2 contents +#end block innerBlock2 + +#end block outerBlock +\end{verbatim} + +Note that the name of the block is optional for the \code{\#end block} tag. + +Technically, \code{\#block} directive is equivalent to a \code{\#def} directive +followed immediately by a \code{\#placeholder} for the same name. In fact, +that's what Cheetah does. Which means you can use \code{\$theBlockName} +elsewhere in the template to output the block content again. + +There is a one-line \code{\#block} syntax analagous to the one-line +\code{\#def}. + +The block must not require arguments because the implicit placeholder that's +generated will call the block without arguments. + + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/introduction.tex b/docs/users_guide_src/introduction.tex new file mode 100755 index 0000000..be34fc6 --- /dev/null +++ b/docs/users_guide_src/introduction.tex @@ -0,0 +1,392 @@ +\section{Introduction} +\label{intro} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Who should read this Guide?} +\label{intro.whoShouldRead} + +This Users' Guide provides a technical overview and reference for the +Cheetah template system. Knowledge of Python and object-oriented programming +is assumed. The emphasis in this Guide is on features useful in a wide variety +of situations. Information on less common situations and troubleshooting tips +are gradually being moved to the Cheetah FAQ. There is also a Cheetah +Developer's Guide for those who want to know what goes on under the hood. + +%% A gentler introduction for template maintainers who don't know +%% Python will be written later. + +This Guide also contains examples of integrating Cheetah with Webware for +Python. You will have to learn Webware from its own documentation in order to +build a Webware + Cheetah site. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{What is Cheetah?} +\label{intro.whatIs} + +Cheetah is a Python-powered template engine and code generator. It may be used +as a standalone utility or combined with other tools. Cheetah has +many potential uses, but web developers looking for a viable alternative to ASP, +JSP, PHP and PSP are expected to be its principle user group. + +Cheetah: +\begin{itemize} +\item generates HTML, SGML, XML, SQL, Postscript, form email, LaTeX, or any + other text-based format. It has also been used to produce Python, Java + and PHP source code. + +\item cleanly separates content, graphic design, and program code. This leads + to highly modular, flexible, and reusable site architectures; faster + development time; and HTML and program code that is easier to understand + and maintain. It is particularly well suited for team efforts. + +\item blends the power and flexibility of Python with a simple template language + that non-programmers can understand. + +\item gives template writers full access in their templates to any Python data + structure, module, function, object, or method. + +\item makes code reuse easy by providing an object-oriented interface to + templates that is accessible from Python code or other Cheetah templates. + One template can subclass another and selectively reimplement sections of + it. A compiled template {\em is} a Python class, so it can subclass a + pure Python class and vice-versa. + +\item provides a simple yet powerful caching mechanism + +%% that can dramatically improve the performance of a dynamic website. +\end{itemize} + +Cheetah integrates tightly with {\bf Webware for Python} +(\url{http://webware.sourceforge.net/}): a Python-powered application server and +persistent servlet framework. Webware provides automatic session, cookie, and +user management and can be used with almost any operating-system, web server, or +database. Through Python, it works with XML, SOAP, XML-RPC, CORBA, COM, DCOM, +LDAP, IMAP, POP3, FTP, SSL, etc.. Python supports structured exception handling, +threading, object serialization, unicode, string internationalization, advanced +cryptography and more. It can also be extended with code and libraries written +in C, C++, Java and other languages. + +Like Python, Cheetah and Webware are Open Source software and are supported by +active user communities. Together, they are a powerful and elegant framework +for building dynamic web sites. + +Like its namesake, Cheetah is fast, flexible and powerful. + +% @@MO: Repeat picture of cheetah. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{What is the philosophy behind Cheetah?} +\label{intro.philosophy} + +Cheetah's design was guided by these principles: +\begin{itemize} +\item Python for the back end, Cheetah for the front end. Cheetah was + designed to complement Python, not replace it. + +\item Cheetah's core syntax should be easy for non-programmers to learn. + +\item Cheetah should make code reuse easy by providing an object-oriented + interface to templates that is accessible from Python code or other + Cheetah templates. + +\item Python objects, functions, and other data structures should be fully + accessible in Cheetah. + +\item Cheetah should provide flow control and error handling. Logic + that belongs in the front end shouldn't be relegated to the + back end simply because it's complex. + +\item It should be easy to {\bf separate} content, graphic design, and program + code, but also easy to {\bf integrate} them. + + A clean separation makes it easier for a team of content writers, + HTML/graphic designers, and programmers to work together without stepping + on each other's toes and polluting each other's work. The HTML framework + and the content it contains are two separate things, and analytical + calculations (program code) is a third thing. Each team member should be + able to concentrate on their specialty and to implement their changes + without having to go through one of the others (i.e., the dreaded + ``webmaster bottleneck''). + + While it should be easy to develop content, graphics and program + code separately, it should be easy to integrate them together into a + website. In particular, it should be easy: + + \begin{itemize} + \item for {\bf programmers} to create reusable components and functions + that are accessible and understandable to designers. + \item for {\bf designers} to mark out placeholders for content and + dynamic components in their templates. + \item for {\bf designers} to soft-code aspects of their design that are + either repeated in several places or are subject to change. + \item for {\bf designers} to reuse and extend existing templates and thus + minimize duplication of effort and code. + \item and, of course, for {\bf content writers} to use the templates that + designers have created. + \end{itemize} + +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Why Cheetah doesn't use HTML-style tags} +\label{intro.htmlStyleTags} + +Cheetah does not use HTML/XML-style tags like some other template languages for +the following reasons: + Cheetah is not limited to HTML, + HTML-style tags are hard to distinguish from real HTML tags, + HTML-style tags are not visible in rendered HTML when something goes wrong, + HTML-style tags often lead to invalid HTML (e.g., +\code{<img src="<template-directive>">}), +Cheetah tags are less verbose and easier to understand than HTML-style tags, +and HTML-style tags aren't compatible with most WYSIWYG editors + +Besides being much more compact, Cheetah also has some advantages over +languages that put information inside the HTML tags, such as Zope Page +Templates or PHP: + HTML or XML-bound languages do not work well with other languages, + While ZPT-like syntaxes work well in many ways with WYSIWYG HTML editors, + they also give up a significant advantage of those editors -- concrete + editing of the document. When logic is hidden away in (largely + inaccessible) tags it is hard to understand a page simply by viewing it, + and it is hard to confirm or modify that logic. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Give me an example!} +\label{intro.example} + +Here's a very simple example that illustrates some of Cheetah's basic syntax: + +\begin{verbatim} + +<HTML> +<HEAD><TITLE>$title</TITLE></HEAD> +<BODY> + +<TABLE> +#for $client in $clients +<TR> +<TD>$client.surname, $client.firstname</TD> +<TD><A HREF="mailto:$client.email">$client.email</A></TD> +</TR> +#end for +</TABLE> + +</BODY> +</HTML> +\end{verbatim} + +Compare this with PSP: + +\begin{verbatim} +<HTML> +<HEAD><TITLE><%=title%></TITLE></HEAD> +<BODY> + +<TABLE> +<% for client in clients: %> +<TR> +<TD><%=client['surname']%>, <%=client['firstname']%></TD> +<TD><A HREF="mailto:<%=client['email']%>"><%=client['email']%></A></TD> +</TR> +<%end%> +</TABLE> + +</BODY> +</HTML> +\end{verbatim} + +Section \ref{gettingStarted.tutorial} has a more typical example that shows +how to get the plug-in values {\em into} Cheetah, and section +\ref{howWorks.cheetah-compile} explains how to turn your template definition +into an object-oriented Python module. + +%% @@TR: I'm going to extend this and briefly introduce: +%% - Template objects vs. .tmpl files. +%% - how to get data into it +%% @@MO: If you do this, reconcile this example and the one in gettingStarted. +%% Keep two examples or collapse into one? + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Give me an example of a Webware servlet!} +\label{intro.example.servlet} + +This example uses an HTML form to ask the user's name, then invokes itself +again to display a {\em personalized} friendly greeting. + +\begin{verbatim} +<HTML><HEAD><TITLE>My Template-Servlet</TITLE></HEAD><BODY> +#set $name = $request.field('name', None) +#if $name +Hello $name +#else +<FORM ACTION="" METHOD="GET"> +Name: <INPUT TYPE="text" NAME="name"><BR> +<INPUT TYPE="submit"> +</FORM> +#end if +</BODY></HTML> +\end{verbatim} + +To try it out for yourself on a Webware system: +\begin{enumerate} +\item copy the template definition to a file {\bf test.tmpl} in your + Webware servlet directory. +\item Run ``\code{cheetah compile test.tmpl}''. This produces + {\bf test.py} (a .py template module) in the same directory. +\item In your web browser, go to {\bf test.py}, using whatever site and + directory is appropriate. Depending on your Webware configuration, you may + also be able to go to {\bf test}. +\end{enumerate} + +At the first request, field `name' will be blank (false) so the ``\#else'' +portion will execute and present a form. You type your name and press submit. +The form invokes the same page. Now `name' is true so the ``\#if'' portion +executes, which displays the greeting. The ``\#set'' directive creates a +local variable that lasts while the template is being filled. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{How mature is Cheetah?} +\label{intro.mature} + +Cheetah is stable, production quality, post-beta code. Cheetah's syntax, +semantics and performance have been generally stable since a performance +overhaul in mid 2001. Most of the changes since October 2001 have +been in response to specific requests by production sites, things they need that +we hadn't considered. + +As of summer 2003, we are putting in the final touches before the 1.0 release. + +The {\bf TODO} and {\bf BUGS} files in the Cheetah distribution show what we're +working on now or planning to work on. There's also a {\bf ToDo} page on the +wiki (see below), which is updated less often. The {\bf WishList} page on the +wiki shows requested features we're considering but haven't commited to. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Where can I get news?} +\label{intro.news} + +Cheetah releases and other stuff can be obtained from the the Cheetah +{\bf Web site}: +\url{http://CheetahTemplate.sourceforge.net} + +Cheetah discussions take place on the {\bf mailing list} +\email{cheetahtemplate-discuss@lists.sourceforge.net}. This is where to hear +the latest news first. + +The Cheetah {\bf wiki} is becoming an increasingly popular place to list +examples of Cheetah in use, provide cookbook tips for solving various problems, +and brainstorm ideas for future versions of Cheetah. +\url{http://www.cheetahtemplate.org/wiki} +(The wiki is actually hosted at +\url{http://cheetah.colorstudy.net/twiki/bin/view/Cheetah/WebHome}, but the +other URL is easier to remember.) +For those unfamiliar with a wiki, it's a type of Web site that readers can edit +themselves to make additions or corrections to. Try it. Examples and tips +from the wiki will also be considered for inclusion in future versions of this +Users' Guide. + +If you encounter difficulties, or are unsure about how to do something, +please post a detailed message to the list. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{How can I contribute?} +\label{intro.contribute} + +Cheetah is the work of many volunteers. If you use Cheetah please share your +experiences, tricks, customizations, and frustrations. + +\subsubsection{Bug reports and patches} + +If you think there is a bug in Cheetah, send a message to the e-mail list +with the following information: + +\begin{enumerate} +\item a description of what you were trying to do and what happened +\item all tracebacks and error output +\item your version of Cheetah +\item your version of Python +\item your operating system +\item whether you have changed anything in the Cheetah installation +\end{enumerate} + +\subsubsection{Example sites and tutorials} +If you're developing a website with Cheetah, please put a link on the wiki on +the {\bf WhoIsUsingCheetah} page, and mention it on the list. Also, if you +discover new and interesting ways to use Cheetah, please put a quick tutorial +(HOWTO) about your technique on the {\bf CheetahRecipies} page on the wiki. + +\subsubsection{Template libraries and function libraries} +We hope to build up a framework of Template libraries (see section +\ref{libraries.templates}) to distribute with Cheetah and would appreciate any +contributions. + +\subsubsection{Test cases} +Cheetah is packaged with a regression testing suite that is run with each +new release to ensure that everything is working as expected and that recent +changes haven't broken anything. The test cases are in the Cheetah.Tests +module. If you find a reproduceable bug please consider writing a test case +that will pass only when the bug is fixed. Send any new test cases to the email +list with the subject-line ``new test case for Cheetah.'' + +\subsubsection{Publicity} +Help spread the word ... recommend it to others, write articles about it, etc. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Acknowledgements} +\label{intro.acknowledgments} + +Cheetah is one of several templating frameworks that grew out of a `templates' +thread on the Webware For Python email list. Tavis Rudd, Mike Orr, Chuck +Esterbrook and Ian Bicking are the core developers. + +We'd like to thank the following people for contributing valuable advice, code +and encouragement: Geoff Talvola, Jeff Johnson, Graham Dumpleton, Clark C. +Evans, Craig Kattner, Franz Geiger, Geir Magnusson, Tom Schwaller, Rober Kuzelj, +Jay Love, Terrel Shumway, Sasa Zivkov, Arkaitz Bitorika, Jeremiah Bellomy, +Baruch Even, Paul Boddie, Stephan Diehl, Chui Tey, Michael Halle, Edmund Lian +and Aaron Held. + +The Velocity, WebMacro and Smarty projects provided inspiration and design +ideas. Cheetah has benefitted from the creativity and energy of their +developers. Thank you. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{License} +\label{intro.license} + +\paragraph*{The gist} +Cheetah is open source, but products developed with Cheetah or derived +from Cheetah may be open source or closed source. + +{\bf Cheetah.Utils.optik} is based on a third-party package Optik by Gregory +P Ward. Optik's license is in appendix \ref{optikLicense}. + + +\paragraph*{Legal terms} +Copyright \copyright 2001, The Cheetah Development Team: Tavis Rudd, Mike Orr, +Ian Bicking, Chuck Esterbrook. + +Permission to use, copy, modify, and distribute this software for any purpose +and without fee is hereby granted, provided that the above copyright notice +appear in all copies and that both that copyright notice and this permission +notice appear in supporting documentation, and that the names of the authors not +be used in advertising or publicity pertaining to distribution of the software +without specific, written prior permission. + +THE AUTHORS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS +BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF +CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +These terms do not apply to the {\bf Cheetah.Utils.optik} package. Optik's +license is in appendix \ref{optikLicense}. + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/language.tex b/docs/users_guide_src/language.tex new file mode 100755 index 0000000..673abca --- /dev/null +++ b/docs/users_guide_src/language.tex @@ -0,0 +1,651 @@ +\section{Language Overview} +\label{language} + +Cheetah's basic syntax was inspired by the Java-based template engines Velocity +and WebMacro. It has two types of tags: {\bf \$placeholders} and {\bf +\#directives}. Both types are case-sensitive. + +Placeholder tags begin with a dollar sign (\code{\$varName}) and are similar to +data fields in a form letter or to the \code{\%(key)s} fields on the left side +of Python's \code{\%} operator. When the template is filled, the placeholders +are replaced with the values they refer to. + +Directive tags begin with a hash character (\#) and are used for comments, +loops, conditional blocks, includes, and all other advanced features. +({\em Note:} you can customize the start and end delimeters for placeholder +and directive tags, but in this Guide we'll assume you're using the default.) + +Placeholders and directives can be escaped by putting a backslash before them. +\verb+\$var+ and \verb+\#if+ will be output as literal text. + +A placeholder or directive can span multiple physical lines, following the same +rules as Python source code: put a backslash (\verb+\+) at the end of all +lines except the last line. However, if there's an unclosed parenthesis, +bracket or brace pending, you don't need the backslash. + +\begin{verbatim} +#if $this_is_a_very_long_line and $has_lots_of_conditions \ + and $more_conditions: +<H1>bla</H1> +#end if + +#if $country in ('Argentina', 'Uruguay', 'Peru', 'Colombia', + 'Costa Rica', 'Venezuela', 'Mexico') +<H1>Hola, senorita!</H1> +#else +<H1>Hey, baby!</H1> +#end if +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Language Constructs -- Summary} +\label{language.constructs} + +\begin{enumerate} +\item Comments and documentation strings + \begin{enumerate} + \item \code{\#\# single line} + \item \code{\#* multi line *\#} + \end{enumerate} + +\item Generation, caching and filtering of output + \begin{enumerate} + \item plain text + \item look up a value: \code{\$placeholder} + \item evaluate an expression: \code{\#echo} \ldots + \item same but discard the output: \code{\#silent} \ldots + \item one-line if: \code{\#if EXPR then EXPR else EXPR} + \item gobble the EOL: \code{\#slurp} + \item parsed file includes: \code{\#include} \ldots + \item raw file includes: \code{\#include raw} \ldots + \item verbatim output of Cheetah code: \code{\#raw} \ldots \code{\#end raw} + \item cached placeholders: \code{\$*var}, \code{\$*<interval>*var} + \item cached regions: \code{\#cache} \ldots \code{\#end cache} + \item set the output filter: \code{\#filter} \ldots + \item control output indentation: \code{\#indent} \ldots ({\em not +implemented yet}) + \end{enumerate} + +\item Importing Python modules and objects: \code{\#import} \ldots, + \code{\#from} \ldots + +\item Inheritance + \begin{enumerate} + \item set the base class to inherit from: \code{\#extends} + \item set the name of the main method to implement: \code{\#implements} +\ldots + \end{enumerate} + +\item Compile-time declaration + \begin{enumerate} + \item define class attributes: \code{\#attr} \ldots + \item define class methods: \code{\#def} \ldots \code{\#end def} + \item \code{\#block} \ldots \code{\#end block} provides a simplified + interface to \code{\#def} \ldots \code{\#end def} + \end{enumerate} + +\item Run-time assignment + \begin{enumerate} + \item local vars: \code{\#set} \ldots + \item global vars: \code{\#set global} \ldots + \item deleting local vars: \code{\#del} \ldots + \end{enumerate} + +\item Flow control + \begin{enumerate} + \item \code{\#if} \ldots \code{\#else} \ldots \code{\#else if} (aka + \code{\#elif}) \ldots \code{\#end if} + \item \code{\#unless} \ldots \code{\#end unless} + \item \code{\#for} \ldots \code{\#end for} + \item \code{\#repeat} \ldots \code{\#end repeat} + \item \code{\#while} \ldots \code{\#end while} + \item \code{\#break} + \item \code{\#continue} + \item \code{\#pass} + \item \code{\#stop} + \end{enumerate} + +\item error/exception handling + \begin{enumerate} + \item \code{\#assert} + \item \code{\#raise} + \item \code{\#try} \ldots \code{\#except} \ldots \code{\#else} \ldots + \code{\#end try} + \item \code{\#try} \ldots \code{\#finally} \ldots \code{\#end try} + \item \code{\#errorCatcher} \ldots set a handler for exceptions raised by +\$placeholder calls. + \end{enumerate} + +\item Instructions to the parser/compiler + \begin{enumerate} + \item \code{\#breakpoint} + \item \code{\#compiler-settings} \ldots \code{\#end compiler-settings} + \end{enumerate} + +\item Escape to pure Python code + \begin{enumerate} + \item evalute expression and print the output: \code{<\%=} \ldots + \code{\%>} + \item execute code and discard output: \code{<\%} \ldots \code{\%>} + \end{enumerate} + +\item Fine control over Cheetah-generated Python modules + \begin{enumerate} + \item set the source code encoding of compiled template modules: \code{\#encoding} + \item set the sh-bang line of compiled template modules: \code{\#shBang} + \end{enumerate} + +\end{enumerate} + +The use of all these constructs will be covered in the next several chapters. + +%% @@MO: TODO: reconcile the order of this summary with the order in the +%% detail sections. + +% @@MO: PSP chapter with examples. What does write() do? Print? + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Placeholder Syntax Rules} +\label{language.placeholders.syntax} + +\begin{itemize} + +\item Placeholders follow the same syntax rules as Python variables except + that they are preceded by \code{\$} (the short form) or enclosed in + \code{\$\{\}} (the long form). + Examples: +\begin{verbatim} +$var +${var} +$var2.abc['def']('gh', $subplaceholder, 2) +${var2.abc['def']('gh', $subplaceholder, 2)} +\end{verbatim} + We recommend \code{\$} in simple cases, and \code{\$\{\}} when followed + directly by a letter or when Cheetah or a human template maintainer might + get confused about where the placeholder ends. You may alternately use + \verb+$()+ or \verb+$[]+, although this may confuse the (human) template + maintainer: +\begin{verbatim} +$(var) +$[var] +$(var2.abc['def']('gh', $subplaceholder, 2)) +$[var2.abc['def']('gh', $subplaceholder, 2)] +\end{verbatim} + {\em Note:} Advanced users can change the delimiters to anything they + want via the \code{\#compiler} directive. + + {\em Note 2:} The long form can be used only with top-level placeholders, + not in expressions. See section \ref{language.placeholders.positions} + for an elaboration on this. + +\item To reiterate Python's rules, placeholders consist of one or more + identifiers separated by periods. Each identifier must start with a letter + or an underscore, and the subsequent characters must be letters, digits or + underscores. Any identifier may be followed by arguments enclosed in + \verb+()+ and/or keys/subscripts in \verb+[]+. + +\item Identifiers are case sensitive. \code{\$var} does not equal \code{\$Var} + or \code{\$vAr} or \code{\$VAR}. + +\item Arguments inside \verb+()+ or \verb+[]+ are just like in Python. + Strings may be quoted using any Python quoting style. Each argument is an + expression and may use any of Python's expression operators. Variables + used in argument expressions are placeholders and should be prefixed with + \code{\$}. This also applies to the *arg and **kw forms. However, you do + {\em not} need the \code{\$} with the special Python constants \code{None}, + \code{True} and \code{False}. + Examples: +\begin{verbatim} +$hex($myVar) +$func($arg=1234) +$func2($*args, $**kw) +$func3(3.14159, $arg2, None, True) +$myList[$mySubscript] +\end{verbatim} + +\item Trailing periods are ignored. Cheetah will recognize that the placeholder + name in \code{\$varName.} is \code{varName}, and the period will be left + alone in the template output. + +\item The syntax \code{\$\{placeholderName, arg1="val1"\}} passes arguments to + the output filter (see \code{\#filter}, section \ref{output.filter}. + The braces and comma are required in this case. It's conventional to + omit the \code{\$} before the keyword arguments (i.e. \code{arg1}) in this + case. + +\item Cheetah ignores all dollar signs (\code{\$}) that are not followed by a + letter or an underscore. + +\end{itemize} + +The following are valid \$placeholders: +\begin{verbatim} +$a $_ $var $_var $var1 $_1var $var2_ $dict.key $list[3] +$object.method $object.method() $object.method +$nest($nest($var)) +\end{verbatim} + +These are not \$placeholders but are treated as literal text: +\begin{verbatim} +$@var $^var $15.50 $$ +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Where can you use placeholders?} +\label{language.placeholders.positions} + +There are three places you can use placeholders: top-level position, +expression position and LVALUE position. Each has slightly different +syntax rules. + +Top-level position means interspersed in text. This is the only place +you can use the placeholder long form: \code{\$\{var\}}. + +{\em Expression position} means inside a Cheetah expression, which is the same +as a Python expression. The placeholder names a searchList or other variable +to be read. Expression position occurs inside () and $[]$ arguments within +placeholder tags (i.e., a placeholder inside a placeholder), and in several +directive tags. + +{\em LVALUE position} means naming a variable that will be written to. LVALUE +is a computer science term meaning ``the left side of an assignment +statement''. The first argument of directives \code{\#set}, \code{\#for}, +\code{\#def}, \code{\#block} and \code{\#attr} is an LVALUE. + +This stupid example shows the three positions. Top-level position is shown +in \code{courier}, expression position is {\em italic}, and LVALUE position is +{\bf bold}. + +\begin{quote} +\#for {\bf \$count} in {\em \$range}({\em \$ninetyNine}, 0, -1)\\ +\#set {\bf \$after} = {\em \$count} - 1\\ +\code{\$count} bottles of beer on the wall. \code{\$count} bottles of beer!\\ +~~~~Take one down, pass it around. \code{\$after} bottles of beer on the wall.\\ +\#end for\\ +\code{\$hex}({\em \$myVar}, {\bf \$default}={\em None}) +\end{quote} + +The output of course is: +\begin{verbatim} +99 bottles of beer on the wall. 99 bottles of beer! + Take one down, pass it around. 98 bottles of beer on the wall. +98 bottles of beer on the wall. 98 bottles of beer! + Take one down, pass it around. 97 bottles of beer on the wall. +... +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Are all those dollar signs really necessary?} +\label{language.placeholders.dollar-signs} + +\code{\$} is a ``smart variable prefix''. When Cheetah sees \code{\$}, it +determines both the variable's position and whether it's a searchList value or +a non-searchList value, and generates the appropriate Python code. + +In top-level position, the \code{\$} is {\em required}. Otherwise there's +nothing to distinguish the variable from ordinary text, and the variable name +is output verbatim. + +In expression position, the \code{\$} is {\em required} if the value comes from +the searchList or a ``\#set global'' variable, {\em recommended} for +local/global/builtin variables, and {\em not necessary} for the special +constants \code{None}, \code{True} and \code{False}. This works because +Cheetah generates a function call for a searchList placeholder, but a bare +variable name for a local/global/builtin variable. + +In LVALUE position, the \code{\$} is {\em recommended}. Cheetah knows where +an LVALUE is expected, so it can handle your variable name whether it has +\code{\$} or not. + +EXCEPTION: Do {\em not} use the \code{\$} prefix for intermediate variables in +a Python list comprehensions. This is a limitation of Cheetah's parser; it +can't tell which variables in a list comprehension are the intermediate +variables, so you have to help it. For example: +\begin{verbatim} +#set $theRange = [x ** 2 for x in $range(10)] +\end{verbatim} +\code{\$theRange} is a regular \code{\#set} variable. \code{\$range} is a +Python built-in function. But \code{x} is a scratch variable internal to +the list comprehension: if you type \code{\$x}, Cheetah will miscompile +it. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{NameMapper Syntax} +\label{language.namemapper} + +One of our core aims for Cheetah was to make it easy for non-programmers to +use. Therefore, Cheetah uses a simplified syntax for mapping placeholders +in Cheetah to values in Python. It's known as the {\bf NameMapper syntax} +and allows for non-programmers to use Cheetah without knowing (a) the +difference between an instance and a dictionary, (b) what functions and methods +are, and (c) what 'self' is. A side benefit is that you can change the +underlying data structure (e.g., instance to dictionary or vice-versa) without +having to modify the templates. + +NameMapper syntax is used for all variables in Cheetah placeholders and +directives. If desired, it can be turned off via the \code{Template} class' +\code{'useNameMapper'} compiler setting. But it's doubtful you'd ever want to +turn it off. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Example} +\label{language.namemapper.example} + +Consider this scenario: + +You are building a customer information system. The designers with you want to +use information from your system on the client's website --AND-- they want to +understand the display code and so they can maintian it themselves. + +You write a UI class with a 'customers' method that returns a dictionary of all +the customer objects. Each customer object has an 'address' method that returns +the a dictionary with information about the customer's address. The designers +want to be able to access that information. + +Using PSP, the display code for the website would look something like the +following, assuming your servlet subclasses the class you created for managing +customer information: + +\begin{verbatim} + <%= self.customer()[ID].address()['city'] %> (42 chars) +\end{verbatim} + +With Cheetah's NameMapper syntax, you can use any of the following: + +\begin{verbatim} + $self.customers()[$ID].address()['city'] (39 chars) + --OR-- + $customers()[$ID].address()['city'] + --OR-- + $customers()[$ID].address().city + --OR-- + $customers()[$ID].address.city + --OR-- + $customers[$ID].address.city (27 chars) +\end{verbatim} + +Which of these would you prefer to explain to the designers, who have no +programming experience? The last form is 15 characters shorter than the PSP +version and -- conceptually -- far more accessible. With PHP or ASP, the +code would be even messier than with PSP. + +This is a rather extreme example and, of course, you could also just implement +\code{\$getCustomer(\$ID).city} and obey the Law of Demeter (search Google for more +on that). But good object orientated design isn't the point of this example. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Dictionary Access} +\label{language.namemapper.dict} + +NameMapper syntax allows access to dictionary items with the same dotted +notation used to access object attributes in Python. This aspect of NameMapper +syntax is known as 'Unified Dotted Notation'. +For example, with Cheetah it is possible to write: +\begin{verbatim} + $customers()['kerr'].address() --OR-- $customers().kerr.address() +\end{verbatim} +where the second form is in NameMapper syntax. + +This works only with dictionary keys that also happen to be valid Python +identifiers. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Autocalling} +\label{language.namemapper.autocalling} + +Cheetah automatically detects functions and methods in Cheetah \$variables and +calls them if the parentheses have been left off. Our previous example can be +further simplified to: +\begin{verbatim} + $customers.kerr.address +\end{verbatim} + +As another example, if 'a' is an object, 'b' is a method +\begin{verbatim} + $a.b +\end{verbatim} + +is equivalent to + +\begin{verbatim} + $a.b() +\end{verbatim} + +If b returns a dictionary, then following variations are possible +\begin{verbatim} + $a.b.c --OR-- $a.b().c --OR-- $a.b()['c'] +\end{verbatim} +where 'c' is a key in the dictionary that a.b() returns. + +Further notes: +\begin{itemize} +\item When Cheetah autocalls a function/method, it calls it without any +arguments. Thus, the function/method must have been declared without arguments +(except \code{self} for methods) or to provide default values for all arguments. +If the function requires arguments, you must use the \code{()}. + +\item Cheetah autocalls only functions and methods. Classes and other callable +objects are not autocalled. The reason is that the primary purpose of a +function/method is to call it, whereas the primary purpose of an instance is to +look up its attributes or call its methods, not to call the instance itself. +And calling a class may allocate large sums of memory uselessly or have other +side effects, depending on the class. For instance, consider +\code{\$myInstance.fname}. Do we want to look up \code{fname} in the namespace +of \code{myInstance} or in the namespace of whatever \code{myinstance} returns? +It could go either way, so Cheetah follows the principle of least surprise. If +you {\em do} want to call the instance, put the \code{()} on, or rename the +\code{.\_\_call\_\_()} method to \code{.\_\_str\_\_}. + +\item Autocalling can be disabled via Cheetah's 'useAutocalling' compiler +setting. You can also disable it for one placeholder by using the syntax +\code{\$getVar('varName', 'default value', False)}. (\code{.getVar()} works +only with searchList values.) +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Namespace cascading and the searchList} +\label{language.searchList} + +When Cheetah maps a variable name in a template to a Python value, it searches +several namespaces in order: + +\begin{enumerate} +\item {\bf Local variables:} created by \code{\#set}, + \code{\#for}, or predefined by Cheetah. +\item The {\bf searchList}, consisting of: + \begin{enumerate} + \item \code{\#set\ global} variables. + \item The {\bf searchList} containers you passed to the \code{Template} + constructor, if any. + \item The {\bf Template instance} (``self''). This contains any attributes + you assigned, \code{\#def} methods and \code{\#block methods}, + attributes/methods inherited via \code{\#extends}, and other + attributes/methods built into \code{Template} or inherited by it + (there's a list of all these methods in section + \ref{tips.allMethods}). + \end{enumerate} +\item {\bf Python globals:} created by \code{\#import}, + \code{\#from\ ...\ import}, or otherwise predefined by Cheetah. +\item {\bf Python builtins:} \code{None}, \code{max}, etc. +\end{enumerate} + +The first matching name found is used. + +Remember, these namespaces apply only to the {\em first} identifier after the +\code{\$}. In a placeholder like \code{\$a.b}, only `a' is looked up in the +searchList and other namespaces. `b' is looked up only inside `a'. + +A searchList container can be any Python object with attributes or keys: +dictionaries, instances, classes or modules. If an instance contains both +attributes and keys, its attributes are searched first, then its keys. + +Because the \code{Template} instance is part of the searchList, you can +access its attributes/methods without `self': \code{\$myAttr}. However, use +the `self' if you want to make sure you're getting the \code{Template} +attribute and not a same-name variable defined in a higher namespace: +\code{\$self.myAttr}. This works because ``self'' itself is a local variable. + +The final resulting value, after all lookups and function calls (but before the +filter is applied) is called the {\em placeholder value}, no matter which +namespace it was found in. + +{\em {\bf Note carefully:}} if you put an object `myObject' in the searchList, +you {\em cannot} look up \code{\$myObject}! You can look up only the +attributes/keys {\em inside} `myObject'. + +Earlier versions of Cheetah did not allow you to override Python builtin +names, but this was fixed in Cheetah 0.9.15. + +If your template will be used as a Webware servlet, do not override methods +'name' and 'log' in the \code{Template} instance or it will interfere with +Webware's logging. However, it {\em is} OK to use those variables in a higher +namespace, since Webware doesn't know about Cheetah namespaces. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Missing Values} +\label{language.namemapper.missing} + +If NameMapper can not find a Python value for a Cheetah variable name, it will +raise the NameMapper.NotFound exception. You can use the \code{\#errorCatcher} +directive (section \ref{errorHandling.errorCatcher}) or {\bf errorCatcher} +Template constructor argument (section \ref{howWorks.constructing}) to specify +an alternate behaviour. BUT BE AWARE THAT errorCatcher IS ONLY INTENDED FOR +DEBUGGING! + +To provide a default value for a placeholder, write it like this: +\code{\$getVar('varName', 'default value')}. If you don't specify a default +and the variable is missing, \code{NameMapper.NotFound} will be raised. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Directive Syntax Rules} +\label{language.directives.syntax} + + +Directive tags begin with a hash character (\#) and are used for comments, +loops, conditional blocks, includes, and all other advanced features. Cheetah +uses a Python-like syntax inside directive tags and understands any valid +Python expression. {\bf However, unlike Python, Cheetah does not use colons +(:) and indentation to mark off multi-line directives.} That doesn't work in +an environment where whitespace is significant as part of the text. Instead, +multi-line directives like \code{\#for} have corresponding closing tags +(\code{\#end for}). Most directives are direct mirrors of Python statements. + +Many directives have arguments after the opening tag, which must be in the +specified syntax for the tag. All end tags have the following syntax: +\begin{verbatim} +#end TAG_NAME [EXPR] +\end{verbatim} +The expression is ignored, so it's essentially a comment. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Directive closures and whitespace handling} +\label{language.directives.closures} +Directive tags can be closed explicitly with \code{\#}, or implicitly with the +end of the line if you're feeling lazy. + +\begin{verbatim} +#block testBlock # +Text in the body of the +block directive +#end block testBlock # +\end{verbatim} +is identical to: +\begin{verbatim} +#block testBlock +Text in the body of the +block directive +#end block testBlock +\end{verbatim} + +When a directive tag is closed explicitly, it can be followed with other text on +the same line: + +\begin{verbatim} +bah, bah, #if $sheep.color == 'black'# black#end if # sheep. +\end{verbatim} + +When a directive tag is closed implicitly with the end of the line, all trailing +whitespace is gobbled, including the newline character: +\begin{verbatim} +""" +foo #set $x = 2 +bar +""" +outputs +""" +foo bar +""" + +while +""" +foo #set $x = 2 # +bar +""" +outputs +""" +foo +bar +""" +\end{verbatim} + +When a directive tag is closed implicitly AND there is no other text on the +line, the ENTIRE line is gobbled up including any preceeding whitespace: +\begin{verbatim} +""" +foo + #set $x = 2 +bar +""" +outputs +""" +foo +bar +""" + +while +""" +foo + - #set $x = 2 +bar +""" +outputs +""" +foo + - bar +""" +\end{verbatim} + +The \code{\#slurp} directive (section \ref{output.slurp}) also gobbles up +whitespace. + +Spaces outside directives are output {\em exactly} as written. In the +black sheep example, there's a space before ``black'' and another before +``sheep''. So although it's legal to put multiple directives on one line, +it can be hard to read. + +\begin{verbatim} +#if $a# #echo $a + 1# #end if + - There's a space between each directive, + or two extra spaces total. +#if $a##echo $a + 1##end if + - No spaces, but you have to look closely + to verify none of the ``##'' are comment markers. +#if $a##echo $a + 1##end if ### A comment. + - In ``###'', the first ``#'' ends the directive, + the other two begin the comment. (This also shows + how you can add extra whitespace in the directive + tag without affecting the output.) +#if $a##echo $a + 1##end if # ## A comment. + - More readable, but now there's a space before the + comment. +\end{verbatim} + +% Local Variables: +% TeX-master: "users_guide" +% End: + +% # vim: sw=4 ts=4 expandtab diff --git a/docs/users_guide_src/libraries.tex b/docs/users_guide_src/libraries.tex new file mode 100755 index 0000000..dc9231a --- /dev/null +++ b/docs/users_guide_src/libraries.tex @@ -0,0 +1,306 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Batteries included: templates and other libraries} +\label{libraries} + +Cheetah comes ``batteries included'' with libraries of templates, functions, +classes and other objects you can use in your own programs. The different +types are listed alphabetically below, followed by a longer description of +the SkeletonPage framework. Some of the objects are classes for specific +purposes (e.g., filters or error catchers), while others are standalone and +can be used without Cheetah. + +If you develop any objects which are generally useful for Cheetah sites, +please consider posting them on the wiki with an announcement on the mailing +list so we can incorporate them into the standard library. That way, all +Cheetah users will benefit, and it will encourage others to contribute their +objects, which might include something you want. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{ErrorCatchers} +\label{libraries.ErrorCatchers} + +Module \code{Cheetah.ErrorCatchers} contains error-handling classes suitable for +the \code{\#errorCatcher} directive. These are debugging tools that are not +intended for use in production systems. See section +\ref{errorHandling.errorCatcher} for a description of the error catchers bundled +with Cheetah. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{FileUtils} +\label{libraries.FileUtils} + +Module \code{Cheetah.FileUtils} contains generic functions and classes for +doing bulk search-and-replace on several files, and for finding all the files +in a directory hierarchy whose names match a glob pattern. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Filters} +\label{libraries.Filters} + +Module \code{Filters} contains filters suitable for the \code{\#Filter} +directive. See section \ref{output.filter} for a description of the +filters bundled with Cheetah. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{SettingsManager} +\label{libraries.SettingsManager} + +The \code{SettingsManager} class in the \code{Cheetah.SettingsManager} module is +a baseclass that provides facilities for managing application settings. It +facilitates the use of user-supplied configuration files to fine tune an +application. A setting is a key/value pair that an application or component +(e.g., a filter, or your own servlets) looks up and treats as a configuration +value to modify its (the component's) behaviour. + +SettingsManager is designed to: +\begin{itemize} +\item work well with nested settings dictionaries of any depth +\item read/write \code{.ini style config files} (or strings) +\item read settings from Python source files (or strings) so that + complex Python objects can be stored in the application's settings + dictionary. For example, you might want to store references to various + classes that are used by the application, and plugins to the application + might want to substitute one class for another. +\item allow sections in \code{.ini config files} to be extended by settings in + Python src files. If a section contains a setting like + ``\code{importSettings=mySettings.py}'', \code{SettingsManager} will merge + all the settings defined in ``\code{mySettings.py}'' with the settings for + that section that are defined in the \code{.ini config file}. +\item maintain the case of setting names, unlike the ConfigParser module +\end{itemize} + +Cheetah uses \code{SettingsManager} to manage its configuration settings. +\code{SettingsManager} might also be useful in your own applications. See the +source code and docstrings in the file \code{src/SettingsManager.py} for more +information. + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Templates} +\label{libraries.templates} + +Package \code{Cheetah.Templates} contains stock templates that you can +either use as is, or extend by using the \code{\#def} directive to redefine +specific {\bf blocks}. Currently, the only template in here is SkeletonPage, +which is described in detail below in section +\ref{libraries.templates.skeletonPage}. (Contributed by Tavis Rudd.) + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Tools} +\label{libraries.Tools} + +Package \code{Cheetah.Tools} contains functions and classes contributed by third +parties. Some are Cheetah-specific but others are generic and can be used +standalone. None of them are imported by any other Cheetah component; you can +delete the Tools/ directory and Cheetah will function fine. + +Some of the items in Tools/ are experimental and have been placed there just to +see how useful they will be, and whether they attract enough users to make +refining them worthwhile (the tools, not the users :). + +Nothing in Tools/ is guaranteed to be: (A) tested, (B) reliable, (C) immune +from being deleted in a future Cheetah version, or (D) immune from +backwards-incompatable changes. If you depend on something in Tools/ on a +production system, consider making a copy of it outside the Cheetah/ directory +so that this version won't be lost when you upgrade Cheetah. Also, learn +enough about Python and about the Tool so that you can maintain it and bugfix +it if necessary. + +If anything in Tools/ is found to be necessary to Cheetah's operation (i.e., if +another Cheetah component starts importing it), it will be moved to the +\code{Cheetah.Utils} package. + +Current Tools include: +\begin{description} +\item{Cheetah.Tools.MondoReport} an ambitious class useful when + iterating over records of data (\code{\#for} loops), displaying one + pageful of records at a time (with previous/next links), and printing + summary statistics about the records or the current page. See + \code{MondoReportDoc.txt} in the same directory as the module. Some + features are not implemented yet. \code{MondoReportTest.py} is a test + suite (and it shows there are currently some errors in MondoReport, hmm). + Contributed by Mike Orr. + +\item{Cheetah.Tools.RecursiveNull} Nothing, but in a friendly way. Good + for filling in for objects you want to hide. If \code{\$form.f1} is a + RecursiveNull object, then \code{\$form.f1.anything["you"].might("use")} + will resolve to the empty string. You can also put a \code{RecursiveNull} + instance at the end of the searchList to convert missing values to '' + rather than raising a \code{NotFound} error or having a (less efficient) + errorCatcher handle it. Of course, maybe you prefer to get a + \code{NotFound} error... Contributed by Ian Bicking. + +\item{Cheetah.Tools.SiteHierarchy} Provides navigational links to this + page's parents and children. The constructor takes a recursive list of + (url,description) pairs representing a tree of hyperlinks to every page in + the site (or section, or application...), and also a string containing the + current URL. Two methods 'menuList' and 'crumbs' return output-ready HTML + showing an indented menu (hierarchy tree) or crumbs list (Yahoo-style bar: + home > grandparent > parent > currentURL). Contributed by Ian Bicking. + +\item +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Utils} +\label{libraries.Utils} + +Package \code{Cheetah.Utils} contains non-Cheetah-specific functions and +classes that are imported by other Cheetah components. Many of these utils can +be used standalone in other applications too. + +Current Utils include: +\begin{description} +\item{Cheetah.Utils.CGIImportMixin} This is inherited by \code{Template} + objects, and provides the method, \code{.cgiImport} method + (section \ref{webware.cgiImport}). + +\item{Cheetah.Utils.Misc} A catch-all module for small functions. + \begin{description} + \item{\code{UseOrRaise(thing, errmsg='')}} Raise 'thing' if it's a + subclass of Exception, otherwise return it. Useful when one + argument does double duty as a default value or an exception to + throw. Contribyted by Mike Orr. + + \item{\code{checkKeywords(dic, legalKeywords, what='argument'}} + Verifies the dictionary does not contain any keys not listed in + 'legalKeywords'. If it does, raise TypeError. Useful for + checking the keyword arguments to a function. Contributed by + Mike Orr. + \end{description} + +\item{Cheetah.Utils.UploadFileMixin} Not implemented yet, but will contain + the \code{.uploadFile} method (or three methods) to ``safely'' copy a + form-uploaded file to a local file, to a searchList variable, or return + it. When finished, this will be inherited by \code{Template}, allowing + all templates to do this. If you want this feature, read the docstring + in the source and let us know on the mailing list what you'd like this + method to do. Contributed by Mike Orr. + +\item{Cheetah.Utils.VerifyType} Functions to verify the type of a + user-supplied function argument. Contributed by Mike Orr. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Cheetah.Templates.SkeletonPage} +\label{libraries.templates.skeletonPage} + +A stock template class that may be useful for web developers is defined in +the \code{Cheetah.Templates.SkeletonPage} module. The \code{SkeletonPage} +template class is generated from the following Cheetah source code: + +\begin{verbatim} +##doc-module: A Skeleton HTML page template, that provides basic structure and utility methods. +################################################################################ +#extends Cheetah.Templates._SkeletonPage +#implements respond +################################################################################ +#cache id='header' +$docType +$htmlTag +<!-- This document was autogenerated by Cheetah(http://CheetahTemplate.org). +Do not edit it directly! + +Copyright $currentYr - $siteCopyrightName - All Rights Reserved. +Feel free to copy any javascript or html you like on this site, +provided you remove all links and/or references to $siteDomainName +However, please do not copy any content or images without permission. + +$siteCredits + +--> + + +#block writeHeadTag +<head> +<title>$title</title> +$metaTags +$stylesheetTags +$javascriptTags +</head> +#end block writeHeadTag + +#end cache header +################# + +$bodyTag + +#block writeBody +This skeleton page has no flesh. Its body needs to be implemented. +#end block writeBody + +</body> +</html> +\end{verbatim} + +You can redefine any of the blocks defined in this template by writing a new +template that \code{\#extends} SkeletonPage. (As you remember, using +\code{\#extends} makes your template implement the \code{.writeBody()} +method instead of \code{.respond()} -- which happens to be the same method +SkeletonPage expects the page content to be (note the writeBody block in +SkeletonPage).) + +\begin{verbatim} +#def bodyContents +Here's my new body. I've got some flesh on my bones now. +#end def bodyContents +\end{verbatim} + +%% @@MO: Is this still accurate? Does the child template really need to put a +%% #def around its whole content? Or by implementing .writeBody() does it +%% automatically insert itself as the writeBody portion of +%% SkeletonPage? @@TR 2005-01-06: it happens automatically at the moment. + +All of the \$placeholders used in the \code{SkeletonPage} template definition +are attributes or methods of the \code{SkeletonPage} class. You can reimplement +them as you wish in your subclass. Please read the source code of the file +\code{src/Templates/\_SkeletonPage.py} before doing so. + +You'll need to understand how to use the following methods of the +\code{SkeletonPage} class: \code{\$metaTags()}, \code{\$stylesheetTags()}, +\code{\$javascriptTags()}, and \code{\$bodyTag()}. They take the data you +define in various attributes and renders them into HTML tags. + +\begin{itemize} +\item {\bf metaTags()} -- Returns a formatted vesion of the self.\_metaTags + dictionary, using the formatMetaTags function from + \code{\_SkeletonPage.py}. +\item {\bf stylesheetTags()} -- Returns a formatted version of the + \code{self.\_stylesheetLibs} and \code{self.\_stylesheets} dictionaries. + The keys in \code{self.\_stylesheets} must be listed in the order that + they should appear in the list \code{self.\_stylesheetsOrder}, to ensure + that the style rules are defined in the correct order. +\item {\bf javascriptTags()} -- Returns a formatted version of the + \code{self.\_javascriptTags} and \code{self.\_javascriptLibs} dictionaries. + Each value in \code{self.\_javascriptTags} should be a either a code string + to include, or a list containing the JavaScript version number and the code + string. The keys can be anything. The same applies for + \code{self.\_javascriptLibs}, but the string should be the SRC filename + rather than a code string. +\item {\bf bodyTag()} -- Returns an HTML body tag from the entries in the dict + \code{self.\_bodyTagAttribs}. +\end{itemize} + +The class also provides some convenience methods that can be used as +\$placeholders in your template definitions: + +\begin{itemize} +\item {\bf imgTag(self, src, alt='', width=None, height=None, border=0)} -- + Dynamically generate an image tag. Cheetah will try to convert the + ``\code{src}'' argument to a WebKit serverSidePath relative to the + servlet's location. If width and height aren't specified they are + calculated using PIL or ImageMagick if either of these tools are available. + If all your images are stored in a certain directory you can reimplement + this method to append that directory's path to the ``\code{src}'' argument. + Doing so would also insulate your template definitions from changes in your + directory structure. +\end{itemize} + + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/links.tex b/docs/users_guide_src/links.tex new file mode 100755 index 0000000..1ec2f6c --- /dev/null +++ b/docs/users_guide_src/links.tex @@ -0,0 +1,112 @@ +\section{Useful Web Links} +\label{links} + +See the wiki for more links. (The wiki is also updated more often than this +chapter is.) + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah Links} +\label{links.cheetah} + +\begin{description} +\item[Home Page] -- \url{http:www.CheetahTemplate.org/} + +\item[On-line Documentation] -- \url{http:www.CheetahTemplate.org/learn.html} + +\item[SourceForge Project Page] -- \url{http:sf.net/projects/cheetahtemplate/} + +\item[Mailing List Subscription Page] -- + \url{http://lists.sourceforge.net/lists/listinfo/cheetahtemplate-discuss} + +\item[Mailing List Archive @ Geocrawler] -- + \url{http://www.geocrawler.com/lists/3/SourceForge/12986/0/} + +\item[Mailing List Archive @ Yahoo] -- + \url{http://groups.yahoo.com/group/cheetah-archive/} + +\item[CVS Repository] -- \url{http://sourceforge.net/cvs/?group\_id=28961} + +\item[CVS-commits archive] -- + \url{http://www.geocrawler.com/lists/3/SourceForge/13091/0/} + +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Third-party Cheetah Stuff} +\label{links.thirdParty} + +\begin{itemize} +\item Steve Howell has written a photo viewer using Python. + \url{http://mountainwebtools.com/PicViewer/install.htm} +\end{itemize} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Webware Links} +\label{links.webware} + +\begin{description} +\item[Home Page] -- \url{http://webware.sf.net/} + +\item[On-line Documentation] -- \url{http://webware.sf.net/Webware/Docs/} + +\item[SourceForge Project Page] -- \url{http://sf.net/projects/webware/} + +\item[Mailing List Subscription Page] -- + \url{http://lists.sourceforge.net/lists/listinfo/webware-discuss} + +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Python Links} +\label{links.python} + +\begin{description} +\item[Home Page] -- \url{http://www.python.org/} +\item[On-line Documentation] -- \url{http://www.python.org/doc/} +\item[SourceForge Project Page] -- \url{http://sf.net/projects/python/} +\item[The Vaults of Parnassus: Python Resources] -- + \url{http://www.vex.net/parnassus/} +\item[Python Cookbook] -- \url{http://aspn.activestate.com/ASPN/Cookbook/Python} +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Other Useful Links} +\label{links.other} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Python Database Modules and Open Source Databases} +\label{links.database} + +\begin{description} +\item[Python Database Topic Guide] -- \url{http://python.org/topics/database/} +\item[PostgreSQL Database] -- \url{http://www.postgresql.org/index.html} +\item[MySQL Database] -- \url{http://www.mysql.com/} +\item[A comparison of PostgreSQL and MySQL] -- + \url{http://phpbuilder.com/columns/tim20001112.php3} +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Other Template Systems} +\label{links.other.templateSystems} + +\begin{description} +\item[Chuck's ``Templates'' Summary Page] -- \url{http://webware.sf.net/Papers/Templates/} +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Other Internet development frameworks} +\label{links.internet} + +\begin{description} +\item[ZOPE (Z Object Publishing Environment)] -- \url{http://zope.org/} +\item[Server Side Java] -- \url{http://jakarta.apache.org/} +\item[PHP] -- \url{http://php.net/} +\item[IBM Websphere] -- \url{http://www.ibm.com/websphere/} +\item[Coldfusion and Spectra] -- \url{http://www.macromedia.com/} +\end{description} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/moreverb.sty b/docs/users_guide_src/moreverb.sty new file mode 100755 index 0000000..92e34bb --- /dev/null +++ b/docs/users_guide_src/moreverb.sty @@ -0,0 +1,197 @@ +%%% moreverb.sty
+%%% AJCD 20 Sep 91
+%%% adds various verbatim environments using Rainer Sch\"opf's new verbatim
+%%% environment.
+
+
+%%% Marginal hacks (RF) to work `properly' with 2e
+\def\filedate{1994/12/13}
+\def\fileversion{v2.0}
+%
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{moreverb}
+ [\filedate\space \fileversion\space
+ LaTeX2e package for `more' verbatim enhancements]
+\typeout{Package: `moreverb'
+ \fileversion \space <\filedate> (RF, after AJCD and RmS)}
+%\typeout{English Documentation \@spaces <\docdate>} % oh no there isn't
+
+%%% load verbatim style if not already loaded.
+\@ifundefined{verbatim@processline}{\RequirePackage{verbatim}}{}
+
+%%% verbatimwrite writes all text in its body to a file, the name of which it
+%%% is given as an argument. Written by RmS.
+\newwrite \verbatim@out
+\def\verbatimwrite#1{%
+ \@bsphack
+ \immediate\openout \verbatim@out #1
+ \let\do\@makeother\dospecials
+ \catcode`\^^M\active \catcode`\^^I=12
+ \def\verbatim@processline{%
+ \immediate\write\verbatim@out
+ {\the\verbatim@line}}%
+ \verbatim@start}
+
+\def\endverbatimwrite{%
+ \immediate\closeout\verbatim@out
+ \@esphack}
+
+%%% Auxiliary macros and counters for expanding tabs. Use by listing and
+%%% verbatimtab environments.
+\newcount\tab@position \newcount\tab@size
+\newcount\verbatimtabsize \verbatimtabsize=8
+\def\@xobeytab{\leavevmode\penalty\@M
+ {\loop\ \global\advance\tab@position-1 \ifnum\tab@position>0 \repeat}}
+\begingroup
+ \catcode`\^^I=\active
+ \gdef\@vobeytabs{\catcode`\^^I\active\let^^I\@xobeytab}%
+\endgroup
+\def\verbatim@tabexpand#1{%
+ \ifx#1\@nil \let\next\par \else
+ \ifx#1\@xobeysp \@xobeysp\advance\tab@position-1 \else
+ \ifx#1\@xobeytab \@xobeytab\else
+ #1\advance\tab@position-1
+ \fi\fi
+ \ifnum\tab@position=0 \tab@position\tab@size \fi
+ \let\next\verbatim@tabexpand
+ \fi\next
+}
+
+%%% listing defines a verbatim environment with numbered lines; it takes an
+%%% optional argument specifying the number of lines between numbered
+%%% lines, and a mandatory argument specifying the starting line. listingcont
+%%% continues from the place where listing left off.
+%%% The style in which the label is set can be altered by re-defining
+%%% \listinglabel. * versions are provided.
+\newcount\listing@line \listing@line=1 \newcount\listing@step \listing@step=1
+% Adding an \hbox in front of the line causes a line break, so I go
+% through this rigmarole to get the lines aligned nicely. I probably
+% missed some obvious reason why \hboxes don't work.
+\def\listinglabel#1{\rlap{\small\rm\the#1}\hskip2.5em}
+\def\thelisting@line{%
+ \setbox0\hbox{\listinglabel\listing@line}%
+ \@tempcnta=\listing@line
+ \divide\@tempcnta\listing@step \multiply\@tempcnta\listing@step
+ \ifnum\listing@line=1 \unhbox0
+ \else \ifnum\@tempcnta=\listing@line \unhbox0
+ \else \hskip\wd0
+ \fi\fi}
+\def\listing{\@ifnextchar[{\@listing}{\@listing[1]}}
+\def\@listing[#1]#2{%
+ \global\listing@line=#2\global\listing@step=#1\listingcont}
+\def\listingcont{%
+ \tab@size=\verbatimtabsize
+ \def\verbatim@processline{\tab@position\tab@size
+ \thelisting@line \global\advance\listing@line1
+ \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}%
+ \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs\verbatim@start}
+\let\endlisting=\endtrivlist
+\let\endlistingcont=\endtrivlist
+\@namedef{listing*}{\@ifnextchar[{\@listingstar}{\@listingstar[1]}}
+\def\@listingstar[#1]#2{%
+ \global\listing@line=#2\global\listing@step=#1\relax
+ \csname listingcont*\endcsname}
+\@namedef{listingcont*}{%
+ \def\verbatim@processline{%
+ \thelisting@line \global\advance\listing@line1
+ \the\verbatim@line\par}%
+ \@verbatim\verbatim@start}
+\expandafter\let\csname endlisting*\endcsname =\endtrivlist
+\expandafter\let\csname endlistingcont*\endcsname =\endtrivlist
+
+%%% file input version of listing
+\def\listinginput{%
+ \@ifnextchar[{\@listinginput}{\@listinginput[1]}}
+{\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N
+ \lowercase{%
+ \gdef\@listinginput[#1]#2#3{\begingroup
+ \global\listing@line=#2\global\listing@step=#1
+ \tab@size=\verbatimtabsize
+ \def\verbatim@processline{\tab@position\tab@size
+ \thelisting@line \global\advance\listing@line1
+ \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}%
+ \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs
+ \def\verbatim@addtoline##1~{%
+ \verbatim@line\expandafter{\the\verbatim@line##1}}%
+ \openin\verbtab@in=#3
+ \ifeof\verbtab@in\typeout{No file #3.}\else
+ \verbtab@oktrue
+ \loop
+ \read\verbtab@in to \verbtab@line
+ \ifeof\verbtab@in\verbtab@okfalse\else
+ \expandafter\verbatim@addtoline\verbtab@line
+ \verbatim@processline
+ \verbatim@startline
+ \fi
+ \ifverbtab@ok\repeat
+ \closein\verbtab@in\fi
+ \endtrivlist\endgroup\@doendpe}}}
+
+%%% verbatimcmd is a verbatim environment with the exception of the escape and
+%%% grouping characters \, {, }.
+\def\verbatimcmd{%
+ \@verbatim \catcode`\\=0 \catcode`\{=1 \catcode`\}=2
+ \frenchspacing\@vobeyspaces\verbatim@start
+}
+\def\endverbatimcmd{%
+ \let\par\relax
+ \def\verbatim@{\endtrivlist\endgroup}%
+ \begingroup}
+
+%%% boxedverbatim produces a verbatim environment in a framed box.
+%%% written by Victor Eijkhout
+\def\boxedverbatim{%
+ % redefine `processline' to produce only a line as wide
+ % as the natural width of the line
+ \def\verbatim@processline{%
+ {\setbox0=\hbox{\the\verbatim@line}%
+ \hsize=\wd0 \the\verbatim@line\par}}%
+ % save the verbatim code in a box
+ \setbox0=\vbox\bgroup \verbatim
+}
+\def\endboxedverbatim{%
+ \endverbatim
+ \egroup % close the box and `fbox' it
+ \fbox{\box0}% <<<=== change here for centering,...
+}
+
+%%% verbatimtab is a verbatim environment which expands tab characters; it
+%%% takes an optional argument specifying the width of tab stops
+\def\verbatimtab{\futurelet\next\@verbatimtab}
+\def\@verbatimtab{\if\next[ \let\next\@@verbatimtab\else
+ \def\next{\@@verbatimtab[\the\verbatimtabsize]}\fi\next}
+\def\@@verbatimtab[#1]{%
+ \do@verbatimtab{#1}{%
+ \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs\verbatim@start}%
+}
+\def\do@verbatimtab#1#2{%
+ \tab@size=#1
+ \def\verbatim@processline{\tab@position\tab@size
+ \expandafter\verbatim@tabexpand\the\verbatim@line\@nil}#2
+}
+\let\endverbatimtab=\endtrivlist
+
+%%% file input version of verbatimtab
+\newread\verbtab@in \newif\ifverbtab@ok
+\def\verbatimtabinput{%
+ \@ifnextchar[{\@verbatimtabinput}{\@verbatimtabinput[\the\verbatimtabsize]}}
+{\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N
+ \lowercase{%
+ \gdef\@verbatimtabinput[#1]#2{\begingroup
+ \do@verbatimtab{#1}{%
+ \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs}%
+ \def\verbatim@addtoline##1~{%
+ \verbatim@line\expandafter{\the\verbatim@line##1}}%
+ \openin\verbtab@in=#2
+ \ifeof\verbtab@in\typeout{No file #2.}\else
+ \verbtab@oktrue
+ \loop
+ \read\verbtab@in to \verbtab@line
+ \ifeof\verbtab@in\verbtab@okfalse\else
+ \expandafter\verbatim@addtoline\verbtab@line
+ \verbatim@processline
+ \verbatim@startline
+ \fi
+ \ifverbtab@ok\repeat
+ \closein\verbtab@in\fi
+ \endtrivlist\endgroup\@doendpe}}}
diff --git a/docs/users_guide_src/nonHtml.tex b/docs/users_guide_src/nonHtml.tex new file mode 100755 index 0000000..b618ab0 --- /dev/null +++ b/docs/users_guide_src/nonHtml.tex @@ -0,0 +1,17 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Non-HTML Output} +\label{nonHTML} + +Cheetah can also output any other text format besides HTML. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Python source code} +\label{nonHTML.python} + +To be written. We're in the middle of working on an autoindenter to +make it easier to encode Python indentation in a Cheetah template. + +% Local Variables: +% TeX-master: "users_guide" +% End: +%# vim: sw=4 ts=4 expandtab diff --git a/docs/users_guide_src/optikLicense.tex b/docs/users_guide_src/optikLicense.tex new file mode 100755 index 0000000..db63682 --- /dev/null +++ b/docs/users_guide_src/optikLicense.tex @@ -0,0 +1,43 @@ +\section{Optik license} +\label{optikLicense} + +The optik package (Cheetah.Utils.optik) is based on Optik 1.3, +\url{http://optik.sourceforge.net/}, \copyright 2001 Gregory P Ward +$<$gward@python.net$>$. It's unmodified from the original version except +the \code{import} statements, which have been adjusted to make them work in +this location. The following license applies to optik: + +\begin{quotation} +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +\begin{itemize} +\item Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +\item Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +\item Neither the name of the author nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. +\end{itemize} + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS +IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR +CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +\end{quotation} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/otherHtml.tex b/docs/users_guide_src/otherHtml.tex new file mode 100755 index 0000000..89fd58a --- /dev/null +++ b/docs/users_guide_src/otherHtml.tex @@ -0,0 +1,95 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{non-Webware HTML output} +\label{otherHTML} + +Cheetah can be used with all types of HTML output, not just with Webware. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Static HTML Pages} +\label{otherHTML.static} + +Some sites like Linux Gazette (\url{http://www.linuxgazette.com/}) require +completely static pages because they are mirrored on servers running completely +different software from the main site. Even dynamic sites may have one or +two pages that are static for whatever reason, and the site administrator may +wish to generate those pages from Cheetah templates. + +There's nothing special here. Just create your templates as usual. Then +compile and fill them whenever the template definition changes, and fill them +again whenever the placeholder values change. You may need an extra step to +copy the .html files to their final location. A Makefile (chapter +\ref{tips.Makefile}) can help encapsulate these steps. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{CGI scripts} +\label{otherHTML} + +Unlike Webware servlets, which don't have to worry about the HTTP headers, +CGI scripts must emit their own headers. To make a template CGI aware, add +this at the top: +\begin{verbatim} +#extends Cheetah.Tools.CGITemplate +#implements respond +$cgiHeaders#slurp +\end{verbatim} + +Or if your template is inheriting from a Python class: +\begin{verbatim} +#extends MyPythonClass +#implements respond +$cgiHeaders#slurp +\end{verbatim} + +A sample Python class: +\begin{verbatim} +from Cheetah.Tools import CGITemplate +class MyPythonClass(CGITemplate): + def cgiHeadersHook(self): + return "Content-Type: text/html; charset=koi8-r\n\n" +\end{verbatim} + + +Compile the template as usual, put the .py template module in your +cgi-bin directory and give it execute permission. \code{.cgiHeaders()} is +a ``smart'' method that outputs the headers if the module is called as a +CGI script, or outputs nothing if not. Being ``called as a CGI script'' +means the environmental variable \code{REQUEST\_METHOD} exists and +\code{self.isControlledByWebKit} is false. If you don't agree with that +definition, override \code{.isCgi()} and provide your own. + +The default header is a simple \verb+Content-type: text/html\n\n+, which works +with all CGI scripts. If you want to customize the headers (e.g., to +specify the character set), override \code{.cgiHeadersHook()} and return +a string containing all the headers. Don't forget to include the extra +newline at the end of the string: the HTTP protocol requires this empty +line to mark the end of the headers. + +To read GET/POST variables from form input, use the \code{.webInput()} method +(section \ref{webware.webInput}), or extract them yourself using Python's +\code{cgi} module or your own function. Although \code{.webInput()} was +originally written for Webware servlets, it now handles CGI scripts too. There +are a couple behavioral differences between CGI scripts and Webware servlets +regarding input variables: + +\begin{enumerate} +\item CGI scripts, using Python's \code{cgi} module, believe + \code{REQUEST\_METHOD} and recognize {\em either} GET variables {\em or} + POST variables, not both. Webware servlets, doing additional processing, + ignore \code{REQUEST\_METHOD} and recognize both, like PHP does. +\item Webware servlets can ask for cookies or session variables instead of + GET/POST variables, by passing the argument \code{src='c'} or + \code{src='s'}. CGI scripts get a \code{RuntimeError} if they try to do + this. +\end{enumerate} + +If you keep your .tmpl files in the same directory as your CGI scripts, make +sure they don't have execute permission. Apache at least refuses to serve +files in a \code{ScriptAlias} directory that don't have execute permission. + + +% Local Variables: +% TeX-master: "users_guide" +% End: +%# vim: sw=4 ts=4 expandtab diff --git a/docs/users_guide_src/output.tex b/docs/users_guide_src/output.tex new file mode 100755 index 0000000..742291e --- /dev/null +++ b/docs/users_guide_src/output.tex @@ -0,0 +1,548 @@ +\section{Generating, Caching and Filtering Output} +\label{output} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Output from complex expressions: \#echo} +\label{output.echo} + +Syntax: +\begin{verbatim} +#echo EXPR +\end{verbatim} + +The \code{\#echo} directive is used to echo the output from expressions that +can't be written as simple \$placeholders. + +\begin{verbatim} +Here is my #echo ', '.join(['silly']*5) # example +\end{verbatim} + +This produces: + +\begin{verbatim} +Here is my silly, silly, silly, silly, silly example. +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Executing expressions without output: \#silent} +\label{output.silent} + +Syntax: +\begin{verbatim} +#silent EXPR +\end{verbatim} + +\code{\#silent} is the opposite of \code{\#echo}. It executes an expression +but discards the output. + +\begin{verbatim} +#silent $myList.reverse() +#silent $myList.sort() +Here is #silent $covertOperation() # nothing +\end{verbatim} + +If your template requires some Python code to be executed at the beginning; +(e.g., to calculate placeholder values, access a database, etc), you can put +it in a "doEverything" method you inherit, and call this method using +\code{\#silent} at the top of the template. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{One-line \#if} +\label{output.oneLineIf} + +Syntax: +\begin{verbatim} +#if EXPR1 then EXPR2 else EXPR3# +\end{verbatim} + +The \code{\#if} flow-control directive (section \ref{flowControl.if}) has a +one-line counterpart akin to Perl's and C's \code{?:} operator. +If \code{EXPR1} is true, it evaluates \code{EXPR2} and outputs the result (just +like \code{\#echo\ EXPR2\#}). Otherwise it evaluates \code{EXPR3} and outputs +that result. This directive is short-circuiting, meaning the expression that +isn't needed isn't evaluated. + +You MUST include both 'then' and 'else'. If this doesn't work for you or you +don't like the style use multi-line \code{\#if} directives (section +\ref{flowControl.if}). + +The trailing \code{\#} is the normal end-of-directive character. As usual +it may be omitted if there's nothing after the directive on the same line. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Caching Output} +\label{output.caching} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Caching individual placeholders} +\label{output.caching.placeholders} + +By default, the values of each \$placeholder is retrieved and +interpolated for every request. However, it's possible to cache the values +of individual placeholders if they don't change very often, in order to +speed up the template filling. + +To cache the value of a single \code{\$placeholder}, add an asterisk after the +\$; e.g., \code{\$*var}. The first time the template is +filled, \code{\$var} is looked up. Then whenever the template is filled again, +the cached value is used instead of doing another lookup. + +The \code{\$*} format caches ``forever''; that is, as long as the template +instance remains in memory. It's also possible to cache for a certain time +period using the form \code{\$*<interval>*variable}, where \code{<interval>} is +the interval. The time interval can be specified in seconds (5s), minutes +(15m), hours (3h), days (2d) or weeks (1.5w). The default is minutes. + +\begin{verbatim} +<HTML> +<HEAD><TITLE>$title</TITLE></HEAD> +<BODY> + +$var ${var} ## dynamic - will be reinterpolated for each request +$*var2 $*{var2} ## static - will be interpolated only once at start-up +$*5*var3 $*5*{var3} ## timed refresh - will be updated every five minutes. + +</BODY> +</HTML> +\end{verbatim} + +Note that ``every five minutes'' in the example really means every five +minutes: the variable is looked up again when the time limit is reached, +whether the template is being filled that frequently or not. Keep this in +mind when setting refresh times for CPU-intensive or I/O intensive +operations. + +If you're using the long placeholder syntax, \verb+${}+, the braces go only +around the placeholder name: \verb+$*.5h*{var.func('arg')}+. + +Sometimes it's preferable to explicitly invalidate a cached item whenever +you say so rather than at certain time intervals. You can't do this with +individual placeholders, but you can do it with cached regions, which will +be described next. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Caching entire regions} +\label{output.caching.regions} + +Syntax: +\begin{verbatim} +#cache [id=EXPR] [timer=EXPR] [test=EXPR] +#end cache +\end{verbatim} + +The \code{\#cache} directive is used to cache a region of +content in a template. The region is cached as a single unit, after +placeholders and directives inside the region have been evaluated. If there +are any \code{\$*<interval>*var} placholders inside the cache +region, they are refreshed only when {\em both} the cache region {\em and} the +placeholder are simultaneously due for a refresh. + +Caching regions offers more flexibility than caching individual placeholders. +You can specify the refresh interval using a placeholder or +expression, or refresh according to other criteria rather than a certain +time interval. + +\code{\#cache} without arguments caches the region statically, the same +way as \code{\$*var}. The region will not be automatically refreshed. + +To refresh the region at an interval, use the \code{timer=EXPRESSION} argument, +equivalent to \code{\$*<interval>*}. The expression should evaluate to a +number or string that is a valid interval (e.g., 0.5, '3m', etc). + +To refresh whenever an expression is true, use \code{test=EXPRESSION}. +The expression can be a method/function returning true or false, a boolean +placeholder, several of these joined by \code{and} and/or \code{or}, or any +other expression. If the expression contains spaces, it's easier to +read if you enclose it in \code{()}, but this is not required. + +To refresh whenever you say so, use \code{id=EXPRESSION}. Your program can +then call \code{.refreshCache(ID)} whenever it wishes. This is useful if the +cache depends on some external condition that changes infrequently but has just +changed now. + +You can combine arguments by separating them with commas. For instance, you can +specify both \code{id=} and \code{interval=}, or \code{id=} and \code{test=}. +(You can also combine interval and test although it's not very useful.) +However, repeating an argument is undefined. + +\begin{verbatim} +#cache +This is a static cache. It will not be refreshed. +$a $b $c +#end cache + +#cache timer='30m', id='cache1' +#for $cust in $customers +$cust.name: +$cust.street - $cust.city +#end for +#end cache + +#cache id='sidebar', test=$isDBUpdated +... left sidebar HTML ... +#end cache + +#cache id='sidebar2', test=($isDBUpdated or $someOtherCondition) +... right sidebar HTML ... +#end cache +\end{verbatim} + + +The \code{\#cache} directive cannot be nested. + +We are planning to add a \code{'varyBy'} keyword argument in the future that +will allow a separate cache instances to be created for a variety of conditions, +such as different query string parameters or browser types. This is inspired by +ASP.net's varyByParam and varyByBrowser output caching keywords. + +% @@MO: Can we cache by Webware sessions? What about sessions where the +% session ID is encoded as a path prefix in the URI? Need examples. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#raw} +\label{output.raw} + +Syntax: +\begin{verbatim} +#raw +#end raw +\end{verbatim} + +Any section of a template definition that is inside a \code{\#raw \ldots +\#end raw} tag pair will be printed verbatim without any parsing of +\$placeholders or other directives. This can be very useful for debugging, or +for Cheetah examples and tutorials. + +\code{\#raw} is conceptually similar to HTML's \code{<PRE>} tag and LaTeX's +\code{\\verbatim\{\}} tag, but unlike those tags, \code{\#raw} does not cause +the body to appear in a special font or typeface. It can't, because Cheetah +doesn't know what a font is. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#include} +\label{output.include} + +Syntax: +\begin{verbatim} +#include [raw] FILENAME_EXPR +#include [raw] source=STRING_EXPR +\end{verbatim} + +The \code{\#include} directive is used to include text from outside the +template definition. The text can come from an external file or from a +\code{\$placeholder} variable. When working with external files, Cheetah will +monitor for changes to the included file and update as necessary. + +This example demonstrates its use with external files: +\begin{verbatim} +#include "includeFileName.txt" +\end{verbatim} +The content of "includeFileName.txt" will be parsed for Cheetah syntax. + +And this example demonstrates use with \code{\$placeholder} variables: +\begin{verbatim} +#include source=$myParseText +\end{verbatim} +The value of \code{\$myParseText} will be parsed for Cheetah syntax. This is not +the same as simply placing the \$placeholder tag ``\code{\$myParseText}'' in +the template definition. In the latter case, the value of \$myParseText would +not be parsed. + +By default, included text will be parsed for Cheetah tags. The argument +``\code{raw}'' can be used to suppress the parsing. + +\begin{verbatim} +#include raw "includeFileName.txt" +#include raw source=$myParseText +\end{verbatim} + +Cheetah wraps each chunk of \code{\#include} text inside a nested +\code{Template} object. Each nested template has a copy of the main +template's searchList. However, \code{\#set} variables are visible +across includes only if the defined using the \code{\#set global} keyword. + +All directives must be balanced in the include file. That is, if you start +a \code{\#for} or \code{\#if} block inside the include, you must end it in +the same include. (This is unlike PHP, which allows unbalanced constructs +in include files.) + +% @@MO: What did we decide about #include and the searchList? Does it really +% use a copy of the searchList, or does it share the searchList with the +% parent? + +% @@MO: deleted +%These nested templates share the same \code{searchList} +%as the top-level template. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#slurp} +\label{output.slurp} + +Syntax: +\begin{verbatim} +#slurp +\end{verbatim} + +The \code{\#slurp} directive eats up the trailing newline on the line it +appears in, joining the following line onto the current line. + + +It is particularly useful in \code{\#for} loops: +\begin{verbatim} +#for $i in range(5) +$i #slurp +#end for +\end{verbatim} +outputs: +\begin{verbatim} +0 1 2 3 4 +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#indent} +\label{output.indent} + +This directive is not implemented yet. When/if it's completed, it will allow +you to +\begin{enumerate} +\item indent your template definition in a natural way (e.g., the bodies + of \code{\#if} blocks) without affecting the output +\item add indentation to output lines without encoding it literally in the + template definition. This will make it easier to use Cheetah to produce + indented source code programmatically (e.g., Java or Python source code). +\end{enumerate} + +There is some experimental code that recognizes the \code{\#indent} +directive with options, but the options are purposely undocumented at this +time. So pretend it doesn't exist. If you have a use for this feature +and would like to see it implemented sooner rather than later, let us know +on the mailing list. + +The latest specification for the future \code{\#indent} directive is in the +TODO file in the Cheetah source distribution. + +% @@MO: disabled because it's not implemented and the spec is changing +% \code{\#indent} decouples the indentation in the template definition from the +% indentation in the output. Normally, Cheetah outputs indentation exactly as +% it sees it, no matter whether the indentation is on the first line of a +% paragraph, in front of a directive, or wherever. \code{\#indent} has two main +% uses: +% \begin{enumerate} +% \item To strip all indentation from source lines. This lets you indent +% multiline directives (e.g., \code{\#if}, \code{\#for}) in a natural way +% without having that indentation appear in the output. +% \item To indent every text line in the output according to a user-specified +% ``indentation level'', independent of whatever indentation the source lines +% may have. This is useful for producing Python output, or any language that +% requires strict indentation levels at certain places. To accomplish this, +% Cheetah adds a call to an indentation method at the beginning of every +% affected source line. +% \end{enumerate} +% +% To accomplish the first part, Cheetah removes leading whitespace from the +% affected source lines before the compiler see them. To accomplish the second +% part, Cheetah keeps track of the current indentation level, a value you have +% full control over. At the beginning of every affected text line, Cheetah calls +% a method that outputs the appropriate indentation string. This affects only +% lines in the template definition itself, not multiline placeholder values. +% See the \code{Indent} filter below to indent multiline placeholder values. +% +% All \code{\#indent} commands operate on the lines physically below them in +% the template definition until the next \code{\#indent}, regardless of scope. +% This means they work thorugh all other directives (\code{\#def}, \code{\#for}, +% \code{\#if}, etc) -- so that if you turn on indentation inside a \code{\#def}, +% it remains in effect past the \code{\#end def}. +% +% The following commands turn indentation on and off: +% \begin{description} +% \item{\code{\#indent on}} Strip leading whitespace and add indentation to the +% following lines. This fulfills use \#2 above. +% \item{\code{\#indent off}} Do not strip leading whitespace or add indentation. +% This is Cheetah's default behavior. +% \item{\code{\#indent strip}} Strip leading whitespace but do {\em not} add +% indentation. This fulfills use \#1 above. +% \end{description} +% +% Indentation by default uses real tabs. But you can change the indentation +% string thus: +% \begin{verbatim} +% ## Output four spaces for each indentation level. +% #indent chars ' ' +% ## Output the mail reply prefix for each indentation level. +% #indent chars '> ' +% ## Use a placeholder. +% #indent chars $indentChars +% ## Return to the default behavior. +% #indent chars '\t' +% \end{verbatim} +% +% +% The following commands change the indentation level, which is a non-negative +% integer initially at zero. All of these commands implicitly do an +% \code{\#indent on}: +% \begin{description} +% \item{\code{\#indent ++}} Increment the current indentation level. +% \item{\code{\#indent --}} Decrement the current indentation level. +% \item{\code{\#indent +3}} Add three indentation levels (or any number). +% \item{\code{\#indent -3}} Subtract three indentation levels (or any number). +% \item{\code{\#indent =3}} Set the indentation level to 3. +% \item{\code{\#indent push +2}} Save the current indentation level on a stack +% and add two. +% \item{\code{\#indent pop}} Return to the most recently pushed level. Raise +% \code{IndentationStackEmptyError} if there is no previous level. +% \end{description} +% +% The expressions after \code{+}/\code{-}/\code{=} may be numeric literals or +% Cheetah expressions. The effect is undefined if the value is negative. There +% may be whitespace after the \code{+}/\code{-}/\code{=} symbol. +% The initial implementation uses a simple preprocessor that doesn't understand +% newline characters in expressions. \code{\\n} is fine, but not a real newline. +% +% To indent multiline placeholder values using the current indentation level, +% use the \code{Indent} filter: +% \begin{verbatim} +% #filter Indent +% \end{verbatim} +% It works like the default filter but adds indentation after every newline. It +% does not strip any leading whitespace. It hooks into \code{\$self.\_indenter}, +% defined in \code{Cheetah.Utils.Indenter}. This object keeps track of the +% current indentation level. Specifically, the filter calls +% \code{\$self.\_indent()}, which is a shortcut to the indenter's +% \code{.indent()} method. This is the same thing \code{\#indent} does. +% However, the filter is usable even when indentation is in +% \code{off} or \code{strip} mode. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Ouput Filtering and \#filter} +\label{output.filter} + +Syntax: +\begin{verbatim} +#filter FILTER_CLASS_NAME +#filter $PLACEHOLDER_TO_A_FILTER_INSTANCE +#filter None +\end{verbatim} + + +Output from \$placeholders is passed through an ouput filter. The default +filter merely returns a string representation of the placeholder value, +unless the value is \code{None}, in which case the filter returns an empty +string. Only top-level placeholders invoke the filter; placeholders inside +expressions do not. + +Certain filters take optional arguments to modify their behaviour. To pass +arguments, use the long placeholder syntax and precede each filter argument by +a comma. By convention, filter arguments don't take a \code{\$} prefix, to +avoid clutter in the placeholder tag which already has plenty of dollar signs. +For instance, the MaxLen filter takes an argument 'maxlen': + +\begin{verbatim} +${placeholderName, maxlen=20} +${functionCall($functionArg), maxlen=$myMaxLen} +\end{verbatim} + +To change the output filter, use the \code{'filter'} keyword to the +\code{Template} class constructor, or the \code{\#filter} +directive at runtime (details below). You may use \code{\#filter} as often as +you wish to switch between several filters, if certain \code{\$placeholders} +need one filter and other \code{\$placeholders} need another. + +The standard filters are in the module \code{Cheetah.Filters}. Cheetah +currently provides: + +\begin{description} +\item{\code{Filter}} + \\ The default filter, which converts None to '' and everything else to + \code{str(whateverItIs)}. This is the base class for all other filters, + and the minimum behaviour for all filters distributed with Cheetah. +\item{\code{ReplaceNone}} + \\ Same. +\item{\code{MaxLen}} + \\ Same, but truncate the value if it's longer than a certain length. + Use the 'maxlen' filter argument to specify the length, as in the + examples above. If you don't specify 'maxlen', the value will not be + truncated. +\item{\code{Pager}} + \\ Output a "pageful" of a long string. After the page, output HTML + hyperlinks to the previous and next pages. This filter uses several + filter arguments and environmental variables, which have not been + documented yet. +\item{\code{WebSafe}} + \\ Same as default, but convert HTML-sensitive characters ('$<$', '\&', + '$>$') + to HTML entities so that the browser will display them literally rather + than interpreting them as HTML tags. This is useful with database values + or user input that may contain sensitive characters. But if your values + contain embedded HTML tags you want to preserve, you do not want this + filter. + + The filter argument 'also' may be used to specify additional characters to + escape. For instance, say you want to ensure a value displays all on one + line. Escape all spaces in the value with '\ ', the non-breaking + space: +\begin{verbatim} +${$country, also=' '}} +\end{verbatim} +\end{description} + +To switch filters using a class object, pass the class using the +{\bf filter} argument to the Template constructor, or via a placeholder to the +\code{\#filter} directive: \code{\#filter \$myFilterClass}. The class must be +a subclass of \code{Cheetah.Filters.Filter}. When passing a class object, the +value of {\bf filtersLib} does not matter, and it does not matter where the +class was defined. + +To switch filters by name, pass the name of the class as a string using the +{\bf filter} argument to the Template constructor, or as a bare word (without +quotes) to the \code{\#filter} directive: \code{\#filter TheFilter}. The +class will be looked up in the {\bf filtersLib}. + +The filtersLib is a module containing filter classes, by default +\code{Cheetah.Filters}. All classes in the module that are subclasses of +\code{Cheetah.Filters.Filter} are considered filters. If your filters are in +another module, pass the module object as the {\bf filtersLib} argument to the +Template constructor. + +Writing a custom filter is easy: just override the \code{.filter} method. +\begin{verbatim} + def filter(self, val, **kw): # Returns a string. +\end{verbatim} +Return the {\em string} that should be output for `val'. `val' may be any +type. Most filters return `' for \code{None}. Cheetah passes one keyword +argument: \verb+kw['rawExpr']+ is the placeholder name as it appears in +the template definition, including all subscripts and arguments. If you use +the long placeholder syntax, any options you pass appear as keyword +arguments. Again, the return value must be a string. + +You can always switch back to the default filter this way: +\code{\#filter None}. This is easy to remember because "no filter" means the +default filter, and because None happens to be the only object the default +filter treats specially. + +We are considering additional filters; see +\url{http://webware.colorstudy.net/twiki/bin/view/Cheetah/MoreFilters} +for the latest ideas. + +%% @@MO: Is '#end filter' implemented? Will it be? Can filters nest? +%% Will '#end filter' and '#filter None' be equivalent? + +%% @@MO: Tavis TODO: fix the description of the Pager filter. It needs a howto. + +%% @@MO: How about using settings to provide default arguments for filters? +%% Each filter could look up FilterName (or FilterNameDefaults) setting, +%% whose value would be a dictionary containing keyword/value pairs. These +%% would be overridden by same-name keys passed by the placeholder. + +%% @@MO: If sed-filters (#sed) get added to Cheetah, give them a section here. + +% Local Variables: +% TeX-master: "users_guide" +% End: + +% vim: shiftwidth=4 tabstop=4 expandtab diff --git a/docs/users_guide_src/parserInstructions.tex b/docs/users_guide_src/parserInstructions.tex new file mode 100755 index 0000000..bfd6bc2 --- /dev/null +++ b/docs/users_guide_src/parserInstructions.tex @@ -0,0 +1,116 @@ +\section{Instructions to the Parser/Compiler} +\label{parserInstructions} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#breakpoint} +\label{parserInstructions.breakpoint} + +Syntax: +\begin{verbatim} +#breakpoint +\end{verbatim} + + +\code{\#breakpoint} is a debugging tool that tells the parser to stop +parsing at a specific point. All source code from that point on will be ignored. + +The difference between \code{\#breakpoint} and \code{\#stop} is that +\code{\#stop} occurs in normal templates (e.g., inside an \code{\#if}) but +\code{\#breakpoint} is used only when debugging Cheetah. Another difference is +that \code{\#breakpoint} operates at compile time, while \code{\#stop} is +executed at run time while filling the template. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#compiler-settings} +\label{parserInstructions.compiler-settings} + +Syntax: +\begin{verbatim} +#compiler-settings +key = value (no quotes) +#end compiler-settings + +#compiler-settings reset +\end{verbatim} + + +The \code{\#compiler-settings} directive overrides Cheetah's standard settings, +changing how it parses source code and generates Python code. This +makes it possible to change the behaviour of Cheetah's parser/compiler for a +certain template, or within a portion of the template. + +The \code{reset} argument reverts to the default settings. With \code{reset}, +there's no end tag. + +Here are some examples of what you can do: +\begin{verbatim} +$myVar +#compiler-settings +cheetahVarStartToken = @ +#end compiler-settings +@myVar +#compiler-settings reset +$myVar +\end{verbatim} + + +\begin{verbatim} +## normal comment +#compiler-settings +commentStartToken = // +#end compiler-settings + +// new style of comment + +#compiler-settings reset + +## back to normal comments +\end{verbatim} + +\begin{verbatim} +#slurp +#compiler-settings +directiveStartToken = % +#end compiler-settings + +%slurp +%compiler-settings reset + +#slurp +\end{verbatim} + +Here's a partial list of the settings you can change: +\begin{enumerate} +\item syntax settings + \begin{enumerate} + \item cheetahVarStartToken + \item commentStartToken + \item multilineCommentStartToken + \item multilineCommentEndToken + \item directiveStartToken + \item directiveEndToken + \end{enumerate} +\item code generation settings + \begin{enumerate} + \item commentOffset + \item outputRowColComments + \item defDocStrMsg + \item useNameMapper + \item useAutocalling + \item reprShortStrConstants + \item reprNewlineThreshold + \end{enumerate} +\end{enumerate} +The meaning of these settings and their default values will be documented in +the future. + + +% Local Variables: +% TeX-master: "users_guide" +% End: + + + + diff --git a/docs/users_guide_src/tipsAndTricks.tex b/docs/users_guide_src/tipsAndTricks.tex new file mode 100755 index 0000000..8a16fb4 --- /dev/null +++ b/docs/users_guide_src/tipsAndTricks.tex @@ -0,0 +1,544 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Tips, Tricks and Troubleshooting} +\label{tips} + +This chapter contains short stuff that doesn't fit anywhere else. + +See the Cheetah FAQ for more specialized issues and for troubleshooting tips. +Check the wiki periodically for recent tips contributed by users. If you +get stuck and none of these resources help, ask on the mailing list. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Placeholder Tips} +\label{tips.placeholder} + +Here's how to do certain important lookups that may not be obvious. +For each, we show first the Cheetah expression and then the Python equivalent, +because you can use these either in templates or in pure Python subclasses. +The Cheetah examples use NameMapper shortcuts (uniform dotted notation, +autocalling) as much as possible. + +To verify whether a variable exists in the searchList: +\begin{verbatim} +$varExists('theVariable') +self.varExists('theVariable') +\end{verbatim} +This is useful in \code{\#if} or \code{\#unless} constructs to avoid a +\code{\#NameMapper.NotFound} error if the variable doesn't exist. For instance, +a CGI GET parameter that is normally supplied but in this case the user typed +the URL by hand and forgot the parameter (or didn't know about it). +(\code{.hasVar} is a synonym for \code{.varExists}.) + +To look up a variable in the searchList from a Python method: +\begin{verbatim} +self.getVar('theVariable') +self.getVar('theVariable', myDefault) +\end{verbatim} +This is the equivalent to \code{\$theVariable} in the template. If the +variable is missing, it returns the second argument, \code{myDefault}, if +present, or raises \code{NameMapper.NotFound} if there is no second argument. +However, it usually easier to write your method so that all needed searchList +values come in as method arguments. That way the caller can just use a +\code{\$placeholder} to specify the argument, which is less verbose than you +writing a getVar call. + +To do a ``safe'' placeholder lookup that returns a default value if the +variable is missing: +\begin{verbatim} +$getVar('theVariable', None) +$getVar('theVariable', $myDefault) +\end{verbatim} + +To get an environmental variable, put \code{os.environ} on the searchList as a +container. Or read the envvar in Python code and set a placeholder variable +for it. + +Remember that variables found earlier in the searchList override same-name +variables located in a later searchList object. Be careful when adding objects +containing other variables besides the ones you want (e.g., \code{os.environ}, +CGI parameters). The "other" variables may override variables your application +depends on, leading to hard-to-find bugs. Also, users can inadvertently or +maliciously set an environmental variable or CGI parameter you didn't expect, +screwing up your program. To avoid all this, know what your namespaces +contain, and place the namespaces you have the most control over first. For +namespaces that could contain user-supplied "other" variables, don't put the +namespace itself in the searchList; instead, copy the needed variables into +your own "safe" namespace. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Diagnostic Output} +\label{tips.diagnostic} + +If you need send yourself some debugging output, you can use \code{\#silent} to +output it to standard error: +\begin{verbatim} +#silent $sys.stderr.write("Incorrigible var is '$incorrigible'.\n") +#silent $sys.stderr.write("Is 'unknown' in the searchList? " + + $getVar("unknown", "No.") + "\n" ) +\end{verbatim} +(Tip contributed by Greg Czajkowski.) + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{When to use Python methods} +\label{tips.pythonMethods} + +You always have a choice whether to code your methods as Cheetah \code{\#def} +methods or Python methods (the Python methods being located in a class your +template inherits). So how do you choose? + +Generally, if the method consists mostly of text and placeholders, use a +Cheetah method (a \code{\#def} method). That's why \code{\#def} exists, to +take the tedium out of writing those kinds of methods. And if you have a +couple \code{\#if} stanzas to \code{\#set} some variables, followed by a +\code{\#for} loop, no big deal. But if your method consists mostly of +directives and only a little text, you're better off writing it in Python. +Especially be on the watch for extensive use of \code{\#set}, \code{\#echo} and +\code{\#silent} in a Cheetah method--it's a sure sign you're probably using the +wrong language. Of course, though, you are free to do so if you wish. + +Another thing that's harder to do in Cheetah is adjacent or nested +multiline stanzas (all those directives with an accompanying \code{\#end} +directive). Python uses indentation to show the beginning and end of nested +stanzas, but Cheetah can't do that because any indentation shows up in the +output, which may not be desired. So unless all those extra spaces and tabs +in the output are acceptable, you have to keep directives flush with the left +margin or the preceding text. + +The most difficult decisions come when you have conflicting goals. What if +a method generates its output in parts (i.e., output concatenation), contains +many searchList placeholders and lots of text, {\em and} requires lots of +\code{\#if \ldots \#set \ldots \#else \#set \ldots \#end if} stanzas. A Cheetah +method would be more advantageous in some ways, but a Python method in others. +You'll just have to choose, perhaps coding groups of methods all the same +way. Or maybe you can split your method into two, one Cheetah and one Python, +and have one method call the other. Usually this means the Cheetah method +calling the Python method to calculate the needed values, then the Cheetah +method produces the output. One snag you might run into though is that +\code{\#set} currently can set only one variable per statement, so if your +Python method needs to return multiple values to your Cheetah method, you'll +have to do it another way. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Calling superclass methods, and why you have to} +\label{tips.callingSuperclassMethods} + +If your template or pure Python class overrides a standard method or attribute +of \code{Template} or one of its base classes, you should call the superclass +method in your method to prevent various things from breaking. The most common +methods to override are \code{.awake} and \code{.\_\_init\_\_}. \code{.awake} +is called automatically by Webware early during the web transaction, so it makes +a convenient place to put Python initialization code your template needs. +You'll definitely want to call the superclass \code{.awake} because it sets up +many wonderful attributes and methods, such as those to access the CGI input +fields. + +There's nothing Cheetah-specific to calling superclass methods, but +because it's vital, we'll recap the standard Python techniques +here. We mention only the solution for old-style classes because +Cheetah classes are old-style (in other Python documentation, you will +find the technique for new-style classes, but they are not listed here +because they cannot be used with Cheetah if you use +dynamically-compiled templates). + +\begin{verbatim} +from Cheetah.Template import Template +class MyClass(Template): + def awake(self, trans): + Template.awake(self, trans) + ... great and exciting features written by me ... +\end{verbatim} + +[ @@MO: Need to test this. .awake is in Servlet, which is a superclass +of Template. Do we really need both imports? Can we call +Template.awake? ] + +To avoid hardcoding the superclass name, you can use this +function \code{callbase()}, which emulates \code{super()} for older versions of +Python. It also works even \code{super()} does exist, so you don't have to +change your servlets immediately when upgrading. Note that the argument +sequence is different than \code{super} uses. + +\begin{verbatim} +=========================================================================== +# Place this in a module SOMEWHERE.py . Contributed by Edmund Lian. +class CallbaseError(AttributeError): + pass + +def callbase(obj, base, methodname='__init__', args=(), kw={}, + raiseIfMissing=None): + try: method = getattr(base, methodname) + except AttributeError: + if raiseIfMissing: + raise CallbaseError, methodname + return None + if args is None: args = () + return method(obj, *args, **kw) +=========================================================================== +# Place this in your class that's overriding .awake (or any method). +from SOMEWHERE import callbase +class MyMixin: + def awake(self, trans): + args = (trans,) + callbase(self, MyMixin, 'awake', args) + ... everything else you want to do ... +=========================================================================== +\end{verbatim} + +% @@MO: Edmund wants us to mention delegation too, as an alternative to +% inheritance. Contact elian@inbrief.net for details. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{All methods} +\label{tips.allMethods} + +Here is a list of all the standard methods and attributes that can be accessed +from a placeholder. Some of them exist for you to call, others are mainly used +by Cheetah internally but you can call them if you wish, and others are only +for internal use by Cheetah or Webware. Do not use these method names in mixin +classes (\code{\#extends}, section \ref{inheritanceEtc.extends}) unless you +intend to override the standard method. + +Variables with a star prefix ({\bf *}) are frequently used in templates or in +pure Python classes. + +\paragraph*{Inherited from Cheetah.Template} + +\begin{description} +\item{{\bf compile(source=None, file=None, moduleName=None, + mainMethodName='respond')}} Compile the template. Automatically called + by \code{.\_\_init\_\_}. +\item{{\bf generatedModuleCode()}} Return the module code the compiler + generated, or \code{None} if no compilation took place. +\item{{\bf generatedClassCode()}} Return the class code the compiler + generated, or \code{None} if no compilation took place. +\item{{\bf * searchList()}} Return a reference to the underlying search list. + (a list of objects). Use this to print out your searchList for debugging. + Modifying the returned list will affect your placeholder searches! +\item{{\bf * errorCatcher()}} Return a reference to the current error + catcher. +\item{{\bf * refreshCache(cacheKey=None)}} If 'cacheKey' is not \code{None}, + refresh that item in the cache. If \code{None}, delete all items in the + cache so they will be recalculated the next time they are encountered. +\item{{\bf * shutdown()}} Break reference cycles before discarding a servlet. +\item{{\bf * getVar(varName, default=NoDefault, autoCall=True)}} Look up a + variable in the searchList. Same as \code{\$varName} but allows you to + specify a default value and control whether autocalling occurs. +\item{{\bf * varExists(varName, autoCall=True)}} +\item{{\bf * getFileContents(path)}} Read the named file. If used as a + placeholder, inserts the file's contents in the output without + interpretation, like \code{\#include\ raw}. If used in an expression, + returns the file's content (e.g., to assign it to a variable). +\item{{\bf runAsMainProgram()}} This is what happens if you run a + .py template module as a standalone program. +\end{description} + +%Private methods: {\bf \_bindCompiledMethod}, {\bf \_bindFunctionAsMethod}, +%{\bf \_includeCheetahSource}, {\bf \_genTmpFilename}, +%{\bf \_importAsDummyModule}, {\bf \_makeDummyPackageForDir}, +%{\bf \_importFromDummyPackage}, {\bf \_importModuleFromDirectory}. +% +%Other private attributes: +%\begin{description} +%\item{{\bf * \_fileMtime}} Time the template definition was modified, in +% Unix ticks. \code{None} if the template definition came from a string or +% file handle rather than a named file, same for the next three variables. +%\item{{\bf * \_fileDirName}} The directory containing the template definition. +%\item{{\bf * \_fileBaseName}} The basename of the template definition file. +%\item{{\bf * \_filePath}} The directory+filename of the template definition. +%\end{description} + +\paragraph*{Inherited from Cheetah.Utils.WebInputMixin} + +\begin{description} +\item{{\bf nonNumericInputError}} Exception raised by \code{.webInput}. +\item{{\bf * webInput(...)}} Convenience method to access GET/POST variables + from a Webware servlet or CGI script, or Webware cookie or session + variables. See section \ref{webware.webInput} for usage information. +\end{description} + +\paragraph*{Inherited from Cheetah.SettingsManager} + +\begin{description} +\item{{\bf setting(name, default=NoDefault)}} Get a compiler setting. +\item{{\bf hasSetting(name)}} Does this compiler setting exist? +\item{{\bf setSetting(name, value)}} Set setting 'name' to 'value'. + See \code{\#compiler-settings}, section + \ref{parserInstructions.compiler-settings}. +\item{{\bf settings()}} Return the underlying settings dictionary. (Warning: + modifying this dictionary will change Cheetah's behavior.) +\item{{\bf copySettings()}} Return a copy of the underlying settings + dictionary. +\item{{\bf deepcopySettings()}} Return a deep copy of the underlying settings + dictionary. See Python's \code{copy} module. +\item{{\bf updateSettings(newSettings, merge=True)}} Update Cheetah's + compiler settings from the 'newSettings' dictionary. If 'merge' is true, + update only the names in newSettings and leave the other names alone. + (The SettingsManager is smart enough to update nested dictionaries one + key at a time rather than overwriting the entire old dictionary.) + If 'merge' is false, delete all existing settings so that the new ones are + the only settings. +\item{{\bf updateSettingsFromPySrcStr(theString, merge=True)}} Same, + but pass a string of \code{name=value} pairs rather + than a dictionary, the same as you would provide in a + \code{\#compiler-settings} directive, section + \ref{parserInstructions.compiler-settings}. +\item{{\bf updateSettingsFromPySrcFile(path, merge=True)}} Same, but + exec a Python source file and use the variables it contains as the new + settings. (e.g., \code{cheetahVarStartToken\ =\ "@"}). +\item{{\bf updateSettingsFromConfigFile(path, **kw)}} Same, but get the new + settings from a text file in ConfigParser format (similar to Windows' + *.ini file format). See Python's \code{ConfigParser} module. +\item{{\bf updateSettingsFromConfigFileObj}} Same, but read the open file + object 'inFile' for the new settings. +\item{{\bf updateSettingsFromConfigStr(configStr, convert=True, merge=True}} + Same, but read the new settings from a string in ConfigParser format. +\item{{\bf writeConfigFile(path)}} Write the current compiler settings to + a file named 'path' in *.ini format. +\item{{\bf getConfigString()}} Return a string containing the current + compiler settings in *.ini format. +\end{description} + +\paragraph*{Inherited from Cheetah.Servlet} + +{\em Do not override these in a subclass or assign to them as attributes +if your template will be used as a servlet,} otherwise Webware will behave +unpredictably. However, it {\em is} OK to put same-name variables in the +searchList, because Webware does not use the searchList. + +EXCEPTION: It's OK to override {\bf awake} and {\bf sleep} as long as you +call the superclass methods. (See section +\ref{tips.callingSuperclassMethods}.) + +\begin{description} +\item{{\bf * isControlledByWebKit}} True if this template instance is + part of a live transaction in a running WebKit servlet. +\item{{\bf * isWebwareInstalled}} True if Webware is installed and the + template instance inherits from WebKit.Servlet. If not, it inherits + from Cheetah.Servlet.DummyServlet. +\item{{\bf * awake(transaction)}} Called by WebKit at the beginning of + the web transaction. +\item{{\bf * sleep(transaction)}} Called by WebKit at the end of the + web transaction. +\item{{\bf * respond(transaction)}} Called by WebKit to produce the + web transaction content. For a template-servlet, this means + filling the template. +\item{{\bf shutdown()}} Break reference cycles before deleting instance. +\item{{\bf * serverSidePath()}} The filesystem pathname of the + template-servlet (as opposed to the URL path). +\item{{\bf transaction}} The current Webware transaction. +\item{{\bf application}} The current Webware application. +\item{{\bf response}} The current Webware response. +\item{{\bf request}} The current Webware request. +\item{{\bf session}} The current Webware session. +\item{{\bf write}} Call this method to insert text in the filled template + output. +\end{description} + +Several other goodies are available to template-servlets under the +\code{request} attribute, see section \ref{webware.input}. + +\code{transaction}, \code{response}, \code{request} and \code{session} are +created from the current transaction when WebKit calls \code{awake}, and don't +exist otherwise. Calling \code{awake} yourself (rather than letting WebKit +call it) will raise an exception because the \code{transaction} argument won't +have the right attributes. + +\paragraph*{Inherited from WebKit.Servlet} +These are accessible only if Cheetah knows Webware is installed. This +listing is based on a CVS snapshot of Webware dated 22 September 2002, and +may not include more recent changes. + +The same caveats about overriding these methods apply. + +\begin{description} +\item{name()} The simple name of the class. Used by Webware's logging and + debugging routines. +\item{log()} Used by Webware's logging and debugging routines. +\item{canBeThreaded()} True if the servlet can be multithreaded. +\item{canBeReused()} True if the servlet can be used for another transaction + after the current transaction is finished. +\item{serverSideDir()} Depreciated by \code{.serverSidePath()}. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Optimizing templates} +\label{tips.optimizing} + +Here are some things you can do to make your templates fill faster and user +fewer CPU cycles. Before you put a lot of energy into this, however, make +sure you really need to. In many situations, templates appear to initialize +and fill instantaneously, so no optimization is necessary. If you do find a +situation where your templates are filling slowly or taking too much memory or +too many CPU cycles, we'd like to hear about it on the mailing list. + +Cache \$placeholders whose values don't change frequently. (Section +\ref{output.caching}). + +Use \code{\#set} for values that are very frequently used, especially if they +come out of an expensive operation like a deeply.nested.structure or a database +lookup. \code{\#set} variables are set to Python local variables, which have a +faster lookup time than Python globals or values from Cheetah's searchList. + +Moving variable lookups into Python code may provide a speedup in certain +circumstances. If you're just reading \code{self} attributes, there's no +reason to use NameMapper lookup (\$placeholders) for them. NameMapper does +a lot more work than simply looking up a \code{self} attribute. + +On the other hand, if you don't know exactly where the value will come from +(maybe from \code{self}, maybe from the searchList, maybe from a CGI input +variable, etc), it's easier to just make that an argument to your method, and +then the template can handle all the NameMapper lookups for you: +\begin{verbatim} +#silent $myMethod($arg1, $arg2, $arg3) +\end{verbatim} +Otherwise you'd have to call \code{self.getVar('arg1')} etc in your +method, which is more wordy, and tedious. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{PSP-style tags} +\label{tips.PSP} + +\code{<\%= \ldots \%>} and \code{<\% \ldots \%>} allow an escape +to Python syntax inside the template. You do not need it to use Cheetah +effectively, and we're hard pressed to think of a case to recommend it. +Nevertheless, it's there in case you encounter a situation you can't +express adequately in Cheetah syntax. For instance, to set a local +variable to an elaborate initializer. + +\code{<\%= \ldots \%>} encloses a Python expression whose result will +be printed in the output. + +\code{<\% \ldots \%>} encloses a Python statement or expression (or set of +statements or expressions) that will be included as-is into the generated +method. The statements themselves won't produce any output, but you can use +the local function \code{write(EXPRESSION)} to produce your own output. +(Actually, it's a method of a file-like object, but it looks like a local +function.) This syntax also may be used to set a local variable with a +complicated initializer. + +To access Cheetah services, you must use Python code like you would in an +inherited Python class. For instance, use \code{self.getVar()} to look up +something in the searchList. + +{\em Warning:} {\bf No error checking is done!} If you write: +\begin{verbatim} +<% break %> ## Wrong! +\end{verbatim} +you'll get a \code{SyntaxError} when you fill the template, but that's what you +deserve. + +Note that these are PSP-{\em style} tags, not PSP tags. A Cheetah template +is not a PSP document, and you can't use PSP commands in it. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Makefiles} +\label{tips.Makefile} + +If your project has several templates and you get sick of typing +``cheetah compile FILENAME.tmpl'' all the time--much less remembering which +commands to type when--and your system has the \code{make} +command available, consider building a Makefile to make your life easier. + +Here's a simple Makefile that controls two templates, ErrorsTemplate and +InquiryTemplate. Two external commands, \code{inquiry} and \code{receive}, +depend on ErrorsTemplate.py. Aditionally, InquiryTemplate +itself depends on ErrorsTemplate. + +\begin{verbatim} +all: inquiry receive + +.PHONY: all receive inquiry printsource + +printsource: + a2ps InquiryTemplate.tmpl ErrorsTemplate.tmpl + +ErrorsTemplate.py: ErrorsTemplate.tmpl + cheetah compile ErrorsTemplate.tmpl + +InquiryTemplate.py: InquiryTemplate.tmpl ErrorsTemplate.py + cheetah compile InquiryTemplate.tmpl + +inquiry: InquiryTemplate.py ErrorsTemplate.py + +receive: ErrorsTemplate.py +\end{verbatim} + +Now you can type \code{make} anytime and it will recompile all the templates +that have changed, while ignoring the ones that haven't. Or you can +recompile all the templates \code{receive} needs by typing \code{make receive}. +Or you can recompile only ErrorsTemplate by typing +\code{make ErrorsTemplate}. There's also another target, ``printsource'': +this sends a Postscript version of the project's source files to the printer. +The .PHONY target is explained in the \code{make} documentation; essentially, +you have it depend on every target that doesn't produce an output file with +the same name as the target. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Using Cheetah in a Multi-Threaded Application} +\label{tips.threads} + +Template classes may be shared freely between threads. However, template +instances should not be shared unless you either: +\begin{itemize} +\item Use a lock (mutex) to serialize template fills, to prevent two threads +from filling the template at the same time. +\item Avoid thread-unsafe features: + \begin{itemize} + \item Modifying searchList values or instance variables. + \item Caching (\code{\$*var}, \code{\#cache}, etc). + \item \code{\#set global}, \code{\#filter}, \code{\#errorCatcher}. + \end{itemize} + Any changes to these in one thread will be visible in other threads, + causing them to give inconsistent output. +\end{itemize} + +About the only advantage in sharing a template instance is building up the +placeholder cache. But template instances are so low overhead that it +probably wouldn't take perceptibly longer to let each thread instantiate its +own template instance. Only if you're filling templates several times a +second would the time difference be significant, or if some of the placeholders +trigger extremely slow calculations (e.g., parsing a long text file each time). +The biggest overhead in Cheetah is importing the \code{Template} module in +the first place, but that has to be done only once in a long-running +application. + +You can use Python's \code{mutex} module for the lock, or any similar +mutex. If you have to change searchList values or instance variables +before each fill (which is usually the case), lock the mutex before +doing this, and unlock it only after the fill is complete. + +For Webware servlets, you're probably better off using Webware's servlet +caching rather than Cheetah's caching. Don't override the servlet's +\code{.canBeThreaded()} method unless you avoid the unsafe operations +listed above. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Using Cheetah with gettext} +\label{tips.gettext} + +{\bf gettext} is a project for creating internationalized applications. For +more details, visit \url{http://docs.python.org/lib/module-gettext.html}. +gettext can be used with Cheetah to create internationalized applications, even +for CJK character sets, but you must keep a couple things in mind: +\begin{itemize} +\item xgettext is used on compiled templates, not on the templates themselves. +\item The way the NameMapper syntax gets compiled to Python gets in the way of +the syntax that xgettext recognizes. Hence, a special case exists for the +functions \code{_}, \code{N_}, and \code{ngettext}. If you need to use a +different set of functions for marking strings for translation, you must set +the Cheetah setting \code{gettextTokens} to a list of strings representing the +names of the functions you are using to mark strings for translation. +\end{itemize} + + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/users_guide.tex b/docs/users_guide_src/users_guide.tex new file mode 100755 index 0000000..74949cf --- /dev/null +++ b/docs/users_guide_src/users_guide.tex @@ -0,0 +1,54 @@ + +\documentclass{howto} +\usepackage{moreverb} %% Verbatim Code Listings + +\title{Cheetah Users' Guide} +\release{0.9.17rc1} + +\author{Edited by Mike Orr and Tavis Rudd} +\authoraddress{\email{cheetahtemplate-discuss@lists.sourceforge.net}} + +\begin{document} +\maketitle + +% @@MO: Picture of cheetah from web site. + +\tableofcontents + +\copyright{Copyright 2001-2005, The Cheetah Development Team. + This document may be copied and modified under the terms of the + {\bf Open Publication License} \url{http://www.opencontent.org/openpub/} } + + %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \include{introduction} + \include{glossary} + \include{gettingStarted} + \include{howItWorks} + \include{language} + \include{comments} + \include{output} + \include{inheritanceEtc} + \include{flowControl} + \include{errorHandling} + \include{parserInstructions} + \include{moduleFormatting} + \include{tipsAndTricks} + \include{webware} + \include{otherHtml} + \include{nonHtml} + \include{nonHTML} + \include{libraries} + \include{editors} + + %% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \appendix + \include{links} + \include{examples} + \include{comparisons} + \include{optikLicense} + +\end{document} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_src/webware.tex b/docs/users_guide_src/webware.tex new file mode 100755 index 0000000..a5702d8 --- /dev/null +++ b/docs/users_guide_src/webware.tex @@ -0,0 +1,575 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Using Cheetah with Webware} +\label{webware} + +{\bf Webware for Python} is a 'Python-Powered Internet Platform' that runs +servlets in a manner similar to Java servlets. {\bf WebKit} is the name of +Webware's application server. For more details, please visit +\url{http://webware.sourceforge.net/}. + +All comments below refer to the official version of Webware, the DamnSimple! +offshoot at ?, and the now-abandoned WebwareExperimental implementation at +\url{http://sourceforge.net/projects/expwebware/}, except where noted. All the +implementations are 95\% identical to the servlet writer: their differences lie +in their internal structure and configuration files. One difference is that +the executable you run to launch standard Webware is called \code{AppServer}, +whereas in WebwareExperimental it's called \code{webkit}. But to servlets +they're both "WebKit, Webware's application server", so it's one half dozen to +the other. In this document, we generally use the term {\bf WebKit} to refer +to the currently-running application server. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Installing Cheetah on a Webware system} +\label{webware.installing} + +Install Cheetah after you have installed Webware, following the instructions in +chapter \ref{gettingStarted}. + +The standard Cheetah test suite ('cheetah test') does not test Webware features. +We plan to build a test suite that can run as a Webware servlet, containing +Webware-specific tests, but that has not been built yet. In the meantime, you +can make a simple template containing something like "This is a very small +template.", compile it, put the *.py template module in a servlet +directory, and see if Webware serves it up OK. + +{\em You must not have a Webware context called "Cheetah".} If you do, Webware +will mistake that directory for the Cheetah module directory, and all +template-servlets will bomb out with a "ImportError: no module named Template". +(This applies only to the standard Webware; WebwareExperimental does not have +contexts.) + +If Webware complains that it cannot find your servlet, make sure +'.tmpl' is listed in 'ExtensionsToIgnore' in your 'Application.config' file. + +% @@MO: Should explain extension cascading and how without it, standard +% Webware pretends a file doesn't exist if it finds two or more servable files +% that match the URL. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Containment vs Inheritance} +\label{webware.background} + +Because Cheetah's core is flexible, there are many ways to integrate it with +Webware servlets. There are two broad strategies: the {\bf Inheritance +approach} and the {\bf Containment approach}. The difference is +that in the Inheritance approach, your template object \code{\em is} the +servlet, whereas in the Containment approach, the servlet is not a template but +merely {\em uses} template(s) for portion(s) of its work. + +The Inheritance approach is recommended for new sites because it's simpler, and +because it scales well for large sites with a +site->section->subsection->servlet hierarchy. The Containment approach is +better for existing servlets that you don't want to restructure. For instance, +you can use the Containment approach to embed a discussion-forum table at the +bottom of a web page. + +However, most people who use Cheetah extensively seem +to prefer the Inheritance approach because even the most analytical servlet +needs to produce {\em some} output, and it has to fit the site's look and feel +{\em anyway}, so you may as well use a template-servlet as the place to put the +output. Especially since it's so easy to add a template-servlet to a site once +the framework is established. So we recommend you at least evaluate the +effort that would be required to convert your site framework to template +superclasses as described below, vs the greater flexibility and manageability +it might give the site over the long term. You don't necessarily have to +convert all your existing servlets right away: just build common site templates +that are visually and behaviorally compatible with your specification, and use +them for new servlets. Existing servlets can be converted later, if at all. + +Edmund Liam is preparing a section on a hybrid approach, in which the +servlet is not a template, but still calls template(s) in an inheritance +chain to produce the output. The advantage of this approach is that you +aren't dealing with \code{Template} methods and Webware methods in the +same object. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{The Containment Approach} +\label{webware.containment} + +In the Containment approach, your servlet is not a template. Instead, it +it makes its own arrangements to create and use template object(s) for whatever +it needs. The servlet must explicitly call the template objects' +\code{.respond()} (or \code{.\_\_str\_\_()}) method each time it needs to fill +the template. This does not present the output to the user; it merely gives +the output to the servlet. The servlet then calls its +\code{\#self.response().write()} method to send the output to the user. + +The developer has several choices for managing her templates. She can store the +template definition in a string, file or database and call +\code{Cheetah.Template.Template} manually on it. Or she can put the +template definition in a *.tmpl file and use {\bf cheetah compile} (section +\ref{howWorks.cheetah-compile}) to convert it to a Python class in a *.py +module, and then import it into her servlet. + +Because template objects are not thread safe, you should not store one +in a module variable and allow multiple servlets to fill it simultaneously. +Instead, each servlet should instantiate its own template object. Template +{\em classes}, however, are thread safe, since they don't change once created. +So it's safe to store a template class in a module global variable. + +% @@MO: Example of containment. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{The Inheritance Approach} +\label{webware.inheritance} + +In the Inheritance approach, your template object doubles as as Webware +servlet, thus these are sometimes called {\bf template-servlets}. {\bf cheetah +compile} (section \ref{howWorks.cheetah-compile}) automatically creates modules +containing valid Webware servlets. A servlet is a subclass of Webware's +\code{WebKit.HTTPServlet} class, contained in a module with the same name as +the servlet. WebKit uses the request URL to find the module, and then +instantiates the servlet/template. The servlet must have a \code{.respond()} +method (or \code{.respondToGet()}, \code{.respondToPut()}, etc., but the +Cheetah default is \code{.respond()}). Servlets created by \code{cheetah +compile} meet all these requirements. + +(Cheetah has a Webware plugin that automatically converts a \code{.tmpl servlet +file} into a \code{.py servlet file} when the \code{.tmpl servlet file} is +requested by a browser. However, that plugin is currently unavailable because +it's being redesigned. For now, use \code{cheetah compile} instead.) + +What about logic code? Cheetah promises to keep content (the placeholder +values), graphic design (the template definition and is display logic), and +algorithmic logic (complex calculations and side effects) separate. How? +Where do you do form processing? + +The answer is that your template class can inherit from a pure Python class +containing the analytical logic. You can either use the \code{\#extends} +directive in Cheetah to indicate the superclass(es), or write a Python +\code{class} statement to do the same thing. See the template +\code{Cheetah.Templates.SkeletonPage.tmpl} and its pure Python class +\code{Cheetah.Templates.\_SkeletonPage.py} for an example of a template +inheriting logic code. (See sections \ref{inheritanceEtc.extends} and +\ref{inheritanceEtc.implements} for more information about \code{\#extends} and +\code{\#implements}. They have to be used a certain right way.) + +If \code{\#WebKit.HTTPServlet} is not available, Cheetah fakes it with a +dummy class to satisfy the dependency. This allows servlets to be tested on +the command line even on systems where Webware is not installed. This works +only with servlets that don't call back into WebKit for information about the +current web transaction, since there is no web transaction. Trying to access +form input, for instance, will raise an exception because it depends on a +live web request object, and in the dummy class the request object is +\code{None}. + +Because Webware servlets must be valid Python modules, and ``cheetah compile'' +can produce only valid module names, if you're converting an existing site that +has .html filenames with hyphens (-), extra dots (.), etc, you'll have to +rename them (and possibly use redirects). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Site frameworks} +\label{webware.siteFrameworks} + +Web sites are normally arranged hierarchically, with certain features common +to every page on the site, other features common to certain sections or +subsections, and others unique to each page. You can model this easily with +a hierarchy of classes, with specific servlets inheriting from their more +general superclasses. Again, you can do this two ways, using Cheetah's +{\bf Containment} approach or {\bf Inheritance} approach. + +In the Inheritance approach, parents provide \code{\#block}s and children +override them using \code{\#def}. Each child \code{\#extend}s its immediate +parent. Only the leaf servlets need to be under WebKit's document root +directory. The superclass servlets can live anywhere in the filesystem +that's in the Python path. (You may want to modify your WebKit startup +script to add that library directory to your \code{PYTHONPATH} before starting +WebKit.) + +% @@MO Examples: simple, IronSite, SkeletonPage. + +Section \ref{libraries.templates.skeletonPage} contains information on a stock +template that simplifies defining the basic HTML structure of your web +page templates. + +In the Containment approach, your hierarchy of servlets are not templates, but +each uses one or more templates as it wishes. Children provide callback +methods to to produce the various portions of the page that are their +responsibility, and parents call those methods. Webware's \code{WebKit.Page} +and \code{WebKit.SidebarPage} classes operate like this. + +% @@MO Show examples of WebKit.Page and WebKit.SidebarPage. + +Note that the two approaches are not compatible! \code{WebKit.Page} was not +designed to intermix with \code{Cheetah.Templates.SkeletonPage}. Choose either +one or the other, or expect to do some integration work. + +If you come up with a different strategy you think is worth noting in this +chapter, let us know. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Directory structure} +\label{webware.directoryStructure} + +Here's one way to organize your files for Webware+Cheetah. + +\begin{verbatim} +www/ # Web root directory. + site1.example.com/ # Site subdirectory. + apache/ # Web server document root (for non-servlets). + www/ # WebKit document root. + index.py # http://site1.example.com/ + index.tmpl # Source for above. + servlet2.py # http://site1.example.com/servlet2 + servlet2.tmpl # Source for above. + lib/ # Directory for helper classes. + Site.py # Site superclass ("#extends Site"). + Site.tmpl # Source for above. + Logic.py # Logic class inherited by some template. + webkit.config # Configuration file (for WebwareExperimental). + Webware/ # Standard Webware's MakeAppWorkDir directory. + AppServer # Startup program (for standard Webware). + Configs/ # Configuration directory (for standard Webware). + Application.config + # Configuration file (for standard Webware). + site2.example.org/ # Another virtual host on this computer.... +\end{verbatim} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Initializing your template-servlet with Python code} +\label{webware.calculations} + +If you need a place to initialize variables or do calculations for your +template-servlet, you can put it in an \code{.awake()} method because WebKit +automatically calls that early when processing the web transaction. If you +do override \code{.awake()}, be sure to call the superclass \code{.awake} +method. You probably want to do that first so that you have access to the +web transaction data \code{Servlet.awake} provides. You don't have to worry +about whether your parent class has its own \code{.awake} method, just call +it anyway, and somebody up the inheritance chain will respond, or at minimum +\code{Servlet.awake} will respond. Section +\ref{tips.callingSuperclassMethods} gives examples of how to call a +superclass method. + +As an alternative, you can put all your calculations in your own method and +call it near the top of your template. (\code{\#silent}, section +\ref{output.silent}). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Form processing} +\label{webware.form} + +There are many ways to display and process HTML forms with Cheetah. +But basically, all form processing involves two steps. +\begin{enumerate} +\item{} Display the form. +\item{} In the next web request, read the parameters the user submitted, +check for user errors, perform any side effects (e.g., reading/writing a +database or session data) and present the user an HTML response or another +form. +\end{enumerate} + +The second step may involve choosing between several templates to fill (or +several servlets to redirect to), or a big if-elif-elif-else construct to +display a different portion of the template depending on the situation. + +In the oldest web applications, step 1 and step 2 were handled by separate +objects. Step 1 was a static HTML file, and step 2 was a CGI script. +Frequently, a better strategy is to have a single servlet handle both steps. +That way, the servlet has better control over the entire situation, and if +the user submits unacceptable data, the servlet can redisplay the form with a +"try again" error message at the top and and all the previous input filled in. +The servlet can use the presence or absence of certain CGI parameters (e.g., +the submit button, or a hidden mode field) to determine which step to take. + +One neat way to build a servlet that can handle both the form displaying and +form processing is like this: + +\begin{enumerate} +\item Put your form HTML into an ordinary template-servlet. In each input + field, use a placeholder for the value of the \code{VALUE=} attribue. + Place another placeholder next to each field, for that field's error + message. +\item Above the form, put a \code{\$processFormData} method call. +\item Define that method in a Python class your template \code{\#extend}s. (Or + if it's a simple method, you can define it in a \code{\#def}.) The method + should: + \begin{enumerate} + \item Get the form input if any. + \item If the input variable corresponding to the submit field is empty, + there is no form input, so we're showing the form for the first time. + Initialize all VALUE= variables to their default value (usually ""), + and all error variables to "". Return "", which will be the value for + \code{\$processFormData}. + \item If the submit variable is not empty, fill the VALUE= variables with + the input data the user just submitted. + \item Now check the input for errors and put error messages in the error + placeholders. + \item If there were any user errors, return a general error message + string; this will be the value for \code{\$processFormData}. + \item If there were no errors, do whatever the form's job is (e.g., update + a database) and return a success message; this will be the value for + \code{\$processFormData}. + \end{enumerate} +\item The top of the page will show your success/failure message (or nothing +the first time around), with the form below. If there are errors, the user +will have a chance to correct them. After a successful submit, the form will +appear again, so the user can either review their entry, or change it and +submit it again. Depending on the application, this may make the servlet +update the same database record again, or it may generate a new record. +\end{enumerate} + +% @@MO: Example of a template that shows a form and then processes the input. + +\code{FunFormKit} is a third-party Webware package that makes it easier to +produce forms and handle their logic. It has been successfully been used with +Cheetah. You can download FunFormKit from +\url{http://colorstudy.net/software/funformkit/} and try it out for yourself. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Form input, cookies, session variables and web server variables} +\label{webware.input} + +General variable tips that also apply to servlets are in section +\ref{tips.placeholder}. + +To look up a CGI GET or POST parameter (with POST overriding): +\begin{verbatim} +$request.field('myField') +self.request().field('myField') +\end{verbatim} +These will fail if Webware is not available, because \code{\$request} +(aka \code{self.request()} will be \code{None} rather than a Webware +\code{WebKit.Request} object. If you plan to read a lot of CGI parameters, +you may want to put the \code{.fields} method into a local variable for +convenience: +\begin{verbatim} +#set $fields = $request.fields +$fields.myField +\end{verbatim} +But remember to do complicated calculations in Python, and assign the results +to simple variables in the searchList for display. These \code{\$request} +forms are useful only for occasions where you just need one or two simple +request items that going to Python for would be overkill. + +To get a cookie or session parameter, subsitute ``cookie'' or ``session'' for +``field'' above. To get a dictionary of all CGI parameters, substitute +``fields'' (ditto for ``cookies''). To verify a field exists, +substitute ``hasField'' (ditto for ``hasCookie''). + +Other useful request goodies: +\begin{verbatim} +## Defined in WebKit.Request +$request.field('myField', 'default value') +$request.time ## Time this request began in Unix ticks. +$request.timeStamp ## Time in human-readable format ('asctime' format). +## Defined in WebKit.HTTPRequest +$request.hasField.myField ## Is a CGI parameter defined? +$request.fields ## Dictionary of all CGI parameters. +$request.cookie.myCookie ## A cookie parameter (also .hasCookie, .cookies). +$request.value.myValue ## A field or cookie variable (field overrides) + ## (also .hasValue). +$request.session.mySessionVar # A session variable. +$request.extraURLPath ## URL path components to right of servlet, if any. +$request.serverDictionary ## Dict of environmental vars from web server. +$request.remoteUser ## Authenticated username. HTTPRequest.py source + ## suggests this is broken and always returns None. +$request.remoteAddress ## User's IP address (string). +$request.remoteName ## User's domain name, or IP address if none. +$request.urlPath ## URI of this servlet. +$request.urlPathDir ## URI of the directory containing this servlet. +$request.serverSidePath ## Absolute path of this servlet on local filesystem. +$request.serverURL ## URL of this servlet, without "http://" prefix, + ## extra path info or query string. +$request.serverURLDir ## URL of this servlet's directory, without "http://". +$log("message") ## Put a message in the Webware server log. (If you + ## define your own 'log' variable, it will override + ## this; use $self.log("message") in that case. +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{.webInput()} +\label{webware.webInput} + +From the method docstring: + +\begin{verbatim} + def webInput(self, names, namesMulti=(), default='', src='f', + defaultInt=0, defaultFloat=0.00, badInt=0, badFloat=0.00, debug=False): + +This method places the specified GET/POST fields, cookies or session variables +into a dictionary, which is both returned and put at the beginning of the +searchList. It handles: + * single vs multiple values + * conversion to integer or float for specified names + * default values/exceptions for missing or bad values + * printing a snapshot of all values retrieved for debugging +All the 'default*' and 'bad*' arguments have "use or raise" behavior, meaning +that if they're a subclass of Exception, they're raised. If they're anything +else, that value is substituted for the missing/bad value. + +The simplest usage is: + + #silent $webInput(['choice']) + $choice + + dic = self.webInput(['choice']) + write(dic['choice']) + +Both these examples retrieves the GET/POST field 'choice' and print it. If you +leave off the "#silent", all the values would be printed too. But a better way +to preview the values is + + #silent $webInput(['name'], $debug=1) + +because this pretty-prints all the values inside HTML <PRE> tags. + +Since we didn't specify any coversions, the value is a string. It's a "single" +value because we specified it in 'names' rather than 'namesMulti'. Single +values work like this: + * If one value is found, take it. + * If several values are found, choose one arbitrarily and ignore the rest. + * If no values are found, use or raise the appropriate 'default*' value. + +Multi values work like this: + * If one value is found, put it in a list. + * If several values are found, leave them in a list. + * If no values are found, use the empty list ([]). The 'default*' + arguments are *not* consulted in this case. + +Example: assume 'days' came from a set of checkboxes or a multiple combo box +on a form, and the user chose "Monday", "Tuesday" and "Thursday". + + #silent $webInput([], ['days']) + The days you chose are: #slurp + #for $day in $days + $day #slurp + #end for + + dic = self.webInput([], ['days']) + write("The days you chose are: ") + for day in dic['days']: + write(day + " ") + +Both these examples print: "The days you chose are: Monday Tuesday Thursday". + +By default, missing strings are replaced by "" and missing/bad numbers by zero. +(A "bad number" means the converter raised an exception for it, usually because +of non-numeric characters in the value.) This mimics Perl/PHP behavior, and +simplifies coding for many applications where missing/bad values *should* be +blank/zero. In those relatively few cases where you must distinguish between +""/zero on the one hand and missing/bad on the other, change the appropriate +'default*' and 'bad*' arguments to something like: + * None + * another constant value + * $NonNumericInputError/self.NonNumericInputError + * $ValueError/ValueError +(NonNumericInputError is defined in this class and is useful for +distinguishing between bad input vs a TypeError/ValueError +thrown for some other reason.) + +Here's an example using multiple values to schedule newspaper deliveries. +'checkboxes' comes from a form with checkboxes for all the days of the week. +The days the user previously chose are preselected. The user checks/unchecks +boxes as desired and presses Submit. The value of 'checkboxes' is a list of +checkboxes that were checked when Submit was pressed. Our task now is to +turn on the days the user checked, turn off the days he unchecked, and leave +on or off the days he didn't change. + + dic = self.webInput([], ['dayCheckboxes']) + wantedDays = dic['dayCheckboxes'] # The days the user checked. + for day, on in self.getAllValues(): + if not on and wantedDays.has_key(day): + self.TurnOn(day) + # ... Set a flag or insert a database record ... + elif on and not wantedDays.has_key(day): + self.TurnOff(day) + # ... Unset a flag or delete a database record ... + +'source' allows you to look up the variables from a number of different +sources: + 'f' fields (CGI GET/POST parameters) + 'c' cookies + 's' session variables + 'v' "values", meaning fields or cookies + +In many forms, you're dealing only with strings, which is why the +'default' argument is third and the numeric arguments are banished to +the end. But sometimes you want automatic number conversion, so that +you can do numeric comparisons in your templates without having to +write a bunch of conversion/exception handling code. Example: + + #silent $webInput(['name', 'height:int']) + $name is $height cm tall. + #if $height >= 300 + Wow, you're tall! + #else + Pshaw, you're short. + #end if + + dic = self.webInput(['name', 'height:int']) + name = dic[name] + height = dic[height] + write("%s is %s cm tall." % (name, height)) + if height > 300: + write("Wow, you're tall!") + else: + write("Pshaw, you're short.") + +To convert a value to a number, suffix ":int" or ":float" to the name. The +method will search first for a "height:int" variable and then for a "height" +variable. (It will be called "height" in the final dictionary.) If a numeric +conversion fails, use or raise 'badInt' or 'badFloat'. Missing values work +the same way as for strings, except the default is 'defaultInt' or +'defaultFloat' instead of 'default'. + +If a name represents an uploaded file, the entire file will be read into +memory. For more sophisticated file-upload handling, leave that name out of +the list and do your own handling, or wait for Cheetah.Utils.UploadFileMixin. + +This mixin class works only in a subclass that also inherits from +Webware's Servlet or HTTPServlet. Otherwise you'll get an AttributeError +on 'self.request'. + +EXCEPTIONS: ValueError if 'source' is not one of the stated characters. +TypeError if a conversion suffix is not ":int" or ":float". +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{More examples} +\label{webware.examples} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Example A -- a standalone servlet} +%\label{} + +% @@MO: + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Example B -- a servlet under a site framework} +%\label{} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Example C -- several servlets with a common template} +%\label{} + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Other Tips} +\label{webware.otherTips} + +If your servlet accesses external files (e.g., via an \code{\#include} +directive), remember that the current directory is not necessarily directory +the servlet is in. It's probably some other directory WebKit chose. To find a +file relative to the servlet's directory, prefix the path with whatever +\code{self.serverSidePath()} returns (from \code{Servlet.serverSidePath()}. + +If you don't understand how \code{\#extends} and \code{\#implements} work, and +about a template's main method, read the chapter on inheritance (sections +\ref{inheritanceEtc.extends} and \ref{inheritanceEtc.implements}). This may +help you avoid buggy servlets. + +% Local Variables: +% TeX-master: "users_guide" +% End: +%# vim: sw=4 ts=4 expandtab |