Package qm :: Package external :: Package DocumentTemplate :: Module DocumentTemplate
[hide private]
[frames] | no frames]

Source Code for Module qm.external.DocumentTemplate.DocumentTemplate

  1  ############################################################################## 
  2  #  
  3  # Zope Public License (ZPL) Version 1.0 
  4  # ------------------------------------- 
  5  #  
  6  # Copyright (c) Digital Creations.  All rights reserved. 
  7  #  
  8  # This license has been certified as Open Source(tm). 
  9  #  
 10  # Redistribution and use in source and binary forms, with or without 
 11  # modification, are permitted provided that the following conditions are 
 12  # met: 
 13  #  
 14  # 1. Redistributions in source code must retain the above copyright 
 15  #    notice, this list of conditions, and the following disclaimer. 
 16  #  
 17  # 2. Redistributions in binary form must reproduce the above copyright 
 18  #    notice, this list of conditions, and the following disclaimer in 
 19  #    the documentation and/or other materials provided with the 
 20  #    distribution. 
 21  #  
 22  # 3. Digital Creations requests that attribution be given to Zope 
 23  #    in any manner possible. Zope includes a "Powered by Zope" 
 24  #    button that is installed by default. While it is not a license 
 25  #    violation to remove this button, it is requested that the 
 26  #    attribution remain. A significant investment has been put 
 27  #    into Zope, and this effort will continue if the Zope community 
 28  #    continues to grow. This is one way to assure that growth. 
 29  #  
 30  # 4. All advertising materials and documentation mentioning 
 31  #    features derived from or use of this software must display 
 32  #    the following acknowledgement: 
 33  #  
 34  #      "This product includes software developed by Digital Creations 
 35  #      for use in the Z Object Publishing Environment 
 36  #      (http://www.zope.org/)." 
 37  #  
 38  #    In the event that the product being advertised includes an 
 39  #    intact Zope distribution (with copyright and license included) 
 40  #    then this clause is waived. 
 41  #  
 42  # 5. Names associated with Zope or Digital Creations must not be used to 
 43  #    endorse or promote products derived from this software without 
 44  #    prior written permission from Digital Creations. 
 45  #  
 46  # 6. Modified redistributions of any form whatsoever must retain 
 47  #    the following acknowledgment: 
 48  #  
 49  #      "This product includes software developed by Digital Creations 
 50  #      for use in the Z Object Publishing Environment 
 51  #      (http://www.zope.org/)." 
 52  #  
 53  #    Intact (re-)distributions of any official Zope release do not 
 54  #    require an external acknowledgement. 
 55  #  
 56  # 7. Modifications are encouraged but must be packaged separately as 
 57  #    patches to official Zope releases.  Distributions that do not 
 58  #    clearly separate the patches from the original work must be clearly 
 59  #    labeled as unofficial distributions.  Modifications which do not 
 60  #    carry the name Zope may be packaged in any form, as long as they 
 61  #    conform to all of the clauses above. 
 62  #  
 63  #  
 64  # Disclaimer 
 65  #  
 66  #   THIS SOFTWARE IS PROVIDED BY DIGITAL CREATIONS ``AS IS'' AND ANY 
 67  #   EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
 68  #   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
 69  #   PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL DIGITAL CREATIONS OR ITS 
 70  #   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 71  #   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
 72  #   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 
 73  #   USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 
 74  #   ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
 75  #   OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 
 76  #   OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
 77  #   SUCH DAMAGE. 
 78  #  
 79  #  
 80  # This software consists of contributions made by Digital Creations and 
 81  # many individuals on behalf of Digital Creations.  Specific 
 82  # attributions are listed in the accompanying credits file. 
 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  # import DT_UI # Install HTML editing 
204  from DT_Util import html_quote 
205