1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Macro, Template and other libraries}
\label{libraries}
Cheetah comes ``batteries included'' with libraries of macros, templates and
other objects you can use in your own programs. If you develop your own, please
consider posting them on the mailing list so others can benefit.
Some useful functions, and other objects, used by Cheetah are in the
\code{Cheetah.Utilities} module. All utility modules contributed by third
parties are in the \code{Cheetah.Tools} package.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Macro libraries}
\label{libraries.macros}
The package \code{Cheetah.Macros} includes libraries of macros that can be
loaded into Templates via the \code{Template.loadMacrosFromModule()} method.
See section \ref{directives.macros.existingFunctions} for more information on
this method. All of the functions contained in the macro libraries can also be
added to the \code{searchList} and used as regular \$placeholders if you wish.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Cheetah.Macros.HTML}
\label{libraries.macros.HTML}
The module \code{Cheetah.Macros.HTML} contains a number of functions that are
usefull for generating common HTML elements.
\begin{itemize}
\item {\bf \code{currentYr()}} -- Returns the current year. This is useful in
copyright strings.
\item {\bf \code{currentDate(formatString=''\%b \%d, \%Y'')}} -- Returns a string
representation of the current date. See the documentation for the Python
\code{time} module for the formatString codes. If you change the
formatString, remember that when this function used as a macro the date
will only be calculated once at compile-time
\item {\bf \code{spacer(width=1,height=1)}} -- Returns an image tag for a
transparent spacer image. This very useful for generating complex image
tables. You'll need to have a single-pixel transparent gif image called
\code{spacer.gif} in the same directory as your template file. If you want
to put the image elsewhere you can easily reimplement the function behind
this macro.
\item {\bf \code{formHTMLTag(tagName, attributes=\{\})}} -- Returns an HTML tag
with the attributes given.
\item {\bf \code{formatMetaTags(metaTags)}} -- Will auto-format a dictionary of
meta-tags. It accepts a dictionary that contains one or two
sub-dictionaries under the keys \code{HTTP_EQUIV} and \code{NAME}. Each of
the sub-dictionaries should contain key-value pairs that represent the
name-contents pairs for each of the desired meta-tags.
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Template libraries}
\label{libraries.templates}
The \code{Cheetah.Templates} package contains stock templates that you can
either use as is, or extend by using the \code{\#redefine} directive to redefine
specific {\bf blocks}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Cheetah.Templates.SkeletonPage}
\label{libraries.templates.skeletonPage}
A stock template that will be very useful for web developers is defined in
the \code{Cheetah.Templates.SkeletonPage} module. The \code{SkeletonPage} page
class is a subclass of \code{Cheetah.Servlet.TemplateServlet} that is bound to
the following template definition:
\begin{verbatim}
$*docType
<HTML>
####################
#block headerComment
<!-- This document was autogenerated by Cheetah. Don't edit it directly!
Copyright #currentYr() - $*siteCopyrightName - All Rights Reserved.
Feel free to copy any javascript or html you like on this site,
provided you remove all links and/or references to $*siteDomainName
However, please do not copy any content or images without permission.
$*siteCredits
-->
#end block headerComment
#####################
#################
#block headTag /#
<HEAD>
<TITLE>$*title</TITLE>
$*metaTags()
$*stylesheetTags()
$*javascriptTags()
</HEAD>
#end block headTag /#
#################
#################
#block bodyTag /#
$bodyTag()
#end block bodyTag /#
#################
#block bodyContents /#
This skeleton page has no flesh. Its body needs to be implemented.
#end block bodyContents /#
</BODY>
</HTML>
\end{verbatim}
You can reimplement any of the blocks defined in this template definition by
writing a {\bf template definition extension} that contains \code{\#redefine}
directives (see section \ref{directives.redefine}).
\begin{verbatim}
#redefine bodyContents
Here's my new body. I've got some flesh on my bones now.
#end redefine bodyContents
\end{verbatim}
The \code{SkeletonPage} class automatically loads the \code{Cheetah.Macros.HTML}
macro library. Thus, macros like \code{\#currentYr()} can be used by any
subclass.
All of the \$placeholders used in the \code{SkeletonPage} template definition
are attributes or methods of the \code{SkeletonPage} class. You can reimplement
them as you wish in your subclass. Please read the source code of the file
\code{src/Templates/SkeletonPage.py} before doing so.
You'll need to understand how to use the following methods of the
\code{SkeletonPage} class: \code{\$metaTags()}, \code{\$stylesheetTags()},
\code{\$javascriptTags()}, and \code{\$bodyTag()}. They take the data you
define in various attributes and renders them into HTML tags.
\begin{itemize}
\item {\bf metaTags()} -- Returns a formatted vesion of the self._metaTags
dictionary, using the formatMetaTags function from \code{Cheetah.Macros.HTML}
\item {\bf stylesheetTags()} -- Returns a formatted version of the
\code{self._stylesheetLibs} and \code{self._stylesheets} dictionaries. The
keys in \code{self._stylesheets} must be listed in the order that they
should appear in the list \code{self._stylesheetsOrder}, to ensure that the
style rules are defined in the correct order.
\item {\bf javascriptTags()} -- Returns a formatted version of the
\code{self._javascriptTags} and \code{self._javascriptLibs} dictionaries.
Each value in \code{self._javascriptTags} should be a either a code string
to include, or a list containing the JavaScript version number and the code
string. The keys can be anything. The same applies for
\code{self._javascriptLibs}, but the string should be the SRC filename
rather than a code string.
\item {\bf bodyTag()} -- Returns an HTML body tag from the entries in the dict
\code{self._bodyTagAttribs}.
\end{itemize}
The class also provides some convenience methods that can be used as
\$placeholders in your template definitions:
\begin{itemize}
\item {\bf imgTag(self, src, alt='', width=None, height=None, border=0)} --
Dynamically generate an image tag. Cheetah will try to convert the
``\code{src}'' argument to a WebKit serverSidePath relative to the
servlet's location. If width and height aren't specified they are
calculated using PIL or ImageMagick if either of these tools are available.
If all your images are stored in a certain directory you can reimplement
this method to append that directory's path to the ``\code{src}'' argument.
Doing so would also insulate your template definitions from changes in your
directory structure.
\end{itemize}
See the file \code{examples/webware_examples/cheetahSite/SiteTemplate.tmpl} for
an extended example of how \code{SkeletonPage} can be used.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Cheetah.Utilities}
\label{libraries.utilities}
\begin{itemize}
\item {\bf \code{mergeNestedDictionaries(dict1, dict2)}} -- Recursively merge
the values of dict2 into dict1. This little function is very handy for
selectively overriding settings in a settings dictionary that has a nested
structure.
\item {\bf \code{removeDuplicateValues(list)}} -- Remove all duplicate values in
a list.
\item {\bf \code{lineNumFromPos(string, pos)}} -- Calculate what line a position
in a string lies on. This doesn't work on Mac-OS.
\item {\bf \code{getLines(string, sliceObj)}} -- Slice a string up into a list
of lines and return a slice.
\item {\bf \code{insertLineNums(string)}} -- Return a version of the string with
each line prefaced with its line number.
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Cheetah.Tools}
\label{libraries.tools}
As mentiond above, utility modules contributed by third parties are stored in
the \code{Cheetah.Tools} package. It currently contains:
\begin{itemize}
\item {\bf Cheetah.Tools.RecursiveNull} -- Nothing, but in a friendly way. Good
for filling in for objects you want to hide. If \code{\$form.f1} is a
RecursiveNull object, then \code{\$form.f1.anything["you"].might("use")} will
resolve to the empty string. Contributed by Ian Bicking.
\end{itemize}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Cheetah.SettingsManager}
\label{libraries.SettingsManager}
The \code{SettingsManager} class in the \code{Cheetah.SettingsManager} module is
a mixin class that provides facilities for managing application settings.
SettingsManager is designed to:
\begin{itemize}
\item work well with nested settings dictionaries of any depth
\item be able to read/write \code{.ini style config files} (or strings)
\item be able to read settings from Python src files (or strings) so that
complex Python objects can be stored in the application's settings
dictionary. For example, you might want to store references to various
classes that are used by the application and plugins to the application
might want to substitute one class for another.
\item allow sections in \code{.ini config files} to be extended by settings in
Python src files. If a section contains a setting like
``\code{importSettings=mySettings.py}'', \code{SettingsManager} will merge
all the settings defined in ``\code{mySettings.py}'' with the settings for
that section that are defined in the \code{.ini config file}.
\item maintain the case of setting names, unlike the ConfigParser module
\end{itemize}
Cheetah uses \code{SettingsManager} to manage its configuration settings.
\code{SettingsManager} might also be useful in your own applications. See the
source code and docstrings in the file \code{src/SettingsManager.py} for more
information. If there is sufficient interest in \code{SettingsManager} we will
release it as a standalone module.
% Local Variables:
% TeX-master: "users_guide"
% End:
|
