1
2
3
4
5
6
7
8
9
10
11
12
13 '''Document templates with fill-in fields
14
15 Document templates provide for creation of textual documents, such as
16 HTML pages, from template source by inserting data from python objects
17 and name-spaces.
18
19 When a document template is created, a collection of default values to
20 be inserted may be specified with a mapping object and with keyword
21 arguments.
22
23 A document templated may be called to create a document with values
24 inserted. When called, an instance, a mapping object, and keyword
25 arguments may be specified to provide values to be inserted. If an
26 instance is provided, the document template will try to look up values
27 in the instance using getattr, so inheritence of values is supported.
28 If an inserted value is a function, method, or class, then an attempt
29 will be made to call the object to obtain values. This allows
30 instance methods to be included in documents.
31
32 Document templates masquerade as functions, so the python object
33 publisher (Bobo) will call templates that are stored as instances of
34 published objects. Bobo will pass the object the template was found in
35 and the HTTP request object.
36
37 Two source formats are supported:
38
39 Extended Python format strings (EPFS) --
40 This format is based on the insertion by name format strings
41 of python with additional format characters, '[' and ']' to
42 indicate block boundaries. In addition, parameters may be
43 used within formats to control how insertion is done.
44
45 For example:
46
47 %%(date fmt=DayOfWeek upper)s
48
49 causes the contents of variable 'date' to be inserted using
50 custom format 'DayOfWeek' and with all lower case letters
51 converted to upper case.
52
53 HTML --
54 This format uses HTML server-side-include syntax with
55 commands for inserting text. Parameters may be included to
56 customize the operation of a command.
57
58 For example:
59
60 <!--#var total fmt=12.2f-->
61
62 is used to insert the variable 'total' with the C format
63 '12.2f'.
64
65 Document templates support conditional and sequence insertion
66
67 Document templates extend python string substitition rules with a
68 mechanism that allows conditional insertion of template text and that
69 allows sequences to be inserted with element-wise insertion of
70 template text.
71
72 Access Control
73
74 Document templates provide a basic level of access control by
75 preventing access to names beginning with an underscore.
76 Additional control may be provided by providing document templates
77 with a 'guarded_getattr' and 'guarded_getitem' method. This would
78 typically be done by subclassing one or more of the DocumentTemplate
79 classes.
80
81 If provided, the the 'guarded_getattr' method will be called when
82 objects are accessed as instance attributes or when they are
83 accessed through keyed access in an expression.
84
85 Document Templates may be created 4 ways:
86
87 DocumentTemplate.String -- Creates a document templated from a
88 string using an extended form of python string formatting.
89
90 DocumentTemplate.File -- Creates a document templated bound to a
91 named file using an extended form of python string formatting.
92 If the object is pickled, the file name, rather than the file
93 contents is pickled. When the object is unpickled, then the
94 file will be re-read to obtain the string. Note that the file
95 will not be read until the document template is used the first
96 time.
97
98 DocumentTemplate.HTML -- Creates a document templated from a
99 string using HTML server-side-include rather than
100 python-format-string syntax.
101
102 DocumentTemplate.HTMLFile -- Creates an HTML document template
103 from a named file.
104
105 '''
106
107
108 __version__='$Revision: 1069 $'[11:-2]
109
110 ParseError='Document Template Parse Error'
111
112 from DT_String import String, File
113 from DT_HTML import HTML, HTMLFile, HTMLDefault
114
115 from DT_Util import html_quote
116