<!-- chapterName "More about pages and page structures" -->

<!-- sectionName "More about template and pageTemplate" -->

<para>
We have already seen that the <font face="Courier">&lt;template&gt;</font> has to
appear at the start of an RML document (after the prolog). This section sets out
to explain it more fully.
</para>

<para>
A <font face="Courier">&lt;template&gt;</font> is the section where the layout of a
document is set out - both for the whole document and for individual pages within it.
</para>

<para>
Up to now, we have just been using <font face="Courier">&lt;template&gt;</font> without
any options. But the <font face="Courier">&lt;template&gt;</font> tag has a number of
optional attributes that you can use to set settings for the whole document:
</para>

<para>
<font face="Courier">pageSize</font> sets the size of the page. This takes a pair
of numbers for the width and the height of the page. If you don't give it any
numbers, it defaults to A4 (the international standard page size which differs
from the American standard page size of letter, but is a standard in other places
such as the UK). While this is a sensible default, it's usually best to explicitly
specify a size. Common sizes are (21cm, 29.7cm) or (595, 842) for A4, (8.5in, 11in)
for letter, and (8.5in, 17in) for legal.
</para>
<para>
<font face="Courier">rotation</font> sets the angular orientation of the page.
This is a float or integer number that should be a multiple of 90.
The default value is zero.
</para>

<para>
<font face="Courier">leftMargin</font> and <font face="Courier">rightMargin</font>
set the horizontal margins for the page.
<font face="Courier">topMargin</font> and <font face="Courier">bottomMargin</font>
set the vertical margins for the page.
</para>

<para>
You can also set the title of the document with the <font face="Courier">title</font>
attribute (which defaults to '(untitled)') and the author with the
<font face="Courier">author</font> attribute (which defaults to '(unauthored)').
</para>

<para>
There are also the optional <font face="Courier">showBoundary</font> and
<font face="Courier">allowSplitting</font> attributes, which
can both be set to "0" or "1" (or "true" and "false"). The
<font face="Courier">showBoundary</font> attribute is off by
default, but when it is set to <font face="Courier">true</font>, it shows
a black border around any frames on the page.
</para>

<para>
<font face="Courier">&lt;template&gt;</font> allows you to set options for the
whole document. The <font face="Courier">&lt;pageTemplate&gt;</font> tag
allows you to set options for individual pages. You can have more than one
<font face="Courier">&lt;pageTemplate&gt;</font> inside the template section.
This allows you to have different <font face="Courier">pageTemplate</font>s
for each page that requires a different structure. For example,
the title page of a report could have a number of graphics on it while the
rest of the pages are more text-orientated.
</para>

<para>
Each <font face="Courier">&lt;pageTemplate&gt;</font> tag must have the mandatory
attribute <font face="Courier">id</font>. This gives the
template a name, and allows both rml2pdf and you to refer to it by name.</para>
<para>The &lt;pageTemplate&gt; tag also allows you to override the
<font face="Courier">rotation</font> and <font face="Courier">pageSize</font> set by the
<font face="Courier">&lt;template&gt;</font> tag.
</para>
<para>
As well as these attributes, you can put any number of
<font face="Courier">&lt;pageGraphics&gt;</font>
into a <font face="Courier">&lt;pageTemplate&gt;</font>
(<font face="Courier">&lt;pageGraphics&gt;</font> are the containers for the
<font face="Courier">&lt;drawString&gt;</font> and shape-drawing commands we
saw earlier).
</para>

<para>
In practice, you may have two <font face="Courier">&lt;pageGraphics&gt;</font>
sections inside a <font face="Courier">&lt;pageTemplate&gt;</font>. The way this
is interperted by RML2PDF is that the first one is carried out <i>before</i> the
contents of the story for that page, and the second one is carried out <i>after</i>
the story. This may be of use when you need some elements to overlap others, and
particularly useful when you are using the <font face="Courier">&lt;includePdfPages&gt;</font>
tag. IncludePdfPages places a number of pages imported from another PDF
file into your document, placing them <i>over</i> the content you
already have (including any header and footers you have designed).
This may mean it obscures headers, footers or something else you need
on very page. The way around this is to place your headers and footers
in a second pageGraphics section, which ensures that it will appear
over anything in your story. Provided you have sensibly defined
frames it won't appear over the main content of your page, but it
will appear over the top of your included PDFs allowing you to have
the same look-and-feel for these pages as you do for the rest of your
document. </para>

<para>
(See section 8.8 ("Integrating with PageCatcher: catchForms, doForm and includePdfPages")
for more info on the <font face="Courier">&lt;includePdfPages&gt;</font> tag.)
</para>


<!-- sectionName "Frame and nextFrame" -->

