diff options
author | R. Tyler Ballance <tyler@monkeypox.org> | 2009-11-16 21:09:13 -0800 |
---|---|---|
committer | R. Tyler Ballance <tyler@monkeypox.org> | 2009-11-16 21:09:13 -0800 |
commit | d9ce7916e309e2393d824e249f512d2629e5e181 (patch) | |
tree | 6b7ad5cd6292f6e017e048fbeb4551facbabd174 /docs/users_guide_2_src/02_glossary.txt | |
parent | e43765a679b84c52df875e9629d303e304af50a1 (diff) | |
download | python-cheetah-docs.tar.gz |
Revert "Delete the "old" docs directory to make way for fancy smancy sphinx"docs
This reverts commit 5dc95cfcd015628665d3672e56d0551943b5db6b.
Diffstat (limited to 'docs/users_guide_2_src/02_glossary.txt')
-rw-r--r-- | docs/users_guide_2_src/02_glossary.txt | 66 |
1 files changed, 66 insertions, 0 deletions
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/ |