diff options
Diffstat (limited to 'docs/users_guide_src')
25 files changed, 0 insertions, 6144 deletions
diff --git a/docs/users_guide_src/Makefile b/docs/users_guide_src/Makefile deleted file mode 100755 index 8b8e977..0000000 --- a/docs/users_guide_src/Makefile +++ /dev/null @@ -1,39 +0,0 @@ -# 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 deleted file mode 100755 index 3b45564..0000000 --- a/docs/users_guide_src/README +++ /dev/null @@ -1,9 +0,0 @@ -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 deleted file mode 100755 index 36323cf..0000000 --- a/docs/users_guide_src/comments.tex +++ /dev/null @@ -1,99 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index 56a0fb3..0000000 --- a/docs/users_guide_src/comparisons.tex +++ /dev/null @@ -1,451 +0,0 @@ -\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 deleted file mode 100755 index 84c8f03..0000000 --- a/docs/users_guide_src/editors.tex +++ /dev/null @@ -1,39 +0,0 @@ -\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 deleted file mode 100755 index 28eee3a..0000000 --- a/docs/users_guide_src/errorHandling.tex +++ /dev/null @@ -1,145 +0,0 @@ -\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 deleted file mode 100755 index 6c394fb..0000000 --- a/docs/users_guide_src/examples.tex +++ /dev/null @@ -1,24 +0,0 @@ -\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 deleted file mode 100755 index 75a5845..0000000 --- a/docs/users_guide_src/flowControl.tex +++ /dev/null @@ -1,414 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index 69a3136..0000000 --- a/docs/users_guide_src/gettingStarted.tex +++ /dev/null @@ -1,266 +0,0 @@ -\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 deleted file mode 100644 index 4ee2d9b..0000000 --- a/docs/users_guide_src/glossary.tex +++ /dev/null @@ -1,96 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index 4efa22f..0000000 --- a/docs/users_guide_src/howItWorks.tex +++ /dev/null @@ -1,420 +0,0 @@ -\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 deleted file mode 100755 index 019b042..0000000 --- a/docs/users_guide_src/inheritanceEtc.tex +++ /dev/null @@ -1,492 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index be34fc6..0000000 --- a/docs/users_guide_src/introduction.tex +++ /dev/null @@ -1,392 +0,0 @@ -\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 deleted file mode 100755 index 673abca..0000000 --- a/docs/users_guide_src/language.tex +++ /dev/null @@ -1,651 +0,0 @@ -\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 deleted file mode 100755 index dc9231a..0000000 --- a/docs/users_guide_src/libraries.tex +++ /dev/null @@ -1,306 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index 1ec2f6c..0000000 --- a/docs/users_guide_src/links.tex +++ /dev/null @@ -1,112 +0,0 @@ -\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 deleted file mode 100755 index 92e34bb..0000000 --- a/docs/users_guide_src/moreverb.sty +++ /dev/null @@ -1,197 +0,0 @@ -%%% 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 deleted file mode 100755 index b618ab0..0000000 --- a/docs/users_guide_src/nonHtml.tex +++ /dev/null @@ -1,17 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index db63682..0000000 --- a/docs/users_guide_src/optikLicense.tex +++ /dev/null @@ -1,43 +0,0 @@ -\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 deleted file mode 100755 index 89fd58a..0000000 --- a/docs/users_guide_src/otherHtml.tex +++ /dev/null @@ -1,95 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index 742291e..0000000 --- a/docs/users_guide_src/output.tex +++ /dev/null @@ -1,548 +0,0 @@ -\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 deleted file mode 100755 index bfd6bc2..0000000 --- a/docs/users_guide_src/parserInstructions.tex +++ /dev/null @@ -1,116 +0,0 @@ -\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 deleted file mode 100755 index 8a16fb4..0000000 --- a/docs/users_guide_src/tipsAndTricks.tex +++ /dev/null @@ -1,544 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 deleted file mode 100755 index 74949cf..0000000 --- a/docs/users_guide_src/users_guide.tex +++ /dev/null @@ -1,54 +0,0 @@ - -\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 deleted file mode 100755 index a5702d8..0000000 --- a/docs/users_guide_src/webware.tex +++ /dev/null @@ -1,575 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 |