diff options
| author | tavis_rudd <tavis_rudd> | 2001-10-10 06:59:45 +0000 |
|---|---|---|
| committer | tavis_rudd <tavis_rudd> | 2001-10-10 06:59:45 +0000 |
| commit | c7d48b5be6d3fefb089fb7b5bfa1942ad136dbf3 (patch) | |
| tree | 1c5eceda36902cdf2a7008af52f47fcf3ad9db89 | |
| parent | bf8408daf1f1a27e0f8bd69eb2acaa8d6e1eb01d (diff) | |
| download | python-cheetah-c7d48b5be6d3fefb089fb7b5bfa1942ad136dbf3.tar.gz | |
further merges of the DEVEL_BRANCH code
| -rw-r--r-- | CHANGES | 26 | ||||
| -rw-r--r-- | LICENSE | 16 | ||||
| -rw-r--r-- | MANIFEST.in | 2 | ||||
| -rw-r--r-- | SetupConfig.py | 37 | ||||
| -rw-r--r-- | SetupTools.py | 305 | ||||
| -rw-r--r-- | TODO | 22 | ||||
| -rw-r--r-- | bin/cheetah-compile | 6 | ||||
| -rw-r--r-- | docs/devel/safeDelegation.txt | 38 | ||||
| -rw-r--r-- | docs/src/Makefile | 36 | ||||
| -rw-r--r-- | docs/src/README | 9 | ||||
| -rw-r--r-- | docs/src/TDL.tex | 402 | ||||
| -rw-r--r-- | docs/src/comparisons.tex | 268 | ||||
| -rw-r--r-- | docs/src/customizing.tex | 250 | ||||
| -rw-r--r-- | docs/src/developer.tex | 91 | ||||
| -rw-r--r-- | docs/src/directives.tex | 775 | ||||
| -rw-r--r-- | docs/src/errorMessages.tex | 10 | ||||
| -rw-r--r-- | docs/src/examples.tex | 29 | ||||
| -rw-r--r-- | docs/src/gettingStarted.tex | 121 | ||||
| -rw-r--r-- | docs/src/gfdl.tex | 367 | ||||
| -rw-r--r-- | docs/src/glossary.tex | 49 | ||||
| -rw-r--r-- | docs/src/introduction.tex | 280 | ||||
| -rw-r--r-- | docs/src/libraries.tex | 242 | ||||
| -rw-r--r-- | docs/src/links.tex | 114 | ||||
| -rwxr-xr-x | docs/src/moreverb.sty | 197 | ||||
| -rw-r--r-- | docs/src/puttingItTogether.tex | 175 | ||||
| -rw-r--r-- | docs/src/tipsAndTricks.tex | 10 | ||||
| -rw-r--r-- | docs/src/webware.tex | 244 | ||||
| -rwxr-xr-x | setup.py | 109 |
28 files changed, 394 insertions, 3836 deletions
@@ -1,5 +1,31 @@ Please initial your changes and add a date for each release ================================================================================ +0.9.9a1 (October 9, 2001) [many changes and bug-fixes] + - a complete reimplementation of Cheetah's core (the parser and compiler + classes) (TR + IB) + + - implemented the #def, #implements, #import, and #from directives + + removed #redefine and #macros + + renamed #extend as #extends (TR + IB) + + - replaced #data with #settings, see the docs (TR) + + - restructured and updated the docs (TR + MO + IB) + + - reimplemented the cheetah-compile script, without the -g option that Ian + had added (TR) + + - changed the signature of Template.__init__. See the docs. (TR) + + - made #set distinguish between local and global vars. See the docs. (TR) + + - added a hundreds of new test cases (TR) + + - started restructuring the SkeletonPage framework [not complete yet] (TR) + + - added the #breakpoint and #compiler-settings directives (TR) + + 0.9.8 (October 9, 2001) - added a few new language constructs (aka 'directives') to Cheetah (TR) @@ -0,0 +1,16 @@ +Copyright 2001, The Cheetah Development Team: Tavis Rudd, Mike Orr, +Chuck Esterbrook, Ian Bicking. + +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. diff --git a/MANIFEST.in b/MANIFEST.in index 620b975..356d255 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include *.py TODO CHANGES README examples third_party_packages docs +include *.py TODO CHANGES LICENSE README examples third_party_packages docs recursive-include bin * recursive-include docs * recursive-include PlateKit *.py diff --git a/SetupConfig.py b/SetupConfig.py new file mode 100644 index 0000000..a5c7bbe --- /dev/null +++ b/SetupConfig.py @@ -0,0 +1,37 @@ +#-------Main Package Settings-----------# +name = "Cheetah" +from src.Version import version +maintainer = "Tavis Rudd" +author = "The Cheetah Development Team" +author_email = "cheetahtemplate-discuss@lists.sf.net" +url = "http://www.CheetahTemplate.org/" +packages = ['Cheetah', + 'Cheetah.Templates', + 'Cheetah.Tests', + 'Cheetah.Tools', + ] + +package_dir = {'Cheetah':'src'} + +import os +from distutils.core import Extension +if os.name == 'posix': + ext_modules=[Extension("Cheetah/_namemapper", ["src/_namemapper.c"])] +else: + ext_modules=[] + + +## Data Files and Scripts +scripts = ['bin/cheetah-compile', + ] +data_files = ['recursive: src *.tmpl *.txt LICENSE README', + ] + +## GET THE DESCRIPTION AND CREATE THE README +from src import __doc__ +README = open('README','w') +README.write(__doc__) +README.close() + +description = __doc__.split('\n')[0] +long_description = __doc__ diff --git a/SetupTools.py b/SetupTools.py new file mode 100644 index 0000000..65afbd3 --- /dev/null +++ b/SetupTools.py @@ -0,0 +1,305 @@ +#!/usr/bin/env python +# $Id: SetupTools.py,v 1.2 2001/10/10 06:59:45 tavis_rudd Exp $ +"""Some tools for extending and working with distutils + +CREDITS: This module borrows code and ideas from M.A. Lemburg's excellent setup +tools for the mxBase package. + +""" + +__author__ = "Tavis Rudd <tavis@calrudd.com>" +__version__ = "$Revision: 1.2 $"[11:-2] + + +################################################## +## GLOBALS AND CONSTANTS ## + +True = (1==1) +False = (1==0) + +################################################## +## DEPENDENCIES ## + +from distutils.core import setup +from distutils.core import Command +from distutils.command.install_data import install_data +from distutils.command.sdist import sdist + +import os +from os import listdir +import os.path +from os.path import exists, isdir, isfile, join, splitext + +import types +import glob +import string + +#imports from Cheetah ... +from src.FileUtils import findFiles + +################################################## +## CLASSES ## + +class mod_install_data(install_data): + + """A copy of M.A Lemburg's modified version of the disutils install_data + command that allows data files to be included directly in the installed + Python package tree. + + Note that it expects that data_files argument to the disutils.setup() + commmand to be a list of strings rather than a list of tuples as is the + default. Each of these string entries can be a real file name or a glob + pattern representing the files to match.""" + + def finalize_options(self): + + if self.install_dir is None: + installobj = self.distribution.get_command_obj('install') + self.install_dir = installobj.install_platlib + install_data.finalize_options(self) + + def run (self): + + if not self.dry_run: + self.mkpath(self.install_dir) + data_files = self.get_inputs() + + for entry in data_files: + if type(entry) != types.StringType: + raise ValueError, 'The entries in "data_files" must be strings' + + entry = string.join(string.split(entry, '/'), os.sep) + # entry is a filename or glob pattern + if entry.startswith('recursive:'): + entry = entry[len('recursive:'):] + dir = entry.split()[0] + globPatterns = entry.split()[1:] + filenames = findFiles(dir, globPatterns) + else: + filenames = glob.glob(entry) + + for filename in filenames: + ## generate the dstPath from the filename + # - deal with 'package_dir' translations + topDir, subPath = (filename.split(os.sep)[0], + os.sep.join( filename.split(os.sep)[1:] ) + ) + + package_dirDict = self.distribution.package_dir + if package_dirDict: + packageDir = topDir + for key, val in package_dirDict.items(): + if val == topDir: + packageDir = key + break + else: + packageDir = topDir + dstPath = os.path.join(self.install_dir, packageDir, subPath) + + ## add the file to the list of outfiles + dstdir = os.path.split(dstPath)[0] + if not self.dry_run: + self.mkpath(dstdir) + outfile = self.copy_file(filename, dstPath)[0] + else: + outfile = dstPath + self.outfiles.append(outfile) + + +class contrib(Command): + """a setup command that will process the contributed packages. + + USAGE: setup.py contrib install + or + setup.py contrib sdist + etc. + """ + description = "" + + # List of option tuples: long name, short name (None if no short + # name), and help string. + user_options = [ ('cmd=', None, + "The command to run on each of the contrib packages"), + ('contrib_dir=', None, + "The directory which contains all of the contrib packages"), + ('contrib_packages=', None, + "A whitespace separated list of contrib package subdirs"), + + ] + + def initialize_options (self): + self.cmd = 'install' + + def finalize_options (self): + pass + + def run(self): + cwd = os.getcwd() + for p in self.contrib_packages.split(): + d = os.path.join(cwd, self.contrib_dir, p) + os.chdir(d) + print "Working on", d, "(", os.getcwd(), ")" + try: + os.system(sys.executable+' setup.py '+ self.cmd) + except: + print "An error occurred while installing the contributed packages." + #os.chdir(cwd) + raise + + +class sdist_docs(sdist): + + """A setup command that will rebuild Users Guide at the same time as + creating a source distribution. + + It relies on the main tex-file being called users_guide.tex and the tex file + being in a form that Python's mkhowto script accepts.""" + + def run(self): + try: + from main_package.Version import version + + currentDir = os.getcwd() + os.chdir(os.path.join(currentDir,'docs','src')) + fp = open('users_guide.tex','r') + originalTexCode = fp.read() + fp.close() + + newTexCode = re.sub(r'(?<=\\release\{)[0-9\.a-zA-Z]*',str(version), originalTexCode) + + fp = open('users_guide.tex','w') + fp.write(newTexCode) + fp.close() + + os.system('make -f Makefile') + os.chdir(currentDir) + except: + print "The sdist_docs command couldn't rebuild the Users Guide" + os.chdir(currentDir) + + sdist.run(self) + + +class uninstall(Command): + + description = "uninstall the package files and directories" + + user_options = [] + + def initialize_options(self): + pass + + def finalize_options(self): + pass + + def run(self): + + # Execute build + self.announce('determining installation files') + self.announce('(re)building package') + savevalue = self.distribution.dry_run + self.distribution.dry_run = 0 + self.run_command('build') + + # Execute install in dry-run mode + self.announce('dry-run package install') + self.distribution.dry_run = 1 + self.run_command('install') + self.distribution.dry_run = savevalue + build = self.get_finalized_command('build') + install = self.get_finalized_command('install') + + # Remove all installed files + self.announce("removing files") + dirs = {} + filenames = install.get_outputs() + for filename in filenames: + if not os.path.isabs(filename): + raise DistutilsError,\ + 'filename %s from .get_output() not absolute' % \ + filename + + if os.path.isfile(filename): + self.announce("removing %s" % filename) + if not self.dry_run: + try: + os.remove(filename) + except OSError, details: + self.warn("Could not remove file: %s" % details) + dir = os.path.split(filename)[0] + if not dirs.has_key(dir): + dirs[dir] = 1 + if os.path.splitext(filename)[1] == '.py': + # Remove byte-code files as well + try: + os.remove(filename + 'c') + except OSError: + pass + try: + os.remove(filename + 'o') + except OSError: + pass + + elif os.path.isdir(filename): + # This functionality is currently not being used by distutils + if not dirs.has_key(dir): + dirs[filename] = 1 + + elif not os.path.splitext(filename)[1] in ('.pyo', '.pyc'): + self.announce("skipping removal of %s (not found)" % + filename) + + # Remove the installation directories + self.announce("removing directories") + dirs = dirs.keys() + dirs.sort(); dirs.reverse() # sort descending + for dir in dirs: + self.announce("removing directory %s" % dir) + if not self.dry_run: + try: + os.rmdir(dir) + except OSError, details: + self.warn("could not remove directory: %s" % details) + + +################################################## +## FUNCTIONS ## + +def run_setup(configurations): + + """ Run distutils setup. + + The parameters passed to setup() are extracted from the list of modules, + classes or instances given in configurations. + + Names with leading underscore are removed from the parameters. + Parameters which are not strings, lists, tuples, or dicts are removed as + well. Configurations which occur later in the configurations list + override settings of configurations earlier in the list. + + """ + # Build parameter dictionary + kws = {} + for configuration in configurations: + kws.update(vars(configuration)) + for name, value in kws.items(): + if name[:1] == '_' or \ + type(value) not in (types.StringType, + types.ListType, + types.TupleType, + types.DictType, + ): + del kws[name] + + # Add setup extensions + cmdclasses = {'install_data': mod_install_data, + 'uninstall':uninstall, + 'contrib':contrib, + 'sdist_docs':sdist_docs, + } + + kws['cmdclass'] = cmdclasses + + # Invoke distutils setup + apply(setup, (), kws) + @@ -9,41 +9,22 @@ Cheetah TODO list Languague Specification ================================================================================ -- come to a decision on the syntax and semantics of the #block, #redefine and - #data directives. There was discussion on the list of making a #define - directive that encapsulated all of this. See the archives for the end of Aug. - -- firm up the autocalling and Unified Dotted Notation syntax rules - +- finish the #cache directive's varyBy keyword Implementation ================================================================================ -- make it possible to compile Cheetah directly into a Python module / class that - doesn't need to do any Cheetah parsing when it is initialized. This is - related to Ian and Mike's ideas for #define. One option is to generalize the - parsing/compiling infrastructure rework the ._codeGenerator() method so that - it can be used to generate code for any method of the Template object, rather - than just for the .respond() method. When compiling the .respond() method any - other methods that need to be compiled would be added to a stack that would be - processed and compiled one at a time. - - redesign and implement the Servlet Factory for Webware so the #extend directive will work with .tmpl files as well as .py files Test Suite ================================================================================ -- create the non-syntax related test cases - write script that will run the test cases with both Python 2.0 and 2.1 -- independent suite of test cases for NameMapper -- test cases for the PSP plugin - test cases for the SkeletonPage framework Documentation ================================================================================ - finish up the Webware section -- finish documenting the Formatters and ErrorChecker frameworks -- add examples to the Examples section Website ================================================================================ @@ -60,3 +41,4 @@ Packaging - Consider moving SettingsManager.py and NameMapper.py into the third_party_packages dir and making setup_all.py the main install script + diff --git a/bin/cheetah-compile b/bin/cheetah-compile index 164ce49..7f5eb28 100644 --- a/bin/cheetah-compile +++ b/bin/cheetah-compile @@ -1,5 +1,3 @@ #! /usr/bin/env python - -from Cheetah.Compiler import MainProgram - -MainProgram().run()
\ No newline at end of file +from Cheetah.CheetahCompile import CheetahCompile +CheetahCompile().run()
\ No newline at end of file diff --git a/docs/devel/safeDelegation.txt b/docs/devel/safeDelegation.txt deleted file mode 100644 index 0dcc776..0000000 --- a/docs/devel/safeDelegation.txt +++ /dev/null @@ -1,38 +0,0 @@ -SAFE DELEGATION - -"Safe delegation, as provided by Zope and Allaire's Spectra, is not implemented -in Cheetah. The core aim has been to help developers and template maintainers -get things done, without throwing unnecessary complications in their -way. So you should give write access to your templates only to those whom you -trust. However, several hooks have been built into Cheetah so that safe -delegation can be implemented at a later date. - -It should be possible to implement safe delegation via a future configuration -Setting \code{safeDelegationLevel} (0=none, 1=semi-secure, 2-alcatraz). This -is not implemented but the steps are listed here in case somebody wants to try -them out and test them. - -Of course, you would also need to benchmark your code -and verify it does not impact performance when safe delegation is off, and -impacts it only modestly when it is on." All necessary changes can be made -at compile time, so there should be no performance impact when filling the -same TO multiple times. - -\begin{enumerate} - -\item Only give untrusted developers access to the .tmpl files. -(Verifying what this means. Why can't trusted developers access them?) - -\item Disable the \code{#data} directive and maybe the \code{#set} directive. - -\item Use Cheetah's directive validation hooks to disallow -references to \code{self}, etc -(e.g. \code{#if $steal(self.thePrivateVar)} ) - -\item Implement a validator for the $\placeholders and use it -to disallow '\_\_' in \$placeholders so that tricks like -\code{\$obj.\_\_class\_\_.\_\_dict\_\_} are not possible. - -\end{enumerate} - - diff --git a/docs/src/Makefile b/docs/src/Makefile deleted file mode 100644 index 4df4eab..0000000 --- a/docs/src/Makefile +++ /dev/null @@ -1,36 +0,0 @@ -# You must change PYTHONSRC to the path of your Python source distributon. -PYTHONSRC=/home/tavis/tmp/Python-2.1 -DOCNAME=users_guide -MKHOWTO=$(PYTHONSRC)/Doc/tools/mkhowto -MAIN_TEX_FILE= users_guide.tex - -all: ps pdf 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 -R ../$(DOCNAME)_html - mv $(DOCNAME) ../$(DOCNAME)_html - -htmlMultiPage: - -rm -rf $(DOCNAME) - $(MKHOWTO) --html --iconserver . $(MAIN_TEX_FILE) - -rm -R ../$(DOCNAME)_html_multipage - mv $(DOCNAME) ../$(DOCNAME)_html_multipage - -text: - $(MKHOWTO) --text $(MAIN_TEX_FILE) - mv $(DOCNAME).txt ../ - -clean: - -rm -rf $(DOCNAME) - -rm *.aux *.l2h *~ *.log *.ind *.bkm *.how *.toc - -rm -rf ../html - diff --git a/docs/src/README b/docs/src/README deleted file mode 100644 index 3b45564..0000000 --- a/docs/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/src/TDL.tex b/docs/src/TDL.tex deleted file mode 100644 index d87fca0..0000000 --- a/docs/src/TDL.tex +++ /dev/null @@ -1,402 +0,0 @@ -\section{The Template Definition Language} -\label{TDL} - -{\bf Template definitions} are text strings, or files, that have been marked up -with Cheetah's {\bf Template Definition Language} for special processing. This -language is not a general purpose programming language like Python. Rather, -it's a mini-language that was designed to make HTML-generation, and -code-generation in general, easy enough for non-programmers to understand and -programmers to love. It is purposefully limited and leaves complex tasks to -Python, where they belong. - -Cheetah does not use HTML/XML style tags as they are hard to distinguish from -real HTML tags and are not be visible in rendered HTML when something goes -wrong. - -Cheetah's Template Definition Language has 2 primary types of tags: {\bf - placeholders} and {\bf directives}. Placeholder tags begin with a dollar sign -(\code{\$varName}) and are replaced with the value of the variable they refer to -when the template is filled. Directives begin with a hash character (\#) and are -used for everything else: for loops, conditional blocks, comments, includes, and -other advanced features. The following sections deal with these tags in detail. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Placeholder Tags} -\label{TDL.placeholders} -Placeholder Tags are equivalent to data fields in a form letter, or to the -\code{\%(key)s} fields used with Python's \code{\%} operator. Here's an example: - -\begin{verbatim} -<HTML> -<HEAD><TITLE>$title</TITLE></HEAD> -<BODY> -$contents -</BODY> -</HTML> -\end{verbatim} - -When this template is filled in, \code{\$title} and \code{\$content} will be -replaced with the values for \code{title} and \code{content}. - -Although these values are strings, they could be any type. Cheetah converts all -\$placeholder values to strings via Python's \code{str()} function each time a -request is processed.\footnote{Actually, it only does this for top-level - \$placeholders that are not inside a \#directive tag or inside the argument - set of another \$placeholder.} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Rules for placeholder names} -\label{TDL.placeholders.rules} - -\begin{itemize} - -\item Placeholder names consist of one or more identifiers separated by periods. - Each identifier follows the same rules as a Python variable name or - attribute name: it must start with a letter or an underscore, and the - subsequent characters must be letters, numbers or underscores. An - identifier may be followed by argument sets enclosed in ``()'' and/or - key/subscript arguments in ``[]''. - -\item Identifiers are case-sensitive. \code{\$var} does not equal \code{\$Var} - or \code{\$vAr} or \code{\$VAR}. - -\item String literals inside argument sets must be quoted, just like in Python. - All Python quoting styles are allowed. - -\item All variable names inside argument sets should be prefixed with a \$. Use - \$func(\$var) instead of \$func(var). Python's builtin functions are an - exception to this rule. - -\item Trailing periods are ignored. Cheetah will recognize that - placeholder name in \code{\$varName.} is \code{varName} and the period will - be left alone in the filled template output. - -\item Placeholders can also be written in the form \code{\$\{placeholderName\}}. - This is useful for cases where there is no whitespace between the - placeholder and surrounding text (\code{surrounding\$\{embeddedVar\}text}). - -\item Cheetah ignores all dollar signs (\code{\$}) that are not followed by a - letter or an underscore. Dollar amounts (\code{\$2.50}) are output - literally as they should be. Cheetah also ignores any placeholder escaped - by a backslash (\code{$\backslash$\$placeholderName}). - -\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 -${*20*a.b1.c('A', 1, $federico + 1).d['-']} -$nest($nest($var)) -\end{verbatim} - -These are not valid: -\begin{verbatim} -$var@2 $^var -\end{verbatim} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Uniform Dotted Notation} -\label{TDL.placeholders.unifiedDottedNotation} - -Cheetah lets you subscript objects and dictionaries in the same way, using -dotted notation. This is far easier for non-programmers to understand and it -insulates you from changes in the API behind the template's \$placeholders. - -\$a.b.c will work with "a = \{'b':\{'c':1234\}\}" or "a = myClass(); a.b = -anotherClass()". - -\$placeholders can be written in either this syntax OR using plain old Python -syntax. You can still write \$a['b']['c'] if you want to. Furthermore, these -two syntax styles can be combined. For example, the composite placeholder -\code{\$a.b.c['d'][5:]} contains brackets for getting dictionary-keys and -list-slices. Cheetah will use translate everything upto the first bracket and -leave the rest unchanged. {\bf Also note that with the current implementation - Cheetah will only use Unified Dotted Notation up until the first set of - parentheses in a \$placeholder such as - \code{\$a.methThatReturnsAnObj(1234).c.d}. We are currently discussing - changing the behaviour.} - -To use Uniform Dotted Notation with dictionaries, the key must be a legal -identifier. That is, it must start with a letter or an underscore, and contain -only letters, digits and underscores. If your dictionary key isn't a valid -identifier you must use the \code{\$a['key 1234a*98']} syntax instead. - -Among Template-engines, Uniform Dotted Notation is unique to Cheetah. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Autocalling} -\label{TDL.placeholders.autocalling} - -Cheetah allows 'autocalling' of methods and functions embedded as -\$placeholders in the template definition. If this feature is enabled -(it is by default) then \$func and \$obj.meth will translated to \$func() and -\$obj.meth(). If the function or method require args then you still -have to do it like in Python \$func('foo', 1234) - -Only functions and methods are autocalled. Other callable types -- in -particular classes and instances -- are never autocalled. So if you want to -call a class or instance or another type, you must use ``()''. {\bf Also note - that with the current implementation, Cheetah will only use autocalling if a) - it is enabled via the Cheetah settings and b) the \$placeholder contains NO - brackets or parentheses. \code{\$a.b.c} would use autocalling, - \code{\$a.b.c['d']}, \code{\$a.b.c(15)}, and \code{\$a(16).b.c} would not. - \code{\$a(\$x.y.z).b.c} would use autocalling on \code{\$x.y.z} but not on - \code{b.c}. We are currently discussing changing the behaviour.} - -Section \ref{customizing.settings} has instructions on how turn this feature off. - -Autocalling is unique to Cheetah. It allows a team using Cheetah to make the -learning curve shorter for non-programmers and also provides a bit of insulation -between Cheetah template definitions and changes in the API of your underlying -program code. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{The searchList} -\label{TDL.placeholders.searchList} - -A {\bf namespace} is a Python dictionary that links names to values. Each -template definition that has been loaded into a \code{Template} object is -associated with an ordered list of namespaces in which values for \$placeholder -variable names can be stored. This list is called the {\bf searchList}. - -The searchList can contain one or more namespaces. In most cases only one -namespace will be in the searchList unless you explicitly load extra ones. When -Cheetah fills in \code{\$content} in previous example it searchs sequentially -through the searchList until it finds a value for \code{content}. Thus, if -three namespaces are loaded and two of them contain a value for -\code{\$content}, the value for \code{content} from the namespace that is -closest to the start of the searchList will be returned. - -If you add a Python object to the searchList, its attributes and methods will be -accessible as \$placeholder names. For example, \code{myObject} contains -\code{myAttrib} and \code{myMethod}. If \code{myObject} is added to the -searchList, \code{\$myAttrib} and \code{\$myMethod} can be used as placeholder -names. - -The default namespace in every searchList is the \code{Template} object itself. -This means that any attributes or methods that are added to classes that inherit -from \code{Template} can be accessed in templates via \code{\$placeholders}. New -namespaces can be added to the searchList at any time using the -\code{Template.addToSearchList()} method. See section \ref{webware} for more -information on how to use namespaces and the searchList. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Missing values} -\label{TDL.placeholders.missing} - -If there is no value defined in the searchList for a placeholder name, -Cheetah will search for an leading underscore version of the name. For -example, if it can't find \code{\$varName} it will attempt to find -\code{\$\_varName}. - -If all attempts to find a value fail, Cheetah inserts the placeholder tag -verbatim in the filled template output. This behaviour can be customized and a -default value set for names that are not found. See section -\ref{customizing} for more details. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Placeholder values} -\label{TDL.placeholders.values} - -Placeholder names can map to Python text strings, numbers, dictionaries, lists -(arrays), functions, objects, or even nested Cheetah templates. - -\begin{verbatim} -<HTML> -<HEAD><TITLE>$title</TITLE></HEAD> -<BODY> - -$aString ## these names are chosen to indicate what -$aNumber ## type of value they map to. They could be -$aList ## any valid placeholder name. -$aDictionary -$aFunction -$aFunction() -$aFunction(myArg=1234) -$anObject - -</BODY> -</HTML> -\end{verbatim} - -Templates can be nested. A \$placeholder may be another Template object. When -your template object is filled, the inner template object will automatically be -filled, and any template object's {\em it} contains will also be filled, ad -infinitum. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Caching} -\label{TDL.placeholders.caching} - -By default the value of each \code{\$placeholder} is updated for each request. -Cheetah can be told to cache individual \code{\$placeholders} or even entire -sections of a template definition. - -If you want to statically cache the value of a single \code{\$placeholder} upon -startup, add an asterisk after the \$ sign. \code{\$var} becomes \code{\$*var}. - -If you only need to update the value of the \code{\$placeholders} at specific -time intervals use this form: \code{\$variable} becomes \code{\$*2.5*variable} , -where 2.5 is the time interval in 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 5 minutes. - -</BODY> -</HTML> -\end{verbatim} - -To cache entire sections of a template definition use the \code{\#cache ... - \#end cache} directive tags: -\begin{verbatim} -#cache -$var ${var} -#end cache - -#cache 2.5 -$var ${var} ## These are re-cached every 2.5 minutes -#end cache -\end{verbatim} - -There is more information on the \code{\#cache} directive in section -\ref{directives.cache}. - -This simple, but powerful, caching mechanism is unique to Cheetah. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Directive tags} -\label{TDL.directives} -Directives tags are used for all functionality that cannot be handled with -simple placeholders. Section \ref{directives} provides a reference guide to the -various directives. Some directives consist of a single tag while others -consist of a pair of {\bf start} and {\bf end} tags that surround a chunk of -text. End tags are written in the form \code{\#end nameOfTheDirective}. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Escaping directives} -\label{TDL.directives.escaping} - -Directives can be escaped by placing a backslash ($\backslash$) before them. -Escaped directives will be printed verbatim. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Tag closures and whitespace handling} -\label{TDL.directives.closures} -Directive tags can closed explicitly with \code{/\#} or implicitly with the end -of the line if you're feeling lazy. - -\begin{verbatim} -#block testBlock /# -Text in the contents area of the -block directive -#end block testBlock/# -\end{verbatim} -is identical to: -\begin{verbatim} -#block testBlock -Text in the contents area 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 will be 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, which is covered in more depth in section -\ref{directives.slurp} is a dummy directive that exists only to facilitate -gobbling of whitespace. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Variables in directives} -\label{TDL.directives.variables} - -In general any variable names used inside a directive tag should be prefaced by -\$, like in this example: - -\begin{verbatim} -#for $clientName, $address in $clients.addresses() -$clientName: $address -#end for -\end{verbatim} - -There are several exceptions: - -\begin{itemize} -\item Variables declared and used inside \code{\#data} directives must not be - prefaced with \$, as the contents of this directive must be pure Python - code. - -\item If you use one of Python's builtin functions in an \code{\#if}, - \code{\#for} or \code{\#set} directive leave off the \$. - -\item Arguments to macro definitions with the \code{\#macro} directive should - have the \$ leave off for now. This might change in the future, but it - will be backwards compatible. - -\end{itemize} - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/comparisons.tex b/docs/src/comparisons.tex deleted file mode 100644 index f1a665c..0000000 --- a/docs/src/comparisons.tex +++ /dev/null @@ -1,268 +0,0 @@ -\section{Cheetah vs. [fill in the blank]} -\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{What features are unique to Cheetah} -\label{comparisons.unique} - -\begin{itemize} -\item The {\bf block framework} and everything that goes with it: \code{\#block}, - \code{\#redefine}, \code{\#extend} -\item Cheetah's powerful, yet simple, {\bf caching framework}. See - \ref{TDL.placeholders.caching} for more information. -\item Cheetah's {\bf Unified Dotted Notation} and {\bf autocalling}. See - sections \ref{TDL.placeholders.unifiedDottedNotation} and - \ref{TDL.placeholders.autocalling} for more information. -\item Cheetah's searchList. See section \ref{TDL.placeholders.searchList} for more - information. -\item Cheetah's \code{\#raw} directive. See section \ref{directives.raw} for more - information. -\item Cheetah's \code{\#slurp} directive. See section \ref{directives.slurp} for more - information. -\item Cheetah's tight integration with {\bf Webware for Python}. See section - \ref{webware} for more information. -\item Cheetah's {\bf SkeletonPage framework}. See section - \ref{webware.inheritance.skeletonPage} for more information. -\item Cheetah's ability to mix PSP style code with Cheetah Template Definition - Language syntax. See section \ref{customizing.plugins} for more - information. 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} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Cheetah vs. Velocity} -\label{comparisons.velocity} - -For a basic introduction to Velocity please visit -\url{http://jakarta.apache.org/velocity}. - - -Velocity is older, 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 cleaner, more flexible and is closer to Python's. - Here's an example -\begin{verbatim} -#for $i in range(15) -$i -#end for -\end{verbatim} - instead of -\begin{verbatim} -#foreach($i in range(15)) -$i -#end -\end{verbatim} - which means the following example is possible Cheetah, but not - Velocity: -\begin{verbatim} -#for $key, $val in $myDict -$key, $val -#end for -\end{verbatim} - - -\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 as - in this example: - -\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 'foo' object to the searchList and the 'foo' has an attribute - called 'bar' you can simply type \$bar in the template rather than \$foo.bar. - If the second item in the searchList is this dictionary {'spam':1234, - 'parrot':666} then \$spam's value will be found in the dict rather than in - the 'foo' object at the start of the searchList. - -\item Cheetah has better whitespace handling around \#directive tags -\item Cheetah has an extension to the \#macro syntax that makes it easier to call - macros that accept large strings as arguments: e.g. a macro that - pretty-prints a chunk of source code. -\item Cheetah integrates tightly with Webware. Velocity doesn't integrate as easily - with Turbine. -\item Cheetah has a plugin that enables PSP-style coding to be freely mixed in with - the Cheetah syntax. Velocity doesn't. -\item It is easy to add new \#directives to Cheetah. You can't do this easily in - Velocity. -\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 please 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 please visit -\url{http://www.zope.org/Members/michel/ZB/DTML.dtml}. - -\begin{itemize} -\item Cheetah is faster than DTML. -\item Cheetah does not use XML 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, while 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, macros, - unified dotted notation, auto-calling, searchList, \code{\#raw} directive, - \code{\#stop} 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 $objectValues('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} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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. PSP, PHP, ASP, JSP, Embperl, etc.} -\label{comparisons.pspEtc} - -[This section is under construction.] - -\begin{description} -\item[Webware's PSP Component] -- \url{http://webware.sourceforge.net/Webware/PSP/Docs/} -\item[PHP Home Page] -- \url{http://www.php.net/} -\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/src/customizing.tex b/docs/src/customizing.tex deleted file mode 100644 index 6e2c4fa..0000000 --- a/docs/src/customizing.tex +++ /dev/null @@ -1,250 +0,0 @@ -\section{Customizing and extending Cheetah} -\label{customizing} - -To extend and customize Cheetah you can create a {\bf subclass} of Template that -reimplements some of its methods, you can use {\bf settings}, or you can use -{\bf plugins}. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Subclasses of the Template class} - -This is an advanced topic that is difficult to explain without full code -examples. It's best to learn how to do this by looking at existing subclasses -of the \code{Template} class. The Cheetah.Servlet module and the -Cheetah.Templates package contain examples. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Settings} - -\code{Template} objects have a \code{\_settings} attribute. This is a dictionary of -configuration settings that control most of Cheetah's core behaviour. The -Template object's constructor method has a keyword argument 'settings' that -accepts a dictionary to override the default settings. Many of these settings -are for internal use and are of little interest to end-users. Some, however, -can be quite useful. This section explains how to use them. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Using tokens other than dollar sign and hash} - -It is possible to use any character sequence to signal the start of a -\$placeholder or \#directive. The ``\code{placeholderStartToken}'' and -``\code{directiveStartToken}'' settings control this. - -\begin{verbatim} -myTemplateDef = "Here's my @@adj template." -myNamespace = {'adj': 'silly'} -from Cheetah.Template import Template -templateObj = Template(myTemplateDef, myNamespace, - settings={'placeholderStartToken':'@@'}) -\end{verbatim} - -\code{placeholderStartToken} can be any character sequence of any length -provided that it doesn't end or start with \code{\#} as this is used by the -\#directives. You can't use a sequence of spaces as the token, although you can -have spaces mixed with other characters. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Alternate comment tokens} - -It is possible to use any character sequence to signal the start of a single -line comment and the start/end of a multiline comment. The -``\code{singleLineComment}'' and ``\code{multiLineComment}'' settings control -this. ``\code{singleLineComment}'' should be a string and -``\code{multiLineComment}'' should be a tuple of two strings. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Disabling 'auto-calling'} - -Cheetah's auto-calling behaviour (see section -\ref{TDL.placeholders.autocalling}) can be disabled via the -``\code{useAutocalling}'' setting. - -\begin{verbatim} -from Cheetah.Template import Template -templateObj = Template(myTemplateDef, myNamespace, - settings={'useAutocalling':0,}) -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Delayed Compilation} - -The \code{Cheetah.Template.Template} class usually compiles its template -definition as soon as it is initialized (e.g. \code{Template(templateDef,NS)}). -There are some situations where you may want to delay the compilation until -later. See section \ref{webware.containment.includes} for one such situation. -The ``\code{delayedCompile}'' setting and the \code{.compileTemplate()} method -are used for this purpose. - -\begin{verbatim} -from Cheetah.Template import Template -templateObj = Template(myTemplateDef, myNamespace, - settings={'delayedCompile':1,}) -... -templateObj.compile() -\end{verbatim} - -\code{Template.recompile()} is a synonym for \code{Template.compile()}. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Error checking of placeholder tags} - -[{\bf This description is a copy of an email. It will be tidied up later.}] - -I've replaced varNotFound_handler with a new feature/framework called -'errorChecker'. This is a debugging tool similar to, but more powerful than, -varNotFound_handler. Cheetah now comes with a Cheetah.ErrorCheckers module that -contains various classes. You can enable one of the classes by doing this: - -\begin{verbatim} -templObj = Template(templDef, NS, - settings={'errorChecker':NAME_OF_CLASS }) -or -templObj = Template(templDef, NS, - settings={'errorCheckerClass': CLASS }) -\end{verbatim} - -where NAME_OF_CLASS is a string referring to one of the classes in -Cheetah.ErrorCheckers. The current options are 'Echo', 'BigEcho', 'KeyError', -'ListErrors'. - -These clases can catch any exception that occurs in a \$placeholderTag, not just -NameMapper.NotFound. They don't work with \$vars inside \#directives. - -If you used 'ListErrors' you can generate a list of errors and when they -occurred: - -\begin{verbatim} -print TO.errorChecker().listErrors() -[('${aoeu}', 'Tue Aug 14 14:54:37 2001'), - ('${a4}', 'Tue Aug 14 14:54:37 2001')] -\end{verbatim} - - -[\bf The ErrorCheckers framework is intended to be used as testing and debugging -tool only. They are relatively slow and should not be used in production -systems with high loads. Furthermore, when they are used the caching framework -is disabled. See Cheetah.ErrorCheckers if you want more on the ErrorChecker API. -} - - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Output filtering} - -[{\bf This description is a copy of an email. It will be tidied up later.}] - -Cheetah now has an extended output filtering framework. It involves the -``formatter'' setting, the Cheetah.Formatters module, and the new \#formatter -directive. This framework allows you to check and re-format your \$placeholder -tag output as it is interpolated into the template output: doing such things as -replacing None with an empty string, doing string translations, truncating the -output at a max length, or even paging through the output dynamically when -Cheetah is used with Webware. - -Cheetah.Formatters contains a number of classes that are ready made formatters. -To use one do this -\begin{verbatim} -templObj = Template(templDef, NS, - settings={'formatter':NAME_OF_CLASS }) -or -templObj = Template(templDef, NS, - settings={'formatterClass': CLASS }) - -\end{verbatim} - -where NAME_OF_CLASS is a string referring to one of the classes and CLASS is a -ref to some other class that subclasses Cheetah.Formatters.BaseClass. The -current options are 'ReplaceNone' and 'MaxLen'. - -If the 'formatter' settings is None, as is the default, then the formatter is -str(). - -You can use the \#formatter directive to change the -formatter at any point in your template. Usage: - -\begin{verbatim} -#formatter None ---> set it back to str() -#formatter 'MaxLen' ---> use the class name in the quotes -#formatter $myFormatterClass ---> use this class (must be -available at compile time) -\end{verbatim} - -Formatters can accept keyword args like this (note the commas!): -\begin{verbatim} -${c, maxlen=$x, dummyKW='1234'} -${c, maxlen=7} -${*c, maxlen=7} -${*15*c, maxlen=7} -\end{verbatim} - -The first example is translated to: -\begin{verbatim} -format(valueFromSearchList(searchList, "c", 1), - dummyKW=7, trans=trans), -\end{verbatim} - -If you use keyword args then you must be using a formatter - using them with -'formatter':None will raise an exception. - -Note the 'trans' arg (aka 'transaction') that is automatically fed to the -formatter. When Cheetah is used with Webware, this will allow the formatters to -provide output paging and other interactive features, such as showing the full -output of a truncated \$placeholder (overriding the 'maxlen' arg). - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Plugins} - -Plugins are objects that are scripted to automatically configure and extend the -Template object. They are used to make it easy to complex modifications of -Cheetah's behaviour that would be awkward or too repetitive to do with {\bf - settings} alone. This section explains how to use pre-built plugins. If you -want to build your own plugin please read the documented source code in the -Cheetah.Plugins package. - -Cheetah's ``\code{plugins}'' argument setting accepts a list of plugins. To use -a plugin import its class from the module that contains it and feed -\code{Template()} a list containing an instance of the class. Here's an example: - -\begin{verbatim} -from Cheetah.Template import Template -from Cheetah.Plugins.MyPlugin import MyPlugin -... -TO = Template(templateDef, namespace, settings={'plugins':[MyPlugin(),]}) -\end{verbatim} - - -\subsubsection{The PSP plugin} -Cheetah ships with a plugin that enables pure PSP-style code to be used along -with Cheetah \$placeholders and \#directives. PSP syntax can also be used -alone without \$placeholders and \#directives. - -Here's a trivial example of how to use it: -\begin{verbatim} -from Cheetah.Template import Template -from Cheetah.Plugins.PSP import PSPplugin - -templateDef = """ -Testing Cheetah's PSP plugin: - -$testVar -<% pspVar = 'X' %> -#set $list = [1,2,3] - -#for $i in map(lambda x: x*x*x, $list) -$i -<%for j in range(15):%> <%=j*15%><%=pspVar%><%end%> -#end for -""" -print Template(templateDef, {'testVar':1234}, plugins=[PSPplugin()]) - -\end{verbatim} - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/developer.tex b/docs/src/developer.tex deleted file mode 100644 index 062ead9..0000000 --- a/docs/src/developer.tex +++ /dev/null @@ -1,91 +0,0 @@ -\section{Developers Information} -\label{developer} - -This chapter is for people on the Cheetah development team, and for those who -want the ``inside scoop'' on how Cheetah works. - -See the TODO file in the Cheetah source distribution for features we're -working on or would like to add. In the CVS version of Cheetah, the directory -docs/devel contains text files detailing possible implementation strategies. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Adding features to Cheetah} - -Whenever you add a feature to Cheetah, follow these steps: - -\begin{enumerate} - -\item Discuss its need and design on the email list and get approval. - -\item Add the feature. - -\item Write a regression test for it. Verify the test suite does not break. - -\item Add an entry to the CHANGES file explaining what you did. - -\item Remove the entry on the TODO list if present. - -\item Update the documentation. - -\item Commit it all. - -\item Notify the list and ask for people to test it. - -\end{enumerate} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Running regression tests} - -Cheetah comes with a set of regression tests to verify it's working properly. -To run the tests: - -\begin{enumerate} - -\item \code{cd} into {\bf src/Tests} in the Cheetah source distribution - or {\bf site-packages/Cheetah/Tests} in your Python library directory. - -\item Run the command: \code{python Test.py} - -\item It will run for 10-30 seconds and then print either "OK" or an error message. - -\end{enumerate} - -The test suite tries to write the file {\bf parseTest.txt} in the current -directory if it doesn't exist. You will get an IOError if you don't have write -permission. You must run the test suite once as a user with write permission -permission (e.g., root), then you'll be able to run it as any user. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Adding regression tests} - -In Tests.py, search for: "\#\#\# *** ADD NEW TYPES OF POSIX CASES -ABOVE HERE. *** \#\#\#" and add your test. \code{posixCases} is a list. Each -element is a list of three strings. The subscripts are: - -\begin{description} - -\item{[0]} A description of the test. - -\item{[1]} A small Template Definition. - -\item{[2]} The expected output. - -\end{description} - - -``Posix cases'' means tests which should work on all platforms. For -platform-specific tests, there are two other lists \code{windowsCases} and -\code{macintoshCases}. -separate lists - -Look near the top of the file for many Placeholder Names you can refer to. If -none of these are suitable, you may add additional ones. - -There is also a ``BEGIN TODO'' section for tests which have not been written -yet or cannot be performed in the current testing framework. - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/directives.tex b/docs/src/directives.tex deleted file mode 100644 index b5c1b32..0000000 --- a/docs/src/directives.tex +++ /dev/null @@ -1,775 +0,0 @@ -\section{The Directives} -\label{directives} - -This section is a reference guide for the various Cheetah \#directive tags. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Comment directives} -\label{directives.comments} - -Comment directives are used to mark notes, explanations, and decorative text -that should not appear in the output. There are two forms of the comment -directive: single-line and multi-line. - -All text in a Template Definition that lies between 2 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 2 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} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#raw} -\label{directives.raw} - -Any section of a Template Definition that is inside a \code{\#raw} ... -\code{\#end raw} tag pair will be printed verbatim without any parsing of -\$placeholders or other directives. The \code{\#raw} directive is inspired by -\LaTeX's \code{verbatim} environment. This can be very useful for debugging, or -writing Cheetah examples and tutorials. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#for ... \#end for} -\label{directives.for} - -The \code{\#for} directive iterates through a set of data. - -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} - -The previous example 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} - -Here's how to loop through a dictionaries keys and values: -\begin{verbatim} -#for $key, $value in $dict -$key - $value -#end for -\end{verbatim} - -Here's how to create 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} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#slurp} -\label{directives.slurp} - -The \code{\#slurp} directive comes in handy for {\bf slurping up} extra newline -characters in for loops: -\begin{verbatim} -#for $i in range(15) -$i - #slurp -#end for -\end{verbatim} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#if ... \#else if ... \#else ... \#end if} -\label{directives.if} - -The \code{\#if} directives 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 Python valid -expression is allowed. As in Python, the expression is true unless it evaluates -to 0, '', None, an empty list, or an empty dictionary. \code{\#elif} is accepted -as a synonym for {\#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} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#break and \#continue} -\label{directives.break} - -These directives are use as they are used in Python. \code{\#break} will -prematurely exit a \code{\#for} loop, while \code{\#continue} will immediately -jump to the next step 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 == 10 - #break -#end if -$name - #slurp -#end for -\end{verbatim} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#set} -\label{directives.set} - -\code{\#set} allows you to assign a value for a placeholder from inside the -Template Definition. One use for this is to assign a short alias to what would -otherwise be a long Placeholder Name. - -The syntax is: \code{\#set \$var = EXPRESSION} - -The expression may be any Python expression. Remember to preface variable names -with \$, unless it is 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 = ['Mo','Larry','Curly'] -#set $sizeSteps = [i*15 for i in range(10)] -\end{verbatim} - -It is probably most useful in conjunction with the \code{\#if} directive, but -remember that more 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} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#include} -\label{directives.include} - -\code{\#include} directives are used to include text from outside the template -definition. The text can come from external files or from \code{\$placeholder} -variables. When working with external files Cheetah will monitor for changes to -the included file and update as necessary. - -This 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 simple placing the \$placeholder tag ``\code{\$myParseText}'' in -your 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 mark the text for verbatim inclusion without any tag -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. These nested templates share the same \code{searchList} -and macros as the top-level template. But, unlike PHP, their Cheetah code must -be self-contained. For example, all \code{\#for} and \code{\#if} blocks started -inside an \code{\#include} must be terminated in that include. The same applies -for \code{\#data}, \code{\#macro} and \code{\#raw}. \code{\#set} -values are visible across includes. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#cache ... \#end cache} -\label{directives.cache} - -\code{\#cache} changes the default caching policy for placeholders inside the -directive body. This affects only Placeholder Tags without their own caching -instruction (i.e., those without a ``*''). - -\begin{verbatim} -<HTML> -<HEAD><TITLE>$title</TITLE></HEAD> -<BODY> - -$var ## dynamic - reinterpolated for each request -$*var2 ## static - interpolated only once during 1st request -$*5*var3 ## timed refresh - updated every 5 minutes - -#cache -$var ## static -$*var2 ## static -$*5*var3 ## timed refresh -#end cache - -#cache 0.5 -$var ## timed refresh every 30 seconds (0.5 minutes) -$*var2 ## static -$*5*var3 ## timed refresh every 5 minutes -#end cache - -</BODY> -</HTML> -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#stop} -\label{directives.stop} - -The \code{\#stop} directive is used to stop processing of a template at a -certain point and return ONLY what has been processed up to that point. When a -\code{\#stop} is called inside an \code{\#include} it will only stop the -processing of the included code, unless it was a ``\code{direct}'' include. - -\begin{verbatim} -the beginning -#if 1 - inside the if block - #stop -#end if -the end -\end{verbatim} - -will print -\begin{verbatim} -the beginning - inside the if block -\end{verbatim} - -instead of -\begin{verbatim} -the beginning - inside the if block -the end -\end{verbatim} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Macros} -\label{directives.macros} - - -{\bf Macros} allow template designers to define a repeated segment of Cheetah -syntax. Their sole purpose is to save keystrokes and minimize typographic -errors. They are simply functions that are called once-off at compile-time to -insert a chunk of Cheetah code to be parsed. Cheetah's macros are different -from the macro concept in Java's Velocity template engine. - -The output from a macro may contain any Cheetah syntax except the \code{\#macro} -directive which is used to define macros (see below). Macros may insert -placeholders, display logic, other directives, etc. \$placeholder() functions -may not. If the output from a \$placeholder() function contains any Cheetah -syntax it will be included without parsing. - -A macro is usually defined using the \code{\#macro} directive. However, it is -possible to write a Python function and register it as a Cheetah macro. -Examples of both are below. Using the \code{\#macro} directive is more -convenient if your macro consists mostly of text to be inserted with occasional -placeholders. Loading it from a function is the only choice if you need to do -any calculations. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Calling macros} -\label{directives.macros.calling} - -To call a macro that has already been defined, use the following syntax: -\code{\#MyMacro(ARGUMENTS)}. The argument syntax is the same as for -\$placeholder arguments: Python expressions separated by commas with variable -names prefaced with \$. The ``()'' are required even if there are no arguments. -Unlike other directives, there is no such thing as an explicit tag closure -(\code{\/\#}) for macro calls. - -The argument set in a macro call may not contain \$placeholders that have been -defined locally in a \code{\#for} directive, as such \$placeholders are not -available at compile-time. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Defining macros inplace using \#macro} -\label{directives.macros.defining} - -An inplace macro definition looks like this: - -\begin{verbatim} -#macro <macroName>(<arg set>) -<macro contents> -#end macro - -#macro testMacro(a, b) -This is the body of a test macro -$a and $b are interpoloted once-once at compile-time -$otherPlaceholder1 and $otherPlaceholder2 are interpolated for every request -#end macro - -#macro tablerows($color) -#for $something in $somelist - <tr><td bgcolor=$color>$something</td></tr> -#end for -#end macro -\end{verbatim} - -When the macro is called, it will insert the body of the macro in the template. -\$placeholders referring to macro arguments are expanded, as are -permanently-cached placeholders. Dynamic or timed-refresh placeholders are left -as is to be expanded when the template object is filled. Macros inside macros are -recursively expanded. Other directives are left alone, to be evaluated when the -template is parsed and compiled. - -The formal arguments in a macro definition are defined in regular Python syntax: -The ARE NOT prefaced with \$. Default values for arguments -may be provided in the usual Python manner. - -Note that the whitespace handling with the \code{\#macro} directive is the same -as with other directives. If you don't want the trailing end-of-line included -in your macro definition you must place the end tag on the same line as the last -bit of text in the macro definition. Here's an example: - -\begin{verbatim} -#macro myMacro() -My macro doesn't include the trailing EOL#end macro -\end{verbatim} - - -Here's a large example of a macro definition from the file -{\bf examples/webware\_examples/cheetahSite/SiteTemplate.tmpl}: - -\begin{verbatim} -#macro insetBox(width=170, boxTitle='', boxContents='') -<TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=$width> - <TR> - <TD COLSPAN=3 HEIGHT=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - </TR> - <TR> - <TD WIDTH=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - <TD WIDTH=900 HEIGHT=1 BGCOLOR="$mainTbl.outerFrameColor">#spacer()</TD> ## force full width - <TD WIDTH=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - </TR> - <TR> - <TD WIDTH=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - <TD WIDTH=900 HEIGHT=1 BGCOLOR="$mainTbl.innerFrameColor"> ## force full width - <DIV CLASS="insetBoxTitleContainer"><DIV CLASS="insetBoxTitle">$boxTitle</DIV></DIV> - </TD> - <TD WIDTH=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - </TR> - <TR> - <TD WIDTH=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - <TD WIDTH=900 HEIGHT=1 BGCOLOR="$mainTbl.outerFrameColor">#spacer()</TD> ## force full width - <TD WIDTH=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - </TR> - <TR> - <TD COLSPAN=3 HEIGHT=1 BGCOLOR="$*insetBoxes.titleFrameColor">#spacer()</TD> - </TR> -</TABLE> - -<TABLE VALIGN="top" WIDTH=$*width BORDER=0 CELLPADDING=0 CELLSPACING=0> - <TR> - <TD WIDTH=1 bgcolor="$*insetBoxes.frameColor">#spacer()</TD> - <TD WIDTH=900 BGCOLOR="$*insetBoxes.bgcolor"> ## force to full width - ## now begin the contents cell of the insetBox - $boxContents - ## end insetBox - </TD> - <TD WIDTH=1 BGCOLOR="$*insetBoxes.frameColor">#spacer()</TD> - </TR> -</TABLE> - -<TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=$width> - <TR> - <TD HEIGHT=1 BGCOLOR="$*insetBoxes.frameColor">#spacer()</TD> - </TR> -</TABLE> -#end macro -\end{verbatim} - -All the formal arguments in the \code{\#insetBox} macro have default values, so -they don't have to be specified when the macro is called. Notice how the author -uses different \$placeholder styles according to the placeholder. Most -placeholders have a ``*'' for permanent caching. Those referring to macro -arguments don't have a ``*'' (that would be silly), as do a few dynamic -placeholders (e.g., \code{\$insetBoxes.titleFrameColor}, which is not defined in -the macro but is assumed to exist when the template is filled. Notice also how -the author calls macros inside macros (e.g., \code{\#spacer()}). - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Using existing functions as macros} -\label{directives.macros.existingFunctions} -Existing functions or object methods may registered as Cheetah macros. To do -this, execute one of these statements in your Template subclass or inside a -\code{\#data} directive. - -\begin{verbatim} -# Create a macro called 'macroName' that uses 'function'. -self.loadMacro('macroName', function) - -# Create macros from functions named 'spacer' and 'formHTMLTag'. Each macro -# will have the same name as its function. -self.loadMacros(spacer, formHTMLTag) - -# Create macros from all the callable objects in module 'Cheetah.Macros.HTML'. -# If the module has the attribute '_exclusionList' the variable names contained -# in the list will not be registered as macros. -self.loadMacrosFromModule(Cheetah.Macros.HTML) -\end{verbatim} - -The \code{Template.loadMacrosFromModule()} method is especially useful for -packaging a group of functions as a macro library. The \code{Cheetah.Macros} -package contains some examples. - -Because the functions these macros are loaded from really {\em are} functions, -they can also be loaded into the Search List and used as placeholder functions: - -\begin{verbatim} -templateObj = Template(templateDef, Cheetah.Macros.HTML) -\end{verbatim} - -There's no confusion here because \code{\$spacer(50)} will get the function and -\code{\#spacer(50)} will get the macro. Just remember that if the macro outputs -embedded macros, directives or placeholders it cannot be used as a placeholder -function. Or rather it can, but the embedded \code{\$placeholders} and -\code{\#directives} won't be parsed. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{\#callMacro(): an extended syntax for calling macros} -\label{directives.macros.callMacro} - -The \code{\#macroName(<arg set>)} syntax is great for macros with small strings for -arguments, but it gets messy when you want to feed in larger chunks of text as -arguments. - -For example: -\begin{verbatim} -#macro tableMacro(width, cell1, cell2, cell3) -<TABLE WIDTH=$width> - <TR> - <TD>$cell1</TD> - <TD>$cell2</TD> - <TD>$cell3</TD> - </TR> -</TABLE> -#/macro -\end{verbatim} - -The cell contents will probably be way to large to use the macro in the normal -fashion: \code{\#tableMacro(200, ``...'', ``...'', ``...'')}. - -The \code{\#callMacro()} directive makes it easier to use macros that accept -large chunks of text as arguments. You would define the macros exactly like -normal macros, but when you call them you could do the following: - -\begin{verbatim} -#callMacro tableMacro(width=200) -#arg cell1 -sahoeusnthao u -aoesthaothu -aoenthaothu -ashushu -#end arg - -#arg cell2 -sahoeusnthao u -aoesthaothu -aoenthaothu -ashushu -#end arg - -#arg cell3 -sahoeusnthao u -aoesthaothu -aoenthaothu -ashushu -#end arg - -#end callMacro - -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Redefinition of macros in subclasses} -\label{directives.macros.redefine} - -The \code{Template.loadMacro('macroName', function)} method may be used to -redefine a macro in an extended template. See sections \ref{directives.extend} -and \ref{directives.extend} for more information. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Macro libraries} -\label{directives.macros.libraries} - -Cheetah comes ``batteries included'', with a library of useful macros in the -\code{Cheetah.Macros} package. See section \ref{libraries.macros} for more -information. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#data ... \#end data} -\label{directives.data} - -[{\bf The syntax and semantics of this directive are currently under - review. They may change before the 1.0 release. }] - -The \code{\#data} directive is a shortcut means of defining variables than be -used by \$placeholders in your template. It's contents can be any valid Python -code. The code contained in a \#data directive is exec'd in an empty namespace -and that namespace is then merged into the attribute list of the Template -object, which is always part the searchList that \$placeholder values are -extracted from. Don't preface you variables with \$ inside the data directive! - -Here's an example: - -\begin{verbatim} -#data -title = "Cheetah - The Python-Powered Template Engine" -siteDomainName = "cheetahtemplate.sourceforge.net" -siteCopyrightName= "The Cheetah Development Team" -# Python comments can be used -bodyTagAttribs = {"bgcolor": "black", - "text":"#000033", - } -navBar = {"bgcolor":"#3366CC", - } -locationBar = {"bgcolor":"#3366CC", - "frameColor":"#CCCCCC", - } -mainTbl = {"width":"90%", - "align":"center", - "contentsBgColor":"white", - "outerFrameColor":"#6699FF", - "innerFrameColor":"#3366CC", - "innerFrameWidth":8, - } -#end data -\end{verbatim} - -\subsubsection{Dictionary merging} - -Dictionaries that are defined in a \code{\#data} directive and already exist as -attributes of the Template object will be merged. Here's an example: - -\begin{verbatim} -from Cheetah.Template import Template - -class mySubclass(Template): - bodyTagAttribs = {"link":"blue"} - -templateDef = """ -#data -bodyTagAttribs = {"bgcolor": "black", - "text":"#000033", - } -#end data -$bodyTagAttribs -""" -print mySubclass(templateDef) -\end{verbatim} - -This will output: -\begin{verbatim} -{'link': 'blue', 'text': '#000033', 'bgcolor': 'black'} -\end{verbatim} - -Dictionary merging can be incredibly useful for selectively changing single -aspects of the cascading style sheet attributes defined by your site-wide -template. See examples in appendix \ref{examples} for more information on this. - -If you want it can be disabled with the \code{nomerge} keyword like this: -\begin{verbatim} -#data nomerge -bodyTagAttribs = {"bgcolor": "black", - "text":"#000033", #333333 - } -#end data -\end{verbatim} - -Dictionary merging is recursive. If a dictionary is contains nested -dictionaries in both the Template object and in the \code{\#data} directive the -entire nested structure will be merged recursively. You can find more -information on dictionary merging by looking at the source code for -\code{mergeNestedDictionaries} in the \code{Cheetah.Utilities module}. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#block ... \#end block} -\label{directives.block} - -[{\bf The syntax and semantics of this directive are currently under - review. They may change before the 1.0 release. }] - -The \code{\#block} directive allows you to delimit sections of your template -that can be selectively reimplemented by sub-classes of the template. It is -very useful for selectively 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 and \#end block} tags removed. - -\begin{verbatim} -#block [blockName] -[block contents] -#end block [blockName] - -#block testBlock -Text in the contents -area of the block directive -#if $testIt -$getFoo() -#end if -#end block testBlock -\end{verbatim} - -\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} - -The implementation of \code{\#block} is quite simple. Each block in the -template definition is replaced with \code{\#include direct - \$cheetahBlocks.<blockName>} and its contents are stored in the dictionary -\code{Template.\_cheetahBlocks} using the 'blockName' as the dictionary key. To -{\bf redefine} the contents of a block Cheetah just replaces the blockName's -entry in \code{Template.\_cheetahBlocks}. The Template class' -\code{redefineBlock(blockName, contents)} and \code{killBlock(blockName)} -methods provide a easy way to redefine blocks. - -Appendix \ref{examples} contains extended examples of how blocks can be used to -simplify the creation and maintenance of large websites. - -Blocks are powerful and unique feature of Cheetah! - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#redefine ... \#end redefine} -\label{directives.redefine} - -[{\bf The syntax and semantics of this directive are currently under - review. They may change before the 1.0 release. }] - -When working with a large number of blocks it can be useful to write all the -redefinitions in one {\bf template extension} string and just feed this string -to the \code{Template.extendTemplate(extensionStr)} method at startup rather -than individually \code{Template.redefineBlock()} for each and every block. - -\begin{verbatim} -#redefine [blockName] -[new contents] -#end redefine [blockName] - -#redefine footer -<HR> -<P>$copyrightNotice<P> -<div align="center">$companyName<BR> -$address. Phone: $phone, Fax: $fax. Email: $email</div> -#end redefine footer -\end{verbatim} - -\code{\#redefine} directives may not be nested. However, the new contents of -the \code{\#redefine} directives may contain other \code{\#blocks}, even nested -ones, and any other Cheetah syntax, except \code{\#data}, \code{\#macro}, and -\code{\#extend}. Extension strings fed to -\code{Template.extendTemplate(extensionStr)} may also contain \code{\#data} and -\code{\#macro} directives at the top-level, that is outside the -\code{\#redefine} directives. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{\#extend} -\label{directives.extend} - -The \code{\#extend} directive is a wrapper around -\code{Template.extendTemplate(extensionStr)} that is used with Webware and {\bf - \code{.tmpl servlet files}} (see section \ref{webware.tmpl} for more). If your -\code{.tmpl servlet file} needs to \code{\#redefine} blocks and/or \code{\#data} -from a parent Template, rather than define a new top-level template use this -directive to specify the Python module or \code{.tmpl servlet file} that -contains the parent Template. - -\code{\#extend <parentTemplateFile-withoutTheExtension>} - -Appendix \ref{examples} contains extended examples of how \code{\#extend} is -used. - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/errorMessages.tex b/docs/src/errorMessages.tex deleted file mode 100644 index b8189c7..0000000 --- a/docs/src/errorMessages.tex +++ /dev/null @@ -1,10 +0,0 @@ -\section{Error Messages} - -\subsection{Errors during compilation} - -\subsection{Run-time errors} - - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/examples.tex b/docs/src/examples.tex deleted file mode 100644 index 62f7a3d..0000000 --- a/docs/src/examples.tex +++ /dev/null @@ -1,29 +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} -Cheetah's \code{Tests} module contains a large number of test cases -that can double as examples of how the Template Definition Language works. -To view these cases go to the base directory of your Cheetah distribution -and open the file Cheetah/Tests.py in a text editor. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Webware Examples} -The 'examples' directory has a subdirectory called 'webware_examples'. It -contains example servlets that use Webware. - -A subdirectory titled 'webwareSite' contains a complete website example. This -site is my proposal for the new Webware website. The site demonstrates the -advanced Cheetah features such as the \code{\#data} and \code{\#redefine} -directives. It also demonstrates how the TScompile program can be used to -generate Webware .py servlet files from .tmpl Template Definition files. - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/gettingStarted.tex b/docs/src/gettingStarted.tex deleted file mode 100644 index 33852af..0000000 --- a/docs/src/gettingStarted.tex +++ /dev/null @@ -1,121 +0,0 @@ -\section{Getting Started} -\label{gettingStarted} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Who should read this Guide?} - -This Users Guide is for those wishing an overview, tutorial and reference for -the Cheetah template system. A basic knowledge of Python is assumed. -This Guide also contains examples of integrating Cheetah with Webware for -Python, a web application development framework. Knowledge of Webware is not -assumed, but of course you will have to learn Webware from its own -documentation in order to build a Webware + Cheetah site. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Requirements} -\label{gettingStarted.requirements} - -Cheetah requires Python release 2.0 or greater and should run on any -operating system that Python 2.0 runs on. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Installation} -\label{gettingStarted.install} - -To install Cheetah for a single user: -\begin{enumerate} -\item copy the 'src' sub-directory to a location that is in the user's - PYTHONPATH and rename it as 'Cheetah'. -\end{enumerate} - -To install Cheetah for system-wide use: -\begin{enumerate} -\item on POSIX systems (AIX, Solaris, Linux, IRIX, etc.) become the 'root' user - and run: python setup.py install - -\item On non-POSIX systems, such as Windows NT, login as an administrator and - type this at the command prompt: python setup.py install -\end{enumerate} - - -On POSIX systems, the system-wide installation will also install the Cheetah's -command-line compiler program, cheetah-compile, to the "bin/" directory of your -Python distribution. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Testing your installation} -\label{gettingStarted.test} - -You can run the test suite to insure that your installation is correct by -following these steps: -\begin{enumerate} -\item CD into the directory ./src/Tests -\item type: \code{python Test.py} -\end{enumerate} - -If the tests pass, start Python in interactive mode and try the example in the -Introduction section of this guide. - -If any of the tests fail please send a message to the email 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 the basic usage of Cheetah. See the -following chapters for more detailed explanations. - -{\bf This tutorial will be fleshed out further at later date.} - -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 from an -interactive Python session. 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 -... blah, blah, blah -... *# -... </BODY> -... </HTML>""" ->>> nameSpace = {'title': 'Hello World Example', 'contents': 'Hello World!'} ->>> templateObj = Template(templateDef, nameSpace) ->>> print templateObj - -<HTML> -<HEAD><TITLE>Hello World Example</TITLE></HEAD> -<BODY> -Hello World! -</BODY> -</HTML> ->>> print templateObj # templateObj can be printed as many times as you need - -<HTML> -<HEAD><TITLE>Hello World Example</TITLE></HEAD> -<BODY> -Hello World! -</BODY> -</HTML> - -\end{verbatim} - -% Local Variables: -% TeX-master: "users_guide" -% End: - diff --git a/docs/src/gfdl.tex b/docs/src/gfdl.tex deleted file mode 100644 index a6774c2..0000000 --- a/docs/src/gfdl.tex +++ /dev/null @@ -1,367 +0,0 @@ -% gfdl.tex -% This file is a chapter. It must be included in a larger document to work -% properly. - -\section{GNU Free Documentation License} - -Version 1.1, March 2000\\ - - Copyright $\copyright$ 2000 Free Software Foundation, Inc.\\ - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\ - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - -\subsection*{Preamble} - -The purpose of this License is to make a manual, textbook, or other -written document ``free'' in the sense of freedom: to assure everyone -the effective freedom to copy and redistribute it, with or without -modifying it, either commercially or noncommercially. Secondarily, -this License preserves for the author and publisher a way to get -credit for their work, while not being considered responsible for -modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -\subsection{Applicability and Definitions} - -This License applies to any manual or other work that contains a -notice placed by the copyright holder saying it can be distributed -under the terms of this License. The ``Document'', below, refers to any -such manual or work. Any member of the public is a licensee, and is -addressed as ``you''. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section of -the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall subject -(or to related matters) and contains nothing that could fall directly -within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any -mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, whose contents can be viewed and edited directly and -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -ASCII without markup, Texinfo input format, \LaTeX~input format, SGML -or XML using a publicly available DTD, and standard-conforming simple -HTML designed for human modification. Opaque formats include -PostScript, PDF, proprietary formats that can be read and edited only -by proprietary word processors, SGML or XML for which the DTD and/or -processing tools are not generally available, and the -machine-generated HTML produced by some word processors for output -purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - - -\subsection{Verbatim Copying} - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -\subsection{Copying in Quantity} - -If you publish printed copies of the Document numbering more than 100, -and the Document's license notice requires Cover Texts, you must enclose -the copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - - -\subsection{Modifications} - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -\begin{itemize} - -\item Use in the Title Page (and on the covers, if any) a title distinct - from that of the Document, and from those of previous versions - (which should, if there were any, be listed in the History section - of the Document). You may use the same title as a previous version - if the original publisher of that version gives permission. -\item List on the Title Page, as authors, one or more persons or entities - responsible for authorship of the modifications in the Modified - Version, together with at least five of the principal authors of the - Document (all of its principal authors, if it has less than five). -\item State on the Title page the name of the publisher of the - Modified Version, as the publisher. -\item Preserve all the copyright notices of the Document. -\item Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. -\item Include, immediately after the copyright notices, a license notice - giving the public permission to use the Modified Version under the - terms of this License, in the form shown in the Addendum below. -\item Preserve in that license notice the full lists of Invariant Sections - and required Cover Texts given in the Document's license notice. -\item Include an unaltered copy of this License. -\item Preserve the section entitled ``History'', and its title, and add to - it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled ``History'' in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. -\item Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the ``History'' section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. -\item In any section entitled ``Acknowledgements'' or ``Dedications'', - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. -\item Preserve all the Invariant Sections of the Document, - unaltered in their text and in their titles. Section numbers - or the equivalent are not considered part of the section titles. -\item Delete any section entitled ``Endorsements''. Such a section - may not be included in the Modified Version. -\item Do not retitle any existing section as ``Endorsements'' - or to conflict in title with any Invariant Section. - -\end{itemize} - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties -- for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - - -\subsection{Combining Documents} - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections entitled ``History'' -in the various original documents, forming one section entitled -``History''; likewise combine any sections entitled ``Acknowledgements'', -and any sections entitled ``Dedications''. You must delete all sections -entitled ``Endorsements.'' - - -\subsection{Collections of Documents} - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - - - -\subsection{Aggregation With Independent Works} - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, does not as a whole count as a Modified Version -of the Document, provided no compilation copyright is claimed for the -compilation. Such a compilation is called an ``aggregate'', and this -License does not apply to the other self-contained works thus compiled -with the Document, on account of their being thus compiled, if they -are not themselves derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one quarter -of the entire aggregate, the Document's Cover Texts may be placed on -covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. - - -\subsection{Translation} - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the -original English version of this License. In case of a disagreement -between the translation and the original English version of this -License, the original English version will prevail. - - -\subsection{Termination} - -You may not copy, modify, sublicense, or distribute the Document except -as expressly provided for under this License. Any other attempt to -copy, modify, sublicense or distribute the Document is void, and will -automatically terminate your rights under this License. However, -parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such -parties remain in full compliance. - - -\subsection{Future Revisions of This Licence} - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -\url{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License "or any later version" applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. - -\subsection*{ADDENDUM: How to use this License for your documents} - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -\begin{quote} - - Copyright $\copyright$ YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled ``GNU - Free Documentation License''. - -\end{quote} - -If you have no Invariant Sections, write ``with no Invariant Sections'' -instead of saying which ones are invariant. If you have no -Front-Cover Texts, write ``no Front-Cover Texts'' instead of -``Front-Cover Texts being LIST''; likewise for Back-Cover Texts. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - diff --git a/docs/src/glossary.tex b/docs/src/glossary.tex deleted file mode 100644 index 316cbdb..0000000 --- a/docs/src/glossary.tex +++ /dev/null @@ -1,49 +0,0 @@ -\section{Glossary} -\label{glossary} - -To avoid confusion when discussing different aspects of the Cheetah system, all -Cheetah-specific terms are defined here. If you are posting to the mailing -list, writing cheetah code or writing cheetah examples please use these terms. - -\begin{description} - -\item{Template Definition Language (TDL)} The markup language used for - Template Definitions. - -\item{Template Object (TO, template)} An instance of the class - \code{Cheetah.Template.Template} or one of its subclasses. In the source - code it is referred to as 'templateObj'. - -\item{Template Definition (TD)} A string marked up in the TDL which is used to - created a template object. In the source code it is referred to as - 'templateDef'. - -\item{Template Definition Extension} A string marked up in the TDL which is used - to extend an existing template definition. A template definition extension - usually contains a number of \code{\#redefine} directives that redefine blocks - declared in the parent template definition. In the source code it is - referred to as 'templateExt'. - -\item{Search List} A list of Python data structures which will be searched to - find values for the \$placeholders in a template definition. Each object - is referred to as a {\bf Namespace} and must be either a dictionary or an - object. In the source code it is referred to as 'searchList'. - -\item{Filled Template} A string which is the result of filling in the - changeable data in the TO with their current values. - -\item{Directive Tag (\#directive, \#D)} All tags that begin with ``\#''; e.g., - \code{\#if}. - -\item{Placeholder Tag (\$placeholder, \$P)} All tags that begin with ``\$''. - -\item{compile} When you instantiate a template object or call its - \code{.compileTemplate()} method, Cheetah compiles the Template Definition - into Python code. - -\end{description} - - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/introduction.tex b/docs/src/introduction.tex deleted file mode 100644 index 23de3b9..0000000 --- a/docs/src/introduction.tex +++ /dev/null @@ -1,280 +0,0 @@ -\section{Introduction} -\label{intro} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{What is Cheetah?} -\label{intro.whatIs} - -Cheetah is a Python-powered template engine and code generator. It can be used -as a standalone utility or it can be combined with other tools. Cheetah has -many potential uses -- generating SQL, SGML or LaTeX source, PostScript, form -emails, etc. -- 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 works with HTML, SGML, XML, SQL, Postscript, form email, LaTeX, or any - other text-based format. - -\item makes it easy to cleanly separate 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 the simplicity of a lean - Template Definition Language that non-programmers can understand. - -\item gives template writers full access to any Python data structure, - function, object, or method in their templates. - -\item compiles `Template Definitions' into native Python code at startup and - 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. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Give me an example!} -\label{intro.whatIs} - -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} - - -%% @@TR: I'm going to extend this and briefly introduce: -%% - Template objects vs. .tmpl files. -%% - how to get data into it - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{What is the philosophy behind Cheetah?} -\label{intro.philosophy} - -Cheetah is guided by these principles: -\begin{itemize} -\item {\bf It should be easy to separate content, graphic design, and program code.} - - 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''). - -\item {\bf But, it should also be easy to integrate content, graphic design, and - program code.} - - 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 extend and customize 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} - -\item {\bf Python for the complex tasks, Cheetah for the simple tasks.} - -\item {\bf Non-programmers should be able to understand Cheetah's syntax.} - -\end{itemize} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Who developed Cheetah?} -\label{intro.developers} - -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. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{How mature is Cheetah?} -\label{intro.mature} - -Cheetah is alpha software as some aspects of its design are -still subject to change and the Users' Guide is incomplete. -We plan to release a stable version later in 2001. - -Here's a summary of known issues and aspects of the design that are in flux: -\begin{itemize} - -\item We're currently reviewing the syntax and semantics of the \#data, \#block - and \#redefine directives. These will most likely change before the 1.0 - release. See the mailing list archives for the end of Aug 2001 for more - information. - -\end{itemize} - -The syntax and usage directions described throughout the rest of this guide are -stable unless noted otherwise. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Where can I get releases?} -\label{intro.releases} - -Download Cheetah releases from -\url{http://CheetahTemplate.sourceforge.net} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Where can I get news?} -\label{intro.news} - -News and updates can be obtained from the the Cheetah website: -\url{http://CheetahTemplate.sourceforge.net} - -Cheetah discussions take place on the list -\email{cheetahtemplate-discuss@lists.sourceforge.net}. - -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 email 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 send a link to the -email list so we can keep track of Cheetah sites. Also, if you discover -new and interesting ways to use Cheetah please share your experience and -write a quick tutorial about your technique. - -\subsubsection{Macro libraries and function libraries} -We hope to build up a framework of macros libraries (see section -\ref{macros.libraries}) 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} - -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, Tom Schwaller, Rober Kuzelj, Jay Love, -Terrel Shumway, Sasa Zivkov, Arkaitz Bitorika, Jeremiah Bellomy, Baruch Even, -Paul Boddie, Stephan Diehl, Chui Tey, and Geir Magnusson. - -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} - -\subsubsection{The gist} -Cheetah is open source, but there is no requirement that products developed with -or derivative to Cheetah become open source. - -\subsubsection{Legal terms} -Copyright \copyright 2001, The Cheetah Development Team: Tavis Rudd, Mike Orr, -Chuck Esterbrook, Ian Bicking. - -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. - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/libraries.tex b/docs/src/libraries.tex deleted file mode 100644 index 295a2f8..0000000 --- a/docs/src/libraries.tex +++ /dev/null @@ -1,242 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Macro, Template and other libraries} -\label{libraries} - -Cheetah comes ``batteries included'' with libraries of macros, templates and -other objects you can use in your own programs. If you develop your own, please -consider posting them on the mailing list so others can benefit. - -Some useful functions, and other objects, used by Cheetah are in the -\code{Cheetah.Utilities} module. All utility modules contributed by third -parties are in the \code{Cheetah.Tools} package. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Macro libraries} -\label{libraries.macros} - -The package \code{Cheetah.Macros} includes libraries of macros that can be -loaded into Templates via the \code{Template.loadMacrosFromModule()} method. -See section \ref{directives.macros.existingFunctions} for more information on -this method. All of the functions contained in the macro libraries can also be -added to the \code{searchList} and used as regular \$placeholders if you wish. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Cheetah.Macros.HTML} -\label{libraries.macros.HTML} -The module \code{Cheetah.Macros.HTML} contains a number of functions that are -usefull for generating common HTML elements. - -\begin{itemize} -\item {\bf \code{currentYr()}} -- Returns the current year. This is useful in - copyright strings. -\item {\bf \code{currentDate(formatString=''\%b \%d, \%Y'')}} -- Returns a string - representation of the current date. See the documentation for the Python - \code{time} module for the formatString codes. If you change the - formatString, remember that when this function used as a macro the date - will only be calculated once at compile-time -\item {\bf \code{spacer(width=1,height=1)}} -- Returns an image tag for a - transparent spacer image. This very useful for generating complex image - tables. You'll need to have a single-pixel transparent gif image called - \code{spacer.gif} in the same directory as your template file. If you want - to put the image elsewhere you can easily reimplement the function behind - this macro. -\item {\bf \code{formHTMLTag(tagName, attributes=\{\})}} -- Returns an HTML tag - with the attributes given. - -\item {\bf \code{formatMetaTags(metaTags)}} -- Will auto-format a dictionary of - meta-tags. It accepts a dictionary that contains one or two - sub-dictionaries under the keys \code{HTTP_EQUIV} and \code{NAME}. Each of - the sub-dictionaries should contain key-value pairs that represent the - name-contents pairs for each of the desired meta-tags. -\end{itemize} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Template libraries} -\label{libraries.templates} - -The \code{Cheetah.Templates} package contains stock templates that you can -either use as is, or extend by using the \code{\#redefine} directive to redefine -specific {\bf blocks}. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Cheetah.Templates.SkeletonPage} -\label{libraries.templates.skeletonPage} - -A stock template that will be very useful for web developers is defined in -the \code{Cheetah.Templates.SkeletonPage} module. The \code{SkeletonPage} page -class is a subclass of \code{Cheetah.Servlet.TemplateServlet} that is bound to -the following template definition: - -\begin{verbatim} -$*docType -<HTML> -#################### -#block headerComment -<!-- This document was autogenerated by Cheetah. Don't 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 - ---> - -#end block headerComment -##################### - -################# -#block headTag /# -<HEAD> -<TITLE>$*title</TITLE> -$*metaTags() -$*stylesheetTags() -$*javascriptTags() -</HEAD> -#end block headTag /# -################# - - -################# -#block bodyTag /# -$bodyTag() -#end block bodyTag /# -################# - -#block bodyContents /# -This skeleton page has no flesh. Its body needs to be implemented. -#end block bodyContents /# - -</BODY> -</HTML> -\end{verbatim} - -You can reimplement any of the blocks defined in this template definition by -writing a {\bf template definition extension} that contains \code{\#redefine} -directives (see section \ref{directives.redefine}). - -\begin{verbatim} -#redefine bodyContents -Here's my new body. I've got some flesh on my bones now. -#end redefine bodyContents -\end{verbatim} - -The \code{SkeletonPage} class automatically loads the \code{Cheetah.Macros.HTML} -macro library. Thus, macros like \code{\#currentYr()} can be used by any -subclass. - -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{Cheetah.Macros.HTML} -\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} - -See the file \code{examples/webware_examples/cheetahSite/SiteTemplate.tmpl} for -an extended example of how \code{SkeletonPage} can be used. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Cheetah.Utilities} -\label{libraries.utilities} - -\begin{itemize} -\item {\bf \code{mergeNestedDictionaries(dict1, dict2)}} -- Recursively merge - the values of dict2 into dict1. This little function is very handy for - selectively overriding settings in a settings dictionary that has a nested - structure. -\item {\bf \code{removeDuplicateValues(list)}} -- Remove all duplicate values in - a list. -\item {\bf \code{lineNumFromPos(string, pos)}} -- Calculate what line a position - in a string lies on. This doesn't work on Mac-OS. -\item {\bf \code{getLines(string, sliceObj)}} -- Slice a string up into a list - of lines and return a slice. -\item {\bf \code{insertLineNums(string)}} -- Return a version of the string with - each line prefaced with its line number. -\end{itemize} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Cheetah.Tools} -\label{libraries.tools} - -As mentiond above, utility modules contributed by third parties are stored in -the \code{Cheetah.Tools} package. It currently contains: - -\begin{itemize} -\item {\bf 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. Contributed by Ian Bicking. -\end{itemize} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Cheetah.SettingsManager} -\label{libraries.SettingsManager} - -The \code{SettingsManager} class in the \code{Cheetah.SettingsManager} module is -a mixin class that provides facilities for managing application settings. -SettingsManager is designed to: -\begin{itemize} -\item work well with nested settings dictionaries of any depth -\item be able to read/write \code{.ini style config files} (or strings) -\item be able to read settings from Python src 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. If there is sufficient interest in \code{SettingsManager} we will -release it as a standalone module. - - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/links.tex b/docs/src/links.tex deleted file mode 100644 index 58e3292..0000000 --- a/docs/src/links.tex +++ /dev/null @@ -1,114 +0,0 @@ -\section{Useful Web Links} -\label{links} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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.cheetah} - -This is NOT a definitive listing of sites and products using Cheetah. If you -have something to add to the list please send an email to -\email{cheetahtemplate-discuss@lists.sf.net}. - -\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.other} - -\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.other} - -\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/src/moreverb.sty b/docs/src/moreverb.sty deleted file mode 100755 index 92e34bb..0000000 --- a/docs/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/src/puttingItTogether.tex b/docs/src/puttingItTogether.tex deleted file mode 100644 index 586a989..0000000 --- a/docs/src/puttingItTogether.tex +++ /dev/null @@ -1,175 +0,0 @@ -\section{Putting it all together} -\label{puttingItTogether} - -This section provides a high-level explanation of how to use Cheetah and an -under-the-hood view of how Cheetah works. If you are using Cheetah with Webware -and want to get straight into it, skip ahead to section -\ref{webware.inheritance.tmpl} and come back here later. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{The Template class} -\label{puttingItTogether.template} - -The \code{Template} class (\code{Cheetah.Template.Template}) is the heart of -Cheetah. Objects of this class parse and compile template definitions into a -chunk of Python code. This chunk of Python code is then bound to the template -object's \code{.__str__()} and \code{.respond()} methods, and is executed each -time you request the filled output from the template by calling either of these -methods. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Constructing template objects} -\label{puttingItTogether.template.constructing} - -Template objects may be created manually in Python code or automatically using -\code{.tmpl} files when Cheetah is used with Webware. See section -\ref{webware.inheritance.tmpl} for more information on \code{.tmpl} files. The -section only deals with manual creation. - -You must pass either a Template Definition string or a 'file' keyword argument, -but not both, to the \code{Template} class' constructor. - -Here are some examples of the various ways to create a template object: -\begin{description} -\item{\code{templateObj = Template("The king is a \$placeholder1.")}} - Pass the Template Definition as a string. -\item{\code{templateObj = Template(file="fink.ctd")}} - Read the Template Definition from a file named "fink.ctd". Note, do not - confuse \code{.ctd} files with the \code{.tmpl} files that may be used - directly with Webware (see section \ref{webware.inheritance.tmpl}) -\item{\code{templateObj = Template(file=f)}} - Read the Template Definition from file-like object 'f'. -\item{\code{templateObj = Template("The king is a \$placeholder1.", 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{templateObj = Template(None, dict, obj, file="fink.txt")}} - Same, but pass a filename instead of a string. The \code{None} is required - here to represent the missing Template Definition string -- this due to - Python's rules for positional parameters. -\item{\code{templateObj = Template(None, dict, obj, file="fink.txt")}} - Same with a file object. -\end{description} - -The following usage examples are not allowed: -\begin{verbatim} -templateObj = Template() -templateObj = Template("The king is a $placeholder1", file="fink.txt") -templateObj = Template("The king is a $placeholder1", file=f) -\end{verbatim} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Using Template objects} -\label{puttingItTogether.template.using} - -To use a template object once it has been created, simply print it using -Python's \code{print} keyword, apply the \code{str()} function to it, or call -its \code{.respond} method. The result is a string with all the Placeholders -filled in with their current values, and all the directives executed. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Methods of the Template class} -\label{puttingItTogether.template.methods} - -\begin{description} - -\item[.compileTemplate()] -- Compile the template. This needs to be called - manually if the setting ``delayedCompile'' is set to True. - -\item[.recompile()] -- Synonym for \code{.compileTemplate}. - -\item[.searchList()] -- Return a reference to the searchList. It's a - \code{UserList} subclass, so you can use Python's standard list operations - on it. - -\item[.addToSearchList(theNamespace)] -- Append the given Namespace to the - searchList. - -\item[.extendTemplate(templateExt)] -- - -\item[.redefineTemplateBlock(blockName, blockContents)] -- Redefine a named block - in the template definition. Both arguments must be strings. You must call - \code{.recompile()} for the change to take effect if the template has - already been compiled. - -\item[.killTemplateBlock(*blockNames)] Delete the named blocks from the template - definition. They will no longer show up in Filled Templates. You must call - \code{.recompile()} for the change to take effect if the template has - already been compiled. - - -\item[.loadMacro(), .loadMacros() and .loadMacrosFromModule()] See section - \ref{directives.macros}. - -\item[.registerServerPlugin(plugin)] Register a plugin that extends the - functionality of the Template. See section \ref{customizing.plugins}. - -\item[.normalizePath()] A hook to enable proper handling of server-side paths - with Webware. - -\item[.getFileContents(fileName)] Returns the contents of the named - file. May be overridded to do, e.g., URL retrievals. - -\item[.runAsMainProgram()] - -\end{description} - -Since the Template class inherits from the \code{SettingsManager} mixin class, -its methods are available to change configuration settings. See section -\ref{libraries.SettingsManager} for more about it. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Putting stuff into the searchList} -\label{puttingItTogether.searchList} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{As attributes/methods of the Template object} -\label{puttingItTogether.searchList.self} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Using mixin classes} -\label{puttingItTogether.searchList.self} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Using the \#data directive} -\label{puttingItTogether.searchList.dataDirective} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Using the .addToSearchList() method} -\label{puttingItTogether.searchList.addToSearchList} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Optimization} -\label{puttingItTogether.optimization} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Shortcut name-binding} -\label{puttingItTogether.optimization.namebinding} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Caching} -\label{puttingItTogether.optimization.caching} - -Please refer to section \ref{puttingItTogether.caching}. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Moving code into Python} -\label{puttingItTogether.optimization.intoPython} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Caching} -\label{puttingItTogether.caching} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Debugging} -\label{puttingItTogether.debugging} - - -% Local Variables: -% TeX-master: "users_guide" -% End: - diff --git a/docs/src/tipsAndTricks.tex b/docs/src/tipsAndTricks.tex deleted file mode 100644 index 246a4c0..0000000 --- a/docs/src/tipsAndTricks.tex +++ /dev/null @@ -1,10 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Tips and Tricks} -\label{tips} - -[{\bf This section is under construction. Do you have anything to contribute?}] - - -% Local Variables: -% TeX-master: "users_guide" -% End: diff --git a/docs/src/webware.tex b/docs/src/webware.tex deleted file mode 100644 index 28ef54a..0000000 --- a/docs/src/webware.tex +++ /dev/null @@ -1,244 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Using Cheetah with Webware} -\label{webware} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Background} -\label{webware.background} - -{\bf Webware} is a 'Python-Powered Internet Platform' that uses 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}. - -As Cheetah's core is flexible there are many ways to use it with Webware -servlets. There are two broad categories: the {\bf Inheritance} approach and the -{\bf Containment} approach. In the Inheritance approach a servlet is created that -subclasses both the \code{Template} class and Webware's \code{HTTPServlet} -class. The Template object {\em IS} the servlet and its \code{.respond()} method is -automatically called by WebKit for each request. All pre-request processing is -handled via Cheetah. - -In the Containment approach an instance of the Template class is contained -inside of a Webware servlet. The servlet must explicitly call the Template -object's \code{.respond()}, or \code{.\_\_str\_\_()}, method for each request. In -this case the servlet class can handle whatever per-request processing needs to -be done before it calls Cheetah.respond(). - -The Inheritance approach is the simplest and is best suited for building sites -from scratch. The Containment approach is slightly more complex and is best -suited for use with existing Webware servlets. It is also ideal for cases where -you wish to use Cheetah for only a portion of the servlet's output, such as a -discussion-forum table at the bottom of a webpage. - -There are two ways to use the Inheritance approach: automatically by creating -{\bf \code{.tmpl servlet files}} (e.g. ``myTemplate.tmpl'') or manually by -creating {\bf \code{.py servlet files}} (e.g. ``myServlet.py''). \code{.py - servlet files} are Webware's default type of servlet file. A \code{.tmpl - servlet file} is a Cheetah specific type of servlet file that is converted -automatically into a \code{.py servlet file} that Webware understands. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Using .tmpl servlet files} -\label{webware.tmpl} - -As mentioned above a \code{.tmpl servlet file} is a Cheetah specific type of -servlet file that is converted automatically, or semi-automatically, into a -\code{.py servlet file} that Webware understands. Working with \code{.tmpl - servlet files} hides alot of extraneous details and is recommended for Cheetah -users who don't have a deep understanding of Python. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Converting .tmpl files into .py files} -\label{webware.tmpl.converting} - -There are two ways to convert \code{.tmpl servlet files} into \code{.py servlet - files}. You can let Cheetah's Webware plugin do it automatically when a -\code{.tmpl servlet file} is requested by a browser. Or you can generate the -\code{.py servlet files} using \code{cheetah-compile}, a small script that is -installed with Cheetah. - -Cheetah's Webware plugin is being re-designed at the moment. The redesign will -be complete for the 0.9.9 release. Until then use the \code{cheetah-compile} -script. - -\code{cheetah-compile} parses the template definitions written in files with the -.tmpl extension and generates a \code{.py servlet file} for each \code{.tmpl - servlet file}. On Unix systems, it is installed into a system directory like -\code{/usr/local/bin}, so you can use it without specifying the absolute path of -the script. On Windows systems, you need to specify the full path -(\code{<cheetahRoot>/bin/cheetah-compile}). Type ``\code{cheetah-compile}'' from the -command line after installing Cheetah to get usage information. The most common -usage is ``\code{cheetah-compile -R .}'', which will convert all the \code{.tmpl - servlet file} in the current directory and its subdirectories. - -\code{cheetah-compile} overwrites \code{.py servlet files} with the same -basename as \code{.tmpl servlet files} in a directory. For this reason, you -should make changes to the \code{.tmpl} version of the template rather than the -\code{.py} version. Any \code{.py servlet files} that are about to be -overwritten will are automatically backed up with the extension \code{.py\_bak}. - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Writing .tmpl servlet files} -\label{webware.tmpl.writing} - -Here's an example \code{.tmpl servlet file} with no Cheetah syntax in it: - -\begin{verbatim} -## FILE: hello_world.tmpl ## -<HTML> -<HEAD><TITLE>Hello World - Test Servlet</TITLE></HEAD> -<BODY> -Hello World! -</BODY> -</HTML> -\end{verbatim} - -Here's the previous example with some Cheetah syntax. Note that all lines that begin with -\code{\#\#} are comment lines. - -\begin{verbatim} -## FILE: hello_world.tmpl ## -##=================================== -#data -title = 'Hello World - Test Servlet' -def contents(): - return 'Hello World!' -#end data -##=================================== -<HTML> -<HEAD><TITLE>$title</TITLE></HEAD> -<BODY> -$contents -</BODY> -</HTML> -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Using .py servlet files} -\label{webware.py} - -When you manually create your Webware \code{.py servlet files} you need to -include some boiler-plate code that is handled automatically in \code{.tmpl - servlet files}. Specifically, you need to create a Python class that inherits -from Cheetah.Servlet, or a subclass, as in the trivial example below. - -\begin{verbatim} -## FILE: hello_world.py ## -template = """ -<HTML> -<HEAD><TITLE>'Hello World - Test Servlet</TITLE></HEAD> -<BODY> -Hello World! -</BODY> -</HTML> -""" -from Cheetah.Servlet import TemplateServlet -class hello_world(TemplateServlet): - def __init__(self): - TemplateServlet.__init__(self, template) -\end{verbatim} - -TemplateServlet's constructor method (\code{TemplateServlet.\_\_init\_\_()}) adds -the attribute dictionary of the servlet to the searchList that -\code{\$placeholder} variables can extracted from. Thus, attributes and methods -of the servlet object can be interpolated into the template like this: - -\begin{verbatim} -## FILE: hello_world.py ## -template = """ -<HTML> -<HEAD><TITLE>$title</TITLE></HEAD> -<BODY> -$contents -</BODY> -</HTML> -""" -from Cheetah.Servlet import TemplateServlet -class hello_world(TemplateServlet): - title = 'Hello World - Test Servlet' - def __init__(self): - TemplateServlet.__init__(self, template) - - def contents(self): - return 'Hello World!' -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{The SkeletonPage framework} -\label{webware.skeletonPage} - -Sect \ref{libraries.templates.skeletonPage} contains information on a stock -template that greatly simplifies defining the basic HTML structure of your web -page templates. It is equivalent to Webware's \code{WebKit.Page} servlet and -is well worth the time spent learning how to use it. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{Using the Containment approach} -\label{webware.containment} - -With the containment approach your template obj does not repond directly to a -request from Webware's AppServer. Rather, you use a non-Cheetah-specific servlet -to handle the request and use one or more Cheetah template objects inside the -servlet's \code{.respond()} method and send their output via the -\code{response.write()} method. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsubsection{Using \#include with the containment approach} -\label{webware.containment.includes} - -Webware's ``\code{current working directory}'' probably isn't the directory that -your servlet files are sitting in. All relative paths need to be adjusted so -they are relative to the servlet's directory and not Webware's \code{current - working directory}. Webware uses the \code{Servlet.serverSidePath()} method -for this purpose. - -The \code{TemplateServlet} class of the inheritance approach does the adjusment -automatically for all relative paths fed to \code{\#include} directive. When -using the containment approach you need to take a few extra steps to make -\code{\#include} directives work properly with relative paths. First, you need -to map \code{<yourTemplateObj>.normalizePath} to -\code{<yourServletObj>.serverSidePath}. Second, you need to make sure that -\code{<yourTemplateObj>} is compiled by your servlet's \code{awake()} method or -its \code{respond()} method as \code{.serverSidePath()} only works during -Webware's \code{awake-response-sleep} cycle. It cannot be compiled by you -servlet's \code{__init__()} method as \code{Servlet.serverSidePath()} doesn't -work there. Also note that due to a bug in Webware your servlet class must -inherit from \code{WebKit.Page} rather than just \code{WebKit.HTTPServlet} for -\code{.serverSidePath()} to work. - -\begin{verbatim} -<yourServlet>.__init__(): - # ... after setting up your 'templateDef' and 'nameSpace' - self.T = Template(templateDef, nameSpace, settings={'delayedCompile':1}) - self.T.normalizePath = self.serverSidePath - self._templateCompiled = 0 - -<yourServlet>.awake(trans): - <yourServlet's BaseClass>.awake(trans) - if not self._templateCompiled - self.T.compileTemplate() - self._templateCompiled = 1 - -<yourServlet>.respond(trans): - if not self._templateCompiled - self.T.compileTemplate() -\end{verbatim} - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{User interaction in either approach} -\label{webware.userInteraction} - -By {\bf user interaction} we mean the use of forms, query strings or sessions to -create interactive pages that allow user interation with a website. -[{\bf This section is under construction. Check back later.}] - - - -% Local Variables: -% TeX-master: "users_guide" -% End: @@ -1,110 +1,11 @@ #!/usr/bin/env python -# $Id: setup.py,v 1.8 2001/10/10 06:18:30 tavis_rudd Exp $ -"""A setup module for the Cheetah package, based on the disutils module +# $Id: setup.py,v 1.10 2001/10/10 06:59:45 tavis_rudd Exp $ -Meta-Data -========== -Author: Tavis Rudd <tavis@calrudd.com> -License: This software is released for unlimited distribution under the - terms of the Python license. -Version: $Revision: 1.8 $ -Start Date: 2001/03/30 -Last Revision Date: $Date: 2001/10/10 06:18:30 $ -""" -__author__ = "Tavis Rudd <tavis@calrudd.com>" -__version__ = "$Revision: 1.8 $"[11:-2] +import SetupTools +import SetupConfig +configurations = (SetupConfig,) +SetupTools.run_setup( configurations ) -################################################## -## DEPENDENCIES ## -from distutils.core import setup, Extension -from distutils.command.sdist import sdist - -import os -import os.path -import re - -################################################## -## CONSTANTS & GLOBALS ## - -True = (1==1) -False = (0==1) - - -################################################## -## CLASSES ## - -class sdist_docs(sdist): - """a setup command that will rebuild Users Guide""" - def run(self): - try: - from src.Version import version - - currentDir = os.getcwd() - os.chdir(os.path.join(currentDir,'docs','src')) - fp = open('users_guide.tex','r') - originalTexCode = fp.read() - fp.close() - - newTexCode = re.sub(r'(?<=\\release\{)[0-9\.]*',str(version), originalTexCode) - - fp = open('users_guide.tex','w') - fp.write(newTexCode) - fp.close() - - os.system('make -f Makefile') - os.chdir(currentDir) - except: - print "The sdist_docs command couldn't rebuild the Users Guide" - os.chdir(currentDir) - - sdist.run(self) - - -################################################## -## if run from the command line ## - -if __name__ == '__main__': - from src.Version import version - - from src import __doc__ - README = open('README','w') - README.write(__doc__) - README.close() - synopsis = __doc__.split('\n')[0] - - if os.name == 'posix': - ext_modules=[Extension("Cheetah/_namemapper", ["src/_namemapper.c"]), - Extension("Cheetah/Foo", ["src/Foo.c"])] - else: - ext_modules=[] - - packages = ['Cheetah', - 'Cheetah.Templates', - 'Cheetah.Plugins', - 'Cheetah.Macros', - 'Cheetah.Tests', - 'Cheetah.Tools', - ] - - setup (name = "Cheetah", - author = "The Cheetah Development Team", - author_email = "cheetahtemplate-devel@sourceforge.net", - version = version, - license = "The Python License", - description = synopsis, - long_description = __doc__, - maintainer = "Tavis Rudd", - url = "http://www.cheetahtemplate.org", - packages = packages, - package_dir = {'Cheetah':'src'}, - - ext_modules=ext_modules, - - scripts = ['bin/cheetah-compile',], - - cmdclass = { 'sdist_docs' : sdist_docs }, - ) - |