diff options
Diffstat (limited to 'docs/users_guide_src/libraries.tex')
| -rw-r--r-- | docs/users_guide_src/libraries.tex | 317 |
1 files changed, 0 insertions, 317 deletions
diff --git a/docs/users_guide_src/libraries.tex b/docs/users_guide_src/libraries.tex deleted file mode 100644 index 1fd1a78..0000000 --- a/docs/users_guide_src/libraries.tex +++ /dev/null @@ -1,317 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\section{Batteries included: templates and other libraries} -\label{libraries} - -Cheetah comes ``batteries included'' with libraries of templates, functions, -classes and other objects you can use in your own programs. The different -types are listed alphabetically below, followed by a longer description of -the SkeletonPage framework. Some of the objects are classes for specific -purposes (e.g., filters or error catchers), while others are standalone and -can be used without Cheetah. - -If you develop any objects which are generally useful for Cheetah sites, -please consider posting them on the wiki with an announcement on the mailing -list so we can incorporate them into the standard library. That way, all -Cheetah users will benefit, and it will encourage others to contribute their -objects, which might include something you want. - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\subsection{ErrorCatchers} -\label{libraries.ErrorCatchers} - -Module \code{Cheetah.ErrorCatchers} contains error-handling classes -suitable for the \code{\#errorCatcher} directive. -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 mixin class that provides facilities for managing application settings. -Class \code{Cheetah.SettingsManager.SettingsManager} 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. For more information, see section -\ref{inheritanceEtc.settings} and the class source. - -Cheetah uses \code{SettingsManager} to manage its configuration settings. -\code{SettingsManager} might also be useful in your own applications. See the -source code and docstrings in the file \code{src/SettingsManager.py} for more -information. If there is sufficient interest in \code{SettingsManager}, we will -release it as a standalone module. - -Both the \code{\#settings} and \code{\#compiler-settings} directives use -\code{SettingsManager}, although they maintain two separate lists of settings. - - -% @@MO: deleted, redundant. -%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} - - - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\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 will be very 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} -$*docType -<HTML> -#################### -#block headerComment -<!-- This document was autogenerated by Cheetah. Don't edit it directly! - -Copyright $currentYr() - $*siteCopyrightName - All Rights Reserved. -Feel free to copy any javascript or html you like on this site, -provided you remove all links and/or references to $*siteDomainName -However, please do not copy any content or images without permission. - -$*siteCredits - ---> - -#end block -##################### - -################# -#block headTag -<HEAD> -<TITLE>$*title</TITLE> -$*metaTags() -$*stylesheetTags() -$*javascriptTags() -</HEAD> -#end block -################# - - -################# -#block bodyTag -$bodyTag() -#end block -################# - -#block writeBody -This skeleton page has no flesh. Its body needs to be implemented. -#end block - -</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? - -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} - -See the file \code{examples/webware\_examples/cheetahSite/SiteTemplate.tmpl} -for an extended example of how \code{SkeletonPage} can be used. - - - -% Local Variables: -% TeX-master: "users_guide" -% End: |