diff options
Diffstat (limited to 'docs/users_guide_src/libraries.tex')
| -rwxr-xr-x | docs/users_guide_src/libraries.tex | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/docs/users_guide_src/libraries.tex b/docs/users_guide_src/libraries.tex new file mode 100755 index 0000000..dc9231a --- /dev/null +++ b/docs/users_guide_src/libraries.tex @@ -0,0 +1,306 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Batteries included: templates and other libraries} +\label{libraries} + +Cheetah comes ``batteries included'' with libraries of templates, functions, +classes and other objects you can use in your own programs. The different +types are listed alphabetically below, followed by a longer description of +the SkeletonPage framework. Some of the objects are classes for specific +purposes (e.g., filters or error catchers), while others are standalone and +can be used without Cheetah. + +If you develop any objects which are generally useful for Cheetah sites, +please consider posting them on the wiki with an announcement on the mailing +list so we can incorporate them into the standard library. That way, all +Cheetah users will benefit, and it will encourage others to contribute their +objects, which might include something you want. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{ErrorCatchers} +\label{libraries.ErrorCatchers} + +Module \code{Cheetah.ErrorCatchers} contains error-handling classes suitable for +the \code{\#errorCatcher} directive. These are debugging tools that are not +intended for use in production systems. See section +\ref{errorHandling.errorCatcher} for a description of the error catchers bundled +with Cheetah. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{FileUtils} +\label{libraries.FileUtils} + +Module \code{Cheetah.FileUtils} contains generic functions and classes for +doing bulk search-and-replace on several files, and for finding all the files +in a directory hierarchy whose names match a glob pattern. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Filters} +\label{libraries.Filters} + +Module \code{Filters} contains filters suitable for the \code{\#Filter} +directive. See section \ref{output.filter} for a description of the +filters bundled with Cheetah. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{SettingsManager} +\label{libraries.SettingsManager} + +The \code{SettingsManager} class in the \code{Cheetah.SettingsManager} module is +a baseclass that provides facilities for managing application settings. It +facilitates the use of user-supplied configuration files to fine tune an +application. A setting is a key/value pair that an application or component +(e.g., a filter, or your own servlets) looks up and treats as a configuration +value to modify its (the component's) behaviour. + +SettingsManager is designed to: +\begin{itemize} +\item work well with nested settings dictionaries of any depth +\item read/write \code{.ini style config files} (or strings) +\item read settings from Python source files (or strings) so that + complex Python objects can be stored in the application's settings + dictionary. For example, you might want to store references to various + classes that are used by the application, and plugins to the application + might want to substitute one class for another. +\item allow sections in \code{.ini config files} to be extended by settings in + Python src files. If a section contains a setting like + ``\code{importSettings=mySettings.py}'', \code{SettingsManager} will merge + all the settings defined in ``\code{mySettings.py}'' with the settings for + that section that are defined in the \code{.ini config file}. +\item maintain the case of setting names, unlike the ConfigParser module +\end{itemize} + +Cheetah uses \code{SettingsManager} to manage its configuration settings. +\code{SettingsManager} might also be useful in your own applications. See the +source code and docstrings in the file \code{src/SettingsManager.py} for more +information. + + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Templates} +\label{libraries.templates} + +Package \code{Cheetah.Templates} contains stock templates that you can +either use as is, or extend by using the \code{\#def} directive to redefine +specific {\bf blocks}. Currently, the only template in here is SkeletonPage, +which is described in detail below in section +\ref{libraries.templates.skeletonPage}. (Contributed by Tavis Rudd.) + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Tools} +\label{libraries.Tools} + +Package \code{Cheetah.Tools} contains functions and classes contributed by third +parties. Some are Cheetah-specific but others are generic and can be used +standalone. None of them are imported by any other Cheetah component; you can +delete the Tools/ directory and Cheetah will function fine. + +Some of the items in Tools/ are experimental and have been placed there just to +see how useful they will be, and whether they attract enough users to make +refining them worthwhile (the tools, not the users :). + +Nothing in Tools/ is guaranteed to be: (A) tested, (B) reliable, (C) immune +from being deleted in a future Cheetah version, or (D) immune from +backwards-incompatable changes. If you depend on something in Tools/ on a +production system, consider making a copy of it outside the Cheetah/ directory +so that this version won't be lost when you upgrade Cheetah. Also, learn +enough about Python and about the Tool so that you can maintain it and bugfix +it if necessary. + +If anything in Tools/ is found to be necessary to Cheetah's operation (i.e., if +another Cheetah component starts importing it), it will be moved to the +\code{Cheetah.Utils} package. + +Current Tools include: +\begin{description} +\item{Cheetah.Tools.MondoReport} an ambitious class useful when + iterating over records of data (\code{\#for} loops), displaying one + pageful of records at a time (with previous/next links), and printing + summary statistics about the records or the current page. See + \code{MondoReportDoc.txt} in the same directory as the module. Some + features are not implemented yet. \code{MondoReportTest.py} is a test + suite (and it shows there are currently some errors in MondoReport, hmm). + Contributed by Mike Orr. + +\item{Cheetah.Tools.RecursiveNull} Nothing, but in a friendly way. Good + for filling in for objects you want to hide. If \code{\$form.f1} is a + RecursiveNull object, then \code{\$form.f1.anything["you"].might("use")} + will resolve to the empty string. You can also put a \code{RecursiveNull} + instance at the end of the searchList to convert missing values to '' + rather than raising a \code{NotFound} error or having a (less efficient) + errorCatcher handle it. Of course, maybe you prefer to get a + \code{NotFound} error... Contributed by Ian Bicking. + +\item{Cheetah.Tools.SiteHierarchy} Provides navigational links to this + page's parents and children. The constructor takes a recursive list of + (url,description) pairs representing a tree of hyperlinks to every page in + the site (or section, or application...), and also a string containing the + current URL. Two methods 'menuList' and 'crumbs' return output-ready HTML + showing an indented menu (hierarchy tree) or crumbs list (Yahoo-style bar: + home > grandparent > parent > currentURL). Contributed by Ian Bicking. + +\item +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Utils} +\label{libraries.Utils} + +Package \code{Cheetah.Utils} contains non-Cheetah-specific functions and +classes that are imported by other Cheetah components. Many of these utils can +be used standalone in other applications too. + +Current Utils include: +\begin{description} +\item{Cheetah.Utils.CGIImportMixin} This is inherited by \code{Template} + objects, and provides the method, \code{.cgiImport} method + (section \ref{webware.cgiImport}). + +\item{Cheetah.Utils.Misc} A catch-all module for small functions. + \begin{description} + \item{\code{UseOrRaise(thing, errmsg='')}} Raise 'thing' if it's a + subclass of Exception, otherwise return it. Useful when one + argument does double duty as a default value or an exception to + throw. Contribyted by Mike Orr. + + \item{\code{checkKeywords(dic, legalKeywords, what='argument'}} + Verifies the dictionary does not contain any keys not listed in + 'legalKeywords'. If it does, raise TypeError. Useful for + checking the keyword arguments to a function. Contributed by + Mike Orr. + \end{description} + +\item{Cheetah.Utils.UploadFileMixin} Not implemented yet, but will contain + the \code{.uploadFile} method (or three methods) to ``safely'' copy a + form-uploaded file to a local file, to a searchList variable, or return + it. When finished, this will be inherited by \code{Template}, allowing + all templates to do this. If you want this feature, read the docstring + in the source and let us know on the mailing list what you'd like this + method to do. Contributed by Mike Orr. + +\item{Cheetah.Utils.VerifyType} Functions to verify the type of a + user-supplied function argument. Contributed by Mike Orr. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsubsection{Cheetah.Templates.SkeletonPage} +\label{libraries.templates.skeletonPage} + +A stock template class that may be useful for web developers is defined in +the \code{Cheetah.Templates.SkeletonPage} module. The \code{SkeletonPage} +template class is generated from the following Cheetah source code: + +\begin{verbatim} +##doc-module: A Skeleton HTML page template, that provides basic structure and utility methods. +################################################################################ +#extends Cheetah.Templates._SkeletonPage +#implements respond +################################################################################ +#cache id='header' +$docType +$htmlTag +<!-- This document was autogenerated by Cheetah(http://CheetahTemplate.org). +Do not edit it directly! + +Copyright $currentYr - $siteCopyrightName - All Rights Reserved. +Feel free to copy any javascript or html you like on this site, +provided you remove all links and/or references to $siteDomainName +However, please do not copy any content or images without permission. + +$siteCredits + +--> + + +#block writeHeadTag +<head> +<title>$title</title> +$metaTags +$stylesheetTags +$javascriptTags +</head> +#end block writeHeadTag + +#end cache header +################# + +$bodyTag + +#block writeBody +This skeleton page has no flesh. Its body needs to be implemented. +#end block writeBody + +</body> +</html> +\end{verbatim} + +You can redefine any of the blocks defined in this template by writing a new +template that \code{\#extends} SkeletonPage. (As you remember, using +\code{\#extends} makes your template implement the \code{.writeBody()} +method instead of \code{.respond()} -- which happens to be the same method +SkeletonPage expects the page content to be (note the writeBody block in +SkeletonPage).) + +\begin{verbatim} +#def bodyContents +Here's my new body. I've got some flesh on my bones now. +#end def bodyContents +\end{verbatim} + +%% @@MO: Is this still accurate? Does the child template really need to put a +%% #def around its whole content? Or by implementing .writeBody() does it +%% automatically insert itself as the writeBody portion of +%% SkeletonPage? @@TR 2005-01-06: it happens automatically at the moment. + +All of the \$placeholders used in the \code{SkeletonPage} template definition +are attributes or methods of the \code{SkeletonPage} class. You can reimplement +them as you wish in your subclass. Please read the source code of the file +\code{src/Templates/\_SkeletonPage.py} before doing so. + +You'll need to understand how to use the following methods of the +\code{SkeletonPage} class: \code{\$metaTags()}, \code{\$stylesheetTags()}, +\code{\$javascriptTags()}, and \code{\$bodyTag()}. They take the data you +define in various attributes and renders them into HTML tags. + +\begin{itemize} +\item {\bf metaTags()} -- Returns a formatted vesion of the self.\_metaTags + dictionary, using the formatMetaTags function from + \code{\_SkeletonPage.py}. +\item {\bf stylesheetTags()} -- Returns a formatted version of the + \code{self.\_stylesheetLibs} and \code{self.\_stylesheets} dictionaries. + The keys in \code{self.\_stylesheets} must be listed in the order that + they should appear in the list \code{self.\_stylesheetsOrder}, to ensure + that the style rules are defined in the correct order. +\item {\bf javascriptTags()} -- Returns a formatted version of the + \code{self.\_javascriptTags} and \code{self.\_javascriptLibs} dictionaries. + Each value in \code{self.\_javascriptTags} should be a either a code string + to include, or a list containing the JavaScript version number and the code + string. The keys can be anything. The same applies for + \code{self.\_javascriptLibs}, but the string should be the SRC filename + rather than a code string. +\item {\bf bodyTag()} -- Returns an HTML body tag from the entries in the dict + \code{self.\_bodyTagAttribs}. +\end{itemize} + +The class also provides some convenience methods that can be used as +\$placeholders in your template definitions: + +\begin{itemize} +\item {\bf imgTag(self, src, alt='', width=None, height=None, border=0)} -- + Dynamically generate an image tag. Cheetah will try to convert the + ``\code{src}'' argument to a WebKit serverSidePath relative to the + servlet's location. If width and height aren't specified they are + calculated using PIL or ImageMagick if either of these tools are available. + If all your images are stored in a certain directory you can reimplement + this method to append that directory's path to the ``\code{src}'' argument. + Doing so would also insulate your template definitions from changes in your + directory structure. +\end{itemize} + + +% Local Variables: +% TeX-master: "users_guide" +% End: |