<para>
As well as containing <font face="Courier">&lt;pageGraphics&gt;</font>, each
<font face="Courier">&lt;pageTemplate&gt;</font> can also contain
<font face="Courier">frame</font>s.
These <font face="Courier">frame</font>s can split the page into more than one
region. For each <font face="Courier">frame</font> in a
<font face="Courier">&lt;pageTemplate&gt;</font>, you must supply an
<font face="Courier">id</font>, the X and Y co-ordinates of the bottom
left hand corner, as well as the <font face="Courier">width</font> and
<font face="Courier">height</font> of the frame. You can have
one <font face="Courier">frame</font> in a page, or use two or more to split
it into a multi-column layout.
Frames really come into their own when you use paragraphs and flowables (see the
section on "Advanced text" below).
</para>

<para>
This is how it looks in practice:
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<frame id="main" x1="4in" y1="2in" width="3in" height="7in"/>
]]>
</codesnippet>
<spacer length="15"/>

<para>
(When you are using text in <font face="Courier">&lt;para&gt;&lt;/para&gt;</font> tags,
you can use the <font face="Courier">&lt;nextFrame/&gt;</font> tag to force it
into the next <font face="Courier">frame</font> on the page. Look at the section on "Advanced text"
later in this document for more details on this). An additional attribute
<font face="Courier">overlapAttachedSpace</font> can be set to
<font face="Courier">0</font> or
<font face="Courier">1</font> to force the frame to overlap space that is implicitly attached to
flowables by their styles. See section <b>6.5</b> on styles. The default value for this attribute
is set using the site wide configuration for reportlab (in <font face="Courier">reportlab/rl_config.py</font>).
</para>

<!-- sectionName "condPageBreak: conditional page breaks" -->

<para>
The <font face="Courier">&lt;condPageBreak/&gt;</font> is a "CONDitional Page Break".
To use it, you give it a height in any units that RML can handle. It then compares
this height with the remaining available space on a page. If the space is sufficient,
then the next elements are placed on the current page, but if there is less space
than the height you have given it anything following the
<font face="Courier">&lt;condPageBreak/&gt;</font> tag is continued on the next page.
</para>
<para>
That is what happens on pages with only one <font face="Courier">frame</font>. On pages
that have multiple <font face="Courier">frame</font>s, this tag acts as a conditional
frame break. If the space in the current frame isn't enough, it will break and place
what follows in the next frame rather than on the next page. The tag and its syntax
still remain the same.
</para>
<para>
This tag is particularly useful with large tables, where you want the whole table to be
presented on one page rather than split between two. It can also be used where you have
a collection of images, and you want them all to be on the same page.
</para>
<para>
<font face="Courier">&lt;condPageBreak/&gt;</font> has only one attribute - the mandatory
one of <font face="Courier">height</font>.
</para>
<para style="nospace">
Examples:
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<condPageBreak height="1in"/>
<condPageBreak height="72"/>
]]>
</codesnippet>
<!-- sectionName "storyPlace: out of band flowables" -->
<para>
The <font face="Courier">&lt;storyPlace&gt;</font> container is a "flowable story that's placed".
This allows for dynamically specified frames to be constructed in the story. This tag is like
having an
<font face="Courier">&lt;illustration&gt;</font> &amp;
<font face="Courier">&lt;place&gt;</font> combination although you cannot separate an illustration from
its frame as you can with
<font face="Courier">&lt;storyPlace&gt;</font>.
</para>
<para>
<font face="Courier">&lt;storyPlace&gt;</font> takes 4 required attributes and one optional one.
<font face="Courier">x</font>, and <font face="Courier">y</font> are the x and y
co-ordinates for where you want the flowables placed. <font face="Courier">width</font> and
<font face="Courier">height</font> are the width and height of the flowable. Finally the
<font face="Courier">origin</font> can be one of
<font face="Courier-Bold">page</font>|<font face="Courier-Bold">frame</font>|<font face="Courier-Bold">local</font>.
If not specified <font face="Courier-Bold">local</font> is assumed.
The <font face="Courier">origin</font> attribute specifies where the x and y
attributes are based.
</para>
<para style="nospace">
Examples:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<storyPlace x="0" y="0" width="18cm" height="1cm" origin="page">
    <para>This is right at the bottom of the page</para>
</storyPlace>
<storyPlace x="0" y="0" width="18cm" height="1cm" origin="frame">
    <para>This is right at the bottom of the current frame</para>
</storyPlace>
<storyPlace x="0" y="0" width="18cm" height="1cm" origin="local">
    <para>This is right at the current frame position!</para>
</storyPlace>
]]>
</codesnippet>

