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 '''Document templates with fill-in fields
86
87 Document templates provide for creation of textual documents, such as
88 HTML pages, from template source by inserting data from python objects
89 and name-spaces.
90
91 When a document template is created, a collection of default values to
92 be inserted may be specified with a mapping object and with keyword
93 arguments.
94
95 A document templated may be called to create a document with values
96 inserted. When called, an instance, a mapping object, and keyword
97 arguments may be specified to provide values to be inserted. If an
98 instance is provided, the document template will try to look up values
99 in the instance using getattr, so inheritence of values is supported.
100 If an inserted value is a function, method, or class, then an attempt
101 will be made to call the object to obtain values. This allows
102 instance methods to be included in documents.
103
104 Document templates masquerade as functions, so the python object
105 publisher (Bobo) will call templates that are stored as instances of
106 published objects. Bobo will pass the object the template was found in
107 and the HTTP request object.
108
109 Two source formats are supported:
110
111 Extended Python format strings (EPFS) --
112 This format is based on the insertion by name format strings
113 of python with additional format characters, '[' and ']' to
114 indicate block boundaries. In addition, parameters may be
115 used within formats to control how insertion is done.
116
117 For example:
118
119 %%(date fmt=DayOfWeek upper)s
120
121 causes the contents of variable 'date' to be inserted using
122 custom format 'DayOfWeek' and with all lower case letters
123 converted to upper case.
124
125 HTML --
126 This format uses HTML server-side-include syntax with
127 commands for inserting text. Parameters may be included to
128 customize the operation of a command.
129
130 For example:
131
132 <!--#var total fmt=12.2f-->
133
134 is used to insert the variable 'total' with the C format
135 '12.2f'.
136
137 Document templates support conditional and sequence insertion
138
139 Document templates extend python string substitition rules with a
140 mechanism that allows conditional insertion of template text and that
141 allows sequences to be inserted with element-wise insertion of
142 template text.
143
144 Access Control
145
146 Document templates provide a basic level of access control by
147 preventing access to names beginning with an underscore.
148 Addational control may be provided by providing document templates
149 with a 'validate' method. This would typically be done by
150 subclassing one or more of the DocumentTemplate classes.
151
152 If provided, the the 'validate' method will be called when objects
153 are accessed as accessed as instance attributes or when they are
154 accessed through keyed access in an expression.. The 'validate'
155 method will be called with five arguments:
156
157 1. The containing object that the object was accessed from,
158
159 2. The actual containing object that the object was found in,
160 which may be different from the containing onject the object
161 was accessed from, if the containing object supports
162 acquisition,
163
164 3. The name used to acces the object,
165
166 4. The object, and
167
168 5. The namespace object used to render the document template.
169
170 If a document template was called from Bobo, then the namespace
171 object will have an attribute, AUTHENTICATED_USER that is the
172 user object that was found if and when Bobo authenticated a user.
173
174 Document Templates may be created 4 ways:
175
176 DocumentTemplate.String -- Creates a document templated from a
177 string using an extended form of python string formatting.
178
179 DocumentTemplate.File -- Creates a document templated bound to a
180 named file using an extended form of python string formatting.
181 If the object is pickled, the file name, rather than the file
182 contents is pickled. When the object is unpickled, then the
183 file will be re-read to obtain the string. Note that the file
184 will not be read until the document template is used the first
185 time.
186
187 DocumentTemplate.HTML -- Creates a document templated from a
188 string using HTML server-side-include rather than
189 python-format-string syntax.
190
191 DocumentTemplate.HTMLFile -- Creates an HTML document template
192 from a named file.
193
194 '''
195
196
197 __version__='$Revision: 694 $'[11:-2]
198
199 ParseError='Document Template Parse Error'
200
201 from DT_String import String, File
202 from DT_HTML import HTML, HTMLFile, HTMLDefault
203
204 from DT_Util import html_quote
205