reportlab/platypus/doctemplate.py
changeset 268 8414113fa500
parent 255 ee9e321e747d
child 272 80107aaffa7e
--- a/reportlab/platypus/doctemplate.py	Tue Jun 13 04:11:49 2000 +0000
+++ b/reportlab/platypus/doctemplate.py	Tue Jun 13 13:03:31 2000 +0000
@@ -31,9 +31,12 @@
 #
 ###############################################################################
 #	$Log: doctemplate.py,v $
+#	Revision 1.15  2000/06/13 13:03:31  aaron_watters
+#	more documentation changes
+#
 #	Revision 1.14  2000/06/01 16:27:56  rgbecker
 #	pageSize is wrong at present
-#
+#	
 #	Revision 1.13  2000/06/01 15:23:06  rgbecker
 #	Platypus re-organisation
 #	
@@ -73,9 +76,29 @@
 #	Revision 1.1  2000/05/12 12:53:33  rgbecker
 #	Initial try at a document template class
 #	
-__version__=''' $Id: doctemplate.py,v 1.14 2000/06/01 16:27:56 rgbecker Exp $ '''
+__version__=''' $Id: doctemplate.py,v 1.15 2000/06/13 13:03:31 aaron_watters Exp $ '''
 __doc__="""
-More complicated Document model
+This module contains the core structure of platypus.
+
+Platypus constructs documents.  Document styles are determined by DocumentTemplates.
+
+Each DocumentTemplate contains one or more PageTemplates which defines the look of the
+pages of the document.
+
+Each PageTemplate has a procedure for drawing the "non-flowing" part of the page
+(for example the header, footer, page number, fixed logo graphic, watermark, etcetera) and
+a set of Frames which enclose the flowing part of the page (for example the paragraphs,
+tables, or non-fixed diagrams of the text).
+
+A document is built when a DocumentTemplate is fed a sequence of Flowables.
+The action of the build consumes the flowables in order and places them onto
+frames on pages as space allows.  When a frame runs out of space the next frame
+of the page is used.  If no frame remains a new page is created.  A new page
+can also be created if a page break is forced.
+
+The special invisible flowable NextPageTemplate can be used to specify
+the page template for the next page (which by default is the one being used
+for the current frame).
 """
 from flowables import *
 from frames import Frame
@@ -87,7 +110,10 @@
 	pass
 
 class ActionFlowable(Flowable):
-	'''This Flowable is never drawn, it can be used for data driven controls'''
+	'''This Flowable is never drawn, it can be used for data driven controls
+	   For example to change a page template (from one column to two, for example)
+	   use NextPageTemplate which creates an ActionFlowable.
+	'''
 	def __init__(self,action=[]):
 		if type(action) not in (ListType, TupleType):
 			action = (action,)
@@ -110,7 +136,7 @@
 				raise NotImplementedError, "Can't handle ActionFlowable(%s)" % action
 			else:
 				raise
-		except:
+		except "bogus":
 			t, v, None = sys.exc_info()
 			raise t, "%s\n   handle_%s args=%s"%(v,action,args)
 
@@ -121,6 +147,7 @@
 PageBegin = ActionFlowable('pageBegin')
 
 class NextPageTemplate(ActionFlowable):
+	"""When you get to the next page, use the template specified (change to two column, for example)  """
 	def __init__(self,pt):
 		ActionFlowable.__init__(self,('nextPageTemplate',pt))
 
@@ -162,6 +189,36 @@
 		story flowables into the frames.
 
 	4)	The document instances can override the base handler routines.
+	
+	Most of the methods for this class are not called directly by the user,
+	but in some advanced usages they may need to be overridden via subclassing.
+	
+	EXCEPTION: doctemplate.build(...) must be called for most reasonable uses
+	since it builds a document using the page template.
+	
+        Each document template builds exactly one document into a file specified
+        by the filename argument on initialization.
+	
+	Possible keyword arguments for the initialization:
+	
+	pageTemplates: A list of templates.  Must be nonempty.  Names
+	  assigned to the templates are used for referring to them so no two used
+	  templates should have the same name.  For example you might want one template
+	  for a title page, one for a section first page, one for a first page of
+	  a chapter and two more for the interior of a chapter on odd and even pages.
+	  If this argument is omitted then at least one pageTemplate should be provided
+	  using the addPageTemplates method before the document is built.
+	showBoundary: (for debugging) if set draw a box around the frame boundaries.
+	leftMargin:
+	rightMargin:
+	topMargin:
+	bottomMargin:  Margin sizes in points (default 1 inch)
+	  These margins may be overridden by the pageTemplates.  They are primarily of interest
+	  for the SimpleDocumentTemplate subclass.
+	allowSplitting:  If set flowables (eg, paragraphs) may be split across frames or pages
+	  (default: 1)
+	title: Internal title for document (does not automatically display on any page)
+	author: Internal author for document (does not automatically display on any page)
 	"""
 	_initArgs = {	'pagesize':DEFAULT_PAGE_SIZE,
 					'pageTemplates':[],
@@ -177,6 +234,7 @@
 	_invalidInitArgs = ()
 
 	def __init__(self, filename, **kw):
+		"""create a document template bound to a filename (see class documentation for keyword arguments)"""
 		self.filename = filename
 
 		for k in self._initArgs.keys():
@@ -205,7 +263,7 @@
 			self.handle_flowable(self._hanging)
 
 	def addPageTemplates(self,pageTemplates):
-		'add one or a sequence of pageTamplates'
+		'add one or a sequence of pageTemplates'
 		if type(pageTemplates) not in (ListType,TupleType):
 			pageTemplates = [pageTemplates]
 		assert filter(lambda x: not isinstance(x,PageTemplate), pageTemplates)==[], "pageTemplates argument error"
@@ -370,7 +428,8 @@
 		del self.frame, self.pageTemplate
 
 	def build(self, flowables):
-		assert filter(lambda x: not isinstance(x,Flowable), flowables)==[], "flowables argument error"
+		"""Build the document from a list of flowables."""
+		#assert filter(lambda x: not isinstance(x,Flowable), flowables)==[], "flowables argument error"
 		self._startBuild()
 
 		while len(flowables):
@@ -380,11 +439,31 @@
 		self._endBuild()
 
 class SimpleDocTemplate(BaseDocTemplate):
+	"""A special case document template that will handle many simple documents.
+	   See documentation for BaseDocTemplate.  No pageTemplates are required 
+	   for this special case.   A page templates are inferred from the
+	   margin information and the onFirstPage, onLaterPages arguments to the build method.
+	   
+	   A document which has all pages with the same look except for the first
+	   page may can be built using this special approach.
+	   """
 	def handle_pageBegin(self):
 		self._handle_pageBegin()
 		self._handle_nextPageTemplate('Later')
 
 	def build(self,flowables,onFirstPage=_doNothing, onLaterPages=_doNothing):
+	        """build the document using the flowables.  Annotate the first page using the onFirstPage
+	           function and later pages using the onLaterPages function.  The onXXX pages should follow
+	           the signature
+	           
+	              def myOnFirstPage(canvas, document):
+	                  # do annotations and modify the document
+	                  ...
+	                  
+	           The functions can do thing like draw logos, page numbers,
+	           footers, etcetera. They can use external variables to vary
+	           the look (for example providing page numbering or section names).
+	        """
 		frameT = Frame(self.leftMargin, self.bottomMargin, self.width, self.height, id='normal')
 		self.addPageTemplates([PageTemplate(id='First',frames=frameT, onPage=onFirstPage),
 						PageTemplate(id='Later',frames=frameT, onPage=onLaterPages)])