<!-- sectionName "pto: Please Turn Over Control" -->
<para>
The
<font face="Courier">&lt;pto&gt;</font>
tag is a flowable container that holds an arbitrary number of other flowables.
The first two may be special
<font face="Courier">&lt;pto_trailer&gt;</font>
or
<font face="Courier">&lt;pto_header&gt;</font>
tags each of which may contain arbitrary flowables. The idea is that the trailer flowables are issued at the bottom of the page
whenever the main container flowables split; the header flowables appear at the top of the next frame.
</para>
<codesnippet language="xml" style="code">
    <![CDATA[
<pto>
    <pto_trailer>
        <para textColor="blue" style="pto">
            See you on next frame
        </para>
    </pto_trailer>
    <pto_header>
        <para textColor="blue" style="pto">
            back from the previous frame
        </para>
    </pto_header>
    <para style="h1">A header</para>
    <para style="bt">
        Many vast star fields in the plane of our Milky Way Galaxy
        are rich in clouds of dust, and gas. First and foremost,
        visible in the above picture are millions of stars, many
        of which are similar to our Sun. Next huge filaments of
        dark interstellar dust run across the image and block the
        light from millions of more stars yet further across our Galaxy.
    </para>
</pto>
]]>
</codesnippet>

<!-- sectionName "keepInFrame fixed space control" -->
<para>
The
<font face="Courier">&lt;keepInFrame&gt;</font>
tag is a flowable container that holds an arbitrary number of other flowables. The intention is that the container
controls the space allocated to the inner flowables. Errors will be caused by attempts to use
<font face="Courier">&lt;nextFrame/&gt;</font> and similar tags inside the
<font face="Courier">&lt;keepInFrame&gt;</font> container.
</para>
<para>
The
<font face="Courier">&lt;keepInFrame&gt;</font>
tag takes several attributes.
<font face="Courier">maxWidth</font>
is the maximum width. If zero then the available width will be used.
<font face="Courier">maxHeight</font>
is the maximum height. If zero then the available height will be used.
<font face="Courier">frame</font> if specified this should be the name or index of the frame in which the
contents should be drawn. The framechange takse place before widths etc are evaluated.
<font face="Courier">mergeSpace</font> if {{code}}1{{endcode}} then adjacent pre and post space for the content elements will be merged.
<font face="Courier">onOverflow</font> this specifies the action to be taken if the contents is too large. Allowed values
are
{{code}}error{{endcode}} ie raise an error,
{{code}}overflow{{endcode}} just scrawl all over the page,
{{code}}shrink{{endcode}} shrink the contents to fit the allowed space,
&amp;
{{code}}overflow{{endcode}} truncate the contents at the borders of the allowed space.
</para>
<para>The example below shows how to cram star fields into a one inch square.</para>
<codesnippet language="xml" style="code">
    <![CDATA[
<keepInFrame maxWidth="72" maxHeight="72">
    <para style="h1">A header</para>
    <para style="bt">
        Many vast star fields in the plane of our Milky Way Galaxy
        are rich in clouds of dust, and gas. First and foremost,
        visible in the above picture are millions of stars, many
        of which are similar to our Sun. Next huge filaments of
        dark interstellar dust run across the image and block the
        light from millions of more stars yet further across our Galaxy.
    </para>
</keepInFrame>
]]>
</codesnippet>
<!-- sectionName "imageAndFlowables tag" -->
<para>
The
<font face="Courier">&lt;imageAndFlowables&gt;</font>
tag allows flowables to flow around an image.
Errors will be caused by attempts to use
<font face="Courier">&lt;nextFrame/&gt;</font> and similar tags inside the
<font face="Courier">&lt;imageAndFlowables&gt;</font> container.
</para>
<para>
The
<font face="Courier">&lt;imageAndFlowables&gt;</font>
tag takes several attributes.
<font face="Courier">imageName</font>
the name of the image file or path.
<font face="Courier">imageWidth</font>
the width of the image; using 0 will cause the pixel size in points to be used.
<font face="Courier">imageHeight</font>
the height of the image; using 0 will cause the pixel size in points to be used.
<font face="Courier">imageMask</font>
a transparency colour or the word "auto"; this only works for image types that support transparency.
<font face="Courier">imageLeftPadding</font>
space to be used on the left of the image.
<font face="Courier">imageRightPadding</font>
space to be used on the right of the image.
<font face="Courier">imageTopPadding</font>
space to be used on the top of the image.
<font face="Courier">imageBottomPadding</font>
space to be used on the bottom of the image.
<font face="Courier">imageSide</font>
which side the image should go on; <i>"left"</i> or <i>"right"</i>.
</para>
<para>Example:</para>
<codesnippet language="xml" style="code">
    <![CDATA[
<imageAndFlowables imageName="../doc/images/replogo.gif"
                   imageWidth="141" imageHeight="90" imageSide="left">
    <para style="h1">Test imageAndFlowables tag with paras</para>
    <para style="style1">
        We should have an image on the <b>right</b>
        side of the paragraphs here.
    </para>
    <para style="style1">
        Summarizing, then, we assume that the fundamental error of regarding
        functional notions as categorial may remedy and, at the same time,
        eliminate the levels of acceptability from fairly high (e.g. (99a)) to
        virtual gibberish (e.g. (98d)).  This suggests that the theory of
        syntactic features developed earlier delimits a descriptive fact.  We
        have already seen that any associated supporting element is not quite
        equivalent to the traditional practice of grammarians.  From C1, it
        follows that the theory of syntactic features developed earlier can be
        defined in such a way as to impose irrelevant intervening contexts in
        selectional rules.  So far, a descriptively adequate grammar is rather
        different from a general convention regarding the forms of the grammar.
    </para>
</imageAndFlowables>
]]>
</codesnippet>


