==================
RML Page Templates
==================

This package also provides optional support a helper class to use page
templates with RML without using the entire Zope framework. This document will
demonstrate how to use page templates and RML together.

In this example, we will simply iterate through a list of names and display
them in the PDF.

The first step is to create a page template:

  >>> import tempfile
  >>> ptFileName = tempfile.mktemp('.pt')
  >>> open(ptFileName, 'w').write('''\
  ... <?xml version="1.0" encoding="UTF-8" ?>
  ... <!DOCTYPE document SYSTEM "rml.dtd">
  ... <document filename="template.pdf"
  ...     xmlns:tal="http://xml.zope.org/namespaces/tal">
  ...
  ...   <template pageSize="(21cm, 29cm)">
  ...     <pageTemplate id="main">
  ...       <frame id="main" x1="2cm" y1="2cm"
  ...              width="17cm" height="25cm" />
  ...     </pageTemplate>
  ...   </template>
  ...
  ...   <story>
  ...     <para
  ...         tal:repeat="name context/names"
  ...         tal:content="name" />
  ...   </story>
  ...
  ... </document>
  ... ''')

The ``context`` namespace will be created during rendering. I get back to this
later. In th enext step we instantiate the page template:

  >>> from z3c.rml import pagetemplate
  >>> rmlPageTemplate = pagetemplate.RMLPageTemplateFile(ptFileName)

All we have to do now is to render the template. The context of the template
is effectively the keyword arguments dictionary:

  >>> rmlPageTemplate(names=(u'Roy', u'Daniel', u'Julian', u'Stephan'))
  '%PDF-1.4...'

You can uncomment the following line to write out the PDF in the current
working directory:

  #>>> open('pagetemplate-test.pdf', 'w').write(
  #...   rmlPageTemplate(names=(u'Roy', u'Daniel', u'Julian', u'Stephan')))