diff options
Diffstat (limited to 'docs/users_guide_2_src')
33 files changed, 6349 insertions, 0 deletions
diff --git a/docs/users_guide_2_src/01_introduction.txt b/docs/users_guide_2_src/01_introduction.txt new file mode 100755 index 0000000..34beeb6 --- /dev/null +++ b/docs/users_guide_2_src/01_introduction.txt @@ -0,0 +1,291 @@ +Introduction +============ + +.. + :label: intro + +Who should read this Guide? +--------------------------- + +.. + :label: intro.whoShouldRead + +This Users' Guide is for Python programmers. Part I is a tutorial/reference +and should be read by everybody. Part II is a cookbook of of techniques for +using Cheetah with various web frameworks and various non-HTML output formats, +plus some technical appendices. The PDF version of this Guide is distributed +as two files so you can print Part I to read offline without having to print a +lot of pages from Part II that don't apply to you. + +What is Cheetah? +---------------- + +.. + :label: intro.whatIs + +Cheetah is a template engine for Python. A template engine is like Python's +``%`` operator for strings: it has fixed parts which are output verbatim, and +*placeholders* which are replaced by their values:: + + # Python's "%" operator (not Cheetah) + >>> "The king is a %(noun)s!" % {"noun": "fink"} + 'The king is a fink!" + +Templates are useful for form letters, dynamic web pages, customized source +code or SQL, and innumerable other tasks. Cheetah is like a super-powered +``%`` operator, but it also has many other features needed in real-world +templating situations. + +Viewed another way, Cheetah is an alternate source format for Python modules, +one that's friendlier for large chunks of text. Compiled templates are +ordinary Python modules which can be imported. Cheetah is one of Python's +oldest template engines and perhaps the most widely used. This is mainly due +to its speed (hence the name Cheetah), stability, and suitability for many +output formats. Cheetah has been used in production environments since 2001 +(0.9.9a1), and changes are committed conservatively, so even the CVS version is +usually more bug-free than the previous release. + +Cheetah's syntax uses ``$`` before placeholders and a ``#`` +before control structures (directives), although these characters can be +changed. This differs from Python's other template systems which generally use +XML tags (Kid and Tal) or a function syntax (PTL and QPY). The difference +allows Cheetah to be more suitable for a variety of output formats, and even +users of the other systems often use Cheetah for non-HTML output such as +text, Python source code, or SQL. Cheetah's syntax and behavior was +inspired most directly by Velocity, a Java template engine. In PHP, Smarty is +Cheetah's closest equivalent. Cheetah templates tend to be function-driven: +define a method with ``#def``, and call it via a placeholder with arguments. +Cheetah also has PSP-style tags (``<% %>``) and ``#include``, which will be +familiar to people coming from ASP/JSP/PHP. However, we'll argue that these +should be used sparingly, since there are other constructs which are more +readable. + + +Cheetah: + +* generates HTML, SGML, XML, SQL, Postscript, form email, LaTeX, or any + other text-based format. It has also been used to produce Python, Java + and PHP source code. + +* cleanly separates content, graphic design, and program code. This leads + to highly modular, flexible, and reusable site architectures; faster + development time; and HTML and program code that is easier to understand + and maintain. It is particularly well suited for team efforts. + +* blends the power and flexibility of Python with a simple template language + that non*programmers can understand. + +* gives template writers full access in their templates to any Python data + structure, module, function, object, or method. + +* makes code reuse easy by providing an object-oriented interface to + templates that is accessible from Python code or other Cheetah templates. + One template can subclass another and selectively reimplement sections of + it. A compiled template {\em is} a Python class, so it can subclass a + pure Python class and vice*versa. + +* provides a simple yet powerful caching mechanism + +Here's a simple example of a Cheetah template:: + + <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> + +* has a lot of features but most of them are optional. Cheetah is easy to use + in simple cases, and scales well to complex cases. Most of Cheetah's + features were added due to demonstrated needs in production environments + where Cheetah was already runing. + +Cheetah is distributed under a BSD-style open-source license. See appendix E +(E_license.txt) for details. Cheetah exists thanks to the help of many +open-source volunteers (http://cheetahtemplate.sourceforge.net/credits.html). + + + +What is the philosophy behind Cheetah? +-------------------------------------- + +.. + :label: intro.philosophy + +Cheetah's design was guided by these principles: + +* Python for the back end (business logic), Cheetah for the front end + (presentation format). Cheetah was designed to complement Python, not + replace it. + +* Cheetah's core syntax should be easy for non-programmers to learn. + +* Cheetah should make code reuse easy by providing an object-oriented + interface to templates that is accessible from Python code or other + Cheetah templates. + +* Python objects, functions, and other data structures should be fully + accessible in Cheetah. + +* Cheetah should provide flow control and error handling. Logic + that belongs in the front end shouldn't be relegated to the + back end simply because it's complex. + +* It should be easy to {\bf separate} content, graphic design, and program + code, but also easy to {\bf integrate} them. + + A clean separation makes it easier for a team of content writers, + HTML/graphic designers, and programmers to work together without stepping + on each other's toes and polluting each other's work. The HTML framework + and the content it contains are two separate things, and analytical + calculations (program code) is a third thing. Each team member should be + able to concentrate on their specialty and to implement their changes + without having to go through one of the others (i.e., the dreaded + "webmaster bottleneck"). + + While it should be easy to develop content, graphics and program + code separately, it should be easy to integrate them together into a + website. In particular, it should be easy: + + - for {\bf programmers} to create reusable components and functions + that are accessible and understandable to designers. + - for {\bf designers} to mark out placeholders for content and + dynamic components in their templates. + - for {\bf designers} to soft-code aspects of their design that are + either repeated in several places or are subject to change. + - for {\bf designers} to reuse and extend existing templates and thus + minimize duplication of effort and code. + - and, of course, for {\bf content writers} to use the templates that + designers have created. + +* Features are added only to support a demonstrated need in production + applications, and generally only if the feature is useful for a wide variety + of situations and output formats. This prevents Cheetah from accumulating + lots of esoteric features which are used only rarely. + + +Why Cheetah doesn't use HTML-style tags +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +.. + :label: intro.htmlStyleTags + +Cheetah does not use HTML/XML-style tags for flow control, unlike some other +Python template engines, for the following reasons: + +* Cheetah is not limited to HTML, +* HTML-style tags are hard to distinguish from real HTML tags, +* HTML-style tags are not visible in rendered HTML when something goes wrong, +* HTML-style tags often lead to invalid HTML (e.g., + \code{<img src="<template*directive>">}), + +Cheetah tags are less verbose and easier to understand than HTML-style tags, +and HTML-style tags aren't compatible with most WYSIWYG editors. In a WSYWIG +editor, Cheetah tags appear to be literal text. + +Besides being much more compact, Cheetah also has some advantages over +languages that put information inside the HTML tags, such as Zope Page +Templates or PHP: + +* HTML or XML-bound languages do not work well with other languages, +* While ZPT-like syntaxes work well in many ways with WYSIWYG HTML editors, + they also give up a significant advantage of those editors -- concrete + editing of the document. When logic is hidden away in (largely + inaccessible) tags it is hard to understand a page simply by viewing it, + and it is hard to confirm or modify that logic. + + +How stable is Cheetah? How do I upgrade? +----------------------------------------- + +.. + :label: intro.stable + +Cheetah 2.0 was released [MONTH] [YEAR] with internal restructuring, +easier-to-understand usage, updated documentation, and many other improvements. +Cheetah 1.0 was released December 2005 after a three-year stable beta. +Production sites have been using Cheetah since 2001. Most changes since then +have been based on requests from production sites: things they need that we +hadn't considered. + +Templates and calling code from Cheetah 1.0 remain 100% compatible. Those from +pre-1.0 versions since December 2001 (0.9.9) remain compatible except in rare +cases. + +.. important:: + You must recompile all precompiled templates when upgrading + to Cheetah 2.0. + +Upgrades from 2.0 to a future version may or may not require +recompilation. Try filling a single precompiled template and see if you get a +version exception. If you do, recompile them all. Or to be safe on a +production site, just recompile them all anyway. + +Cheetah's development version is normally as stable as the last release if not +better. All CVS checkins are installed and run through the test suite before +being checked in. + +Additional information is in these files in the Cheetah source distribution: + +CHANGES: + All changes in each version. +BUGS: + Known bugs we haven't fixed yet. +TODO: + Enhancements we're planning, thing's like to do someday, and user requests + we haven't committed to. + + +Web site and mailing list +------------------------- + +.. + :label: intro.news + +Cheetah releases and other stuff can be obtained from the the Cheetah +{\bf Web site}: +\url{http://CheetahTemplate.sourceforge.net} + +Cheetah discussions take place on the {\bf mailing list} +\email{cheetahtemplate-discuss@lists.sourceforge.net}. This is where to hear +the latest news first. + +If you encounter difficulties, or are unsure about how to do something, +please post a detailed message to the list. Also please share your +experiences, tricks, customizations, and frustrations. And if you have a +success story for the "Who Is Using Cheetah" +(http://cheetahtemplate.sourceforge.net/whouses.html) or +"Testimonials" (http://cheetahtemplate.sourceforge.net/praise.html) +page on the website, send it to the mailing list. + + +Bug reports, patches, and the test suite +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +If you think there is a bug in Cheetah, send a message to the mailing list +with the following information: + +* a description of what you were trying to do and what happened +* all tracebacks and error output +* your version of Cheetah +* your version of Python +* your operating system +* whether you have changed anything in the Cheetah installation + +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". (@@MO Shorten +paragraph, link to testing section.) + diff --git a/docs/users_guide_2_src/02_glossary.txt b/docs/users_guide_2_src/02_glossary.txt new file mode 100644 index 0000000..49988fd --- /dev/null +++ b/docs/users_guide_2_src/02_glossary.txt @@ -0,0 +1,66 @@ +Glossary +======== + +.. + :label: glossary + +**Template** is an informal term meaning a template definition, a template +class or a template instance. A **template definition** is what the human +maintainer writes: a file or string consisting of text, placeholders and +directives. **Placeholders** are variables that will be looked up when the +template is filled. **Directives** are commands to be executed when the +template is filled, or instructions to the Cheetah compiler. Placeholders +normally start with "$"; directives with "#". The conventional suffix for a +file containing a template definition is **.tmpl**. + +To use a template, you first **compile** the template definition into +**template class**. Then you instantiate the class and **fill** it by calling +one of its instance methods. Filling does all the placeholder lookups and +returns the finished result. Templates can be compiled in memory or written to +a Python module, called a **precompiled template**. + +Every template has a **main** method that fills the entire template. The main +method is usually ``.respond()``. Calling ``str()`` or ``unicode()`` on a +template instance is the same as calling the main method. Templates can also +contain **#def methods** (via ``#def`` or ``#block``), which can be called +directly. + +A **placeholder** consists of one or more **identifiers** separated by periods. +Identifiers must follow the same rules as Python variable names, and may be +followed by the usual ``[]`` and ``()`` as in Python. Example with three +identifiers: ``a.b[2].c("arg")``. The value discovered at fill time is the +**placeholder value**. + +The first (or only) identifier of a placeholder name represents a **variable** +to be looked up. If Cheetah's **NameMapper** is turned on (the default), it +looks in various **namespaces** including the template instance's ``self``, +Python variables local/global to the template method, and an arbitrary list of +**user-defined namespaces** you may have passed to the template constructor. +A user-defined namespace is any Python object; Cheetah searches its attributes +and keys for a matching name. ``#set`` and ``#for`` create local +variables. ``#import`` and ``#set module global`` create global variables. +``#attr``, ``#def``, and ``#block`` create ``self`` variables. When the +NameMapper is turned off, only local/global variables are accessible. + +The NameMapper also handles universal dotted notation and autocalling. +**Universal dotted notation** means that keys may be written as if they were +attributes: ``a.b`` instead of ``a['b']``. **Autocalling** means that +if any identifier's value is found to be a function or method, Cheetah will +call it without arguments if there is no ``()`` following. More about the +NameMapper is in section \ref{language.namemapper}. + +Cheetah 1 used the term "searchList" for user-defined namespaces. However, +Cheetah has another **search list** internally: the actual list of namespaces +it consults. This is almost the same thing but not quite. To avoid confusion, +this Guide uses the term "search list" only for the internal list. + +Some directives are multi-line, meaning they have a matching **\#end** tag. +The lines of text between the start and end tags is the **body** of the +directive. Arguments on the same line as the start tag, in contrast, are +considered part of the directive tag. + +A **template-servlet** is a Webware_-specific construct. Any .py template +module in a Webware servlet directory can be filled directly through the web by +requesting the URL. + +.. _Webware: http://www.webwareforpython.org/ diff --git a/docs/users_guide_2_src/03_gettingStarted.txt b/docs/users_guide_2_src/03_gettingStarted.txt new file mode 100755 index 0000000..6e447c2 --- /dev/null +++ b/docs/users_guide_2_src/03_gettingStarted.txt @@ -0,0 +1,262 @@ +Getting Started +======================================== + +.. + :label: gettingStarted + + +Requirements +---------------------------------------- + +.. + :label: gettingStarted.requirements + +Cheetah requires Python release 2.2 or newer, and has been tested with all +versions through 2.4.2. It should run everywhere Python runs, and has been +tested on Linux, Windows NT/98/XP, FreeBSD, Solaris, and Mac OS X. + +99% of Cheetah is written in Python. There is one small C module +(``_namemapper.so``) for speed, but Cheetah automatically falls back to a +Python equivalent (``NameMapper.py``) if the C module is not available. + + +Installation +---------------------------------------- + +.. + :label: gettingStarted.install + +If you have ``easy_install`` +(http://peak.telecommunity.com/DevCenter/EasyInstall) set up, this command will +download and install the latest version of Cheetah as a Python Egg +(http://peak.telecommunity.com/DevCenter/PythonEggs):: + + # easy_install Cheetah + +Or from an already-downloaded tarball:: + + # easy_install Cheetah-2.0.tar.gz + +Or from an unpacked source directory or CVS sandbox:: + + # easy_install . + +If you don't have ``easy_install``, you'll have to install Cheetah manually:: + + # tar xzvf Cheetah-2.0.tar.gz + # cd Cheetah-2.0 + # python setup.py install + +You can also specify non-default locations:: + + # python setup.py install --install-lib=/home/tavis/python + # python setup.py install --home=/home/tavis + # python setup.py install --help + +.. tip:: + + If you install Cheetah manually and then install an egg that depends on + Cheetah (like TurboCheetah_), ``easy_install`` may *reinstall* + Cheetah as an egg. This leaves two copies of Cheetah on your system, + possibly different versions. Python will use whichever version comes + first in the Python path. To avoid this, use ``easy_install``'s + **--no-deps** option or delete the copy you don't wish to use. + + +Uninstalling +---------------------------------------- + +.. + :label: gettingstarted.uninstalling + +To uninstall Cheetah: + +1. Delete the "cheetah" program +from whichever bin/ directory it was put in (perhaps /usr/local/bin/). + +2. If Cheetah was installed as an egg, delete the egg directory +(e.g., /usr/local/lib/python2.4/site-packages/Cheetah-2.0-py2.4.egg/), and +remove the "Cheetah" line in **easy-install.pth** in the same directory. + +3. If Cheetah was not installed as an egg, delete the package directory +(e.g., /usr/local/lib/python2.4/site-packages/Cheetah/). + + +The 'cheetah' command +---------------------------------------- + +.. + :label: gettingStarted.cheetah + +Cheetah comes with a utility "cheetah" that provides a command-line +interface to various housekeeping tasks. The command's first argument is +the name of the task. The following commands are currently supported:: + + cheetah compile [options] [FILES ...] : Compile template definitions + cheetah fill [options] [FILES ...] : Fill template definitions + cheetah help : Print this help message + cheetah options : Print options help message + cheetah test : Run Cheetah's regression tests + cheetah version : Print Cheetah version number + +You only have to type the first letter of the command: +``cheetah c`` is the same as ``cheetah compile``. + +The test suite is described in the next section. The ``compile`` +command in section \ref{howWorks.cheetah-compile}, +and the ``fill`` command in section \ref{howWorks.cheetah-fill}. + + +Testing your installation +---------------------------------------- + +.. + :label: gettingStarted.test + +After installing Cheetah, you can run its self-test routine to verify it's +working properly on your system. First cd to to any directory you have write +permission in (the tests write temporary files) *except* the unpacked Cheetah +source directory (it might produce spurious errors). Type the following at the +command prompt:: + + $ cheetah test + +The tests will run for about three minutes and print a success/failure +message. If the tests pass, start Python in interactive mode and try the +example in the next section. + +Sometimes the CheetahWrapper tests fail on Windows because they can't execute +"cheetah" via ``os.system()``. Ignore these; you won't be doing this when +you use Cheetah. + +If any other tests fail, please send a message to the e-mail list with a copy +of the test output and the following details about your installation: + +* your version of Cheetah +* your version of Python +* your operating system +* whether you have changed anything in the Cheetah installation + + + +Quickstart tutorial +---------------------------------------- + +.. + :label: gettingStarted.tutorial + +This tutorial briefly introduces how to use Cheetah from the Python prompt. +The following chapters will discuss other ways to use templates and more of +Cheetah's features. + +The core of Cheetah is the ``Template`` class in the ``Cheetah.Template`` +module. The following example shows how to use the ``Template`` class in an +interactive Python session. ``t`` is the Template instance. Lines prefixed +with ``>>>`` and ``...`` are user input. The remaining lines are Python +output. :: + + >>> from Cheetah.Template import Template + >>> templateDef = """ + ... <HTML> + ... <HEAD><TITLE>$title</TITLE></HEAD> + ... <BODY> + ... $contents + ... ## this is a single-line Cheetah comment and won't appear in the output + ... #* This is a multi-line comment and won't appear in the output + ... blah, blah, blah + ... *# + ... </BODY> + ... </HTML>""" + >>> namespace = {'title': 'Hello World Example', 'contents': 'Hello World!'} + >>> t = Template(templateDef, namespaces=[namespace]) + >>> print t + + <HTML> + <HEAD><TITLE>Hello World Example</TITLE></HEAD> + <BODY> + Hello World! + </BODY> + </HTML> + >>> print t # print it as many times as you want + [ ... same output as above ... ] + >>> namespace['title'] = 'Example #2' + >>> namespace['contents'] = 'Hiya Planet Earth!' + >>> print t # Now with different plug-in values. + <HTML> + <HEAD><TITLE>Example #2</TITLE></HEAD> + <BODY> + Hiya Planet Earth! + </BODY> + </HTML> + +Because Cheetah is extremely flexible, you can achieve the same result this +way:: + + >>> t2 = Template(templateDef) + >>> t2.title = 'Hello World Example!' + >>> t2.contents = 'Hello World' + >>> print t2 + [ ... same output as the first example above ... ] + >>> t2.title = 'Example #2' + >>> t2.contents = 'Hello World!' + >>> print t2 + [ ... same as Example #2 above ... ] + +Or the values can be extracted from an object's attributes. + + >>> myInstance.title + 'Hello World Example!' + >>> myInstance.contents = 'Hello World!' + >>> t2 = Template(templateDef, namespaces=[myInstance]) + +The template will search your namespaces in order, then its own ``self`` +attributes, until it finds a match. The template definition can also +come from a file rather than a string. + +Let's look at the ``Template`` constructor again:: + + t = Template(templateDef, namespaces=[namespace]) + +This does more than it appears. It compiles the template definition into a +template class, a subclass of ``Template``, and instantiates it. Sometimes +it's desirable to separate these operations, and the ``.compile`` class method +does this:: + + tclass = Template.compile(templateDef) + t = tclass(namespaces=[namespace]) + +The first line compiles the template class; the second line instantiates it. +You can also do this on one line:: + + t = Template.compile(templateDef)(namespaces=[namespace]) + +You can use either ``Template()`` or ``Template.compile()`` in your programs, +but you should learn both styles so you'll recognize them in other people's +code. + +This is all fine for short templates, but for long templates or for an +application that depends on many templates, it's easier to store the templates +in separate \*.tmpl files and use the **cheetah** program to compile +them into Python modules. This will be covered in section +\ref{howWorks.cheetah-compile}. Here's how you use a precompiled template:: + + >>> from MyPrecompiledTemplate import MyPrecompiledTemplate + >>> t = MyPrecompiledTemplate() + >>> t.name = "Fred Flintstone" + >>> t.city = "Bedrock City" + >>> print t + +Or:: + + >>> from MyPrecompiledTemplate import MyPrecompiledTemplate + >>> namespace = {"name": "Fred Flintstone", "city": "Bedrock City"} + >>> t = MyPrecompiledTemplate(namespaces=[namespace]) + >>> print t + +For the minimalists out there, here's a template compilation, +instantiation and filling all in one Python statement:: + + >>> print Template("Templates are pretty useless without placeholders.") + Templates are useless without placeholders. + +.. _TurboCheetah: http://python.org/pypi/TurboCheetah/ diff --git a/docs/users_guide_2_src/04_howItWorks.txt b/docs/users_guide_2_src/04_howItWorks.txt new file mode 100755 index 0000000..17ee3d5 --- /dev/null +++ b/docs/users_guide_2_src/04_howItWorks.txt @@ -0,0 +1,369 @@ +How Cheetah Works +================= + +.. + :label: howWorks + + + +Constructing Template Objects +----------------------------- + +.. + :label: howWorks.templateClass + +.. + :label: howWorks.constructing + +The heart of Cheetah is the ``Template`` class in the +``Cheetah.Template`` module. There are several ways to construct templates, +each with slightly different arguments. Where *source* is shown, it's always +the first argument and may be specified positionally. The order of the +other arguments may change, so always specify them as keyword arguments. + +``Template()`` accepts the following arguments: + + source + The template definition as a string. The source can be a string + literal in your module, or perhaps a string you read from a database + or other data structure. + + file + A filename or file object containing the template definition. A + filename must be a string, and a file object must be open for reading. + By convention, template definition files have the extension **.tmpl**. + + namespaces, searchList + A list of objects which Cheetah will search for placeholder values. + (Cheetah also searches certain other objects automatically; see the + "Placeholders" chapter for details.) Use either argument; they both + mean the same thing. + + filter + Equivalent to putting ``#filter`` at the top of the template. The + argument may be a subclass of ``Cheetah.Filters.Filter``, or a string + naming a class in filtersLib (the next argument below). See + ``#filter`` for details. + + filtersLib + A module containing the filters Cheetah should look up by name. The + default is ``Cheetah.Filters``. All classes in this module that are + subclasses of ``Cheetah.Filters.Filter`` are considered filters. + + errorCatcher + Equivalent to putting ``#errorCatcher`` at the top of the template. + The object may be a subclass of ``Cheetah.ErrorCatchers.ErrorCatcher``, + or a string naming a class in ``Cheetah.ErrorCatchers``. See + ``#errorCatcher`` for details. + + compilerSettings + Equivalent to putting ``#compiler-settings`` at the top of the + template. The argument is a dictionary or nesting of dictionaries. + See ``#compiler-settings`` for details. + +A template class returned by ``Cheetah.compile`` or precompiled via "cheetah +compile" takes the same constructor arguments as above, except "source" and +"file" which are not allowed. Use keyword arguments for all arguments +because their order may change. + +The class method ``Template.compile()`` takes the following +arguments: + + source, file, compilerSettings + Same as above. *These are the only arguments most users will ever + use.* The other args below are for specialized advanced uses. + + returnAClass + If true (default), return a subclass of ``Template`` specific to this + template definition. If false, return the Python source of a module + containing this class; i.e., what "cheetah compile" would write to a + file. + + moduleName, className, mainMethodName + Override the default names. For instance, TurboCheetah (a third-party + library) requires its templates to have a fixed class name, so it uses + *className*. + + compilerClass + Use an You'll probably never need this. + + baseclass + Equivalent to putting ``#extends`` at the top of the template. + ``#extends`` overrides this, unlike other arguments. + + moduleGlobals + In case you want to sneak in some extra variables that don't require + the NameMapper. + + preprocessors + A list of filter functions which will modify the template definition + before Cheetah's compiler sees it. See chapter @@MO for details. + + compilerClass, cacheCompilationResults, useCache, cacheModuleFilesForTracebacks, cacheDirForModuleFiles, keepRefToGeneratedCode + You'll probably never need these. They are used to provide an + alternate compiler, disable Cheetah's template caching (*not* related + to ``#cache``), or modify Cheetah's enhanced traceback reporting. See + the ``Template.compile()`` docstring for details. + +Here are typical ways to create a template instance: + +``t = Template("The king is a \$placeholder1.")`` + Pass the template definition as a string. +``t = Template(file="fink.tmpl")`` + Read the template definition from a file named "fink.tmpl". +``t = Template(file=f)`` + Read the template definition from file-like object 'f'. +``t = Template("The king is a \$placeholder1.", namespaces=[dict, obj])`` + Pass the template definition as a string. Also pass two namespaces for + the namespaces: a dictionary 'dict' and an instance 'obj'. +``t = Template(file="fink.txt", namespaces=[dict, obj])`` + Same, but pass a filename instead of a string. +``t = Template(file=f, namespaces=[dict, obj])`` + Same with a file object. + +Filling templates and extracting data +------------------------------------- + +There are several ways to fill a template. Assume ``t`` is a template +instance:: + + 1 output = t.respond() + 2 output = str(t) # Shortcut for "str(t.respond())". + 3 output = unicode(t) # Shortcut for "unicode(t.respond())". + 4 print t # Shortcut for "print str(t.respond())". + 4 sys.stderr.write( unicode(t).encode('latin1') ) + 5 result = t.my_def_method(arg1, arg2) + +These all assume the template's main method is ``.respond``, which is true +in the normal case. [#]_ ``str()`` and +``unicode()`` will always call the main method whatever it's named. + +If the output contains non-ASCII characters, examples 2 and 4 will raise +an exception. Use one of the other examples instead. + +Example 5 calls a ``#def`` method with arguments. Only that method's output +is returned. + +If the template contains ``#attr`` attributes, you can access those directly:: + + title = t.title + author = t.author + + +.. [#] See the Inheritance chapter... (#implements, mainMethodName, + inheritance). + +"cheetah compile" and precompiled templates +------------------------------------------- + +.. + :label: howWorks.cheetah-compile + +To create a precompiled template module, do either of these:: + + cheetah compile [options] [FILES ...] + cheetah c [options] [FILES ...] + +There are several advantages of precompiled templates: + +- Precompiled templates are easier to debug because you can see the generated + Python code, and the line numbers in error messages will correspond to the + actual line in the template definition file. (If the template definition is + embedded in a string literal inside a module, you'll have to count down from + the first line in the string to find the error line.) + +- Data analysis programs can import the template classes and query their + attributes, which can be set via ``#attr``. Example: a directory of + templates can each contain ``.title`` and ``.author`` attributes, and + another program can read them all and make an index page. + +- Slightly faster performance since the compilation is done before + the user runs your application, and Python will optimize this further + with .pyc or .pyo files. The actual speed difference is minimal -- + Cheetah appears to compile templates instantaneously anyway, and it caches + templates in memory if possible, but precompiling templates will make + some developers feel better for conserving electrons. + +- ``#extends`` requires that the base template be precompiled, or the + child template cannot be instantiated. (@@MO: The *baseclass* constructor + arg can be used to set the parent class for a dynamically-compiled + template.) + +- Only precompiled templates may be used as Webware servlets. + +Some of Cheetah's developers use only precompiled templates and recommend the +same. However, it's your choice whether to do this. + +The following options are supported:: + + --idir DIR, --odir DIR : input/output directories (default: current dir) + --iext EXT, --oext EXT : input/output filename extensions + (default input: tmpl, default output: py) + -R : recurse subdirectories looking for input files + --debug : print lots of diagnostic output to standard error + --flat : no destination subdirectories + --nobackup : don't make backups + --stdout, -p : output to standard output (pipe) + --settings : a string representing the compiler settings to use + e.g. --settings='useNameMapper=False,useFilters=False' + This string is eval'd in Python so it should contain + valid Python syntax. + --templateAPIClass : a string representing a subclass of + Cheetah.Template:Template to use for compilation + +.. tip:: + If Cheetah can't find your input files, or if it puts output files + in the wrong place, use the ``--debug`` option to see how Cheetah + interpreted your command line. + +The most basic usage is:: + + cheetah compile a.tmpl : writes a.py + cheetah compile a.tmpl b.tmpl : writes a.py and b.py + + +Cheetah will automatically add the default input extension (.tmpl) if the exact +file is not found. So the following two examples are the same as above if +"a" and "b" don't exist:: + + cheetah compile a : writes a.py (from a.tmpl) + cheetah compile a b : writes a.py and b.py + + +Use the ``-R`` option to recurse subdirectories:: + + cheetah compile dir1 : error, file is a directory + cheetah compile -R dir1 : look under `dir1' for files to compile + cheetah compile : error, no file specified + cheetah compile -R : compile all templates under current + directory and subdirectories + cheetah compile -R a b dir1 : compile files and recurse + +When recursing, only regular files that end in the input extension (.tmpl) are +considered source files. All other filenames are ignored. + +The options ``--idir`` and ``--odir`` allow you to specify that +the source (and/or destination) paths are relative to a certain directory +rather than to the current directory. This is useful if you keep your +\*.tmpl and \*.py files in separate directory hierarchies. After editing a +source file, just run one of these (or put the command in a script or +Makefile):: + + cheetah compile --odir /var/webware a.tmpl + cheetah compile -R --odir /var/webware + cheetah c --odir /var/webware sub/a.tmpl + : writes /var/webware/sub/a.py + + +"cheetah compile" overwrites any existing ``.py`` file it finds, after +backing it up to FILENAME.py_bak (unless you specify ``--nobackup``). For +this reason, you should make changes to the ``.tmpl`` version of the +template rather than to the ``.py`` version. + +For the same reason, if your template requires custom Python methods or +other Python code, don't put it in the ``FILENAME.py`` file or it will be +overwritten! Instead, put it in a separate base class and use +``#extends`` to inherit from it. + +Because FILENAME will be used as a class and module name, it must be a valid +Python identifier. For instance, ``cheetah compile spam-eggs.tmpl`` is +illegal because of the hyphen ("-"). This is sometimes inconvenient when +converting a site of HTML files into Webware servlets. Fortunately, the +*directory* it's in does not have to be an identifier. (*Hint:* for +date-specific files, try converting 2002/04/12.html to 2002/04/12/index.tmpl. +This also gives you a directory to store images or supplemental files.) + +Occasionally you may want output files put directly into the output directory +(or current directory), rather than into subdirectories parallel to the input +file. The ``--flat`` option does this. This may cause several input files +might map to the same output file. Cheetah checks for output file collisions +before writing any files, and aborts if there are any collisions. :: + + cheetah c sub/a.py : writes sub/a.py + cheetah c --flat sub/a.py : writes a.py + cheetah c --odir DEST sub/a.tmpl + : writes DEST/sub/a.py + cheetah c --flat --odir DEST sub/a.tmpl + : writes DEST/a.py + cheetah c --idir /home/henry sub/rollins.tmpl + : writes sub/rollins.py + cheetah c --flat --idir /home/henry sub/rollins.tmpl + : writes rollins.py + cheetah c --idir /home/henry --odir /home/henry sub/rollins.tmpl + : writes /home/henry/sub/rollins.py + cheetah c --flat --idir /home/henry --odir /home/henry sub/rollins.tmpl + : writes /home/henry/rollins.py + + +Whenever "cheetah compile" has to create an output directory or subdirectory, +it also creates an __init__.py file in it. This file is necessary in order +to make Python treat the directory as a Python package. + +Chapter @@MO has a look inside a precompiled template module. + +"cheetah fill" +-------------- + +.. + :label: howWorks.cheetah-fill + +You can fill templates from the command line with "cheetah fill". The most +common example is static HTML files which are generated from templates. The +output extension is .html by default. The compiled template modules are not +written to disk. All the options to "cheetah compile" are allowed. + +Examples:: + + cheetah fill a.tmpl : writes a.html + cheetah fill a.tmpl b.tmpl : writes a.html and b.html + cheetah f --oext txt a : writes a.txt (from a.tmpl) + +You can't specify user-defined namespaces the normal way, so the templates must +be written to have default values for all variables. However, there is limited +support for gathering placeholder values from operating-system resources:: + + --env : make the environment variables a user-defined namespace + --pickle FILE : unpickle FILE and make that object a user-defined namespace + +Using ``--env`` may have security or reliability implications because the +environment normally contains lots of variables you inherited rather than +defining yourself. If any of these variables override any of yours (say a +``#def``), you will get incorrect output, may reveal private information, +and may get an exception due to the variable being an unexpected type +(environment variables are always strings). Your calling program may wish +to clear out the environment before setting environment variables for the +template. + +There are two other differences between "cheetah compile" and "cheetah fill". +Cheetah doesn't create __init__.py files when creating directories in +fill mode. Also, the source filenames don't have to be identifiers. This +allows you to create any .html filename even if it contains characters like "-" +that are illegal in identifiers. + + +Running a .py template module as a standalone program +----------------------------------------------------- + +.. + :label: howWorks.standalone + +In addition to importing your .py template module file into a Python +script or using it as a Webware servlet, you can also run it from the +command line as a standalone program. The program will print the filled +template on standard output. This is useful while debugging the template, +and for producing formatted output in shell scripts. + +When running the template as a program, you cannot provide a searchList or +set ``self.`` attributes in the normal way, so you must take +alternative measures to ensure that every placeholder has a value. +Otherwise, you will get the usual ``NameMapper.NotFound`` exception at +the first missing value. You can either set default values in the template +itself (via the ``\#attr`` or ``\#def`` directives) or in a Python +superclass, or use the ``--env`` or ``--pickle`` command-line options, +which work just like their "cheetah fill" counterparts. + +Run ``python FILENAME.py --help`` to see all the command-line +options your .py template module accepts. + + + diff --git a/docs/users_guide_2_src/05_language.txt b/docs/users_guide_2_src/05_language.txt new file mode 100755 index 0000000..673abca --- /dev/null +++ b/docs/users_guide_2_src/05_language.txt @@ -0,0 +1,651 @@ +\section{Language Overview} +\label{language} + +Cheetah's basic syntax was inspired by the Java-based template engines Velocity +and WebMacro. It has two types of tags: {\bf \$placeholders} and {\bf +\#directives}. Both types are case-sensitive. + +Placeholder tags begin with a dollar sign (\code{\$varName}) and are similar to +data fields in a form letter or to the \code{\%(key)s} fields on the left side +of Python's \code{\%} operator. When the template is filled, the placeholders +are replaced with the values they refer to. + +Directive tags begin with a hash character (\#) and are used for comments, +loops, conditional blocks, includes, and all other advanced features. +({\em Note:} you can customize the start and end delimeters for placeholder +and directive tags, but in this Guide we'll assume you're using the default.) + +Placeholders and directives can be escaped by putting a backslash before them. +\verb+\$var+ and \verb+\#if+ will be output as literal text. + +A placeholder or directive can span multiple physical lines, following the same +rules as Python source code: put a backslash (\verb+\+) at the end of all +lines except the last line. However, if there's an unclosed parenthesis, +bracket or brace pending, you don't need the backslash. + +\begin{verbatim} +#if $this_is_a_very_long_line and $has_lots_of_conditions \ + and $more_conditions: +<H1>bla</H1> +#end if + +#if $country in ('Argentina', 'Uruguay', 'Peru', 'Colombia', + 'Costa Rica', 'Venezuela', 'Mexico') +<H1>Hola, senorita!</H1> +#else +<H1>Hey, baby!</H1> +#end if +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Language Constructs -- Summary} +\label{language.constructs} + +\begin{enumerate} +\item Comments and documentation strings + \begin{enumerate} + \item \code{\#\# single line} + \item \code{\#* multi line *\#} + \end{enumerate} + +\item Generation, caching and filtering of output + \begin{enumerate} + \item plain text + \item look up a value: \code{\$placeholder} + \item evaluate an expression: \code{\#echo} \ldots + \item same but discard the output: \code{\#silent} \ldots + \item one-line if: \code{\#if EXPR then EXPR else EXPR} + \item gobble the EOL: \code{\#slurp} + \item parsed file includes: \code{\#include} \ldots + \item raw file includes: \code{\#include raw} \ldots + \item verbatim output of Cheetah code: \code{\#raw} \ldots \code{\#end raw} + \item cached placeholders: \code{\$*var}, \code{\$*<interval>*var} + \item cached regions: \code{\#cache} \ldots \code{\#end cache} + \item set the output filter: \code{\#filter} \ldots + \item control output indentation: \code{\#indent} \ldots ({\em not +implemented yet}) + \end{enumerate} + +\item Importing Python modules and objects: \code{\#import} \ldots, + \code{\#from} \ldots + +\item Inheritance + \begin{enumerate} + \item set the base class to inherit from: \code{\#extends} + \item set the name of the main method to implement: \code{\#implements} +\ldots + \end{enumerate} + +\item Compile-time declaration + \begin{enumerate} + \item define class attributes: \code{\#attr} \ldots + \item define class methods: \code{\#def} \ldots \code{\#end def} + \item \code{\#block} \ldots \code{\#end block} provides a simplified + interface to \code{\#def} \ldots \code{\#end def} + \end{enumerate} + +\item Run-time assignment + \begin{enumerate} + \item local vars: \code{\#set} \ldots + \item global vars: \code{\#set global} \ldots + \item deleting local vars: \code{\#del} \ldots + \end{enumerate} + +\item Flow control + \begin{enumerate} + \item \code{\#if} \ldots \code{\#else} \ldots \code{\#else if} (aka + \code{\#elif}) \ldots \code{\#end if} + \item \code{\#unless} \ldots \code{\#end unless} + \item \code{\#for} \ldots \code{\#end for} + \item \code{\#repeat} \ldots \code{\#end repeat} + \item \code{\#while} \ldots \code{\#end while} + \item \code{\#break} + \item \code{\#continue} + \item \code{\#pass} + \item \code{\#stop} + \end{enumerate} + +\item error/exception handling + \begin{enumerate} + \item \code{\#assert} + \item \code{\#raise} + \item \code{\#try} \ldots \code{\#except} \ldots \code{\#else} \ldots + \code{\#end try} + \item \code{\#try} \ldots \code{\#finally} \ldots \code{\#end try} + \item \code{\#errorCatcher} \ldots set a handler for exceptions raised by +\$placeholder calls. + \end{enumerate} + +\item Instructions to the parser/compiler + \begin{enumerate} + \item \code{\#breakpoint} + \item \code{\#compiler-settings} \ldots \code{\#end compiler-settings} + \end{enumerate} + +\item Escape to pure Python code + \begin{enumerate} + \item evalute expression and print the output: \code{<\%=} \ldots + \code{\%>} + \item execute code and discard output: \code{<\%} \ldots \code{\%>} + \end{enumerate} + +\item Fine control over Cheetah-generated Python modules + \begin{enumerate} + \item set the source code encoding of compiled template modules: \code{\#encoding} + \item set the sh-bang line of compiled template modules: \code{\#shBang} + \end{enumerate} + +\end{enumerate} + +The use of all these constructs will be covered in the next several chapters. + +%% @@MO: TODO: reconcile the order of this summary with the order in the +%% detail sections. + +% @@MO: PSP chapter with examples. What does write() do? Print? + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Placeholder Syntax Rules} +\label{language.placeholders.syntax} + +\begin{itemize} + +\item Placeholders follow the same syntax rules as Python variables except + that they are preceded by \code{\$} (the short form) or enclosed in + \code{\$\{\}} (the long form). + Examples: +\begin{verbatim} +$var +${var} +$var2.abc['def']('gh', $subplaceholder, 2) +${var2.abc['def']('gh', $subplaceholder, 2)} +\end{verbatim} + We recommend \code{\$} in simple cases, and \code{\$\{\}} when followed + directly by a letter or when Cheetah or a human template maintainer might + get confused about where the placeholder ends. You may alternately use + \verb+$()+ or \verb+$[]+, although this may confuse the (human) template + maintainer: +\begin{verbatim} +$(var) +$[var] +$(var2.abc['def']('gh', $subplaceholder, 2)) +$[var2.abc['def']('gh', $subplaceholder, 2)] +\end{verbatim} + {\em Note:} Advanced users can change the delimiters to anything they + want via the \code{\#compiler} directive. + + {\em Note 2:} The long form can be used only with top-level placeholders, + not in expressions. See section \ref{language.placeholders.positions} + for an elaboration on this. + +\item To reiterate Python's rules, placeholders consist of one or more + identifiers separated by periods. Each identifier must start with a letter + or an underscore, and the subsequent characters must be letters, digits or + underscores. Any identifier may be followed by arguments enclosed in + \verb+()+ and/or keys/subscripts in \verb+[]+. + +\item Identifiers are case sensitive. \code{\$var} does not equal \code{\$Var} + or \code{\$vAr} or \code{\$VAR}. + +\item Arguments inside \verb+()+ or \verb+[]+ are just like in Python. + Strings may be quoted using any Python quoting style. Each argument is an + expression and may use any of Python's expression operators. Variables + used in argument expressions are placeholders and should be prefixed with + \code{\$}. This also applies to the *arg and **kw forms. However, you do + {\em not} need the \code{\$} with the special Python constants \code{None}, + \code{True} and \code{False}. + Examples: +\begin{verbatim} +$hex($myVar) +$func($arg=1234) +$func2($*args, $**kw) +$func3(3.14159, $arg2, None, True) +$myList[$mySubscript] +\end{verbatim} + +\item Trailing periods are ignored. Cheetah will recognize that the placeholder + name in \code{\$varName.} is \code{varName}, and the period will be left + alone in the template output. + +\item The syntax \code{\$\{placeholderName, arg1="val1"\}} passes arguments to + the output filter (see \code{\#filter}, section \ref{output.filter}. + The braces and comma are required in this case. It's conventional to + omit the \code{\$} before the keyword arguments (i.e. \code{arg1}) in this + case. + +\item Cheetah ignores all dollar signs (\code{\$}) that are not followed by a + letter or an underscore. + +\end{itemize} + +The following are valid \$placeholders: +\begin{verbatim} +$a $_ $var $_var $var1 $_1var $var2_ $dict.key $list[3] +$object.method $object.method() $object.method +$nest($nest($var)) +\end{verbatim} + +These are not \$placeholders but are treated as literal text: +\begin{verbatim} +$@var $^var $15.50 $$ +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Where can you use placeholders?} +\label{language.placeholders.positions} + +There are three places you can use placeholders: top-level position, +expression position and LVALUE position. Each has slightly different +syntax rules. + +Top-level position means interspersed in text. This is the only place +you can use the placeholder long form: \code{\$\{var\}}. + +{\em Expression position} means inside a Cheetah expression, which is the same +as a Python expression. The placeholder names a searchList or other variable +to be read. Expression position occurs inside () and $[]$ arguments within +placeholder tags (i.e., a placeholder inside a placeholder), and in several +directive tags. + +{\em LVALUE position} means naming a variable that will be written to. LVALUE +is a computer science term meaning ``the left side of an assignment +statement''. The first argument of directives \code{\#set}, \code{\#for}, +\code{\#def}, \code{\#block} and \code{\#attr} is an LVALUE. + +This stupid example shows the three positions. Top-level position is shown +in \code{courier}, expression position is {\em italic}, and LVALUE position is +{\bf bold}. + +\begin{quote} +\#for {\bf \$count} in {\em \$range}({\em \$ninetyNine}, 0, -1)\\ +\#set {\bf \$after} = {\em \$count} - 1\\ +\code{\$count} bottles of beer on the wall. \code{\$count} bottles of beer!\\ +~~~~Take one down, pass it around. \code{\$after} bottles of beer on the wall.\\ +\#end for\\ +\code{\$hex}({\em \$myVar}, {\bf \$default}={\em None}) +\end{quote} + +The output of course is: +\begin{verbatim} +99 bottles of beer on the wall. 99 bottles of beer! + Take one down, pass it around. 98 bottles of beer on the wall. +98 bottles of beer on the wall. 98 bottles of beer! + Take one down, pass it around. 97 bottles of beer on the wall. +... +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Are all those dollar signs really necessary?} +\label{language.placeholders.dollar-signs} + +\code{\$} is a ``smart variable prefix''. When Cheetah sees \code{\$}, it +determines both the variable's position and whether it's a searchList value or +a non-searchList value, and generates the appropriate Python code. + +In top-level position, the \code{\$} is {\em required}. Otherwise there's +nothing to distinguish the variable from ordinary text, and the variable name +is output verbatim. + +In expression position, the \code{\$} is {\em required} if the value comes from +the searchList or a ``\#set global'' variable, {\em recommended} for +local/global/builtin variables, and {\em not necessary} for the special +constants \code{None}, \code{True} and \code{False}. This works because +Cheetah generates a function call for a searchList placeholder, but a bare +variable name for a local/global/builtin variable. + +In LVALUE position, the \code{\$} is {\em recommended}. Cheetah knows where +an LVALUE is expected, so it can handle your variable name whether it has +\code{\$} or not. + +EXCEPTION: Do {\em not} use the \code{\$} prefix for intermediate variables in +a Python list comprehensions. This is a limitation of Cheetah's parser; it +can't tell which variables in a list comprehension are the intermediate +variables, so you have to help it. For example: +\begin{verbatim} +#set $theRange = [x ** 2 for x in $range(10)] +\end{verbatim} +\code{\$theRange} is a regular \code{\#set} variable. \code{\$range} is a +Python built-in function. But \code{x} is a scratch variable internal to +the list comprehension: if you type \code{\$x}, Cheetah will miscompile +it. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{NameMapper Syntax} +\label{language.namemapper} + +One of our core aims for Cheetah was to make it easy for non-programmers to +use. Therefore, Cheetah uses a simplified syntax for mapping placeholders +in Cheetah to values in Python. It's known as the {\bf NameMapper syntax} +and allows for non-programmers to use Cheetah without knowing (a) the +difference between an instance and a dictionary, (b) what functions and methods +are, and (c) what 'self' is. A side benefit is that you can change the +underlying data structure (e.g., instance to dictionary or vice-versa) without +having to modify the templates. + +NameMapper syntax is used for all variables in Cheetah placeholders and +directives. If desired, it can be turned off via the \code{Template} class' +\code{'useNameMapper'} compiler setting. But it's doubtful you'd ever want to +turn it off. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Example} +\label{language.namemapper.example} + +Consider this scenario: + +You are building a customer information system. The designers with you want to +use information from your system on the client's website --AND-- they want to +understand the display code and so they can maintian it themselves. + +You write a UI class with a 'customers' method that returns a dictionary of all +the customer objects. Each customer object has an 'address' method that returns +the a dictionary with information about the customer's address. The designers +want to be able to access that information. + +Using PSP, the display code for the website would look something like the +following, assuming your servlet subclasses the class you created for managing +customer information: + +\begin{verbatim} + <%= self.customer()[ID].address()['city'] %> (42 chars) +\end{verbatim} + +With Cheetah's NameMapper syntax, you can use any of the following: + +\begin{verbatim} + $self.customers()[$ID].address()['city'] (39 chars) + --OR-- + $customers()[$ID].address()['city'] + --OR-- + $customers()[$ID].address().city + --OR-- + $customers()[$ID].address.city + --OR-- + $customers[$ID].address.city (27 chars) +\end{verbatim} + +Which of these would you prefer to explain to the designers, who have no +programming experience? The last form is 15 characters shorter than the PSP +version and -- conceptually -- far more accessible. With PHP or ASP, the +code would be even messier than with PSP. + +This is a rather extreme example and, of course, you could also just implement +\code{\$getCustomer(\$ID).city} and obey the Law of Demeter (search Google for more +on that). But good object orientated design isn't the point of this example. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Dictionary Access} +\label{language.namemapper.dict} + +NameMapper syntax allows access to dictionary items with the same dotted +notation used to access object attributes in Python. This aspect of NameMapper +syntax is known as 'Unified Dotted Notation'. +For example, with Cheetah it is possible to write: +\begin{verbatim} + $customers()['kerr'].address() --OR-- $customers().kerr.address() +\end{verbatim} +where the second form is in NameMapper syntax. + +This works only with dictionary keys that also happen to be valid Python +identifiers. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Autocalling} +\label{language.namemapper.autocalling} + +Cheetah automatically detects functions and methods in Cheetah \$variables and +calls them if the parentheses have been left off. Our previous example can be +further simplified to: +\begin{verbatim} + $customers.kerr.address +\end{verbatim} + +As another example, if 'a' is an object, 'b' is a method +\begin{verbatim} + $a.b +\end{verbatim} + +is equivalent to + +\begin{verbatim} + $a.b() +\end{verbatim} + +If b returns a dictionary, then following variations are possible +\begin{verbatim} + $a.b.c --OR-- $a.b().c --OR-- $a.b()['c'] +\end{verbatim} +where 'c' is a key in the dictionary that a.b() returns. + +Further notes: +\begin{itemize} +\item When Cheetah autocalls a function/method, it calls it without any +arguments. Thus, the function/method must have been declared without arguments +(except \code{self} for methods) or to provide default values for all arguments. +If the function requires arguments, you must use the \code{()}. + +\item Cheetah autocalls only functions and methods. Classes and other callable +objects are not autocalled. The reason is that the primary purpose of a +function/method is to call it, whereas the primary purpose of an instance is to +look up its attributes or call its methods, not to call the instance itself. +And calling a class may allocate large sums of memory uselessly or have other +side effects, depending on the class. For instance, consider +\code{\$myInstance.fname}. Do we want to look up \code{fname} in the namespace +of \code{myInstance} or in the namespace of whatever \code{myinstance} returns? +It could go either way, so Cheetah follows the principle of least surprise. If +you {\em do} want to call the instance, put the \code{()} on, or rename the +\code{.\_\_call\_\_()} method to \code{.\_\_str\_\_}. + +\item Autocalling can be disabled via Cheetah's 'useAutocalling' compiler +setting. You can also disable it for one placeholder by using the syntax +\code{\$getVar('varName', 'default value', False)}. (\code{.getVar()} works +only with searchList values.) +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Namespace cascading and the searchList} +\label{language.searchList} + +When Cheetah maps a variable name in a template to a Python value, it searches +several namespaces in order: + +\begin{enumerate} +\item {\bf Local variables:} created by \code{\#set}, + \code{\#for}, or predefined by Cheetah. +\item The {\bf searchList}, consisting of: + \begin{enumerate} + \item \code{\#set\ global} variables. + \item The {\bf searchList} containers you passed to the \code{Template} + constructor, if any. + \item The {\bf Template instance} (``self''). This contains any attributes + you assigned, \code{\#def} methods and \code{\#block methods}, + attributes/methods inherited via \code{\#extends}, and other + attributes/methods built into \code{Template} or inherited by it + (there's a list of all these methods in section + \ref{tips.allMethods}). + \end{enumerate} +\item {\bf Python globals:} created by \code{\#import}, + \code{\#from\ ...\ import}, or otherwise predefined by Cheetah. +\item {\bf Python builtins:} \code{None}, \code{max}, etc. +\end{enumerate} + +The first matching name found is used. + +Remember, these namespaces apply only to the {\em first} identifier after the +\code{\$}. In a placeholder like \code{\$a.b}, only `a' is looked up in the +searchList and other namespaces. `b' is looked up only inside `a'. + +A searchList container can be any Python object with attributes or keys: +dictionaries, instances, classes or modules. If an instance contains both +attributes and keys, its attributes are searched first, then its keys. + +Because the \code{Template} instance is part of the searchList, you can +access its attributes/methods without `self': \code{\$myAttr}. However, use +the `self' if you want to make sure you're getting the \code{Template} +attribute and not a same-name variable defined in a higher namespace: +\code{\$self.myAttr}. This works because ``self'' itself is a local variable. + +The final resulting value, after all lookups and function calls (but before the +filter is applied) is called the {\em placeholder value}, no matter which +namespace it was found in. + +{\em {\bf Note carefully:}} if you put an object `myObject' in the searchList, +you {\em cannot} look up \code{\$myObject}! You can look up only the +attributes/keys {\em inside} `myObject'. + +Earlier versions of Cheetah did not allow you to override Python builtin +names, but this was fixed in Cheetah 0.9.15. + +If your template will be used as a Webware servlet, do not override methods +'name' and 'log' in the \code{Template} instance or it will interfere with +Webware's logging. However, it {\em is} OK to use those variables in a higher +namespace, since Webware doesn't know about Cheetah namespaces. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Missing Values} +\label{language.namemapper.missing} + +If NameMapper can not find a Python value for a Cheetah variable name, it will +raise the NameMapper.NotFound exception. You can use the \code{\#errorCatcher} +directive (section \ref{errorHandling.errorCatcher}) or {\bf errorCatcher} +Template constructor argument (section \ref{howWorks.constructing}) to specify +an alternate behaviour. BUT BE AWARE THAT errorCatcher IS ONLY INTENDED FOR +DEBUGGING! + +To provide a default value for a placeholder, write it like this: +\code{\$getVar('varName', 'default value')}. If you don't specify a default +and the variable is missing, \code{NameMapper.NotFound} will be raised. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Directive Syntax Rules} +\label{language.directives.syntax} + + +Directive tags begin with a hash character (\#) and are used for comments, +loops, conditional blocks, includes, and all other advanced features. Cheetah +uses a Python-like syntax inside directive tags and understands any valid +Python expression. {\bf However, unlike Python, Cheetah does not use colons +(:) and indentation to mark off multi-line directives.} That doesn't work in +an environment where whitespace is significant as part of the text. Instead, +multi-line directives like \code{\#for} have corresponding closing tags +(\code{\#end for}). Most directives are direct mirrors of Python statements. + +Many directives have arguments after the opening tag, which must be in the +specified syntax for the tag. All end tags have the following syntax: +\begin{verbatim} +#end TAG_NAME [EXPR] +\end{verbatim} +The expression is ignored, so it's essentially a comment. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Directive closures and whitespace handling} +\label{language.directives.closures} +Directive tags can be closed explicitly with \code{\#}, or implicitly with the +end of the line if you're feeling lazy. + +\begin{verbatim} +#block testBlock # +Text in the body of the +block directive +#end block testBlock # +\end{verbatim} +is identical to: +\begin{verbatim} +#block testBlock +Text in the body of the +block directive +#end block testBlock +\end{verbatim} + +When a directive tag is closed explicitly, it can be followed with other text on +the same line: + +\begin{verbatim} +bah, bah, #if $sheep.color == 'black'# black#end if # sheep. +\end{verbatim} + +When a directive tag is closed implicitly with the end of the line, all trailing +whitespace is gobbled, including the newline character: +\begin{verbatim} +""" +foo #set $x = 2 +bar +""" +outputs +""" +foo bar +""" + +while +""" +foo #set $x = 2 # +bar +""" +outputs +""" +foo +bar +""" +\end{verbatim} + +When a directive tag is closed implicitly AND there is no other text on the +line, the ENTIRE line is gobbled up including any preceeding whitespace: +\begin{verbatim} +""" +foo + #set $x = 2 +bar +""" +outputs +""" +foo +bar +""" + +while +""" +foo + - #set $x = 2 +bar +""" +outputs +""" +foo + - bar +""" +\end{verbatim} + +The \code{\#slurp} directive (section \ref{output.slurp}) also gobbles up +whitespace. + +Spaces outside directives are output {\em exactly} as written. In the +black sheep example, there's a space before ``black'' and another before +``sheep''. So although it's legal to put multiple directives on one line, +it can be hard to read. + +\begin{verbatim} +#if $a# #echo $a + 1# #end if + - There's a space between each directive, + or two extra spaces total. +#if $a##echo $a + 1##end if + - No spaces, but you have to look closely + to verify none of the ``##'' are comment markers. +#if $a##echo $a + 1##end if ### A comment. + - In ``###'', the first ``#'' ends the directive, + the other two begin the comment. (This also shows + how you can add extra whitespace in the directive + tag without affecting the output.) +#if $a##echo $a + 1##end if # ## A comment. + - More readable, but now there's a space before the + comment. +\end{verbatim} + +% Local Variables: +% TeX-master: "users_guide" +% End: + +% # vim: sw=4 ts=4 expandtab diff --git a/docs/users_guide_2_src/05_placeholders_and_the_namemapper.txt b/docs/users_guide_2_src/05_placeholders_and_the_namemapper.txt new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/docs/users_guide_2_src/05_placeholders_and_the_namemapper.txt diff --git a/docs/users_guide_2_src/06_comments.txt b/docs/users_guide_2_src/06_comments.txt new file mode 100755 index 0000000..36323cf --- /dev/null +++ b/docs/users_guide_2_src/06_comments.txt @@ -0,0 +1,99 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Comments} +\label{comments} + +Comments are used to mark notes, explanations, and decorative text that should +not appear in the output. Cheetah maintains the comments in the Python module +it generates from the Cheetah source code. There are two forms of the comment +directive: single-line and multi-line. + +All text in a template definition that lies between two hash characters +(\code{\#\#}) and the end of the line is treated as a single-line comment and +will not show up in the output, unless the two hash characters are escaped with +a backslash. +\begin{verbatim} +##============================= this is a decorative comment-bar +$var ## this is an end-of-line comment +##============================= +\end{verbatim} + +Any text between \code{\#*} and \code{*\#} will be treated as a multi-line +comment. +\begin{verbatim} +#* + Here is some multiline + comment text +*# +\end{verbatim} + +If you put blank lines around method definitions or loops to separate them, +be aware that the blank lines will be output as is. To avoid this, make sure +the blank lines are enclosed in a comment. Since you normally have a +comment before the next method definition (right?), you can just extend that +comment to include the blank lines after the previous method definition, like +so: +\begin{verbatim} +#def method1 +... lines ... +#end def +#* + + + Description of method2. + $arg1, string, a phrase. +*# +#def method2($arg1) +... lines ... +#end def +\end{verbatim} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Docstring Comments} +\label{comments.docstring} + +Python modules, classes, and methods can be documented with inline +'documentation strings' (aka 'docstrings'). Docstrings, unlike comments, are +accesible at run-time. Thus, they provide a useful hook for interactive help +utilities. + +Cheetah comments can be transformed into doctrings by adding one of the +following prefixes: + +\begin{verbatim} +##doc: This text will be added to the method docstring +#*doc: If your template file is MyTemplate.tmpl, running "cheetah compile" + on it will produce MyTemplate.py, with a class MyTemplate in it, + containing a method .respond(). This text will be in the .respond() + method's docstring. *# + +##doc-method: This text will also be added to .respond()'s docstring +#*doc-method: This text will also be added to .respond()'s docstring *# + +##doc-class: This text will be added to the MyTemplate class docstring +#*doc-class: This text will be added to the MyTemplate class docstring *# + +##doc-module: This text will be added to the module docstring MyTemplate.py +#*doc-module: This text will be added to the module docstring MyTemplate.py*# +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Header Comments} +\label{comments.headers} +Cheetah comments can also be transformed into module header comments using the +following syntax: + +\begin{verbatim} +##header: This text will be added to the module header comment +#*header: This text will be added to the module header comment *# +\end{verbatim} + +Note the difference between \code{\#\#doc-module: } and \code{header: }: +``cheetah-compile'' puts \code{\#\#doc-module: } text inside the module +docstring. \code{header: } makes the text go {\em above} the docstring, as a +set of \#-prefixed comment lines. + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_2_src/07_output.txt b/docs/users_guide_2_src/07_output.txt new file mode 100755 index 0000000..742291e --- /dev/null +++ b/docs/users_guide_2_src/07_output.txt @@ -0,0 +1,548 @@ +\section{Generating, Caching and Filtering Output} +\label{output} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Output from complex expressions: \#echo} +\label{output.echo} + +Syntax: +\begin{verbatim} +#echo EXPR +\end{verbatim} + +The \code{\#echo} directive is used to echo the output from expressions that +can't be written as simple \$placeholders. + +\begin{verbatim} +Here is my #echo ', '.join(['silly']*5) # example +\end{verbatim} + +This produces: + +\begin{verbatim} +Here is my silly, silly, silly, silly, silly example. +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Executing expressions without output: \#silent} +\label{output.silent} + +Syntax: +\begin{verbatim} +#silent EXPR +\end{verbatim} + +\code{\#silent} is the opposite of \code{\#echo}. It executes an expression +but discards the output. + +\begin{verbatim} +#silent $myList.reverse() +#silent $myList.sort() +Here is #silent $covertOperation() # nothing +\end{verbatim} + +If your template requires some Python code to be executed at the beginning; +(e.g., to calculate placeholder values, access a database, etc), you can put +it in a "doEverything" method you inherit, and call this method using +\code{\#silent} at the top of the template. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{One-line \#if} +\label{output.oneLineIf} + +Syntax: +\begin{verbatim} +#if EXPR1 then EXPR2 else EXPR3# +\end{verbatim} + +The \code{\#if} flow-control directive (section \ref{flowControl.if}) has a +one-line counterpart akin to Perl's and C's \code{?:} operator. +If \code{EXPR1} is true, it evaluates \code{EXPR2} and outputs the result (just +like \code{\#echo\ EXPR2\#}). Otherwise it evaluates \code{EXPR3} and outputs +that result. This directive is short-circuiting, meaning the expression that +isn't needed isn't evaluated. + +You MUST include both 'then' and 'else'. If this doesn't work for you or you +don't like the style use multi-line \code{\#if} directives (section +\ref{flowControl.if}). + +The trailing \code{\#} is the normal end-of-directive character. As usual +it may be omitted if there's nothing after the directive on the same line. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Caching Output} +\label{output.caching} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Caching individual placeholders} +\label{output.caching.placeholders} + +By default, the values of each \$placeholder is retrieved and +interpolated for every request. However, it's possible to cache the values +of individual placeholders if they don't change very often, in order to +speed up the template filling. + +To cache the value of a single \code{\$placeholder}, add an asterisk after the +\$; e.g., \code{\$*var}. The first time the template is +filled, \code{\$var} is looked up. Then whenever the template is filled again, +the cached value is used instead of doing another lookup. + +The \code{\$*} format caches ``forever''; that is, as long as the template +instance remains in memory. It's also possible to cache for a certain time +period using the form \code{\$*<interval>*variable}, where \code{<interval>} is +the interval. The time interval can be specified in seconds (5s), minutes +(15m), hours (3h), days (2d) or weeks (1.5w). The default is minutes. + +\begin{verbatim} +<HTML> +<HEAD><TITLE>$title</TITLE></HEAD> +<BODY> + +$var ${var} ## dynamic - will be reinterpolated for each request +$*var2 $*{var2} ## static - will be interpolated only once at start-up +$*5*var3 $*5*{var3} ## timed refresh - will be updated every five minutes. + +</BODY> +</HTML> +\end{verbatim} + +Note that ``every five minutes'' in the example really means every five +minutes: the variable is looked up again when the time limit is reached, +whether the template is being filled that frequently or not. Keep this in +mind when setting refresh times for CPU-intensive or I/O intensive +operations. + +If you're using the long placeholder syntax, \verb+${}+, the braces go only +around the placeholder name: \verb+$*.5h*{var.func('arg')}+. + +Sometimes it's preferable to explicitly invalidate a cached item whenever +you say so rather than at certain time intervals. You can't do this with +individual placeholders, but you can do it with cached regions, which will +be described next. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Caching entire regions} +\label{output.caching.regions} + +Syntax: +\begin{verbatim} +#cache [id=EXPR] [timer=EXPR] [test=EXPR] +#end cache +\end{verbatim} + +The \code{\#cache} directive is used to cache a region of +content in a template. The region is cached as a single unit, after +placeholders and directives inside the region have been evaluated. If there +are any \code{\$*<interval>*var} placholders inside the cache +region, they are refreshed only when {\em both} the cache region {\em and} the +placeholder are simultaneously due for a refresh. + +Caching regions offers more flexibility than caching individual placeholders. +You can specify the refresh interval using a placeholder or +expression, or refresh according to other criteria rather than a certain +time interval. + +\code{\#cache} without arguments caches the region statically, the same +way as \code{\$*var}. The region will not be automatically refreshed. + +To refresh the region at an interval, use the \code{timer=EXPRESSION} argument, +equivalent to \code{\$*<interval>*}. The expression should evaluate to a +number or string that is a valid interval (e.g., 0.5, '3m', etc). + +To refresh whenever an expression is true, use \code{test=EXPRESSION}. +The expression can be a method/function returning true or false, a boolean +placeholder, several of these joined by \code{and} and/or \code{or}, or any +other expression. If the expression contains spaces, it's easier to +read if you enclose it in \code{()}, but this is not required. + +To refresh whenever you say so, use \code{id=EXPRESSION}. Your program can +then call \code{.refreshCache(ID)} whenever it wishes. This is useful if the +cache depends on some external condition that changes infrequently but has just +changed now. + +You can combine arguments by separating them with commas. For instance, you can +specify both \code{id=} and \code{interval=}, or \code{id=} and \code{test=}. +(You can also combine interval and test although it's not very useful.) +However, repeating an argument is undefined. + +\begin{verbatim} +#cache +This is a static cache. It will not be refreshed. +$a $b $c +#end cache + +#cache timer='30m', id='cache1' +#for $cust in $customers +$cust.name: +$cust.street - $cust.city +#end for +#end cache + +#cache id='sidebar', test=$isDBUpdated +... left sidebar HTML ... +#end cache + +#cache id='sidebar2', test=($isDBUpdated or $someOtherCondition) +... right sidebar HTML ... +#end cache +\end{verbatim} + + +The \code{\#cache} directive cannot be nested. + +We are planning to add a \code{'varyBy'} keyword argument in the future that +will allow a separate cache instances to be created for a variety of conditions, +such as different query string parameters or browser types. This is inspired by +ASP.net's varyByParam and varyByBrowser output caching keywords. + +% @@MO: Can we cache by Webware sessions? What about sessions where the +% session ID is encoded as a path prefix in the URI? Need examples. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#raw} +\label{output.raw} + +Syntax: +\begin{verbatim} +#raw +#end raw +\end{verbatim} + +Any section of a template definition that is inside a \code{\#raw \ldots +\#end raw} tag pair will be printed verbatim without any parsing of +\$placeholders or other directives. This can be very useful for debugging, or +for Cheetah examples and tutorials. + +\code{\#raw} is conceptually similar to HTML's \code{<PRE>} tag and LaTeX's +\code{\\verbatim\{\}} tag, but unlike those tags, \code{\#raw} does not cause +the body to appear in a special font or typeface. It can't, because Cheetah +doesn't know what a font is. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#include} +\label{output.include} + +Syntax: +\begin{verbatim} +#include [raw] FILENAME_EXPR +#include [raw] source=STRING_EXPR +\end{verbatim} + +The \code{\#include} directive is used to include text from outside the +template definition. The text can come from an external file or from a +\code{\$placeholder} variable. When working with external files, Cheetah will +monitor for changes to the included file and update as necessary. + +This example demonstrates its use with external files: +\begin{verbatim} +#include "includeFileName.txt" +\end{verbatim} +The content of "includeFileName.txt" will be parsed for Cheetah syntax. + +And this example demonstrates use with \code{\$placeholder} variables: +\begin{verbatim} +#include source=$myParseText +\end{verbatim} +The value of \code{\$myParseText} will be parsed for Cheetah syntax. This is not +the same as simply placing the \$placeholder tag ``\code{\$myParseText}'' in +the template definition. In the latter case, the value of \$myParseText would +not be parsed. + +By default, included text will be parsed for Cheetah tags. The argument +``\code{raw}'' can be used to suppress the parsing. + +\begin{verbatim} +#include raw "includeFileName.txt" +#include raw source=$myParseText +\end{verbatim} + +Cheetah wraps each chunk of \code{\#include} text inside a nested +\code{Template} object. Each nested template has a copy of the main +template's searchList. However, \code{\#set} variables are visible +across includes only if the defined using the \code{\#set global} keyword. + +All directives must be balanced in the include file. That is, if you start +a \code{\#for} or \code{\#if} block inside the include, you must end it in +the same include. (This is unlike PHP, which allows unbalanced constructs +in include files.) + +% @@MO: What did we decide about #include and the searchList? Does it really +% use a copy of the searchList, or does it share the searchList with the +% parent? + +% @@MO: deleted +%These nested templates share the same \code{searchList} +%as the top-level template. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#slurp} +\label{output.slurp} + +Syntax: +\begin{verbatim} +#slurp +\end{verbatim} + +The \code{\#slurp} directive eats up the trailing newline on the line it +appears in, joining the following line onto the current line. + + +It is particularly useful in \code{\#for} loops: +\begin{verbatim} +#for $i in range(5) +$i #slurp +#end for +\end{verbatim} +outputs: +\begin{verbatim} +0 1 2 3 4 +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#indent} +\label{output.indent} + +This directive is not implemented yet. When/if it's completed, it will allow +you to +\begin{enumerate} +\item indent your template definition in a natural way (e.g., the bodies + of \code{\#if} blocks) without affecting the output +\item add indentation to output lines without encoding it literally in the + template definition. This will make it easier to use Cheetah to produce + indented source code programmatically (e.g., Java or Python source code). +\end{enumerate} + +There is some experimental code that recognizes the \code{\#indent} +directive with options, but the options are purposely undocumented at this +time. So pretend it doesn't exist. If you have a use for this feature +and would like to see it implemented sooner rather than later, let us know +on the mailing list. + +The latest specification for the future \code{\#indent} directive is in the +TODO file in the Cheetah source distribution. + +% @@MO: disabled because it's not implemented and the spec is changing +% \code{\#indent} decouples the indentation in the template definition from the +% indentation in the output. Normally, Cheetah outputs indentation exactly as +% it sees it, no matter whether the indentation is on the first line of a +% paragraph, in front of a directive, or wherever. \code{\#indent} has two main +% uses: +% \begin{enumerate} +% \item To strip all indentation from source lines. This lets you indent +% multiline directives (e.g., \code{\#if}, \code{\#for}) in a natural way +% without having that indentation appear in the output. +% \item To indent every text line in the output according to a user-specified +% ``indentation level'', independent of whatever indentation the source lines +% may have. This is useful for producing Python output, or any language that +% requires strict indentation levels at certain places. To accomplish this, +% Cheetah adds a call to an indentation method at the beginning of every +% affected source line. +% \end{enumerate} +% +% To accomplish the first part, Cheetah removes leading whitespace from the +% affected source lines before the compiler see them. To accomplish the second +% part, Cheetah keeps track of the current indentation level, a value you have +% full control over. At the beginning of every affected text line, Cheetah calls +% a method that outputs the appropriate indentation string. This affects only +% lines in the template definition itself, not multiline placeholder values. +% See the \code{Indent} filter below to indent multiline placeholder values. +% +% All \code{\#indent} commands operate on the lines physically below them in +% the template definition until the next \code{\#indent}, regardless of scope. +% This means they work thorugh all other directives (\code{\#def}, \code{\#for}, +% \code{\#if}, etc) -- so that if you turn on indentation inside a \code{\#def}, +% it remains in effect past the \code{\#end def}. +% +% The following commands turn indentation on and off: +% \begin{description} +% \item{\code{\#indent on}} Strip leading whitespace and add indentation to the +% following lines. This fulfills use \#2 above. +% \item{\code{\#indent off}} Do not strip leading whitespace or add indentation. +% This is Cheetah's default behavior. +% \item{\code{\#indent strip}} Strip leading whitespace but do {\em not} add +% indentation. This fulfills use \#1 above. +% \end{description} +% +% Indentation by default uses real tabs. But you can change the indentation +% string thus: +% \begin{verbatim} +% ## Output four spaces for each indentation level. +% #indent chars ' ' +% ## Output the mail reply prefix for each indentation level. +% #indent chars '> ' +% ## Use a placeholder. +% #indent chars $indentChars +% ## Return to the default behavior. +% #indent chars '\t' +% \end{verbatim} +% +% +% The following commands change the indentation level, which is a non-negative +% integer initially at zero. All of these commands implicitly do an +% \code{\#indent on}: +% \begin{description} +% \item{\code{\#indent ++}} Increment the current indentation level. +% \item{\code{\#indent --}} Decrement the current indentation level. +% \item{\code{\#indent +3}} Add three indentation levels (or any number). +% \item{\code{\#indent -3}} Subtract three indentation levels (or any number). +% \item{\code{\#indent =3}} Set the indentation level to 3. +% \item{\code{\#indent push +2}} Save the current indentation level on a stack +% and add two. +% \item{\code{\#indent pop}} Return to the most recently pushed level. Raise +% \code{IndentationStackEmptyError} if there is no previous level. +% \end{description} +% +% The expressions after \code{+}/\code{-}/\code{=} may be numeric literals or +% Cheetah expressions. The effect is undefined if the value is negative. There +% may be whitespace after the \code{+}/\code{-}/\code{=} symbol. +% The initial implementation uses a simple preprocessor that doesn't understand +% newline characters in expressions. \code{\\n} is fine, but not a real newline. +% +% To indent multiline placeholder values using the current indentation level, +% use the \code{Indent} filter: +% \begin{verbatim} +% #filter Indent +% \end{verbatim} +% It works like the default filter but adds indentation after every newline. It +% does not strip any leading whitespace. It hooks into \code{\$self.\_indenter}, +% defined in \code{Cheetah.Utils.Indenter}. This object keeps track of the +% current indentation level. Specifically, the filter calls +% \code{\$self.\_indent()}, which is a shortcut to the indenter's +% \code{.indent()} method. This is the same thing \code{\#indent} does. +% However, the filter is usable even when indentation is in +% \code{off} or \code{strip} mode. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Ouput Filtering and \#filter} +\label{output.filter} + +Syntax: +\begin{verbatim} +#filter FILTER_CLASS_NAME +#filter $PLACEHOLDER_TO_A_FILTER_INSTANCE +#filter None +\end{verbatim} + + +Output from \$placeholders is passed through an ouput filter. The default +filter merely returns a string representation of the placeholder value, +unless the value is \code{None}, in which case the filter returns an empty +string. Only top-level placeholders invoke the filter; placeholders inside +expressions do not. + +Certain filters take optional arguments to modify their behaviour. To pass +arguments, use the long placeholder syntax and precede each filter argument by +a comma. By convention, filter arguments don't take a \code{\$} prefix, to +avoid clutter in the placeholder tag which already has plenty of dollar signs. +For instance, the MaxLen filter takes an argument 'maxlen': + +\begin{verbatim} +${placeholderName, maxlen=20} +${functionCall($functionArg), maxlen=$myMaxLen} +\end{verbatim} + +To change the output filter, use the \code{'filter'} keyword to the +\code{Template} class constructor, or the \code{\#filter} +directive at runtime (details below). You may use \code{\#filter} as often as +you wish to switch between several filters, if certain \code{\$placeholders} +need one filter and other \code{\$placeholders} need another. + +The standard filters are in the module \code{Cheetah.Filters}. Cheetah +currently provides: + +\begin{description} +\item{\code{Filter}} + \\ The default filter, which converts None to '' and everything else to + \code{str(whateverItIs)}. This is the base class for all other filters, + and the minimum behaviour for all filters distributed with Cheetah. +\item{\code{ReplaceNone}} + \\ Same. +\item{\code{MaxLen}} + \\ Same, but truncate the value if it's longer than a certain length. + Use the 'maxlen' filter argument to specify the length, as in the + examples above. If you don't specify 'maxlen', the value will not be + truncated. +\item{\code{Pager}} + \\ Output a "pageful" of a long string. After the page, output HTML + hyperlinks to the previous and next pages. This filter uses several + filter arguments and environmental variables, which have not been + documented yet. +\item{\code{WebSafe}} + \\ Same as default, but convert HTML-sensitive characters ('$<$', '\&', + '$>$') + to HTML entities so that the browser will display them literally rather + than interpreting them as HTML tags. This is useful with database values + or user input that may contain sensitive characters. But if your values + contain embedded HTML tags you want to preserve, you do not want this + filter. + + The filter argument 'also' may be used to specify additional characters to + escape. For instance, say you want to ensure a value displays all on one + line. Escape all spaces in the value with '\ ', the non-breaking + space: +\begin{verbatim} +${$country, also=' '}} +\end{verbatim} +\end{description} + +To switch filters using a class object, pass the class using the +{\bf filter} argument to the Template constructor, or via a placeholder to the +\code{\#filter} directive: \code{\#filter \$myFilterClass}. The class must be +a subclass of \code{Cheetah.Filters.Filter}. When passing a class object, the +value of {\bf filtersLib} does not matter, and it does not matter where the +class was defined. + +To switch filters by name, pass the name of the class as a string using the +{\bf filter} argument to the Template constructor, or as a bare word (without +quotes) to the \code{\#filter} directive: \code{\#filter TheFilter}. The +class will be looked up in the {\bf filtersLib}. + +The filtersLib is a module containing filter classes, by default +\code{Cheetah.Filters}. All classes in the module that are subclasses of +\code{Cheetah.Filters.Filter} are considered filters. If your filters are in +another module, pass the module object as the {\bf filtersLib} argument to the +Template constructor. + +Writing a custom filter is easy: just override the \code{.filter} method. +\begin{verbatim} + def filter(self, val, **kw): # Returns a string. +\end{verbatim} +Return the {\em string} that should be output for `val'. `val' may be any +type. Most filters return `' for \code{None}. Cheetah passes one keyword +argument: \verb+kw['rawExpr']+ is the placeholder name as it appears in +the template definition, including all subscripts and arguments. If you use +the long placeholder syntax, any options you pass appear as keyword +arguments. Again, the return value must be a string. + +You can always switch back to the default filter this way: +\code{\#filter None}. This is easy to remember because "no filter" means the +default filter, and because None happens to be the only object the default +filter treats specially. + +We are considering additional filters; see +\url{http://webware.colorstudy.net/twiki/bin/view/Cheetah/MoreFilters} +for the latest ideas. + +%% @@MO: Is '#end filter' implemented? Will it be? Can filters nest? +%% Will '#end filter' and '#filter None' be equivalent? + +%% @@MO: Tavis TODO: fix the description of the Pager filter. It needs a howto. + +%% @@MO: How about using settings to provide default arguments for filters? +%% Each filter could look up FilterName (or FilterNameDefaults) setting, +%% whose value would be a dictionary containing keyword/value pairs. These +%% would be overridden by same-name keys passed by the placeholder. + +%% @@MO: If sed-filters (#sed) get added to Cheetah, give them a section here. + +% Local Variables: +% TeX-master: "users_guide" +% End: + +% vim: shiftwidth=4 tabstop=4 expandtab diff --git a/docs/users_guide_2_src/08_inheritanceEtc.txt b/docs/users_guide_2_src/08_inheritanceEtc.txt new file mode 100755 index 0000000..3e76ce2 --- /dev/null +++ b/docs/users_guide_2_src/08_inheritanceEtc.txt @@ -0,0 +1,564 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Import, Inheritance, Declaration and Assignment} +\label{inheritanceEtc} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#import and \#from directives} +\label{inheritanceEtc.import} + +Syntax: +\begin{verbatim} +#import MODULE_OR_OBJECT [as NAME] [, ...] +#from MODULE import MODULE_OR_OBJECT [as NAME] [, ...] +\end{verbatim} + + +The \code{\#import} and \code{\#from} directives are used to make external +Python modules or objects available to placeholders. The syntax is identical +to the import syntax in Python. Imported modules are visible globally to all +methods in the generated Python class. + +\begin{verbatim} +#import math +#import math as mathModule +#from math import sin, cos +#from math import sin as _sin +#import random, re +#from mx import DateTime # ## Part of Egenix's mx package. +\end{verbatim} + +After the above imports, \code{\$math}, \code{\$mathModule}, +\code{\$sin}, \code{\$cos} and \code{\$\_sin}, \code{\$random}, \code{\$re} +and \code{\$DateTime} may be used in \code{\$placeholders} and expressions. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#extends} +\label{inheritanceEtc.extends} + +Syntax: +\begin{verbatim} +#extends CLASS +\end{verbatim} + + +All templates are subclasses of \code{Cheetah.Template.Template}. However, +it's possible for a template to subclass another template or a pure Python +class. This is where \code{\#extends} steps in: it +specifies the parent class. It's equivalent to PSP's \code{``@page extends=''} +directive. + +Cheetah imports the class mentioned in an \code{\#extends} directive +automatically if you haven't imported it yet. The implicit importing works +like this: + +\begin{verbatim} +#extends Superclass +## Implicitly does '#from Superclass import Superclass'. + +#extends Cheetah.Templates.SkeletonPage +## Implicitly does '#from Cheetah.Templates.SkeletonPage import SkeletonPage'. +\end{verbatim} + +If your superclass is in an unusual location or in a module named +differently than the class, you must import it explicitly. There is no +support for extending from a class that is not imported; e.g., from a template +dynamically created from a string. Since the most practical way to +get a parent template into a module is to precompile it, all parent templates +essentially have to be precompiled. + +There can be only one \code{\#extends} directive in a template and it +may list only one class. In other words, templates don't do multiple +inheritance. This is intentional: it's too hard to initialize multiple +base classes correctly from inside a template. However, you can do +multiple inheritance in your pure Python classes. + +If your pure Python class overrides any of the standard \code{Template} +methods such as \code{.\_\_init\_\_} or \code{.awake}, be sure to call +the superclass method in your method or things will break. Examples of calling +the superclass method are in section \ref{tips.callingSuperclassMethods}. +A list of all superclass methods is in section +\ref{tips.allMethods}. + +In all cases, the root superclass must be \code{Template}. If your +bottommost class is a template, simply omit the \code{\#extends} in it and it +will automatically inherit from \code{Template}. {\em If your bottommost class +is a pure Python class, it must inherit from \code{Template} explicitly: } +\begin{verbatim} +from Cheetah.Template import Template +class MyPurePythonClass(Template): +\end{verbatim} + +If you're not keen about having your Python classes inherit from +\code{Template}, create a tiny glue class that inherits both from your +class and from \code{Template}. + +Before giving any examples we'll stress that Cheetah does {\em not} +dictate how you should structure your inheritance tree. As long as +you follow the rules above, many structures are possible. + +Here's an example for a large web site that has not only a general site +template, but also a template for this section of the site, and then a +specific template-servlet for each URL. (This is the ``inheritance +approach'' discussed in the Webware chapter.) Each template inherits from a +pure Python class that contains methods/attributes used by the template. We'll +begin with the bottommost superclass and end with the specific +template-servlet: + +\begin{verbatim} +1. SiteLogic.py (pure Python class containing methods for the site) + from Cheetah.Template import Template + class SiteLogic(Template): + +2. Site.tmpl/py (template containing the general site framework; + this is the template that controls the output, + the one that contains "<HTML><HEAD>...", the one + that contains text outside any #def/#block.) + #from SiteLogic import SiteLogic + #extends SiteLogic + #implements respond + +3. SectionLogic.py (pure Python class with helper code for the section) + from Site import Site + class SectionLogic(Site) + +4. Section.tmpl/py (template with '#def' overrides etc. for the section) + #from SectionLogic import SectionLogic + #extends SectionLogic + +5. page1Logic.py (pure Python class with helper code for the template-servlet) + from Section import Section + class indexLogic(Section): + +6. page1.tmpl/py (template-servlet for a certain page on the site) + #from page1Logic import page1Logic + #extends page1Logic +\end{verbatim} + +A pure Python classes might also contain methods/attributes that aren't used by +their immediate child template, but are available for any descendant +template to use if it wishes. For instance, the site template might have +attributes for the name and e-mail address of the site administrator, +ready to use as \$placeholders in any template that wants it. + +{\em Whenever you use \code{\#extends}, you often need \code{\#implements} +too,} as in step 2 above. Read the next section to understand what +\code{\#implements} is and when to use it. + +% @@MO: Edmund suggests making some diagrams of inheritance chains. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#implements} +\label{inheritanceEtc.implements} + +Syntax: +\begin{verbatim} +#implements METHOD +\end{verbatim} + +You can call any \code{\#def} or \code{\#block} method directly and get its +outpt. The top-level content -- all the text/placeholders/directives outside any +\code{\#def}/\code{\#block} -- gets concatenated and wrapped in a ``main +method'', by default \code{.respond()}. So if you call \code{.respond()}, you +get the ``whole template output''. When Webware calls \code{.respond()}, +that's what it's doing. And when you do 'print t' or 'str(t)' on a template +instance, you're taking advantage of the fact that Cheetah makes +\code{.\_\_str\_\_()} an alias for the main method. + +That's all fine and dandy, but what if your application prefers to call another +method name rather than \code{.respond()}? What if it wants to call, say, +\code{.send\_output()} instead? That's where \code{\#implements} steps in. It +lets you choose the name for the main method. Just put this in your template +definition: +\begin{verbatim} +#implements send_output +\end{verbatim} + +When one template extends another, every template in the inheritance chain +has its own main method. To fill the template, you invoke exactly one of +these methods and the others are ignored. The method you call may be in any of +the templates in the inheritance chain: the base template, the leaf template, +or any in between, depending on how you structure your application. So you +have two problems: (1) calling the right method name, and (2) preventing an +undesired same-name subclass method from overriding the one you want to call. + +Cheetah assumes the method you will call is \code{.respond()} because +that's what Webware calls. It further assumes the desired main method is the +one in the lowest-level base template, because that works well with +\code{\#block} as described in the Inheritance Approach for building Webware +servlets (section \ref{webware.inheritance}), which was originally the +principal use for Cheetah. So when you use \code{\#extends}, Cheetah changes +that template's main method to \code{.writeBody()} to get it out of the way and +prevent it from overriding the base template's \code{.respond()}. + +Unfortunately this assumption breaks down if the template is used in other +ways. For instance, you may want to use the main method in the highest-level +leaf template, and treat the base template(s) as merely a library of +methods/attributes. In that case, the leaf template needs \code{\#implements +respond} to change its main method name back to \code{.respond()} (or whatever +your application desires to call). Likewise, if your main method is in one of the +intermediate templates in an inheritance chain, that template needs +\code{\#implements respond}. + +The other way the assumption breaks down is if the main method {\em is} in +the base template but that template extends a pure Python class. Cheetah sees +the \code{\#extends} and dutifully but incorrectly renames the method to +\code{.writeBody()}, so you have to use \code{\#implements respond} to change +it back. Otherwise the dummy \code{.respond()} in \code{Cheetah.Template} +is found, which outputs... nothing. {\bf So if you're using \code{\#extends} +and get no output, the {\em first} thing you should think is, ``Do I need to +add \code{\#implements respond} somewhere?'' } + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#set} +\label{inheritanceEtc.set} + +Syntax: +\begin{verbatim} +#set [global] $var = EXPR +\end{verbatim} + +\code{\#set} is used to create and update local variables at run time. +The expression may be any Python expression. +Remember to preface variable names with \$ unless they're part of an +intermediate result in a list comprehension. + +Here are some examples: +\begin{verbatim} +#set $size = $length * 1096 +#set $buffer = $size + 1096 +#set $area = $length * $width +#set $namesList = ['Moe','Larry','Curly'] +#set $prettyCountry = $country.replace(' ', ' ') +\end{verbatim} + +\code{\#set} variables are useful to assign a short name to a +\code{\$deeply.nested.value}, to a calculation, or to a printable version of +a value. The last example above converts any spaces in the 'country' value +into HTML non-breakable-space entities, to ensure the entire value appears on +one line in the browser. + +\code{\#set} variables are also useful in \code{\#if} expressions, but +remember that complex logical routines should be coded in Python, not in +Cheetah! +\begin{verbatim} +#if $size > 1500 + #set $adj = 'large' +#else + #set $adj = 'small' +#end if +\end{verbatim} +Or Python's one-line equivalent, "A and B or C". Remember that in this case, +B must be a true value (not None, '', 0, [] or {}). +\begin{verbatim} +#set $adj = $size > 1500 and 'large' or 'small' +\end{verbatim} +(Note: Cheetah's one-line \code{\#if} will not work for this, since it +produces output rather than setting a variable. + +You can also use the augmented assignment operators: +\begin{verbatim} +## Increment $a by 5. +#set $a += 5 +\end{verbatim} + +By default, \code{\#set} variables are not visible in method calls or include +files unless you use the \code{global} attribute: \code{\#set global \$var = +EXPRESSION}. Global variables are visible in all methods, nested templates and +included files. Use this feature with care to prevent surprises. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#del} +\label{inheritanceEtc.del} + +Syntax: +\begin{verbatim} +#del $var +\end{verbatim} + +\code{\#del} is the opposite of \code{\#set}. It deletes a {\em local} +variable. Its usage is just like Python's \code{del} statement: +\begin{verbatim} +#del $myVar +#del $myVar, $myArray[5] +\end{verbatim} + +Only local variables can be deleted. There is no directive to delete a +\code{\#set global} variable, a searchList variable, or any other type of +variable. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#attr} +\label{inheritanceEtc.attr} + +Syntax: +\begin{verbatim} +#attr $var = EXPR +\end{verbatim} + +The \code{\#attr} directive creates class attributes in the generated Python +class. It should be used to assign simple Python literals such as numbers or +strings. In particular, the expression must {\em not} depend on searchList +values or \code{\#set} variables since those are not known at compile time. + +\begin{verbatim} +#attr $title = "Rob Roy" +#attr $author = "Sir Walter Scott" +#attr $version = 123.4 +\end{verbatim} + +This template or any child template can output the value thus: +\begin{verbatim} +$title, by $author, version $version +\end{verbatim} + +If you have a library of templates derived from etexts +(\url{http://www.gutenberg.org/}), you can extract the titles and authors +and put them in a database (assuming the templates have been compiled into +.py template modules): + +%\begin{verbatim} +%import glob +% +%\end{verbatim} +% +% @@MO: Finish this example. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#def} +\label{inheritanceEtc.def} + +Syntax: +\begin{verbatim} +#def METHOD[(ARGUMENTS)] +#end def +\end{verbatim} + +Or the one-line variation: +\begin{verbatim} +#def METHOD[(ARGUMENTS)] : TEXT_AND_PLACEHOLDERS +\end{verbatim} + + +The \code{\#def} directive is used to define new methods in the generated +Python class, or to override superclass methods. It is analogous to Python's +\code{def} statement. The directive is silent, meaning it does not itself +produce any output. However, the content of the method will be inserted into +the output (and the directives executed) whenever the method is later called by +a \$placeholder. + +\begin{verbatim} +#def myMeth() +This is the text in my method +$a $b $c(123) ## these placeholder names have been defined elsewhere +#end def + +## and now use it... +$myMeth() +\end{verbatim} + +The arglist and parentheses can be omitted: +\begin{verbatim} +#def myMeth +This is the text in my method +$a $b $c(123) +#end def + +## and now use it... +$myMeth +\end{verbatim} + +Methods can have arguments and have defaults for those arguments, just like +in Python. Remember the \code{\$} before variable names: +\begin{verbatim} +#def myMeth($a, $b=1234) +This is the text in my method +$a - $b +#end def + +## and now use it... +$myMeth(1) +\end{verbatim} + +The output from this last example will be: + +\begin{verbatim} +This is the text in my method +1 - 1234 +\end{verbatim} + +There is also a single line version of the \code{\#def} directive. +{\bf Unlike the multi-line directives, it uses a colon (:) to delimit the method +signature and body}: +\begin{verbatim} +#attr $adj = 'trivial' +#def myMeth: This is the $adj method +$myMeth +\end{verbatim} +Leading and trailing whitespace is stripped from the method. This is in +contrast to: +\begin{verbatim} +#def myMeth2 +This is the $adj method +#end def +\end{verbatim} +where the method includes a newline after "method". If you don't want the +newline, add \code{\#slurp}: +\begin{verbatim} +#def myMeth3 +This is the $adj method#slurp +#end def +\end{verbatim} + +Because \code{\#def} is handled at compile time, it can appear above or +below the placeholders that call it. And if a superclass placeholder +calls a method that's overridden in a subclass, it's the subclass method +that will be called. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#block ... \#end block} +\label{inheritanceEtc.block} + + +The \code{\#block} directive allows you to mark a section of your template that +can be selectively reimplemented in a subclass. It is very useful for +changing part of a template without having to copy-paste-and-edit +the entire thing. The output from a template definition that uses blocks will +be identical to the output from the same template with the \code{\#block \ldots +\#end block} tags removed. + +({\em Note:} don't be confused by the generic word `block'' in this Guide, +which means a section of code inside {\em any} \code{\#TAG \ldots \#end TAG} +pair. Thus, an if-block, for-block, def-block, block-block etc. In this +section we are talking only of block-blocks.) + +To reimplement the block, use the \code{\#def} directive. The magical effect +is that it appears to go back and change the output text {\em at the point the +original block was defined} rather than at the location of the +reimplementation. + +\begin{verbatim} +#block testBlock +Text in the contents +area of the block directive +#if $testIt +$getFoo() +#end if +#end block testBlock +\end{verbatim} + +You can repeat the block name in the \code{\#end block} directive or not, as +you wish. + +\code{\#block} directives can be nested to any depth. + +\begin{verbatim} +#block outerBlock +Outer block contents + +#block innerBlock1 +inner block1 contents +#end block innerBlock1 + +#block innerBlock2 +inner block2 contents +#end block innerBlock2 + +#end block outerBlock +\end{verbatim} + +Note that the name of the block is optional for the \code{\#end block} tag. + +Technically, \code{\#block} directive is equivalent to a \code{\#def} directive +followed immediately by a \code{\#placeholder} for the same name. In fact, +that's what Cheetah does. Which means you can use \code{\$theBlockName} +elsewhere in the template to output the block content again. + +There is a one-line \code{\#block} syntax analagous to the one-line +\code{\#def}. + +The block must not require arguments because the implicit placeholder that's +generated will call the block without arguments. + + +% Local Variables: +% TeX-master: "users_guide" +% End: + + +Object-Oriented Documents +------------------------- + +.. + :label: howWorks.objoriented + +Because Cheetah documents are actually class definitions, templates may inherit +from one another in a natural way, using regular Python semantics. For +instance, consider this template, FrogBase.tmpl:: + + #def title + This document has not defined its title + #end def + #def htTitle + $title + #end def + <HTML><HEAD> + <TITLE>$title</TITLE> + </HEAD><BODY> + <H1>$htTitle</H1> + $body + </BODY></HTML> + +And its subclassed document, Frog1.tmpl:: + + #from FrogBase import FrogBase + #extends FrogBase + #def title + The Frog Page + #end def + #def htTitle + The <IMG SRC="Frog.png"> page + #end def + #def body + ... lots of info about frogs ... + #end def + + +This is a classic use of inheritance. The parent "template" is simply an +abstract superclass. Each document specializes the output of its parent. +For instance, here the parent defines +``\$htTitle`` so that by default it's identical to whatever the +``\$title`` is, but it can also be customized. + +In many other templating systems, you'd have to use case statements or +if-elseif blocks of some sort, repeated in many different sections of code. + +While we show another Cheetah document inheriting from this parent, a Python +class can inherit from it just as easily. This Python class could define its +programmatically-driven value for ``\$body`` and ``\$title``, simply by +defining body() and title() methods that return a string. (Actually they +can return anything, but we'll get into that later.) :: + + from FrogBase import FrogBase + class Frog2(FrogBase): + def title(self): + return "Frog 2 Page" + # We don't override .htTitle, so it defaults to "Frog 2 Page" too. + def body(self): + return " ... more info about frogs ..." + +Similarly, the Cheetah document can inherit from an arbitrary class. That's +how Cheetah makes templates usable as Webware servlets, by subclassing +``Servlet``. This technique should be possible for non-Webware systems +too. + +(*Note:*\ ``FrogBase.tmpl`` could be improved by using the +``\#block`` directive, section \ref{inheritanceEtc.block}.) + + diff --git a/docs/users_guide_2_src/09_flowControl.txt b/docs/users_guide_2_src/09_flowControl.txt new file mode 100755 index 0000000..75a5845 --- /dev/null +++ b/docs/users_guide_2_src/09_flowControl.txt @@ -0,0 +1,414 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Flow Control} +\label{flowControl} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#for ... \#end for} +\label{flowControl.for} + +Syntax: +\begin{verbatim} +#for $var in EXPR +#end for +\end{verbatim} + + +The \code{\#for} directive iterates through a sequence. The syntax is the same +as Python, but remember the \code{\$} before variables. + +Here's a simple client listing: +\begin{verbatim} +<TABLE> +#for $client in $service.clients +<TR> +<TD>$client.surname, $client.firstname</TD> +<TD><A HREF="mailto:$client.email" >$client.email</A></TD> +</TR> +#end for +</TABLE> +\end{verbatim} + +Here's how to loop through the keys and values of a dictionary: +\begin{verbatim} +<PRE> +#for $key, $value in $dict.items() +$key: $value +#end for +</PRE> +\end{verbatim} + +Here's how to create list of numbers separated by hyphens. This ``\#end for'' +tag shares the last line to avoid introducing a newline character after each +hyphen. +\begin{verbatim} +#for $i in range(15) +$i - #end for +\end{verbatim} + +If the location of the \code{\#end for} offends your sense of indentational +propriety, you can do this instead: +\begin{verbatim} +#for $i in $range(15) +$i - #slurp +#end for +\end{verbatim} + +The previous two examples will put an extra hyphen after last number. Here's +how to get around that problem, using the \code{\#set} directive, which will be +dealt with in more detail below. +\begin{verbatim} +#set $sep = '' +#for $name in $names +$sep$name +#set $sep = ', ' +#end for +\end{verbatim} + +Although to just put a separator between strings, you don't need a for loop: +\begin{verbatim} +#echo ', '.join($names) +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#repeat ... \#end repeat} +\label{flowControl.repeat} + +Syntax: +\begin{verbatim} +#repeat EXPR +#end repeat +\end{verbatim} + + +Do something a certain number of times. +The argument may be any numeric expression. +If it's zero or negative, the loop will execute zero times. +\begin{verbatim} +#repeat $times + 3 +She loves me, she loves me not. +#repeat +She loves me. +\end{verbatim} + + +Inside the loop, there's no way to tell which iteration you're on. If you +need a counter variable, use \code{\#for} instead with Python's \code{range} +function. Since Python's ranges are base 0 by default, there are two ways +to start counting at 1. Say we want to count from 1 to 5, and that +\code{\$count} is 5. +\begin{verbatim} +#for $i in $range($count) +#set $step = $i + 1 +$step. Counting from 1 to $count. +#end for + + +#for $i in $range(1, $count + 1) +$i. Counting from 1 to $count. +#end for +\end{verbatim} + + +A previous implementation used a local variable \code{\$i} as the repeat +counter. However, this prevented instances of \code{\#repeat} from +being nested. The current implementation does not have this problem as it +uses a new local variable for every instance of \code{\#repeat}. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#while ... \#end while} +\label{flowControl.while} + +Syntax: +\begin{verbatim} +#while EXPR +#end while +\end{verbatim} + + +\code{\#while} is the same as Python's \code{while} statement. It may be +followed by any boolean expression: +\begin{verbatim} +#while $someCondition('arg1', $arg2) +The condition is true. +#end while +\end{verbatim} + +Be careful not to create an infinite loop. \code{\#while 1} will loop until +the computer runs out of memory. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#if ... \#else if ... \#else ... \#end if} +\label{flowControl.if} + +Syntax: +\begin{verbatim} +#if EXPR +#else if EXPR +#elif EXPR +#else +#end if +\end{verbatim} + + +The \code{\#if} directive and its kin are used to display a portion of text +conditionally. \code{\#if} and \code{\#else if} should be followed by a +true/false expression, while \code{\#else} should not. Any valid Python +expression is allowed. As in Python, the expression is true unless it evaluates +to 0, '', None, an empty list, or an empty dictionary. In deference to Python, +\code{\#elif} is accepted as a synonym for \code{\#else if}. + +Here are some examples: +\begin{verbatim} +#if $size >= 1500 +It's big +#else if $size < 1500 and $size > 0 +It's small +#else +It's not there +#end if +\end{verbatim} + +\begin{verbatim} +#if $testItem($item) +The item $item.name is OK. +#end if +\end{verbatim} + +Here's an example that combines an \code{\#if} tag with a \code{\#for} tag. +\begin{verbatim} +#if $people +<table> +<tr> +<th>Name</th> +<th>Address</th> +<th>Phone</th> +</tr> +#for $p in $people +<tr> +<td>$p.name</td> +<td>$p.address</td> +<td>$p.phone</td> +</tr> +#end for +</table> +#else +<p> Sorry, the search did not find any people. </p> +#end if +\end{verbatim} + +See section \ref{output.oneLineIf} for the one-line \code{\#if} directive, +which is equivalent to Perl's and C's \code{?:} operator. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#unless ... \#end unless} +\label{flowControl.unless} + +Syntax: +\begin{verbatim} +#unless EXPR +#end unless +\end{verbatim} + + +\code{\#unless} is the opposite of \code{\#if}: the text is executed if the +condition is {\bf false}. Sometimes this is more convenient. +\code{\#unless EXPR} is equivalent to \code{\#if not (EXPR)}. + +\begin{verbatim} +#unless $alive +This parrot is no more! He has ceased to be! +'E's expired and gone to meet 'is maker! ... +THIS IS AN EX-PARROT!! +#end unless +\end{verbatim} + +You cannot use \code{\#else if} or \code{\#else} inside an \code{\#unless} +construct. If you need those, use \code{\#if} instead. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#break and \#continue} +\label{flowControl.break} + +Syntax: +\begin{verbatim} +#break +#continue +\end{verbatim} + + +These directives are used as in Python. \code{\#break} will +exit a \code{\#for} loop prematurely, while \code{\#continue} will immediately +jump to the next iteration in the \code{\#for} loop. + +In this example the output list will not contain ``10 - ''. +\begin{verbatim} +#for $i in range(15) +#if $i == 10 + #continue +#end if +$i - #slurp +#end for +\end{verbatim} + +In this example the loop will exit if it finds a name that equals 'Joe': +\begin{verbatim} +#for $name in $names +#if $name == 'Joe' + #break +#end if +$name - #slurp +#end for +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#pass} +\label{flowControl.pass} + +Syntax: +\begin{verbatim} +#pass +\end{verbatim} + + +The \code{\#pass} directive is identical to Python \code{pass} statement: it +does nothing. It can be used when a statement is required syntactically but the +program requires no action. + +The following example does nothing if only \$A is true +\begin{verbatim} +#if $A and $B + do something +#elif $A + #pass +#elif $B + do something +#else + do something +#end if +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#stop} +\label{flowControl.stop} + +Syntax: +\begin{verbatim} +#stop +\end{verbatim} + + +The \code{\#stop} directive is used to stop processing of a template at a +certain point. The output will show {\em only} what has been processed up to +that point. + +When \code{\#stop} is called inside an \code{\#include} it skips the rest of +the included code and continues on from after the \code{\#include} directive. +stop the processing of the included code. Likewise, when \code{\#stop} is +called inside a \code{\#def} or \code{\#block}, it stops only the \code{\#def} +or \code{\#block}. + +\begin{verbatim} +A cat +#if 1 + sat on a mat + #stop + watching a rat +#end if +in a flat. +\end{verbatim} + +will print +\begin{verbatim} +A cat + sat on a mat +\end{verbatim} + +And +\begin{verbatim} +A cat +#block action + sat on a mat + #stop + watching a rat +#end block +in a flat. +\end{verbatim} + +will print + +\begin{verbatim} +A cat + sat on a mat +in a flat. +\end{verbatim} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#return} +\label{flowControl.return} + +Syntax: +\begin{verbatim} +#return +\end{verbatim} + + +This is used as in Python. \code{\#return} will exit the current method with a +default return value of \code{None} or the value specified. It may be used +only inside a \code{\#def} or a \code{\#block}. + +Note that \code{\#return} is different from the \code{\#stop} directive, +which returns the sum of all text output from the method in which it is called. +The following examples illustrate this point: + +\begin{verbatim} +1 +$test[1] +3 +#def test +1.5 +#if 1 +#return '123' +#else +99999 +#end if +#end def +\end{verbatim} + +will produce +\begin{verbatim} +1 +2 +3 +\end{verbatim} + +while +\begin{verbatim} +1 +$test +3 +#def test +1.5 +#if 1 +#stop +#else +99999 +#end if +#end def +\end{verbatim} + +will produce +\begin{verbatim} +1 +1.5 +3 +\end{verbatim} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_2_src/10_errorHandling.txt b/docs/users_guide_2_src/10_errorHandling.txt new file mode 100755 index 0000000..28eee3a --- /dev/null +++ b/docs/users_guide_2_src/10_errorHandling.txt @@ -0,0 +1,145 @@ +\section{Error Handling} +\label{errorHandling} + +There are two ways to handle runtime errors (exceptions) in Cheetah. The first +is with the Cheetah directives that mirror Python's structured exception +handling statements. The second is with Cheetah's \code{ErrorCatcher} +framework. These are described below. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#try ... \#except ... \#end try, \#finally, and \#assert} +\label{errorHandling.directives} + +Cheetah's exception-handling directives are exact mirrors Python's +exception-handling statements. See Python's documentation for details. The +following Cheetah code demonstrates their use: + + +\begin{verbatim} +#try + $mightFail() +#except + It failed +#end try + +#try + #assert $x == $y +#except AssertionError + They're not the same! +#end try + +#try + #raise ValueError +#except ValueError + #pass +#end try + + +#try + $mightFail() +#except ValueError + Hey, it raised a ValueError! +#except NameMapper.NotFound + Hey, it raised a NameMapper.NotFound! +#else + It didn't raise anything! +#end try + +#try + $mightFail() +#finally + $cleanup() +#end try +\end{verbatim} + +Like Python, \code{\#except} and \code{\#finally} cannot appear in the same +try-block, but can appear in nested try-blocks. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#errorCatcher and ErrorCatcher objects} +\label{errorHandling.errorCatcher} + +Syntax: +\begin{verbatim} +#errorCatcher CLASS +#errorCatcher $PLACEHOLDER_TO_AN_ERROR_CATCHER_INSTANCE +\end{verbatim} + + +\code{ErrorCatcher} is a debugging tool that catches exceptions that occur +inside \code{\$placeholder} tags and provides a customizable warning to the +developer. Normally, the first missing namespace value raises a +\code{NameMapper.NotFound} error and halts the filling of the template. This +requires the developer to resolve the exceptions in order without seeing the +subsequent output. When an \code{ErrorCatcher} is enabled, the developer can +see all the exceptions at once as well as the template output around them. + +The \code{Cheetah.ErrorCatchers} module defines the base class for +ErrorCatchers: + +\begin{verbatim} +class ErrorCatcher: + _exceptionsToCatch = (NameMapper.NotFound,) + + def __init__(self, templateObj): + pass + + def exceptions(self): + return self._exceptionsToCatch + + def warn(self, exc_val, code, rawCode, lineCol): + return rawCode +\end{verbatim} + +This ErrorCatcher catches \code{NameMapper.NotFound} exceptions and leaves the +offending placeholder visible in its raw form in the template output. If the +following template is executed: +\begin{verbatim} +#errorCatcher Echo +#set $iExist = 'Here I am!' +Here's a good placeholder: $iExist +Here's bad placeholder: $iDontExist +\end{verbatim} + +the output will be: +\begin{verbatim} +Here's a good placeholder: Here I am! +Here's bad placeholder: $iDontExist +\end{verbatim} + +The base class shown above is also accessible under the alias +\code{Cheetah.ErrorCatchers.Echo}. \code{Cheetah.ErrorCatchers} also provides a +number of specialized subclasses that warn about exceptions in different ways. +\code{Cheetah.ErrorCatchers.BigEcho} will output + +\begin{verbatim} +Here's a good placeholder: Here I am! +Here's bad placeholder: ===============<$iDontExist could not be found>=============== +\end{verbatim} + +ErrorCatcher has a significant performance impact and is turned off by default. +It can also be turned on with the \code{Template} class' \code{'errorCatcher'} +keyword argument. The value of this argument should either be a string +specifying which of the classes in \code{Cheetah.ErrorCatchers} to use, or a +class that subclasses \code{Cheetah.ErrorCatchers.ErrorCatcher}. The +\code{\#errorCatcher} directive can also be used to change the errorCatcher part +way through a template. + +\code{Cheetah.ErrorCatchers.ListErrors} will produce the same ouput as +\code{Echo} while maintaining a list of the errors that can be retrieved later. +To retrieve the list, use the \code{Template} class' \code{'errorCatcher'} +method to retrieve the errorCatcher and then call its \code{listErrors} method. + +ErrorCatcher doesn't catch exceptions raised inside directives. + +% @@MO: How do you turn ErrorCatcher off after turn it on. +% '#ErrorCatcher None'? + +% Local Variables: +% TeX-master: "users_guide" +% End: + + + + diff --git a/docs/users_guide_2_src/11_parserInstructions.txt b/docs/users_guide_2_src/11_parserInstructions.txt new file mode 100755 index 0000000..bfd6bc2 --- /dev/null +++ b/docs/users_guide_2_src/11_parserInstructions.txt @@ -0,0 +1,116 @@ +\section{Instructions to the Parser/Compiler} +\label{parserInstructions} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#breakpoint} +\label{parserInstructions.breakpoint} + +Syntax: +\begin{verbatim} +#breakpoint +\end{verbatim} + + +\code{\#breakpoint} is a debugging tool that tells the parser to stop +parsing at a specific point. All source code from that point on will be ignored. + +The difference between \code{\#breakpoint} and \code{\#stop} is that +\code{\#stop} occurs in normal templates (e.g., inside an \code{\#if}) but +\code{\#breakpoint} is used only when debugging Cheetah. Another difference is +that \code{\#breakpoint} operates at compile time, while \code{\#stop} is +executed at run time while filling the template. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{\#compiler-settings} +\label{parserInstructions.compiler-settings} + +Syntax: +\begin{verbatim} +#compiler-settings +key = value (no quotes) +#end compiler-settings + +#compiler-settings reset +\end{verbatim} + + +The \code{\#compiler-settings} directive overrides Cheetah's standard settings, +changing how it parses source code and generates Python code. This +makes it possible to change the behaviour of Cheetah's parser/compiler for a +certain template, or within a portion of the template. + +The \code{reset} argument reverts to the default settings. With \code{reset}, +there's no end tag. + +Here are some examples of what you can do: +\begin{verbatim} +$myVar +#compiler-settings +cheetahVarStartToken = @ +#end compiler-settings +@myVar +#compiler-settings reset +$myVar +\end{verbatim} + + +\begin{verbatim} +## normal comment +#compiler-settings +commentStartToken = // +#end compiler-settings + +// new style of comment + +#compiler-settings reset + +## back to normal comments +\end{verbatim} + +\begin{verbatim} +#slurp +#compiler-settings +directiveStartToken = % +#end compiler-settings + +%slurp +%compiler-settings reset + +#slurp +\end{verbatim} + +Here's a partial list of the settings you can change: +\begin{enumerate} +\item syntax settings + \begin{enumerate} + \item cheetahVarStartToken + \item commentStartToken + \item multilineCommentStartToken + \item multilineCommentEndToken + \item directiveStartToken + \item directiveEndToken + \end{enumerate} +\item code generation settings + \begin{enumerate} + \item commentOffset + \item outputRowColComments + \item defDocStrMsg + \item useNameMapper + \item useAutocalling + \item reprShortStrConstants + \item reprNewlineThreshold + \end{enumerate} +\end{enumerate} +The meaning of these settings and their default values will be documented in +the future. + + +% Local Variables: +% TeX-master: "users_guide" +% End: + + + + diff --git a/docs/users_guide_2_src/12_moduleFormatting.txt b/docs/users_guide_2_src/12_moduleFormatting.txt new file mode 100644 index 0000000..9c558e3 --- /dev/null +++ b/docs/users_guide_2_src/12_moduleFormatting.txt @@ -0,0 +1 @@ +. diff --git a/docs/users_guide_2_src/13_tipsAndTroubleshooting.txt b/docs/users_guide_2_src/13_tipsAndTroubleshooting.txt new file mode 100755 index 0000000..a7b58e5 --- /dev/null +++ b/docs/users_guide_2_src/13_tipsAndTroubleshooting.txt @@ -0,0 +1,549 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Tips, Tricks and Troubleshooting} +\label{tips} + +Troubleshooting: make a precomiled template with "cheetah compile" and inspect +the Python code. Put $_CHEETAH__searchList in the template. (Caveat about +"<value>" results.) Make a tiny template containing only the suspicious code +and precompile it. + +This chapter contains short stuff that doesn't fit anywhere else. + +See the Cheetah FAQ for more specialized issues and for troubleshooting tips. +Check the wiki periodically for recent tips contributed by users. If you +get stuck and none of these resources help, ask on the mailing list. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Placeholder Tips} +\label{tips.placeholder} + +Here's how to do certain important lookups that may not be obvious. +For each, we show first the Cheetah expression and then the Python equivalent, +because you can use these either in templates or in pure Python subclasses. +The Cheetah examples use NameMapper shortcuts (uniform dotted notation, +autocalling) as much as possible. + +To verify whether a variable exists in the searchList: +\begin{verbatim} +$varExists('theVariable') +self.varExists('theVariable') +\end{verbatim} +This is useful in \code{\#if} or \code{\#unless} constructs to avoid a +\code{\#NameMapper.NotFound} error if the variable doesn't exist. For instance, +a CGI GET parameter that is normally supplied but in this case the user typed +the URL by hand and forgot the parameter (or didn't know about it). +(\code{.hasVar} is a synonym for \code{.varExists}.) + +To look up a variable in the searchList from a Python method: +\begin{verbatim} +self.getVar('theVariable') +self.getVar('theVariable', myDefault) +\end{verbatim} +This is the equivalent to \code{\$theVariable} in the template. If the +variable is missing, it returns the second argument, \code{myDefault}, if +present, or raises \code{NameMapper.NotFound} if there is no second argument. +However, it usually easier to write your method so that all needed searchList +values come in as method arguments. That way the caller can just use a +\code{\$placeholder} to specify the argument, which is less verbose than you +writing a getVar call. + +To do a ``safe'' placeholder lookup that returns a default value if the +variable is missing: +\begin{verbatim} +$getVar('theVariable', None) +$getVar('theVariable', $myDefault) +\end{verbatim} + +To get an environmental variable, put \code{os.environ} on the searchList as a +container. Or read the envvar in Python code and set a placeholder variable +for it. + +Remember that variables found earlier in the searchList override same-name +variables located in a later searchList object. Be careful when adding objects +containing other variables besides the ones you want (e.g., \code{os.environ}, +CGI parameters). The "other" variables may override variables your application +depends on, leading to hard-to-find bugs. Also, users can inadvertently or +maliciously set an environmental variable or CGI parameter you didn't expect, +screwing up your program. To avoid all this, know what your namespaces +contain, and place the namespaces you have the most control over first. For +namespaces that could contain user-supplied "other" variables, don't put the +namespace itself in the searchList; instead, copy the needed variables into +your own "safe" namespace. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Diagnostic Output} +\label{tips.diagnostic} + +If you need send yourself some debugging output, you can use \code{\#silent} to +output it to standard error: +\begin{verbatim} +#silent $sys.stderr.write("Incorrigible var is '$incorrigible'.\n") +#silent $sys.stderr.write("Is 'unknown' in the searchList? " + + $getVar("unknown", "No.") + "\n" ) +\end{verbatim} +(Tip contributed by Greg Czajkowski.) + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{When to use Python methods} +\label{tips.pythonMethods} + +You always have a choice whether to code your methods as Cheetah \code{\#def} +methods or Python methods (the Python methods being located in a class your +template inherits). So how do you choose? + +Generally, if the method consists mostly of text and placeholders, use a +Cheetah method (a \code{\#def} method). That's why \code{\#def} exists, to +take the tedium out of writing those kinds of methods. And if you have a +couple \code{\#if} stanzas to \code{\#set} some variables, followed by a +\code{\#for} loop, no big deal. But if your method consists mostly of +directives and only a little text, you're better off writing it in Python. +Especially be on the watch for extensive use of \code{\#set}, \code{\#echo} and +\code{\#silent} in a Cheetah method--it's a sure sign you're probably using the +wrong language. Of course, though, you are free to do so if you wish. + +Another thing that's harder to do in Cheetah is adjacent or nested +multiline stanzas (all those directives with an accompanying \code{\#end} +directive). Python uses indentation to show the beginning and end of nested +stanzas, but Cheetah can't do that because any indentation shows up in the +output, which may not be desired. So unless all those extra spaces and tabs +in the output are acceptable, you have to keep directives flush with the left +margin or the preceding text. + +The most difficult decisions come when you have conflicting goals. What if +a method generates its output in parts (i.e., output concatenation), contains +many searchList placeholders and lots of text, {\em and} requires lots of +\code{\#if \ldots \#set \ldots \#else \#set \ldots \#end if} stanzas. A Cheetah +method would be more advantageous in some ways, but a Python method in others. +You'll just have to choose, perhaps coding groups of methods all the same +way. Or maybe you can split your method into two, one Cheetah and one Python, +and have one method call the other. Usually this means the Cheetah method +calling the Python method to calculate the needed values, then the Cheetah +method produces the output. One snag you might run into though is that +\code{\#set} currently can set only one variable per statement, so if your +Python method needs to return multiple values to your Cheetah method, you'll +have to do it another way. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Calling superclass methods, and why you have to} +\label{tips.callingSuperclassMethods} + +If your template or pure Python class overrides a standard method or attribute +of \code{Template} or one of its base classes, you should call the superclass +method in your method to prevent various things from breaking. The most common +methods to override are \code{.awake} and \code{.\_\_init\_\_}. \code{.awake} +is called automatically by Webware early during the web transaction, so it makes +a convenient place to put Python initialization code your template needs. +You'll definitely want to call the superclass \code{.awake} because it sets up +many wonderful attributes and methods, such as those to access the CGI input +fields. + +There's nothing Cheetah-specific to calling superclass methods, but +because it's vital, we'll recap the standard Python techniques +here. We mention only the solution for old-style classes because +Cheetah classes are old-style (in other Python documentation, you will +find the technique for new-style classes, but they are not listed here +because they cannot be used with Cheetah if you use +dynamically-compiled templates). + +\begin{verbatim} +from Cheetah.Template import Template +class MyClass(Template): + def awake(self, trans): + Template.awake(self, trans) + ... great and exciting features written by me ... +\end{verbatim} + +[ @@MO: Need to test this. .awake is in Servlet, which is a superclass +of Template. Do we really need both imports? Can we call +Template.awake? ] + +To avoid hardcoding the superclass name, you can use this +function \code{callbase()}, which emulates \code{super()} for older versions of +Python. It also works even \code{super()} does exist, so you don't have to +change your servlets immediately when upgrading. Note that the argument +sequence is different than \code{super} uses. + +\begin{verbatim} +=========================================================================== +# Place this in a module SOMEWHERE.py . Contributed by Edmund Lian. +class CallbaseError(AttributeError): + pass + +def callbase(obj, base, methodname='__init__', args=(), kw={}, + raiseIfMissing=None): + try: method = getattr(base, methodname) + except AttributeError: + if raiseIfMissing: + raise CallbaseError, methodname + return None + if args is None: args = () + return method(obj, *args, **kw) +=========================================================================== +# Place this in your class that's overriding .awake (or any method). +from SOMEWHERE import callbase +class MyMixin: + def awake(self, trans): + args = (trans,) + callbase(self, MyMixin, 'awake', args) + ... everything else you want to do ... +=========================================================================== +\end{verbatim} + +% @@MO: Edmund wants us to mention delegation too, as an alternative to +% inheritance. Contact elian@inbrief.net for details. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{All methods} +\label{tips.allMethods} + +Here is a list of all the standard methods and attributes that can be accessed +from a placeholder. Some of them exist for you to call, others are mainly used +by Cheetah internally but you can call them if you wish, and others are only +for internal use by Cheetah or Webware. Do not use these method names in mixin +classes (\code{\#extends}, section \ref{inheritanceEtc.extends}) unless you +intend to override the standard method. + +Variables with a star prefix ({\bf *}) are frequently used in templates or in +pure Python classes. + +\paragraph*{Inherited from Cheetah.Template} + +\begin{description} +\item{{\bf compile(source=None, file=None, moduleName=None, + mainMethodName='respond')}} Compile the template. Automatically called + by \code{.\_\_init\_\_}. +\item{{\bf generatedModuleCode()}} Return the module code the compiler + generated, or \code{None} if no compilation took place. +\item{{\bf generatedClassCode()}} Return the class code the compiler + generated, or \code{None} if no compilation took place. +\item{{\bf * searchList()}} Return a reference to the underlying search list. + (a list of objects). Use this to print out your searchList for debugging. + Modifying the returned list will affect your placeholder searches! +\item{{\bf * errorCatcher()}} Return a reference to the current error + catcher. +\item{{\bf * refreshCache(cacheKey=None)}} If 'cacheKey' is not \code{None}, + refresh that item in the cache. If \code{None}, delete all items in the + cache so they will be recalculated the next time they are encountered. +\item{{\bf * shutdown()}} Break reference cycles before discarding a servlet. +\item{{\bf * getVar(varName, default=NoDefault, autoCall=True)}} Look up a + variable in the searchList. Same as \code{\$varName} but allows you to + specify a default value and control whether autocalling occurs. +\item{{\bf * varExists(varName, autoCall=True)}} +\item{{\bf * getFileContents(path)}} Read the named file. If used as a + placeholder, inserts the file's contents in the output without + interpretation, like \code{\#include\ raw}. If used in an expression, + returns the file's content (e.g., to assign it to a variable). +\item{{\bf runAsMainProgram()}} This is what happens if you run a + .py template module as a standalone program. +\end{description} + +%Private methods: {\bf \_bindCompiledMethod}, {\bf \_bindFunctionAsMethod}, +%{\bf \_includeCheetahSource}, {\bf \_genTmpFilename}, +%{\bf \_importAsDummyModule}, {\bf \_makeDummyPackageForDir}, +%{\bf \_importFromDummyPackage}, {\bf \_importModuleFromDirectory}. +% +%Other private attributes: +%\begin{description} +%\item{{\bf * \_fileMtime}} Time the template definition was modified, in +% Unix ticks. \code{None} if the template definition came from a string or +% file handle rather than a named file, same for the next three variables. +%\item{{\bf * \_fileDirName}} The directory containing the template definition. +%\item{{\bf * \_fileBaseName}} The basename of the template definition file. +%\item{{\bf * \_filePath}} The directory+filename of the template definition. +%\end{description} + +\paragraph*{Inherited from Cheetah.Utils.WebInputMixin} + +\begin{description} +\item{{\bf nonNumericInputError}} Exception raised by \code{.webInput}. +\item{{\bf * webInput(...)}} Convenience method to access GET/POST variables + from a Webware servlet or CGI script, or Webware cookie or session + variables. See section \ref{webware.webInput} for usage information. +\end{description} + +\paragraph*{Inherited from Cheetah.SettingsManager} + +\begin{description} +\item{{\bf setting(name, default=NoDefault)}} Get a compiler setting. +\item{{\bf hasSetting(name)}} Does this compiler setting exist? +\item{{\bf setSetting(name, value)}} Set setting 'name' to 'value'. + See \code{\#compiler-settings}, section + \ref{parserInstructions.compiler-settings}. +\item{{\bf settings()}} Return the underlying settings dictionary. (Warning: + modifying this dictionary will change Cheetah's behavior.) +\item{{\bf copySettings()}} Return a copy of the underlying settings + dictionary. +\item{{\bf deepcopySettings()}} Return a deep copy of the underlying settings + dictionary. See Python's \code{copy} module. +\item{{\bf updateSettings(newSettings, merge=True)}} Update Cheetah's + compiler settings from the 'newSettings' dictionary. If 'merge' is true, + update only the names in newSettings and leave the other names alone. + (The SettingsManager is smart enough to update nested dictionaries one + key at a time rather than overwriting the entire old dictionary.) + If 'merge' is false, delete all existing settings so that the new ones are + the only settings. +\item{{\bf updateSettingsFromPySrcStr(theString, merge=True)}} Same, + but pass a string of \code{name=value} pairs rather + than a dictionary, the same as you would provide in a + \code{\#compiler-settings} directive, section + \ref{parserInstructions.compiler-settings}. +\item{{\bf updateSettingsFromPySrcFile(path, merge=True)}} Same, but + exec a Python source file and use the variables it contains as the new + settings. (e.g., \code{cheetahVarStartToken\ =\ "@"}). +\item{{\bf updateSettingsFromConfigFile(path, **kw)}} Same, but get the new + settings from a text file in ConfigParser format (similar to Windows' + *.ini file format). See Python's \code{ConfigParser} module. +\item{{\bf updateSettingsFromConfigFileObj}} Same, but read the open file + object 'inFile' for the new settings. +\item{{\bf updateSettingsFromConfigStr(configStr, convert=True, merge=True}} + Same, but read the new settings from a string in ConfigParser format. +\item{{\bf writeConfigFile(path)}} Write the current compiler settings to + a file named 'path' in *.ini format. +\item{{\bf getConfigString()}} Return a string containing the current + compiler settings in *.ini format. +\end{description} + +\paragraph*{Inherited from Cheetah.Servlet} + +{\em Do not override these in a subclass or assign to them as attributes +if your template will be used as a servlet,} otherwise Webware will behave +unpredictably. However, it {\em is} OK to put same-name variables in the +searchList, because Webware does not use the searchList. + +EXCEPTION: It's OK to override {\bf awake} and {\bf sleep} as long as you +call the superclass methods. (See section +\ref{tips.callingSuperclassMethods}.) + +\begin{description} +\item{{\bf * isControlledByWebKit}} True if this template instance is + part of a live transaction in a running WebKit servlet. +\item{{\bf * isWebwareInstalled}} True if Webware is installed and the + template instance inherits from WebKit.Servlet. If not, it inherits + from Cheetah.Servlet.DummyServlet. +\item{{\bf * awake(transaction)}} Called by WebKit at the beginning of + the web transaction. +\item{{\bf * sleep(transaction)}} Called by WebKit at the end of the + web transaction. +\item{{\bf * respond(transaction)}} Called by WebKit to produce the + web transaction content. For a template-servlet, this means + filling the template. +\item{{\bf shutdown()}} Break reference cycles before deleting instance. +\item{{\bf * serverSidePath()}} The filesystem pathname of the + template-servlet (as opposed to the URL path). +\item{{\bf transaction}} The current Webware transaction. +\item{{\bf application}} The current Webware application. +\item{{\bf response}} The current Webware response. +\item{{\bf request}} The current Webware request. +\item{{\bf session}} The current Webware session. +\item{{\bf write}} Call this method to insert text in the filled template + output. +\end{description} + +Several other goodies are available to template-servlets under the +\code{request} attribute, see section \ref{webware.input}. + +\code{transaction}, \code{response}, \code{request} and \code{session} are +created from the current transaction when WebKit calls \code{awake}, and don't +exist otherwise. Calling \code{awake} yourself (rather than letting WebKit +call it) will raise an exception because the \code{transaction} argument won't +have the right attributes. + +\paragraph*{Inherited from WebKit.Servlet} +These are accessible only if Cheetah knows Webware is installed. This +listing is based on a CVS snapshot of Webware dated 22 September 2002, and +may not include more recent changes. + +The same caveats about overriding these methods apply. + +\begin{description} +\item{name()} The simple name of the class. Used by Webware's logging and + debugging routines. +\item{log()} Used by Webware's logging and debugging routines. +\item{canBeThreaded()} True if the servlet can be multithreaded. +\item{canBeReused()} True if the servlet can be used for another transaction + after the current transaction is finished. +\item{serverSideDir()} Depreciated by \code{.serverSidePath()}. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Optimizing templates} +\label{tips.optimizing} + +Here are some things you can do to make your templates fill faster and user +fewer CPU cycles. Before you put a lot of energy into this, however, make +sure you really need to. In many situations, templates appear to initialize +and fill instantaneously, so no optimization is necessary. If you do find a +situation where your templates are filling slowly or taking too much memory or +too many CPU cycles, we'd like to hear about it on the mailing list. + +Cache \$placeholders whose values don't change frequently. (Section +\ref{output.caching}). + +Use \code{\#set} for values that are very frequently used, especially if they +come out of an expensive operation like a deeply.nested.structure or a database +lookup. \code{\#set} variables are set to Python local variables, which have a +faster lookup time than Python globals or values from Cheetah's searchList. + +Moving variable lookups into Python code may provide a speedup in certain +circumstances. If you're just reading \code{self} attributes, there's no +reason to use NameMapper lookup (\$placeholders) for them. NameMapper does +a lot more work than simply looking up a \code{self} attribute. + +On the other hand, if you don't know exactly where the value will come from +(maybe from \code{self}, maybe from the searchList, maybe from a CGI input +variable, etc), it's easier to just make that an argument to your method, and +then the template can handle all the NameMapper lookups for you: +\begin{verbatim} +#silent $myMethod($arg1, $arg2, $arg3) +\end{verbatim} +Otherwise you'd have to call \code{self.getVar('arg1')} etc in your +method, which is more wordy, and tedious. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{PSP-style tags} +\label{tips.PSP} + +\code{<\%= \ldots \%>} and \code{<\% \ldots \%>} allow an escape +to Python syntax inside the template. You do not need it to use Cheetah +effectively, and we're hard pressed to think of a case to recommend it. +Nevertheless, it's there in case you encounter a situation you can't +express adequately in Cheetah syntax. For instance, to set a local +variable to an elaborate initializer. + +\code{<\%= \ldots \%>} encloses a Python expression whose result will +be printed in the output. + +\code{<\% \ldots \%>} encloses a Python statement or expression (or set of +statements or expressions) that will be included as-is into the generated +method. The statements themselves won't produce any output, but you can use +the local function \code{write(EXPRESSION)} to produce your own output. +(Actually, it's a method of a file-like object, but it looks like a local +function.) This syntax also may be used to set a local variable with a +complicated initializer. + +To access Cheetah services, you must use Python code like you would in an +inherited Python class. For instance, use \code{self.getVar()} to look up +something in the searchList. + +{\em Warning:} {\bf No error checking is done!} If you write: +\begin{verbatim} +<% break %> ## Wrong! +\end{verbatim} +you'll get a \code{SyntaxError} when you fill the template, but that's what you +deserve. + +Note that these are PSP-{\em style} tags, not PSP tags. A Cheetah template +is not a PSP document, and you can't use PSP commands in it. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Makefiles} +\label{tips.Makefile} + +If your project has several templates and you get sick of typing +``cheetah compile FILENAME.tmpl'' all the time--much less remembering which +commands to type when--and your system has the \code{make} +command available, consider building a Makefile to make your life easier. + +Here's a simple Makefile that controls two templates, ErrorsTemplate and +InquiryTemplate. Two external commands, \code{inquiry} and \code{receive}, +depend on ErrorsTemplate.py. Aditionally, InquiryTemplate +itself depends on ErrorsTemplate. + +\begin{verbatim} +all: inquiry receive + +.PHONY: all receive inquiry printsource + +printsource: + a2ps InquiryTemplate.tmpl ErrorsTemplate.tmpl + +ErrorsTemplate.py: ErrorsTemplate.tmpl + cheetah compile ErrorsTemplate.tmpl + +InquiryTemplate.py: InquiryTemplate.tmpl ErrorsTemplate.py + cheetah compile InquiryTemplate.tmpl + +inquiry: InquiryTemplate.py ErrorsTemplate.py + +receive: ErrorsTemplate.py +\end{verbatim} + +Now you can type \code{make} anytime and it will recompile all the templates +that have changed, while ignoring the ones that haven't. Or you can +recompile all the templates \code{receive} needs by typing \code{make receive}. +Or you can recompile only ErrorsTemplate by typing +\code{make ErrorsTemplate}. There's also another target, ``printsource'': +this sends a Postscript version of the project's source files to the printer. +The .PHONY target is explained in the \code{make} documentation; essentially, +you have it depend on every target that doesn't produce an output file with +the same name as the target. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Using Cheetah in a Multi-Threaded Application} +\label{tips.threads} + +Template classes may be shared freely between threads. However, template +instances should not be shared unless you either: +\begin{itemize} +\item Use a lock (mutex) to serialize template fills, to prevent two threads +from filling the template at the same time. +\item Avoid thread-unsafe features: + \begin{itemize} + \item Modifying searchList values or instance variables. + \item Caching (\code{\$*var}, \code{\#cache}, etc). + \item \code{\#set global}, \code{\#filter}, \code{\#errorCatcher}. + \end{itemize} + Any changes to these in one thread will be visible in other threads, + causing them to give inconsistent output. +\end{itemize} + +About the only advantage in sharing a template instance is building up the +placeholder cache. But template instances are so low overhead that it +probably wouldn't take perceptibly longer to let each thread instantiate its +own template instance. Only if you're filling templates several times a +second would the time difference be significant, or if some of the placeholders +trigger extremely slow calculations (e.g., parsing a long text file each time). +The biggest overhead in Cheetah is importing the \code{Template} module in +the first place, but that has to be done only once in a long-running +application. + +You can use Python's \code{mutex} module for the lock, or any similar +mutex. If you have to change searchList values or instance variables +before each fill (which is usually the case), lock the mutex before +doing this, and unlock it only after the fill is complete. + +For Webware servlets, you're probably better off using Webware's servlet +caching rather than Cheetah's caching. Don't override the servlet's +\code{.canBeThreaded()} method unless you avoid the unsafe operations +listed above. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Using Cheetah with gettext} +\label{tips.gettext} + +{\bf gettext} is a project for creating internationalized applications. For +more details, visit \url{http://docs.python.org/lib/module-gettext.html}. +gettext can be used with Cheetah to create internationalized applications, even +for CJK character sets, but you must keep a couple things in mind: +\begin{itemize} +\item xgettext is used on compiled templates, not on the templates themselves. +\item The way the NameMapper syntax gets compiled to Python gets in the way of +the syntax that xgettext recognizes. Hence, a special case exists for the +functions \code{_}, \code{N_}, and \code{ngettext}. If you need to use a +different set of functions for marking strings for translation, you must set +the Cheetah setting \code{gettextTokens} to a list of strings representing the +names of the functions you are using to mark strings for translation. +\end{itemize} + + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_2_src/13a_precompiledTemplateModules.txt b/docs/users_guide_2_src/13a_precompiledTemplateModules.txt new file mode 100644 index 0000000..5b0f978 --- /dev/null +++ b/docs/users_guide_2_src/13a_precompiledTemplateModules.txt @@ -0,0 +1,109 @@ +A look inside precompiled template modules +========================================== + +.. + :label: howWorks.pyTrivia + +When debugging a template, it's useful to compile it with "cheetah compile" +and then inspect the resulting Python module. This will often clear up whether +Cheetah misinterpreted your intent. You can do this even if you don't intend to +use the precompiled templates in production. It's also a good way to learn how +Cheetah works. Simply make a throwaway template definition containing only one +placeholder or directive, compile it with "cheetah compile", and see what +Python code Cheetah generated. + +However, precompiled template modules can be a bit cryptic to read unless you +have a bit of background information. Let's look at an example. Put the +following into /tmp/x.tmpl (or any other file) and run "cheetah compile" on +it:: + + The number is $Test.unittest.main. + #set mood = "lucky" + I'm feeling $lucky. + +Open the resulting /tmp/x.py in your favorite text editor. You'll see a class +with the same name as the module:: + + class x(Template): + +This template class contains a method ``.respond()``:: + + def respond(self, trans=None): + ## CHEETAH: main method generated for this template + if (not trans and not self._CHEETAH__isBuffering and + not callable(self.transaction)): + trans = self.transaction # is None unless self.awake() was called + if not trans: + trans = DummyTransaction() + _dummyTrans = True + else: _dummyTrans = False + write = trans.response().write + SL = self._CHEETAH__searchList + _filter = self._CHEETAH__currentFilter + + ######################################## + ## START - generated method body + + + write('The number is ') + _v = VFFSL(SL,"Test.unittest.main",True) + # '$Test.unittest.main' on line 1, col 15 + if _v is not None: write(_filter(_v, rawExpr='$Test.unittest.main')) + # from line 1, col 15. + write('.\n') + mood = "lucky" + write("I'm feeling ") + _v = VFFSL(SL,"lucky",True) # '$lucky' on line 3, col 13 + if _v is not None: write(_filter(_v, rawExpr='$lucky')) + # from line 3, col 13. + write('.\n') + + ######################################## + ## END - generated method body + + return _dummyTrans and trans.response().getvalue() or "" + +This becomes clearer when we scroll up to see some important imports and +global variables:: + + from Cheetah.Template import Template + from Cheetah.DummyTransaction import DummyTransaction + from Cheetah.NameMapper import NotFound, valueFromFrameOrSearchList + VFFSL=valueFromFrameOrSearchList + __CHEETAH_version__ = '2.0rc6' + __CHEETAH_src__ = 'x.tmpl' + +The actual code will differ slightly depending on your Cheetah version. Also, +we've split some long lines to make this page printer-friendly. + +Placeholder lookup is handled by ``VFFSL``, which is really the +``Cheetah.NameMapper.valueFromFrameOrSearchList`` function or its equivalent +in Cheetah/_namemapper.c. + +``trans`` and ``write()`` are Webware compatibility features. Normally +``trans`` is not specified and Cheetah creates a ``DummyTransaction`` +instance. ``write()`` is a shortcut for ``trans.response().write()``, +which concatenates the output to an internal buffer. The method returns +the result: ``trans.response().getvalue()``. You might assume from +``.getvalue()`` that Cheetah uses ``StringIO`` internally, but you'd be wrong. +Cheetah *used* to use ``StringIO`` but now it uses a list and ``str.join()``. +The ``.getvalue()`` name is retained for backward compatibility. + +If this template is part of a Webware site and the user enters its URL, Webware +calls ``.respond()`` with a live Webware transaction. In this case, +``write()`` writes the output directly to Webware's output stream. (Or to +a Webware buffer, but that's not our concern.) There's nothing to return +because the output has already been written, so the method returns the empty +string. That way if it accidentally gets concatenated to the output, no harm +will be done. + +You can write your own transaction class to support non-Webware output +streaming, but Cheetah currently comes with no examples of this. Ask on +the mailing list if you need help with it. + +Global variables and class attributes defined by Cheetah have a +``_CHEETAH_`` prefix. Instance attributes defined by Cheetah have a +``__CHEETAH__`` prefix (two trailing underscores). You should normally +never write to these but you can read them if desired; many are +self-explanatory. One such attribute is ``._CHEETAH__searchList``. This +is the actual search List ``VFFSL()`` will consult for placeholder lookups. diff --git a/docs/users_guide_2_src/14_webware.txt b/docs/users_guide_2_src/14_webware.txt new file mode 100755 index 0000000..8c47e90 --- /dev/null +++ b/docs/users_guide_2_src/14_webware.txt @@ -0,0 +1,582 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Using Cheetah with Webware} +\label{webware} + +{\bf Webware for Python} is a 'Python-Powered Internet Platform' that runs +servlets in a manner similar to Java servlets. {\bf WebKit} is the name of +Webware's application server. For more details, please visit +\url{http://webware.sourceforge.net/}. + +All comments below refer to the official version of Webware, the DamnSimple! +offshoot at ?, and the now-abandoned WebwareExperimental implementation at +\url{http://sourceforge.net/projects/expwebware/}, except where noted. All the +implementations are 95\% identical to the servlet writer: their differences lie +in their internal structure and configuration files. One difference is that +the executable you run to launch standard Webware is called \code{AppServer}, +whereas in WebwareExperimental it's called \code{webkit}. But to servlets +they're both "WebKit, Webware's application server", so it's one half dozen to +the other. In this document, we generally use the term {\bf WebKit} to refer +to the currently-running application server. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Installing Cheetah on a Webware system} +\label{webware.installing} + +Install Cheetah after you have installed Webware, following the instructions in +chapter \ref{gettingStarted}. + +The standard Cheetah test suite ('cheetah test') does not test Webware features. +We plan to build a test suite that can run as a Webware servlet, containing +Webware-specific tests, but that has not been built yet. In the meantime, you +can make a simple template containing something like "This is a very small +template.", compile it, put the *.py template module in a servlet +directory, and see if Webware serves it up OK. + +{\em You must not have a Webware context called "Cheetah".} If you do, Webware +will mistake that directory for the Cheetah module directory, and all +template-servlets will bomb out with a "ImportError: no module named Template". +(This applies only to the standard Webware; WebwareExperimental does not have +contexts.) + +If Webware complains that it cannot find your servlet, make sure +'.tmpl' is listed in 'ExtensionsToIgnore' in your 'Application.config' file. + +% @@MO: Should explain extension cascading and how without it, standard +% Webware pretends a file doesn't exist if it finds two or more servable files +% that match the URL. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Containment vs Inheritance} +\label{webware.background} + +Because Cheetah's core is flexible, there are many ways to integrate it with +Webware servlets. There are two broad strategies: the {\bf Inheritance +approach} and the {\bf Containment approach}. The difference is +that in the Inheritance approach, your template object \code{\em is} the +servlet, whereas in the Containment approach, the servlet is not a template but +merely {\em uses} template(s) for portion(s) of its work. + +The Inheritance approach is recommended for new sites because it's simpler, and +because it scales well for large sites with a +site->section->subsection->servlet hierarchy. The Containment approach is +better for existing servlets that you don't want to restructure. For instance, +you can use the Containment approach to embed a discussion-forum table at the +bottom of a web page. + +However, most people who use Cheetah extensively seem +to prefer the Inheritance approach because even the most analytical servlet +needs to produce {\em some} output, and it has to fit the site's look and feel +{\em anyway}, so you may as well use a template-servlet as the place to put the +output. Especially since it's so easy to add a template-servlet to a site once +the framework is established. So we recommend you at least evaluate the +effort that would be required to convert your site framework to template +superclasses as described below, vs the greater flexibility and manageability +it might give the site over the long term. You don't necessarily have to +convert all your existing servlets right away: just build common site templates +that are visually and behaviorally compatible with your specification, and use +them for new servlets. Existing servlets can be converted later, if at all. + +Edmund Liam is preparing a section on a hybrid approach, in which the +servlet is not a template, but still calls template(s) in an inheritance +chain to produce the output. The advantage of this approach is that you +aren't dealing with \code{Template} methods and Webware methods in the +same object. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{The Containment Approach} +\label{webware.containment} + +In the Containment approach, your servlet is not a template. Instead, it +it makes its own arrangements to create and use template object(s) for whatever +it needs. The servlet must explicitly call the template objects' +\code{.respond()} (or \code{.\_\_str\_\_()}) method each time it needs to fill +the template. This does not present the output to the user; it merely gives +the output to the servlet. The servlet then calls its +\code{\#self.response().write()} method to send the output to the user. + +The developer has several choices for managing her templates. She can store the +template definition in a string, file or database and call +\code{Cheetah.Template.Template} manually on it. Or she can put the +template definition in a *.tmpl file and use {\bf cheetah compile} (section +\ref{howWorks.cheetah-compile}) to convert it to a Python class in a *.py +module, and then import it into her servlet. + +Because template objects are not thread safe, you should not store one +in a module variable and allow multiple servlets to fill it simultaneously. +Instead, each servlet should instantiate its own template object. Template +{\em classes}, however, are thread safe, since they don't change once created. +So it's safe to store a template class in a module global variable. + +% @@MO: Example of containment. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{The Inheritance Approach} +\label{webware.inheritance} + +In the Inheritance approach, your template object doubles as as Webware +servlet, thus these are sometimes called {\bf template-servlets}. {\bf cheetah +compile} (section \ref{howWorks.cheetah-compile}) automatically creates modules +containing valid Webware servlets. A servlet is a subclass of Webware's +\code{WebKit.HTTPServlet} class, contained in a module with the same name as +the servlet. WebKit uses the request URL to find the module, and then +instantiates the servlet/template. The servlet must have a \code{.respond()} +method (or \code{.respondToGet()}, \code{.respondToPut()}, etc., but the +Cheetah default is \code{.respond()}). Servlets created by \code{cheetah +compile} meet all these requirements. + +(Cheetah has a Webware plugin that automatically converts a \code{.tmpl servlet +file} into a \code{.py servlet file} when the \code{.tmpl servlet file} is +requested by a browser. However, that plugin is currently unavailable because +it's being redesigned. For now, use \code{cheetah compile} instead.) + +What about logic code? Cheetah promises to keep content (the placeholder +values), graphic design (the template definition and is display logic), and +algorithmic logic (complex calculations and side effects) separate. How? +Where do you do form processing? + +The answer is that your template class can inherit from a pure Python class +containing the analytical logic. You can either use the \code{\#extends} +directive in Cheetah to indicate the superclass(es), or write a Python +\code{class} statement to do the same thing. See the template +\code{Cheetah.Templates.SkeletonPage.tmpl} and its pure Python class +\code{Cheetah.Templates.\_SkeletonPage.py} for an example of a template +inheriting logic code. (See sections \ref{inheritanceEtc.extends} and +\ref{inheritanceEtc.implements} for more information about \code{\#extends} and +\code{\#implements}. They have to be used a certain right way.) + +If \code{\#WebKit.HTTPServlet} is not available, Cheetah fakes it with a +dummy class to satisfy the dependency. This allows servlets to be tested on +the command line even on systems where Webware is not installed. This works +only with servlets that don't call back into WebKit for information about the +current web transaction, since there is no web transaction. Trying to access +form input, for instance, will raise an exception because it depends on a +live web request object, and in the dummy class the request object is +\code{None}. + +Because Webware servlets must be valid Python modules, and ``cheetah compile'' +can produce only valid module names, if you're converting an existing site that +has .html filenames with hyphens (-), extra dots (.), etc, you'll have to +rename them (and possibly use redirects). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Site frameworks} +\label{webware.siteFrameworks} + +Web sites are normally arranged hierarchically, with certain features common +to every page on the site, other features common to certain sections or +subsections, and others unique to each page. You can model this easily with +a hierarchy of classes, with specific servlets inheriting from their more +general superclasses. Again, you can do this two ways, using Cheetah's +{\bf Containment} approach or {\bf Inheritance} approach. + +In the Inheritance approach, parents provide \code{\#block}s and children +override them using \code{\#def}. Each child \code{\#extend}s its immediate +parent. Only the leaf servlets need to be under WebKit's document root +directory. The superclass servlets can live anywhere in the filesystem +that's in the Python path. (You may want to modify your WebKit startup +script to add that library directory to your \code{PYTHONPATH} before starting +WebKit.) + +% @@MO Examples: simple, IronSite, SkeletonPage. + +Section \ref{libraries.templates.skeletonPage} contains information on a stock +template that simplifies defining the basic HTML structure of your web +page templates. + +In the Containment approach, your hierarchy of servlets are not templates, but +each uses one or more templates as it wishes. Children provide callback +methods to to produce the various portions of the page that are their +responsibility, and parents call those methods. Webware's \code{WebKit.Page} +and \code{WebKit.SidebarPage} classes operate like this. + +% @@MO Show examples of WebKit.Page and WebKit.SidebarPage. + +Note that the two approaches are not compatible! \code{WebKit.Page} was not +designed to intermix with \code{Cheetah.Templates.SkeletonPage}. Choose either +one or the other, or expect to do some integration work. + +If you come up with a different strategy you think is worth noting in this +chapter, let us know. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Directory structure} +\label{webware.directoryStructure} + +Here's one way to organize your files for Webware+Cheetah. + +\begin{verbatim} +www/ # Web root directory. + site1.example.com/ # Site subdirectory. + apache/ # Web server document root (for non-servlets). + www/ # WebKit document root. + index.py # http://site1.example.com/ + index.tmpl # Source for above. + servlet2.py # http://site1.example.com/servlet2 + servlet2.tmpl # Source for above. + lib/ # Directory for helper classes. + Site.py # Site superclass ("#extends Site"). + Site.tmpl # Source for above. + Logic.py # Logic class inherited by some template. + webkit.config # Configuration file (for WebwareExperimental). + Webware/ # Standard Webware's MakeAppWorkDir directory. + AppServer # Startup program (for standard Webware). + Configs/ # Configuration directory (for standard Webware). + Application.config + # Configuration file (for standard Webware). + site2.example.org/ # Another virtual host on this computer.... +\end{verbatim} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Initializing your template-servlet with Python code} +\label{webware.calculations} + +If you need a place to initialize variables or do calculations for your +template-servlet, you can put it in an \code{.awake()} method because WebKit +automatically calls that early when processing the web transaction. If you +do override \code{.awake()}, be sure to call the superclass \code{.awake} +method. You probably want to do that first so that you have access to the +web transaction data \code{Servlet.awake} provides. You don't have to worry +about whether your parent class has its own \code{.awake} method, just call +it anyway, and somebody up the inheritance chain will respond, or at minimum +\code{Servlet.awake} will respond. Section +\ref{tips.callingSuperclassMethods} gives examples of how to call a +superclass method. + +As an alternative, you can put all your calculations in your own method and +call it near the top of your template. (\code{\#silent}, section +\ref{output.silent}). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Form processing} +\label{webware.form} + +There are many ways to display and process HTML forms with Cheetah. +But basically, all form processing involves two steps. +\begin{enumerate} +\item{} Display the form. +\item{} In the next web request, read the parameters the user submitted, +check for user errors, perform any side effects (e.g., reading/writing a +database or session data) and present the user an HTML response or another +form. +\end{enumerate} + +The second step may involve choosing between several templates to fill (or +several servlets to redirect to), or a big if-elif-elif-else construct to +display a different portion of the template depending on the situation. + +In the oldest web applications, step 1 and step 2 were handled by separate +objects. Step 1 was a static HTML file, and step 2 was a CGI script. +Frequently, a better strategy is to have a single servlet handle both steps. +That way, the servlet has better control over the entire situation, and if +the user submits unacceptable data, the servlet can redisplay the form with a +"try again" error message at the top and and all the previous input filled in. +The servlet can use the presence or absence of certain CGI parameters (e.g., +the submit button, or a hidden mode field) to determine which step to take. + +One neat way to build a servlet that can handle both the form displaying and +form processing is like this: + +\begin{enumerate} +\item Put your form HTML into an ordinary template-servlet. In each input + field, use a placeholder for the value of the \code{VALUE=} attribue. + Place another placeholder next to each field, for that field's error + message. +\item Above the form, put a \code{\$processFormData} method call. +\item Define that method in a Python class your template \code{\#extend}s. (Or + if it's a simple method, you can define it in a \code{\#def}.) The method + should: + \begin{enumerate} + \item Get the form input if any. + \item If the input variable corresponding to the submit field is empty, + there is no form input, so we're showing the form for the first time. + Initialize all VALUE= variables to their default value (usually ""), + and all error variables to "". Return "", which will be the value for + \code{\$processFormData}. + \item If the submit variable is not empty, fill the VALUE= variables with + the input data the user just submitted. + \item Now check the input for errors and put error messages in the error + placeholders. + \item If there were any user errors, return a general error message + string; this will be the value for \code{\$processFormData}. + \item If there were no errors, do whatever the form's job is (e.g., update + a database) and return a success message; this will be the value for + \code{\$processFormData}. + \end{enumerate} +\item The top of the page will show your success/failure message (or nothing +the first time around), with the form below. If there are errors, the user +will have a chance to correct them. After a successful submit, the form will +appear again, so the user can either review their entry, or change it and +submit it again. Depending on the application, this may make the servlet +update the same database record again, or it may generate a new record. +\end{enumerate} + +% @@MO: Example of a template that shows a form and then processes the input. + +\code{FunFormKit} is a third-party Webware package that makes it easier to +produce forms and handle their logic. It has been successfully been used with +Cheetah. You can download FunFormKit from +\url{http://colorstudy.net/software/funformkit/} and try it out for yourself. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Form input, cookies, session variables and web server variables} +\label{webware.input} + +General variable tips that also apply to servlets are in section +\ref{tips.placeholder}. + +To look up a CGI GET or POST parameter (with POST overriding): +\begin{verbatim} +$request.field('myField') +self.request().field('myField') +\end{verbatim} +These will fail if Webware is not available, because \code{\$request} +(aka \code{self.request()} will be \code{None} rather than a Webware +\code{WebKit.Request} object. If you plan to read a lot of CGI parameters, +you may want to put the \code{.fields} method into a local variable for +convenience: +\begin{verbatim} +#set $fields = $request.fields +$fields.myField +\end{verbatim} +But remember to do complicated calculations in Python, and assign the results +to simple variables in the searchList for display. These \code{\$request} +forms are useful only for occasions where you just need one or two simple +request items that going to Python for would be overkill. + +To get a cookie or session parameter, subsitute ``cookie'' or ``session'' for +``field'' above. To get a dictionary of all CGI parameters, substitute +``fields'' (ditto for ``cookies''). To verify a field exists, +substitute ``hasField'' (ditto for ``hasCookie''). + +Other useful request goodies: +\begin{verbatim} +## Defined in WebKit.Request +$request.field('myField', 'default value') +$request.time ## Time this request began in Unix ticks. +$request.timeStamp ## Time in human-readable format ('asctime' format). +## Defined in WebKit.HTTPRequest +$request.hasField.myField ## Is a CGI parameter defined? +$request.fields ## Dictionary of all CGI parameters. +$request.cookie.myCookie ## A cookie parameter (also .hasCookie, .cookies). +$request.value.myValue ## A field or cookie variable (field overrides) + ## (also .hasValue). +$request.session.mySessionVar # A session variable. +$request.extraURLPath ## URL path components to right of servlet, if any. +$request.serverDictionary ## Dict of environmental vars from web server. +$request.remoteUser ## Authenticated username. HTTPRequest.py source + ## suggests this is broken and always returns None. +$request.remoteAddress ## User's IP address (string). +$request.remoteName ## User's domain name, or IP address if none. +$request.urlPath ## URI of this servlet. +$request.urlPathDir ## URI of the directory containing this servlet. +$request.serverSidePath ## Absolute path of this servlet on local filesystem. +$request.serverURL ## URL of this servlet, without "http://" prefix, + ## extra path info or query string. +$request.serverURLDir ## URL of this servlet's directory, without "http://". +$log("message") ## Put a message in the Webware server log. (If you + ## define your own 'log' variable, it will override + ## this; use $self.log("message") in that case. +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{.webInput()} +\label{webware.webInput} + +From the method docstring: + +\begin{verbatim} + def webInput(self, names, namesMulti=(), default='', src='f', + defaultInt=0, defaultFloat=0.00, badInt=0, badFloat=0.00, debug=False): + +This method places the specified GET/POST fields, cookies or session variables +into a dictionary, which is both returned and put at the beginning of the +searchList. It handles: + * single vs multiple values + * conversion to integer or float for specified names + * default values/exceptions for missing or bad values + * printing a snapshot of all values retrieved for debugging +All the 'default*' and 'bad*' arguments have "use or raise" behavior, meaning +that if they're a subclass of Exception, they're raised. If they're anything +else, that value is substituted for the missing/bad value. + +The simplest usage is: + + #silent $webInput(['choice']) + $choice + + dic = self.webInput(['choice']) + write(dic['choice']) + +Both these examples retrieves the GET/POST field 'choice' and print it. If you +leave off the "#silent", all the values would be printed too. But a better way +to preview the values is + + #silent $webInput(['name'], $debug=1) + +because this pretty-prints all the values inside HTML <PRE> tags. + +Since we didn't specify any coversions, the value is a string. It's a "single" +value because we specified it in 'names' rather than 'namesMulti'. Single +values work like this: + * If one value is found, take it. + * If several values are found, choose one arbitrarily and ignore the rest. + * If no values are found, use or raise the appropriate 'default*' value. + +Multi values work like this: + * If one value is found, put it in a list. + * If several values are found, leave them in a list. + * If no values are found, use the empty list ([]). The 'default*' + arguments are *not* consulted in this case. + +Example: assume 'days' came from a set of checkboxes or a multiple combo box +on a form, and the user chose "Monday", "Tuesday" and "Thursday". + + #silent $webInput([], ['days']) + The days you chose are: #slurp + #for $day in $days + $day #slurp + #end for + + dic = self.webInput([], ['days']) + write("The days you chose are: ") + for day in dic['days']: + write(day + " ") + +Both these examples print: "The days you chose are: Monday Tuesday Thursday". + +By default, missing strings are replaced by "" and missing/bad numbers by zero. +(A "bad number" means the converter raised an exception for it, usually because +of non-numeric characters in the value.) This mimics Perl/PHP behavior, and +simplifies coding for many applications where missing/bad values *should* be +blank/zero. In those relatively few cases where you must distinguish between +""/zero on the one hand and missing/bad on the other, change the appropriate +'default*' and 'bad*' arguments to something like: + * None + * another constant value + * $NonNumericInputError/self.NonNumericInputError + * $ValueError/ValueError +(NonNumericInputError is defined in this class and is useful for +distinguishing between bad input vs a TypeError/ValueError +thrown for some other reason.) + +Here's an example using multiple values to schedule newspaper deliveries. +'checkboxes' comes from a form with checkboxes for all the days of the week. +The days the user previously chose are preselected. The user checks/unchecks +boxes as desired and presses Submit. The value of 'checkboxes' is a list of +checkboxes that were checked when Submit was pressed. Our task now is to +turn on the days the user checked, turn off the days he unchecked, and leave +on or off the days he didn't change. + + dic = self.webInput([], ['dayCheckboxes']) + wantedDays = dic['dayCheckboxes'] # The days the user checked. + for day, on in self.getAllValues(): + if not on and wantedDays.has_key(day): + self.TurnOn(day) + # ... Set a flag or insert a database record ... + elif on and not wantedDays.has_key(day): + self.TurnOff(day) + # ... Unset a flag or delete a database record ... + +'source' allows you to look up the variables from a number of different +sources: + 'f' fields (CGI GET/POST parameters) + 'c' cookies + 's' session variables + 'v' "values", meaning fields or cookies + +In many forms, you're dealing only with strings, which is why the +'default' argument is third and the numeric arguments are banished to +the end. But sometimes you want automatic number conversion, so that +you can do numeric comparisons in your templates without having to +write a bunch of conversion/exception handling code. Example: + + #silent $webInput(['name', 'height:int']) + $name is $height cm tall. + #if $height >= 300 + Wow, you're tall! + #else + Pshaw, you're short. + #end if + + dic = self.webInput(['name', 'height:int']) + name = dic[name] + height = dic[height] + write("%s is %s cm tall." % (name, height)) + if height > 300: + write("Wow, you're tall!") + else: + write("Pshaw, you're short.") + +To convert a value to a number, suffix ":int" or ":float" to the name. The +method will search first for a "height:int" variable and then for a "height" +variable. (It will be called "height" in the final dictionary.) If a numeric +conversion fails, use or raise 'badInt' or 'badFloat'. Missing values work +the same way as for strings, except the default is 'defaultInt' or +'defaultFloat' instead of 'default'. + +If a name represents an uploaded file, the entire file will be read into +memory. For more sophisticated file-upload handling, leave that name out of +the list and do your own handling, or wait for Cheetah.Utils.UploadFileMixin. + +This mixin class works only in a subclass that also inherits from +Webware's Servlet or HTTPServlet. Otherwise you'll get an AttributeError +on 'self.request'. + +EXCEPTIONS: ValueError if 'source' is not one of the stated characters. +TypeError if a conversion suffix is not ":int" or ":float". +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{More examples} +\label{webware.examples} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Example A -- a standalone servlet} +%\label{} + +% @@MO: + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Example B -- a servlet under a site framework} +%\label{} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection*{Example C -- several servlets with a common template} +%\label{} + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Other Tips} +\label{webware.otherTips} + +If your servlet accesses external files (e.g., via an \code{\#include} +directive), remember that the current directory is not necessarily directory +the servlet is in. It's probably some other directory WebKit chose. To find a +file relative to the servlet's directory, prefix the path with whatever +\code{self.serverSidePath()} returns (from \code{Servlet.serverSidePath()}. + +If you don't understand how \code{\#extends} and \code{\#implements} work, and +about a template's main method, read the chapter on inheritance (sections +\ref{inheritanceEtc.extends} and \ref{inheritanceEtc.implements}). This may +help you avoid buggy servlets. + +% Local Variables: +% TeX-master: "users_guide" +% End: +%# vim: sw=4 ts=4 expandtab + + + +``Template`` subclasses Webware's ``Servlet`` class when available, +so the generated class can be used as a Webware servlet. This is practical +only with precompiled templates. + diff --git a/docs/users_guide_2_src/15_otherHtml.txt b/docs/users_guide_2_src/15_otherHtml.txt new file mode 100755 index 0000000..89fd58a --- /dev/null +++ b/docs/users_guide_2_src/15_otherHtml.txt @@ -0,0 +1,95 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{non-Webware HTML output} +\label{otherHTML} + +Cheetah can be used with all types of HTML output, not just with Webware. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Static HTML Pages} +\label{otherHTML.static} + +Some sites like Linux Gazette (\url{http://www.linuxgazette.com/}) require +completely static pages because they are mirrored on servers running completely +different software from the main site. Even dynamic sites may have one or +two pages that are static for whatever reason, and the site administrator may +wish to generate those pages from Cheetah templates. + +There's nothing special here. Just create your templates as usual. Then +compile and fill them whenever the template definition changes, and fill them +again whenever the placeholder values change. You may need an extra step to +copy the .html files to their final location. A Makefile (chapter +\ref{tips.Makefile}) can help encapsulate these steps. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{CGI scripts} +\label{otherHTML} + +Unlike Webware servlets, which don't have to worry about the HTTP headers, +CGI scripts must emit their own headers. To make a template CGI aware, add +this at the top: +\begin{verbatim} +#extends Cheetah.Tools.CGITemplate +#implements respond +$cgiHeaders#slurp +\end{verbatim} + +Or if your template is inheriting from a Python class: +\begin{verbatim} +#extends MyPythonClass +#implements respond +$cgiHeaders#slurp +\end{verbatim} + +A sample Python class: +\begin{verbatim} +from Cheetah.Tools import CGITemplate +class MyPythonClass(CGITemplate): + def cgiHeadersHook(self): + return "Content-Type: text/html; charset=koi8-r\n\n" +\end{verbatim} + + +Compile the template as usual, put the .py template module in your +cgi-bin directory and give it execute permission. \code{.cgiHeaders()} is +a ``smart'' method that outputs the headers if the module is called as a +CGI script, or outputs nothing if not. Being ``called as a CGI script'' +means the environmental variable \code{REQUEST\_METHOD} exists and +\code{self.isControlledByWebKit} is false. If you don't agree with that +definition, override \code{.isCgi()} and provide your own. + +The default header is a simple \verb+Content-type: text/html\n\n+, which works +with all CGI scripts. If you want to customize the headers (e.g., to +specify the character set), override \code{.cgiHeadersHook()} and return +a string containing all the headers. Don't forget to include the extra +newline at the end of the string: the HTTP protocol requires this empty +line to mark the end of the headers. + +To read GET/POST variables from form input, use the \code{.webInput()} method +(section \ref{webware.webInput}), or extract them yourself using Python's +\code{cgi} module or your own function. Although \code{.webInput()} was +originally written for Webware servlets, it now handles CGI scripts too. There +are a couple behavioral differences between CGI scripts and Webware servlets +regarding input variables: + +\begin{enumerate} +\item CGI scripts, using Python's \code{cgi} module, believe + \code{REQUEST\_METHOD} and recognize {\em either} GET variables {\em or} + POST variables, not both. Webware servlets, doing additional processing, + ignore \code{REQUEST\_METHOD} and recognize both, like PHP does. +\item Webware servlets can ask for cookies or session variables instead of + GET/POST variables, by passing the argument \code{src='c'} or + \code{src='s'}. CGI scripts get a \code{RuntimeError} if they try to do + this. +\end{enumerate} + +If you keep your .tmpl files in the same directory as your CGI scripts, make +sure they don't have execute permission. Apache at least refuses to serve +files in a \code{ScriptAlias} directory that don't have execute permission. + + +% Local Variables: +% TeX-master: "users_guide" +% End: +%# vim: sw=4 ts=4 expandtab diff --git a/docs/users_guide_2_src/16_nonHtml.txt b/docs/users_guide_2_src/16_nonHtml.txt new file mode 100755 index 0000000..b618ab0 --- /dev/null +++ b/docs/users_guide_2_src/16_nonHtml.txt @@ -0,0 +1,17 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Non-HTML Output} +\label{nonHTML} + +Cheetah can also output any other text format besides HTML. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Python source code} +\label{nonHTML.python} + +To be written. We're in the middle of working on an autoindenter to +make it easier to encode Python indentation in a Cheetah template. + +% Local Variables: +% TeX-master: "users_guide" +% End: +%# vim: sw=4 ts=4 expandtab diff --git a/docs/users_guide_2_src/17_libraries.txt b/docs/users_guide_2_src/17_libraries.txt new file mode 100755 index 0000000..dc9231a --- /dev/null +++ b/docs/users_guide_2_src/17_libraries.txt @@ -0,0 +1,306 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Batteries included: templates and other libraries} +\label{libraries} + +Cheetah comes ``batteries included'' with libraries of templates, functions, +classes and other objects you can use in your own programs. The different +types are listed alphabetically below, followed by a longer description of +the SkeletonPage framework. Some of the objects are classes for specific +purposes (e.g., filters or error catchers), while others are standalone and +can be used without Cheetah. + +If you develop any objects which are generally useful for Cheetah sites, +please consider posting them on the wiki with an announcement on the mailing +list so we can incorporate them into the standard library. That way, all +Cheetah users will benefit, and it will encourage others to contribute their +objects, which might include something you want. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{ErrorCatchers} +\label{libraries.ErrorCatchers} + +Module \code{Cheetah.ErrorCatchers} contains error-handling classes suitable for +the \code{\#errorCatcher} directive. These are debugging tools that are not +intended for use in production systems. See section +\ref{errorHandling.errorCatcher} for a description of the error catchers bundled +with Cheetah. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{FileUtils} +\label{libraries.FileUtils} + +Module \code{Cheetah.FileUtils} contains generic functions and classes for +doing bulk search-and-replace on several files, and for finding all the files +in a directory hierarchy whose names match a glob pattern. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Filters} +\label{libraries.Filters} + +Module \code{Filters} contains filters suitable for the \code{\#Filter} +directive. See section \ref{output.filter} for a description of the +filters bundled with Cheetah. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{SettingsManager} +\label{libraries.SettingsManager} + +The \code{SettingsManager} class in the \code{Cheetah.SettingsManager} module is +a baseclass that provides facilities for managing application settings. It +facilitates the use of user-supplied configuration files to fine tune an +application. A setting is a key/value pair that an application or component +(e.g., a filter, or your own servlets) looks up and treats as a configuration +value to modify its (the component's) behaviour. + +SettingsManager is designed to: +\begin{itemize} +\item work well with nested settings dictionaries of any depth +\item read/write \code{.ini style config files} (or strings) +\item read settings from Python source files (or strings) so that + complex Python objects can be stored in the application's settings + dictionary. For example, you might want to store references to various + classes that are used by the application, and plugins to the application + might want to substitute one class for another. +\item allow sections in \code{.ini config files} to be extended by settings in + Python src files. If a section contains a setting like + ``\code{importSettings=mySettings.py}'', \code{SettingsManager} will merge + all the settings defined in ``\code{mySettings.py}'' with the settings for + that section that are defined in the \code{.ini config file}. +\item maintain the case of setting names, unlike the ConfigParser module +\end{itemize} + +Cheetah uses \code{SettingsManager} to manage its configuration settings. +\code{SettingsManager} might also be useful in your own applications. See the +source code and docstrings in the file \code{src/SettingsManager.py} for more +information. + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Templates} +\label{libraries.templates} + +Package \code{Cheetah.Templates} contains stock templates that you can +either use as is, or extend by using the \code{\#def} directive to redefine +specific {\bf blocks}. Currently, the only template in here is SkeletonPage, +which is described in detail below in section +\ref{libraries.templates.skeletonPage}. (Contributed by Tavis Rudd.) + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Tools} +\label{libraries.Tools} + +Package \code{Cheetah.Tools} contains functions and classes contributed by third +parties. Some are Cheetah-specific but others are generic and can be used +standalone. None of them are imported by any other Cheetah component; you can +delete the Tools/ directory and Cheetah will function fine. + +Some of the items in Tools/ are experimental and have been placed there just to +see how useful they will be, and whether they attract enough users to make +refining them worthwhile (the tools, not the users :). + +Nothing in Tools/ is guaranteed to be: (A) tested, (B) reliable, (C) immune +from being deleted in a future Cheetah version, or (D) immune from +backwards-incompatable changes. If you depend on something in Tools/ on a +production system, consider making a copy of it outside the Cheetah/ directory +so that this version won't be lost when you upgrade Cheetah. Also, learn +enough about Python and about the Tool so that you can maintain it and bugfix +it if necessary. + +If anything in Tools/ is found to be necessary to Cheetah's operation (i.e., if +another Cheetah component starts importing it), it will be moved to the +\code{Cheetah.Utils} package. + +Current Tools include: +\begin{description} +\item{Cheetah.Tools.MondoReport} an ambitious class useful when + iterating over records of data (\code{\#for} loops), displaying one + pageful of records at a time (with previous/next links), and printing + summary statistics about the records or the current page. See + \code{MondoReportDoc.txt} in the same directory as the module. Some + features are not implemented yet. \code{MondoReportTest.py} is a test + suite (and it shows there are currently some errors in MondoReport, hmm). + Contributed by Mike Orr. + +\item{Cheetah.Tools.RecursiveNull} Nothing, but in a friendly way. Good + for filling in for objects you want to hide. If \code{\$form.f1} is a + RecursiveNull object, then \code{\$form.f1.anything["you"].might("use")} + will resolve to the empty string. You can also put a \code{RecursiveNull} + instance at the end of the searchList to convert missing values to '' + rather than raising a \code{NotFound} error or having a (less efficient) + errorCatcher handle it. Of course, maybe you prefer to get a + \code{NotFound} error... Contributed by Ian Bicking. + +\item{Cheetah.Tools.SiteHierarchy} Provides navigational links to this + page's parents and children. The constructor takes a recursive list of + (url,description) pairs representing a tree of hyperlinks to every page in + the site (or section, or application...), and also a string containing the + current URL. Two methods 'menuList' and 'crumbs' return output-ready HTML + showing an indented menu (hierarchy tree) or crumbs list (Yahoo-style bar: + home > grandparent > parent > currentURL). Contributed by Ian Bicking. + +\item +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Utils} +\label{libraries.Utils} + +Package \code{Cheetah.Utils} contains non-Cheetah-specific functions and +classes that are imported by other Cheetah components. Many of these utils can +be used standalone in other applications too. + +Current Utils include: +\begin{description} +\item{Cheetah.Utils.CGIImportMixin} This is inherited by \code{Template} + objects, and provides the method, \code{.cgiImport} method + (section \ref{webware.cgiImport}). + +\item{Cheetah.Utils.Misc} A catch-all module for small functions. + \begin{description} + \item{\code{UseOrRaise(thing, errmsg='')}} Raise 'thing' if it's a + subclass of Exception, otherwise return it. Useful when one + argument does double duty as a default value or an exception to + throw. Contribyted by Mike Orr. + + \item{\code{checkKeywords(dic, legalKeywords, what='argument'}} + Verifies the dictionary does not contain any keys not listed in + 'legalKeywords'. If it does, raise TypeError. Useful for + checking the keyword arguments to a function. Contributed by + Mike Orr. + \end{description} + +\item{Cheetah.Utils.UploadFileMixin} Not implemented yet, but will contain + the \code{.uploadFile} method (or three methods) to ``safely'' copy a + form-uploaded file to a local file, to a searchList variable, or return + it. When finished, this will be inherited by \code{Template}, allowing + all templates to do this. If you want this feature, read the docstring + in the source and let us know on the mailing list what you'd like this + method to do. Contributed by Mike Orr. + +\item{Cheetah.Utils.VerifyType} Functions to verify the type of a + user-supplied function argument. Contributed by Mike Orr. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Cheetah.Templates.SkeletonPage} +\label{libraries.templates.skeletonPage} + +A stock template class that may be useful for web developers is defined in +the \code{Cheetah.Templates.SkeletonPage} module. The \code{SkeletonPage} +template class is generated from the following Cheetah source code: + +\begin{verbatim} +##doc-module: A Skeleton HTML page template, that provides basic structure and utility methods. +################################################################################ +#extends Cheetah.Templates._SkeletonPage +#implements respond +################################################################################ +#cache id='header' +$docType +$htmlTag +<!-- This document was autogenerated by Cheetah(http://CheetahTemplate.org). +Do not edit it directly! + +Copyright $currentYr - $siteCopyrightName - All Rights Reserved. +Feel free to copy any javascript or html you like on this site, +provided you remove all links and/or references to $siteDomainName +However, please do not copy any content or images without permission. + +$siteCredits + +--> + + +#block writeHeadTag +<head> +<title>$title</title> +$metaTags +$stylesheetTags +$javascriptTags +</head> +#end block writeHeadTag + +#end cache header +################# + +$bodyTag + +#block writeBody +This skeleton page has no flesh. Its body needs to be implemented. +#end block writeBody + +</body> +</html> +\end{verbatim} + +You can redefine any of the blocks defined in this template by writing a new +template that \code{\#extends} SkeletonPage. (As you remember, using +\code{\#extends} makes your template implement the \code{.writeBody()} +method instead of \code{.respond()} -- which happens to be the same method +SkeletonPage expects the page content to be (note the writeBody block in +SkeletonPage).) + +\begin{verbatim} +#def bodyContents +Here's my new body. I've got some flesh on my bones now. +#end def bodyContents +\end{verbatim} + +%% @@MO: Is this still accurate? Does the child template really need to put a +%% #def around its whole content? Or by implementing .writeBody() does it +%% automatically insert itself as the writeBody portion of +%% SkeletonPage? @@TR 2005-01-06: it happens automatically at the moment. + +All of the \$placeholders used in the \code{SkeletonPage} template definition +are attributes or methods of the \code{SkeletonPage} class. You can reimplement +them as you wish in your subclass. Please read the source code of the file +\code{src/Templates/\_SkeletonPage.py} before doing so. + +You'll need to understand how to use the following methods of the +\code{SkeletonPage} class: \code{\$metaTags()}, \code{\$stylesheetTags()}, +\code{\$javascriptTags()}, and \code{\$bodyTag()}. They take the data you +define in various attributes and renders them into HTML tags. + +\begin{itemize} +\item {\bf metaTags()} -- Returns a formatted vesion of the self.\_metaTags + dictionary, using the formatMetaTags function from + \code{\_SkeletonPage.py}. +\item {\bf stylesheetTags()} -- Returns a formatted version of the + \code{self.\_stylesheetLibs} and \code{self.\_stylesheets} dictionaries. + The keys in \code{self.\_stylesheets} must be listed in the order that + they should appear in the list \code{self.\_stylesheetsOrder}, to ensure + that the style rules are defined in the correct order. +\item {\bf javascriptTags()} -- Returns a formatted version of the + \code{self.\_javascriptTags} and \code{self.\_javascriptLibs} dictionaries. + Each value in \code{self.\_javascriptTags} should be a either a code string + to include, or a list containing the JavaScript version number and the code + string. The keys can be anything. The same applies for + \code{self.\_javascriptLibs}, but the string should be the SRC filename + rather than a code string. +\item {\bf bodyTag()} -- Returns an HTML body tag from the entries in the dict + \code{self.\_bodyTagAttribs}. +\end{itemize} + +The class also provides some convenience methods that can be used as +\$placeholders in your template definitions: + +\begin{itemize} +\item {\bf imgTag(self, src, alt='', width=None, height=None, border=0)} -- + Dynamically generate an image tag. Cheetah will try to convert the + ``\code{src}'' argument to a WebKit serverSidePath relative to the + servlet's location. If width and height aren't specified they are + calculated using PIL or ImageMagick if either of these tools are available. + If all your images are stored in a certain directory you can reimplement + this method to append that directory's path to the ``\code{src}'' argument. + Doing so would also insulate your template definitions from changes in your + directory structure. +\end{itemize} + + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_2_src/18_editors.txt b/docs/users_guide_2_src/18_editors.txt new file mode 100755 index 0000000..84c8f03 --- /dev/null +++ b/docs/users_guide_2_src/18_editors.txt @@ -0,0 +1,39 @@ +\section{Visual Editors} +\label{visualEditors} + +This chapter is about maintaining Cheetah templates with visual editors, +and the tradeoffs between making it friendly to both text editors and visual +editors. + +Cheetah's main developers do not use visual editors. Tavis uses \code{emacs}; +Mike uses \code{vim}. So our first priority is to make templates easy to +maintain in text editors. In particular, we don't want to add features +like Zope Page Template's +placeholder-value-with-mock-text-for-visual-editors-all-in-an-XML-tag. +The syntax is so verbose it makes for a whole lotta typing just to insert a +simple placeholder, for the benefit of editors we never use. However, as users +identify features which would help their visual editing without making it +harder to maintain templates in a text editor, we're all for it. + +As it said in the introduction, Cheetah purposely does not use HTML/XML +tags for \$placeholders or \#directives. That way, when you preview the +template in an editor that interprets HTML tags, you'll still see the +placeholder and directive source definitions, which provides some ``mock text'' +even if it's not the size the final values will be, and allows you to use +your imagination to translate how the directive output will look visually in +the final. + +If your editor has syntax highlighting, turn it on. That makes a big +difference in terms of making the template easier to edit. Since no +``Cheetah mode'' has been invented yet, set your highlighting to Perl +mode, and at least the directives/placeholders will show up in different +colors, although the editor won't reliably guess where the +directive/placeholder ends and normal text begins. + +% Local Variables: +% TeX-master: "users_guide" +% End: + + + + diff --git a/docs/users_guide_2_src/A_links.txt b/docs/users_guide_2_src/A_links.txt new file mode 100755 index 0000000..1ec2f6c --- /dev/null +++ b/docs/users_guide_2_src/A_links.txt @@ -0,0 +1,112 @@ +\section{Useful Web Links} +\label{links} + +See the wiki for more links. (The wiki is also updated more often than this +chapter is.) + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah Links} +\label{links.cheetah} + +\begin{description} +\item[Home Page] -- \url{http:www.CheetahTemplate.org/} + +\item[On-line Documentation] -- \url{http:www.CheetahTemplate.org/learn.html} + +\item[SourceForge Project Page] -- \url{http:sf.net/projects/cheetahtemplate/} + +\item[Mailing List Subscription Page] -- + \url{http://lists.sourceforge.net/lists/listinfo/cheetahtemplate-discuss} + +\item[Mailing List Archive @ Geocrawler] -- + \url{http://www.geocrawler.com/lists/3/SourceForge/12986/0/} + +\item[Mailing List Archive @ Yahoo] -- + \url{http://groups.yahoo.com/group/cheetah-archive/} + +\item[CVS Repository] -- \url{http://sourceforge.net/cvs/?group\_id=28961} + +\item[CVS-commits archive] -- + \url{http://www.geocrawler.com/lists/3/SourceForge/13091/0/} + +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Third-party Cheetah Stuff} +\label{links.thirdParty} + +\begin{itemize} +\item Steve Howell has written a photo viewer using Python. + \url{http://mountainwebtools.com/PicViewer/install.htm} +\end{itemize} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Webware Links} +\label{links.webware} + +\begin{description} +\item[Home Page] -- \url{http://webware.sf.net/} + +\item[On-line Documentation] -- \url{http://webware.sf.net/Webware/Docs/} + +\item[SourceForge Project Page] -- \url{http://sf.net/projects/webware/} + +\item[Mailing List Subscription Page] -- + \url{http://lists.sourceforge.net/lists/listinfo/webware-discuss} + +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Python Links} +\label{links.python} + +\begin{description} +\item[Home Page] -- \url{http://www.python.org/} +\item[On-line Documentation] -- \url{http://www.python.org/doc/} +\item[SourceForge Project Page] -- \url{http://sf.net/projects/python/} +\item[The Vaults of Parnassus: Python Resources] -- + \url{http://www.vex.net/parnassus/} +\item[Python Cookbook] -- \url{http://aspn.activestate.com/ASPN/Cookbook/Python} +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Other Useful Links} +\label{links.other} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Python Database Modules and Open Source Databases} +\label{links.database} + +\begin{description} +\item[Python Database Topic Guide] -- \url{http://python.org/topics/database/} +\item[PostgreSQL Database] -- \url{http://www.postgresql.org/index.html} +\item[MySQL Database] -- \url{http://www.mysql.com/} +\item[A comparison of PostgreSQL and MySQL] -- + \url{http://phpbuilder.com/columns/tim20001112.php3} +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Other Template Systems} +\label{links.other.templateSystems} + +\begin{description} +\item[Chuck's ``Templates'' Summary Page] -- \url{http://webware.sf.net/Papers/Templates/} +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Other Internet development frameworks} +\label{links.internet} + +\begin{description} +\item[ZOPE (Z Object Publishing Environment)] -- \url{http://zope.org/} +\item[Server Side Java] -- \url{http://jakarta.apache.org/} +\item[PHP] -- \url{http://php.net/} +\item[IBM Websphere] -- \url{http://www.ibm.com/websphere/} +\item[Coldfusion and Spectra] -- \url{http://www.macromedia.com/} +\end{description} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_2_src/B_examples.txt b/docs/users_guide_2_src/B_examples.txt new file mode 100755 index 0000000..6c394fb --- /dev/null +++ b/docs/users_guide_2_src/B_examples.txt @@ -0,0 +1,24 @@ +\section{Examples} +\label{examples} + +The Cheetah distribution comes with an 'examples' directory. Browse the +files in this directory and its subdirectories for examples of how +Cheetah can be used. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Syntax examples} +The \code{Cheetah.Tests} module contains a large number of test cases that can +double as examples of how the Cheetah Language works. To view these cases go +to the base directory of your Cheetah distribution and open the file +\code{Cheetah/Tests/SyntaxAndOutput.py} in a text editor. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Webware Examples} +For examples of Cheetah in use with Webware visit the Cheetah and Webware wikis +or use google. We used to have more examples in the cheetah source tarball, but +they were out of date and confused people. + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_2_src/C_comparisions.txt b/docs/users_guide_2_src/C_comparisions.txt new file mode 100755 index 0000000..56a0fb3 --- /dev/null +++ b/docs/users_guide_2_src/C_comparisions.txt @@ -0,0 +1,451 @@ +\section{Cheetah vs. Other Template Engines} +\label{comparisons} + +This appendix compares Cheetah with various other template/emdedded scripting +languages and Internet development frameworks. As Cheetah is similar to +Velocity at a superficial level, you may also wish to read comparisons between +Velocity and other languages at +\url{http://jakarta.apache.org/velocity/ymtd/ymtd.html}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Which features are unique to Cheetah} +\label{comparisons.unique} + +\begin{itemize} +\item The {\bf block framework} (section \ref{inheritanceEtc.block}) +\item Cheetah's powerful yet simple {\bf caching framework} (section + \ref{output.caching}) +\item Cheetah's {\bf Unified Dotted Notation} and {\bf autocalling} + (sections \ref{language.namemapper.dict} and + \ref{language.namemapper.autocalling}) +\item Cheetah's searchList (section \ref{language.searchList}) + information. +\item Cheetah's \code{\#raw} directive (section \ref{output.raw}) +\item Cheetah's \code{\#slurp} directive (section \ref{output.slurp}) +\item Cheetah's tight integration with Webware for Python (section + \ref{webware}) +\item Cheetah's {\bf SkeletonPage framework} (section + \ref{libraries.templates.skeletonPage}) +\item Cheetah's ability to mix PSP-style code with Cheetah + Language syntax (section \ref{tips.PSP}) + Because of Cheetah's design and Python's flexibility it is + relatively easy to extend Cheetah's syntax with syntax elements from almost + any other template or embedded scripting language. +\end{itemize} + +%% @@MO: What about the new features we've been adding? + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. Velocity} +\label{comparisons.velocity} + +For a basic introduction to Velocity, visit +\url{http://jakarta.apache.org/velocity}. + +Velocity is a Java template engine. It's older than Cheetah, has a larger user +base, and has better examples and docs at the moment. Cheetah, however, has a +number of advantages over Velocity: +\begin{itemize} +\item Cheetah is written in Python. Thus, it's easier to use and extend. +\item Cheetah's syntax is closer to Python's syntax than Velocity's is to +Java's. +\item Cheetah has a powerful caching mechanism. Velocity has no equivalent. +\item It's far easier to add data/objects into the namespace where \$placeholder + values are extracted from in Cheetah. Velocity calls this namespace a 'context'. + Contexts are dictionaries/hashtables. You can put anything you want into a + context, BUT you have to use the .put() method to populate the context; + e.g., + +\begin{verbatim} +VelocityContext context1 = new VelocityContext(); +context1.put("name","Velocity"); +context1.put("project", "Jakarta"); +context1.put("duplicate", "I am in context1"); +\end{verbatim} + + Cheetah takes a different approach. Rather than require you to manually + populate the 'namespace' like Velocity, Cheetah will accept any existing + Python object or dictionary AS the 'namespace'. Furthermore, Cheetah + allows you to specify a list namespaces that will be searched in sequence + to find a varname-to-value mapping. This searchList can be extended at + run-time. + + If you add a `foo' object to the searchList and the `foo' has an attribute + called 'bar', you can simply type \code{\$bar} in the template. If the + second item in the searchList is dictionary 'foofoo' containing + \code{\{'spam':1234, 'parrot':666\}}, Cheetah will first look in the `foo' + object for a `spam' attribute. Not finding it, Cheetah will then go to + `foofoo' (the second element in the searchList) and look among its + dictionary keys for `spam'. Finding it, Cheetah will select + \code{foofoo['spam']} as \code{\$spam}'s value. + +\item In Cheetah, the tokens that are used to signal the start of + \$placeholders and \#directives are configurable. You can set them to any + character sequences, not just \$ and \#. +\end{itemize} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. WebMacro} +\label{comparisons.webmacro} + +For a basic introduction to WebMacro, visit +\url{http://webmacro.org}. + +The points discussed in section \ref{comparisons.velocity} also apply to the +comparison between Cheetah and WebMacro. For further differences please refer +to \url{http://jakarta.apache.org/velocity/differences.html}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. Zope's DTML} +\label{comparisons.dtml} + +For a basic introduction to DTML, visit +\url{http://www.zope.org/Members/michel/ZB/DTML.dtml}. + +\begin{itemize} +\item Cheetah is faster than DTML. +\item Cheetah does not use HTML-style tags; DTML does. Thus, Cheetah tags are + visible in rendered HTML output if something goes wrong. +\item DTML can only be used with ZOPE for web development; Cheetah can be + used as a standalone tool for any purpose. +\item Cheetah's documentation is more complete than DTML's. +\item Cheetah's learning curve is shorter than DTML's. +\item DTML has no equivalent of Cheetah's blocks, caching framework, + unified dotted notation, and \code{\#raw} directive. +\end{itemize} + +Here are some examples of syntax differences between DTML and Cheetah: +\begin{verbatim} +<ul> +<dtml-in frogQuery> + <li><dtml-var animal_name></li> +</dtml-in> +</ul> +\end{verbatim} + +\begin{verbatim} +<ul> +#for $animal_name in $frogQuery + <li>$animal_name</li> +#end for +</ul> +\end{verbatim} + +\begin{verbatim} +<dtml-if expr="monkeys > monkey_limit"> + <p>There are too many monkeys!</p> +<dtml-elif expr="monkeys < minimum_monkeys"> + <p>There aren't enough monkeys!</p> +<dtml-else> + <p>There are just enough monkeys.</p> +</dtml-if> +\end{verbatim} + +\begin{verbatim} +#if $monkeys > $monkey_limit + <p>There are too many monkeys!</p> +#else if $monkeys < $minimum_monkeys + <p>There aren't enough monkeys!</p> +#else + <p>There are just enough monkeys.</p> +#end if +\end{verbatim} + +\begin{verbatim} +<table> +<dtml-in expr="objectValues('File')"> + <dtml-if sequence-even> + <tr bgcolor="grey"> + <dtml-else> + <tr> + </dtml-if> + <td> + <a href="&dtml-absolute_url;"><dtml-var title_or_id></a> + </td></tr> +</dtml-in> +</table> +\end{verbatim} + +\begin{verbatim} +<table> +#set $evenRow = 0 +#for $file in $files('File') + #if $evenRow + <tr bgcolor="grey"> + #set $evenRow = 0 + #else + <tr> + #set $evenRow = 1 + #end if + <td> + <a href="$file.absolute_url">$file.title_or_id</a> + </td></tr> +#end for +</table> +\end{verbatim} + +The last example changed the name of \code{\$objectValues} to +\code{\$files} because that's what a Cheetah developer would write. +The developer would be responsible for ensuring \code{\$files} returned a +list (or tuple) of objects (or dictionaries) containing the attributes (or +methods or dictionary keys) `absolute\_url' and `title\_or\_id'. All these +names (`objectValues', `absolute\_url' and `title\_or\_id') are standard parts +of Zope, but in Cheetah the developer is in charge of writing them and giving +them a reasonable behaviour. + +Some of DTML's features are being ported to Cheetah, such as +\code{Cheetah.Tools.MondoReport}, which is based on the +\code{<dtml-in>} tag. We are also planning an output filter as flexible as +the \code{<dtml-var>} formatting options. However, neither of these are +complete yet. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. Zope Page Templates} +\label{comparisons.zpt} + +For a basic introduction to Zope Page Templates, please visit +\url{http://www.zope.org/Documentation/Articles/ZPT2}. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. PHP's Smarty templates} +\label{comparisons.smarty} + +PHP (\url{http://www.php.net/}) is one of the few scripting languages +expressly designed for web servlets. However, it's also a full-fledged +programming language with libraries similar to Python's and Perl's. The +syntax and functions are like a cross between Perl and C plus some original +ideas (e.g.; a single array type serves as both a list and a dictionary, +\verb+$arr[]="value";+ appends to an array). + +Smarty (\url{http://smarty.php.net/}) is an advanced template engine for +PHP. ({\em Note:} this comparision is based on Smarty's on-line documentation. +The author has not used Smarty. Please send corrections or ommissions to the +Cheetah mailing list.) Like Cheetah, Smarty: + +\begin{itemize} +\item compiles to the target programming language (PHP). +\item has configurable delimeters. +\item passes if-blocks directly to PHP, so you can use any PHP expression in +them. +\item allows you to embed PHP code in a template. +\item has a caching framework (although it works quite differently). +\item can read the template definition from any arbitrary source. +\end{itemize} + +Features Smarty has that Cheetah lacks: +\begin{itemize} +\item Preprocessors, postprocessors and output filters. You can emulate a +preprocessor in Cheetah by running your template definition through a filter +program or function before Cheetah sees it. To emulate a postprocessor, run a +.py template module through a filter program/function. To emulate a Smarty +output filter, run the template output through a filter program/function. If +you want to use ``cheetah compile'' or ``cheetah fill'' in a pipeline, use +\code{-} as the input file name and \code{--stdout} to send the result to +standard output. Note that Cheetah uses the term ``output filter'' differently +than Smarty: Cheetah output filters (\code{\#filter}) operate on placeholders, +while Smarty output filters operate on the entire template output. There has +been a proposed \code{\#sed} directive that would operate on the entire output +line by line, but it has not been implemented. +\item Variable modifiers. In some cases, Python has equivalent string +methods (\code{.strip}, \code{.capitalize}, \code{.replace(SEARCH, REPL)}), +but in other cases you must wrap the result in a function call or write +a custom output filter (\code{\#filter}). +\item Certain web-specific functions, which can be emulated with +third-party functions. +\item The ability to ``plug in'' new directives in a modular way. Cheetah +directives are tightly bound to the compiler. However, third-party +{\em functions} can be freely imported and called from placeholders, and +{\em methods} can be mixed in via \code{\#extends}. Part of this is +because Cheetah distinguishes between functions and directives, while +Smarty treats them all as ``functions''. Cheetah's design does not +allow functions to have flow control effect outside the function +(e.g., \code{\#if} and \code{\#for}, which operate on template body lines), +so directives like these cannot be encoded as functions. +\item Configuration variables read from an .ini-style file. The +\code{Cheetah.SettingsManager} module can parse such a file, but you'd +have to invoke it manually. (See the docstrings in the module for +details.) In Smarty, this feature is used for +multilingual applications. In Cheetah, the developers maintain that everybody +has their own preferred way to do this (such as using Python's \code{gettext} +module), and it's not worth blessing one particular strategy in Cheetah since +it's easy enough to integrate third-party code around the template, or to add +the resulting values to the searchList. +\end{itemize} + +Features Cheetah has that Smarty lacks: +\begin{itemize} +\item Saving the compilation result in a Python (PHP) module for quick +reading later. +\item Caching individual placeholders or portions of a template. Smarty +caches only the entire template output as a unit. +\end{itemize} + +Comparisions of various Smarty constructs: +\begin{verbatim} +{assign var="name" value="Bob"} (#set has better syntax in the author's opinion) +counter (looks like equivalent to #for) +eval (same as #include with variable) +fetch: insert file content into output (#include raw) +fetch: insert URL content into output (no euqivalent, user can write + function calling urllib, call as $fetchURL('URL') ) +fetch: read file into variable (no equivalent, user can write function + based on the 'open/file' builtin, or on .getFileContents() in + Template.) +fetch: read URL content into variable (no equivalent, use above + function and call as: #set $var = $fetchURL('URL') +html_options: output an HTML option list (no equivalent, user can + write custom function. Maybe FunFormKit can help.) +html_select_date: output three dropdown controls to specify a date + (no equivalent, user can write custom function) +html_select_time: output four dropdown controls to specify a time + (no equvalent, user can write custom function) +math: eval calculation and output result (same as #echo) +math: eval calculation and assign to variable (same as #set) +popup_init: library for popup windows (no equivalent, user can write + custom method outputting Javascript) + + +Other commands: +capture (no equivalent, collects output into variable. A Python + program would create a StringIO instance, set sys.stdout to + it temporarily, print the output, set sys.stdout back, then use + .getvalue() to get the result.) +config_load (roughly analagous to #settings, which was removed + from Cheetah. Use Cheetah.SettingsManager manually or write + a custom function.) +include (same as #include, but can include into variable. + Variables are apparently shared between parent and child.) +include_php: include a PHP script (e.g., functions) + (use #extends or #import instead) +insert (same as #include not in a #cache region) +{ldelim}{rdelim} (escape literal $ and # with a backslash, + use #compiler-settings to change the delimeters) +literal (#raw) +php (``<% %>'' tags) +section (#for $i in $range(...) ) +foreach (#for) +strip (like the #sed tag which was never implemented. Strips + leading/trailing whitespace from lines, joins several lines + together.) + + +Variable modifiers: +capitalize ( $STRING.capitalize() ) +count_characters ( $len(STRING) ) +count_paragraphs/sentances/words (no equivalent, user can write function) +date_format (use 'time' module or download Egenix's mx.DateTime) +default ($getVar('varName', 'default value') ) +escape: html encode ($cgi.escape(VALUE) ) +escape: url encode ($urllib.quote_plus(VALUE) ) +escape: hex encode (no equivalent? user can write function) +escape: hex entity encode (no equivalent? user can write function) +indent: indent all lines of a var's output (may be part of future + #indent directive) +lower ($STRING.lower() ) +regex_replace ('re' module) +replace ($STRING.replace(OLD, NEW, MAXSPLIT) ) +spacify (#echo "SEPARATOR".join(SEQUENCE) ) +string_format (#echo "%.2f" % FLOAT , etc.) +strip_tags (no equivalent, user can write function to strip HTML tags, + or customize the WebSafe filter) +truncate (no equivalent, user can write function) +upper ($STRING.upper() ) +wordwrap ('writer' module, or a new module coming in Python 2.3) +\end{verbatim} + +Some of these modifiers could be added to the super output filter we +want to write someday. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. PHPLib's Template class} +\label{comparisons.php} + +PHPLib (\url(http://phplib.netuse.de/) is a collection of classes for various +web objects (authentication, shopping cart, sessions, etc), but what we're +interested in is the \code{Template} object. It's much more primitive than +Smarty, and was based on an old Perl template class. In fact, one of the +precursors to Cheetah was based on it too. Differences from Cheetah: + +\begin{itemize} +\item Templates consist of text with \code{\{placeholders\}} in braces. +\item Instead of a searchList, there is one flat namespace. Every variable + must be assigned via the \code{set\_var} method. However, you can pass + this method an array (dictionary) of several variables at once. +\item You cannot embed lookups or calculations into the template. Every + placeholder must be an exact variable name. +\item There are no directives. You must do all display logic (if, for, etc) + in the calling routine. +\item There is, however, a ``block'' construct. A block is a portion of text + between the comment markers \code{<!-- BEGIN blockName --> \ldots + <!-- END blockName>}. The \code{set\_block} method extracts this text + into a namespace variable and puts a placeholder referring to it in the + template. This has a few parallels with Cheetah's \code{\#block} + directive but is overall quite different. +\item To do the equivalent of \code{\#if}, extract the block. Then if true, do + nothing. If false, assign the empty string to the namespace variable. +\item To do the equivalent of \code{\#for}, extract the block. Set any + namespace variables needed inside the loop. To parse one iteration, use + the \code{parse} method to fill the block variable (a mini-template) into + another namespace variable, appending to it. Refresh the namespace + variables needed inside the loop and parse again; repeat for each + iteration. You'll end up with a mini-result that will be plugged into the + main template's placeholder. +\item To read a template definition from a file, use the \code{set\_file} + method. This places the file's content in a namespace variable. + To read a template definition from a string, assign it to a namespace + variable. +\item Thus, for complicated templates, you are doing a lot of recursive block + filling and file reading and parsing mini-templates all into one flat + namespace as you finally build up values for the main template. In + Cheetah, all this display logic can be embedded into the template using + directives, calling out to Python methods for the more complicated tasks. +\item Although you can nest blocks in the template, it becomes tedious and + arguably hard to read, because all blocks have identical syntax. Unless + you choose your block names carefully and put comments around them, it's + hard to tell which blocks are if-blocks and which are for-blocks, or what + their nesting order is. +\item PHPLib templates do not have caching, output filters, etc. +\end{itemize} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Cheetah vs. PSP, PHP, ASP, JSP, Embperl, etc.} +\label{comparisons.pspEtc} + +\begin{description} +\item[Webware's PSP Component] -- \url{http://webware.sourceforge.net/Webware/PSP/Docs/} +\item[Tomcat JSP Information] -- \url{http://jakarta.apache.org/tomcat/index.html} +\item[ASP Information at ASP101] -- \url{http://www.asp101.com/} +\item[Embperl] -- \url{http://perl.apache.org/embperl/} +\end{description} + + +Here's a basic Cheetah example: +\begin{verbatim} +<TABLE> +#for $client in $service.clients +<TR> +<TD>$client.surname, $client.firstname</TD> +<TD><A HREF="mailto:$client.email" >$client.email</A></TD> +</TR> +#end for +</TABLE> +\end{verbatim} + +Compare this with PSP: + +\begin{verbatim} +<TABLE> +<% for client in service.clients(): %> +<TR> +<TD><%=client.surname()%>, <%=client.firstname()%></TD> +<TD><A HREF="mailto:<%=client.email()%>"><%=client.email()%></A></TD> +</TR> +<%end%> +</TABLE> +\end{verbatim} + +% Local Variables: +% TeX-master: "users_guide" +% End: diff --git a/docs/users_guide_2_src/E_license.txt b/docs/users_guide_2_src/E_license.txt new file mode 100644 index 0000000..8a5a73f --- /dev/null +++ b/docs/users_guide_2_src/E_license.txt @@ -0,0 +1,32 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{License} +\label{intro.license} + +\paragraph*{The gist} +Cheetah is open source, but products developed with Cheetah or derived +from Cheetah may be open source or closed source. + +(@@MO If this licence is identical to the MIT license, let's say so. That will +make it easier for distributors/aggregators to classify the product.) + +\paragraph*{Legal terms} +Copyright \copyright 2001-2006, The Cheetah Development Team: Tavis Rudd, Mike +Orr, Ian Bicking, Chuck Esterbrook, JJ Behrens. + +(@@MO Who is the current development team? Chuck and Ian have not been major +contributors for years. However, some of their code may remain in Cheetah.) + +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/docs/users_guide_2_src/Makefile b/docs/users_guide_2_src/Makefile new file mode 100644 index 0000000..ad0b786 --- /dev/null +++ b/docs/users_guide_2_src/Makefile @@ -0,0 +1,16 @@ +RST = rst2html.py --stylesheet=default.css --link-stylesheet --initial-header-level=2 + +#%.html: %.txt +# ${RST} $< $@ + +all: + #${RST} --warnings=/dev/null index.txt index.html + ${RST} 01_introduction.txt 01_introduction.html + ${RST} 02_glossary.txt 02_glossary.html + ${RST} 03_gettingStarted.txt 03_gettingStarted.html + ${RST} 04_howItWorks.txt 04_howItWorks.html + ${RST} 04_howItWorks.txt 04_howItWorks.html + ${RST} 13a_precompiledTemplateModules.txt 13a_precompiledTemplateModules.html + + +# vim: sw=8 ts=8 noexpandtab ai diff --git a/docs/users_guide_2_src/default.css b/docs/users_guide_2_src/default.css new file mode 100644 index 0000000..fa715d6 --- /dev/null +++ b/docs/users_guide_2_src/default.css @@ -0,0 +1,293 @@ +/* BEGIN Cheetah additions. *********************************** */ + +body { + /* font-size: 10pt; */ +} + +blockquote { + font-family: sans-serif; +} + +li { + margin-bottom: 1em; +} + +/* END Cheetah additions. ************************************ */ + +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Date: $Date: 2006/02/20 07:38:08 $ +:Revision: $Revision: 1.1 $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* "! important" is used here to override other ``margin-top`` and + ``margin-bottom`` styles that are later in the stylesheet or + more specific. See http://www.w3.org/TR/CSS1#the-cascade */ +.first { + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +dl.docutils dt { + font-weight: bold } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin-left: 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left { + clear: left } + +img.align-right { + clear: right } + +img.borderless { + border: 0 } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.line-block { + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid thin gray } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid thin black } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +tt.docutils { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } + + +/* vim: sw=4 ts=4 expandtab ai */ diff --git a/docs/users_guide_2_src/eg_1.py b/docs/users_guide_2_src/eg_1.py new file mode 100644 index 0000000..8098e6b --- /dev/null +++ b/docs/users_guide_2_src/eg_1.py @@ -0,0 +1,11 @@ +#eg_1 +# +#Looking up values held in dictionaries. +#No need to use all values in searchlist. + +from Cheetah.Template import Template +tmpl = "$value1 $value2 $value3" +NS = [{'value1':1, 'value2':2}, {'value3':3},{'value4':4}] +T = Template.compile(source=tmpl) +t = T(namespaces=NS) +print t.respond() #1,2,3 diff --git a/docs/users_guide_2_src/eg_2.py b/docs/users_guide_2_src/eg_2.py new file mode 100644 index 0000000..ee0f7a7 --- /dev/null +++ b/docs/users_guide_2_src/eg_2.py @@ -0,0 +1,10 @@ +from Cheetah.Template import Template + +#A retrieved value can be any Python object and can be used _exactly_ +#as it would be in Python code + +tmpl = "$value1, $value2, $value3[0], $value3[1], $value4[0]['this'][0]" +NS = [{'value1':1, 'value2':2, 'value3':[3,4], 'value4': [ {'this':[5]}]} ] +#Compile and fill template in one step +t = Template.compile(source=tmpl)(namespaces=NS) +print t.respond() #1, 2, 3, 4, 5 diff --git a/docs/users_guide_2_src/eg_3.py b/docs/users_guide_2_src/eg_3.py new file mode 100644 index 0000000..5c89a65 --- /dev/null +++ b/docs/users_guide_2_src/eg_3.py @@ -0,0 +1,18 @@ +from Cheetah.Template import Template + +#The namespaces list is a list of dictionaries and/or +#class instances. Search is for dictionary key or object +#attributes in this list +class X: + pass + + +x = X() +x.value3 = 3 +x.value4 = 4 + +tmpl = "$value1, $value2, $value3, $value4" +NS = [{'value1':1},{'value2':2}, x] + +t = Template.compile(source=tmpl)(namespaces=NS) +print t.respond() #1,2,3,4 diff --git a/docs/users_guide_2_src/eg_4.py b/docs/users_guide_2_src/eg_4.py new file mode 100644 index 0000000..8fab657 --- /dev/null +++ b/docs/users_guide_2_src/eg_4.py @@ -0,0 +1,22 @@ +from Cheetah.Template import Template +from Cheetah import NameMapper + +#Error. Cheetah cannot find 'x' because +#it is not dictionary key or instance member: + + +class X: + pass + +x = X() +x.value3 = 3 + +tmpl = "$x.value3" +NS = [x] +t = Template.compile(source=tmpl)(namespaces=NS) +try: + t.respond() #Here substitution is attempted +except NameMapper.NotFound, e: + print 'NameMapper.NotFound: %s' % e + #NameMapper.NotFound: cannot find 'x' + diff --git a/docs/users_guide_2_src/eg_5.py b/docs/users_guide_2_src/eg_5.py new file mode 100644 index 0000000..551f9c0 --- /dev/null +++ b/docs/users_guide_2_src/eg_5.py @@ -0,0 +1,25 @@ +from Cheetah.Template import Template + +# ways of using Python to process values after +#retrieval. 1. Sets a new variable then uses it, +#2. Uses pure Python function to set new variable +#3. Cheetah calls function directly +#4. Extended ${} syntax without function call + +tmpl = """ + +#set $value1 = $value.replace(' ','-') +1. $value1 +<% def change(x): + return x.replace(' ','-') +%> +#set $value1 = change($value) +2. $value1 +3. $change($value) +4. ${value.replace(' ','-')} +""" +NS = [ {'value':'this and that'}] + +#compile and fill the template +t = Template(source=tmpl, namespaces=NS) +print t.respond() diff --git a/docs/users_guide_2_src/latex2rst.py b/docs/users_guide_2_src/latex2rst.py new file mode 100755 index 0000000..80f9a1d --- /dev/null +++ b/docs/users_guide_2_src/latex2rst.py @@ -0,0 +1,45 @@ +#!/usr/bin/env python +"""Convert files from LaTeX format to ReStructured Text. + + This converter is meant only for saving keystrokes. It won't catch + everything and it may misformat stuff, so proofread the file after + processing. + + "Verbatim" blocks are not converted due to the difficulty in placing the + preceding colon(s) and indenting every line. +""" +import os, re, shutil, sys + +def convert(filename): + print "Processing file", filename + backup = filename + ".bak" + shutil.copy2(filename, backup) + f = open(filename, 'r+') + text = f.read() + text = re.sub( R"%%%+", R"", text) + text = re.sub( R"\\section\{(.*?)\}", R"\1\n" + ("=" * 40), text) + text = re.sub( R"\\subsection\{(.*?)\}", R"\1\n" + ("-" * 40), text) + text = re.sub( R"\\label\{(.*?)\}", R"\n..\n :label: \1", text) + text = re.sub( R"``|''", R'"', text) + text = re.sub( R"(?s)\{\\em (.*?)\}", R"*\1*", text) + text = re.sub( R"(?s)\{\\bf (.*?)\}", R"**\1**", text) + text = re.sub( R"(?s)\\code\{(.*?)\}", R"``\1``", text) + text = re.sub( R"\\(begin|end)\{(itemize|enumerate)\}\n", R"", text) + text = re.sub( R"\\item ", R"* ", text) + #text = re.sub( + # R"(?sm)(\w):\n\s*^\\begin\{verbatim\}\s*(.*?)\\end\{verbatim\}", + # R"\1::\n\n\2", text) + f.seek(0) + f.write(text) + f.truncate() + f.close() + + +def main(): + if len(sys.argv) < 2: + prog = os.path.basename(sys.argv[0]) + raise SystemExit("usage: %s FILENAMES ..." % prog) + for filename in sys.argv[1:]: + convert(filename) + +if __name__ == "__main__": main() diff --git a/docs/users_guide_2_src/unused.txt b/docs/users_guide_2_src/unused.txt new file mode 100644 index 0000000..3b78fc9 --- /dev/null +++ b/docs/users_guide_2_src/unused.txt @@ -0,0 +1,67 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Give me an example of a Webware servlet!} +\label{intro.example.servlet} + +This example uses an HTML form to ask the user's name, then invokes itself +again to display a {\em personalized} friendly greeting. + +\begin{verbatim} +<HTML><HEAD><TITLE>My Template-Servlet</TITLE></HEAD><BODY> +#set $name = $request.field('name', None) +#if $name +Hello $name +#else +<FORM ACTION="" METHOD="GET"> +Name: <INPUT TYPE="text" NAME="name"><BR> +<INPUT TYPE="submit"> +</FORM> +#end if +</BODY></HTML> +\end{verbatim} + +To try it out for yourself on a Webware system: +\begin{enumerate} +\item copy the template definition to a file {\bf test.tmpl} in your + Webware servlet directory. +\item Run ``\code{cheetah compile test.tmpl}''. This produces + {\bf test.py} (a .py template module) in the same directory. +\item In your web browser, go to {\bf test.py}, using whatever site and + directory is appropriate. Depending on your Webware configuration, you may + also be able to go to {\bf test}. +\end{enumerate} + +At the first request, field `name' will be blank (false) so the ``\#else'' +portion will execute and present a form. You type your name and press submit. +The form invokes the same page. Now `name' is true so the ``\#if'' portion +executes, which displays the greeting. The ``\#set'' directive creates a +local variable that lasts while the template is being filled. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +To install Cheetah in your system-wide Python library: +* Login as a user with privileges to install system-wide Python packages. + On POSIX systems (AIX, Solaris, Linux, IRIX, etc.), the command is + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Certain test failures are insignificant: +\begin{description} +\item{**AssertionError: Template output mismatch: Expected Output = 0(end) +Actual Output = False(end)**} Python 2.3 changed the string representation of +booleans, and the tests haven't yet been updated to reflect this. +\item{**AssertionError: subcommand exit status 127**} Certain tests run +"cheetah" as a subcommand. The failure may mean the command wasn't found +in your system path. (What happens if you run "cheetah" on the command line?) +The failure also happens on some Windows systems for unknown reasons. This +failure has never been observed outside the test suite. Long term, we plan to +rewrite the tests to do a function call rather than a subcommand, which will +also make the tests run significantly faster. +\item{**ImportError: No module named SampleBaseClass**} The test tried to +write a temporary module in the current directory and ``import`` it. Reread +the first paragraph in this section about the current directory. +\item{**ImportError: No module named tmp**} May be the same problem as +SampleBaseClass; let us know if changing the current directory doesn't work. +\end{description} + + normally 'su root'. On non-POSIX systems such as Windows NT, login as an + administrator. |