<!-- sectionName "More about stylesheets" -->

<para>
Just like in a word processor, RML allows you to define a stylesheet at the start
of your document, and then apply it to paragraphs later on. This means that you
can define a complicated mixture of settings that you want to apply to paragraphs,
only define it in one place, and refer to it with a simple name at the start of
each paragraph rather than having to type or cut-and-paste large blocks of text over
and over for each paragraph.
</para>

<para>
Each stylesheet starts with the <font face="Courier">&lt;stylesheet&gt;</font> tag.
There may then be an optional initialisation section where aliases can be set
(bounded by the pair of tags <font face="Courier">&lt;initialize&gt;&lt;/initialize&gt;</font>).
After that come a number of <font face="Courier">&lt;paraStyle&gt;</font> tags - each one
defining a style that you want to use for paragraphs. The
<font face="Courier">&lt;paraStyle&gt;</font> tag must have
an attribute <font face="Courier">name</font>, and then may have as many optional
attributes as you want, each one setting one feature of the appearance of a paragraph.
</para>

<para>
Each one of these <font face="Courier">&lt;paraStyle&gt;</font> tags is an empty
element (i.e. it is closed with a "<font face="Courier">/&gt;</font>" rather than a separate closing tag),
but you might want to indent the tag so that each of the options is on a
separate line. This makes it easier to see what each style is defining
(see the example below for how this looks).
</para>

<para>
One attribute for <font face="Courier">&lt;paraStyle&gt;</font> that isn't the same
as those used by <font face="Courier">&lt;para&gt;</font> is the
<font face="Courier">parent</font> attribute. Once you have defined a style using a
<font face="Courier">&lt;paraStyle&gt;</font> tag, you can use those settings as a
basis for other styles. <font face="Courier">parent</font> allows one style to
inherit from another.
</para>

<para>
The other attribute that isn't shared by the <font face="Courier">&lt;para&gt;</font> tag is
<font face="Courier">backColor</font>. As you can probably
guess, this attribute sets a background color for the paragraph it is describing.
</para>

<para style="nospace">
The following optional attributes for <font face="Courier">&lt;paraStyle&gt;</font> are
the same as those for the <font face="Courier">&lt;para&gt;</font> tag - you can find
more description of them in the "Advanced text" section below:
</para>
<para>
<font face="Courier">fontName, fontSize, leading, leftIndent, rightIndent, firstLineIndent,
alignment, spaceBefore, spaceAfter, bulletFontName, bulletFontSize, bulletIndent,
textColor. </font>
</para>

<para>
Here is an example of how the <font face="Courier">&lt;stylesheet&gt;</font> tag might look in use:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<stylesheet>
    <initialize>
        <alias id="style.normal" value="style.Normal"/>
    </initialize>

    <paraStyle name="h1"
               fontName="Courier-Bold"
               fontSize="12"
               spaceBefore="0.5 cm"
               />

    <paraStyle name="style1"
               fontName="Courier"
               fontSize="10"
               />

    <paraStyle name="style2"
               parent="style1"
               leftIndent="1in"
               />

    <paraStyle name="style7"
               parent="style1"
               leading="15"
               leftIndent="1in"
               rightIndent="1in"
               />
</stylesheet>
]]>
</codesnippet>
<spacer length="15"/>

<para>
<font face="Courier">stylesheet</font>s also allow you to define styles for other tags -
you can define styles for <font face="Courier">blockTable</font>s with the
<font face="Courier">&lt;blockTableStyle&gt;</font> tag, or
the various form creation elements (<font face="Courier">checkBox</font>es,
<font face="Courier">letterBox</font>es and <font face="Courier">textBox</font>es)
with the <font face="Courier">boxStyle</font> tag. Refer to the sections on
<font face="Courier">blockTable</font>s and <i>Form Field Tags</i>
later in this document for details on how to use these.
</para>


