docs/userguide/ch6_tables.py
author jonas
Fri, 12 Jun 2009 17:11:10 +0000
changeset 3173 ded6e2bbf425
parent 3090 09b11ad17a4d
child 3326 ce725978d11c
permissions -rw-r--r--
More documentation for SimpleIndex.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     1
#Copyright ReportLab Europe Ltd. 2000-2004
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     2
#see license.txt for license details
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     3
#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/ch6_tables.py
2966
c9df63ccabdf reportlab-2.2: major changes to make tests run
rgbecker
parents: 2963
diff changeset
     4
from tools.docco.rl_doc_utils import *
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     5
from reportlab.platypus import Image
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     6
import reportlab
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     7
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     8
heading1("Tables and TableStyles")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     9
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    10
The $Table$  and $LongTable$ classes derive from the $Flowable$ class and are intended
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    11
as a simple textual gridding mechanisms. The $longTable$ class uses a greedy algorithm
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    12
when calculating column widths and is intended for long tables where speed counts.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    13
$Table$ cells can hold anything which can be converted to
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    14
a <b>Python</b> $string$ or $Flowables$ (or lists of $Flowables$).
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    15
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    16
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    17
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    18
Our present tables are a trade-off between efficient drawing and specification
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    19
and functionality.  We assume the reader has some familiarity with HTML tables.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    20
In brief, they have the following characteristics:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    21
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    22
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    23
bullet("""They can contain anything convertible to a string; flowable
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    24
objects such as other tables; or entire sub-stories""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    25
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    26
bullet("""They can work out the row heights to fit the data if you don't supply
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    27
the row height.  (They can also work out the widths, but generally it is better
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    28
for a designer to set the width manually, and it draws faster).""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    29
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    30
bullet("""They can split across pages if needed (see the canSplit attribute).
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    31
You can specify that a number of rows at the top and bottom should be
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    32
repeated after the split (e.g. show the headers again on page 2,3,4...)""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    33
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    34
bullet("""They have a simple and powerful notation for specifying shading and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    35
gridlines which works well with financial or database tables, where you
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    36
don't know the number of rows up front.  You can easily say 'make the last row
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    37
bold and put a line above it'""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    38
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    39
bullet("""The style and data are separated, so you can declare a handful of table
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    40
styles and use them for a family of reports.  Styes can also 'inherit', as with
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    41
paragraphs.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    42
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    43
disc("""There is however one main limitation compared to an HTML table.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    44
They define a simple rectangular grid.  There is no simple row or column
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    45
spanning; if you need to span cells, you must nest tables inside table cells instead or use a more
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    46
complex scheme in which the lead cell of a span contains the actual contents.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    47
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    48
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    49
$Tables$ are created by passing the constructor an optional sequence of column widths,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    50
an optional sequence of row heights, and the data in row order.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    51
Drawing of the table can be controlled by using a $TableStyle$ instance. This allows control of the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    52
color and weight of the lines (if any), and the font, alignment and padding of the text.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    53
A primitive automatic row height and or column width calculation mechanism is provided for.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    54
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    55
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    56
heading2('$Table$ User Methods')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    57
disc("""These are the main methods which are of interest to the client programmer.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    58
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    59
heading4("""$Table(data, colWidths=None, rowHeights=None, style=None, splitByRow=1,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    60
repeatRows=0, repeatCols=0)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    61
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    62
disc("""The $data$ argument is a sequence of sequences of cell values each of which
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    63
should be convertible to a string value using the $str$ function or should be a Flowable instance (such as a $Paragraph$) or a list (or tuple) of such instances.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    64
If a cell value is a $Flowable$ or list of $Flowables$ these must either have a determined width
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    65
or the containing column must have a fixed width.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    66
The first row of cell values
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    67
is in $data[0]$ i.e. the values are in row order. The $i$, $j$<sup>th.</sup> cell value is in
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    68
$data[i][j]$. Newline characters $'\\n'$ in cell values are treated as line split characters and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    69
are used at <i>draw</i> time to format the cell into lines.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    70
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    71
disc("""The other arguments are fairly obvious, the $colWidths$ argument is a sequence
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    72
of numbers or possibly $None$, representing the widths of the columns. The number of elements
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    73
in $colWidths$ determines the number of columns in the table.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    74
A value of $None$ means that the corresponding column width should be calculated automatically.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    75
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    76
disc("""The $rowHeights$ argument is a sequence
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    77
of numbers or possibly $None$, representing the heights of the rows. The number of elements
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    78
in $rowHeights$ determines the number of rows in the table.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    79
A value of $None$ means that the corresponding row height should be calculated automatically.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    80
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    81
disc("""The $style$ argument can be an initial style for the table.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    82
disc("""The $splitByRow$ argument is only needed for tables both too tall and too wide
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    83
to fit in the current context.  In this case you must decide whether to 'tile'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    84
down and across, or across and then down.  This parameter is a Boolean indicating that the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    85
$Table$ should split itself
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    86
by row before attempting to split itself by column when too little space is available in
3044
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    87
the current drawing area and the caller wants the $Table$ to split.
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    88
Splitting a $Table$ by column is currently not implemented, so setting $splitByRow$ to $False$ will result in a $NotImplementedError$.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    89
3044
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    90
disc("""The $repeatRows$ argument specifies the number of leading rows
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    91
that should be repeated when the $Table$ is asked to split itself. The $repeatCols$ argument is currently ignored as a $Table$ cannot be split by column.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    92
heading4('$Table.setStyle(tblStyle)$')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    93
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    94
This method applies a particular instance of class $TableStyle$ (discussed below)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    95
to the $Table$ instance. This is the only way to get $tables$ to appear
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    96
in a nicely formatted way.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    97
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    98
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    99
Successive uses of the $setStyle$ method apply the styles in an additive fashion.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   100
That is, later applications override earlier ones where they overlap.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   101
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   102
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   103
heading2('$TableStyle$')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   104
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   105
This class is created by passing it a sequence of <i>commands</i>, each command
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   106
is a tuple identified by its first element which is a string; the remaining
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   107
elements of the command tuple represent the start and stop cell coordinates
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   108
of the command and possibly thickness and colors, etc.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   109
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   110
heading2("$TableStyle$ User Methods")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   111
heading3("$TableStyle(commandSequence)$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   112
disc("""The creation method initializes the $TableStyle$ with the argument
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   113
command sequence as an example:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   114
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   115
    LIST_STYLE = TableStyle(
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   116
        [('LINEABOVE', (0,0), (-1,0), 2, colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   117
        ('LINEABOVE', (0,1), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   118
        ('LINEBELOW', (0,-1), (-1,-1), 2, colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   119
        ('ALIGN', (1,1), (-1,-1), 'RIGHT')]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   120
        )
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   121
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   122
heading3("$TableStyle.add(commandSequence)$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   123
disc("""This method allows you to add commands to an existing
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   124
$TableStyle$, i.e. you can build up $TableStyles$ in multiple statements.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   125
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   126
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   127
    LIST_STYLE.add('BACKGROUND', (0,0), (-1,0), colors.Color(0,0.7,0.7))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   128
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   129
heading3("$TableStyle.getCommands()$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   130
disc("""This method returns the sequence of commands of the instance.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   131
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   132
    cmds = LIST_STYLE.getCommands()
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   133
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   134
heading2("$TableStyle$ Commands")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   135
disc("""The commands passed to $TableStyles$ come in three main groups
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   136
which affect the table background, draw lines, or set cell styles.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   137
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   138
disc("""The first element of each command is its identifier,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   139
the second and third arguments determine the cell coordinates of
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   140
the box of cells which are affected with negative coordinates
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   141
counting backwards from the limit values as in <b>Python</b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   142
indexing. The coordinates are given as
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   143
(column, row) which follows the spreadsheet 'A1' model, but not
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   144
the more natural (for mathematicians) 'RC' ordering.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   145
The top left cell is (0, 0) the bottom right is (-1, -1). Depending on
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   146
the command various extra (???) occur at indices beginning at 3 on.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   147
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   148
heading3("""$TableStyle$ Cell Formatting Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   149
disc("""The cell formatting commands all begin with an identifier, followed by
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   150
the start and stop cell definitions and the perhaps other arguments.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   151
the cell formatting commands are:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   152
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   153
FONT                    - takes fontname, optional fontsize and optional leading.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   154
FONTNAME (or FACE)      - takes fontname.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   155
FONTSIZE (or SIZE)      - takes fontsize in points; leading may get out of sync.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   156
LEADING                 - takes leading in points.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   157
TEXTCOLOR               - takes a color name or (R,G,B) tuple.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   158
ALIGNMENT (or ALIGN)    - takes one of LEFT, RIGHT and CENTRE (or CENTER) or DECIMAL.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   159
LEFTPADDING             - takes an integer, defaults to 6.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   160
RIGHTPADDING            - takes an integer, defaults to 6.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   161
BOTTOMPADDING           - takes an integer, defaults to 3.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   162
TOPPADDING              - takes an integer, defaults to 3.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   163
BACKGROUND              - takes a color.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   164
ROWBACKGROUNDS          - takes a list of colors to be used cyclically.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   165
COLBACKGROUNDS          - takes a list of colors to be used cyclically.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   166
VALIGN                  - takes one of TOP, MIDDLE or the default BOTTOM
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   167
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   168
disc("""This sets the background cell color in the relevant cells.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   169
The following example shows the $BACKGROUND$, and $TEXTCOLOR$ commands in action:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   170
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   171
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   172
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   173
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   174
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   175
t=Table(data)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   176
t.setStyle(TableStyle([('BACKGROUND',(1,1),(-2,-2),colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   177
                        ('TEXTCOLOR',(0,0),(1,-1),colors.red)]))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   178
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   179
disc("""To see the effects of the alignment styles we need  some widths
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   180
and a grid, but it should be easy to see where the styles come from.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   181
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   182
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   183
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   184
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   185
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   186
t=Table(data,5*[0.4*inch], 4*[0.4*inch])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   187
t.setStyle(TableStyle([('ALIGN',(1,1),(-2,-2),'RIGHT'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   188
                        ('TEXTCOLOR',(1,1),(-2,-2),colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   189
                        ('VALIGN',(0,0),(0,-1),'TOP'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   190
                        ('TEXTCOLOR',(0,0),(0,-1),colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   191
                        ('ALIGN',(0,-1),(-1,-1),'CENTER'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   192
                        ('VALIGN',(0,-1),(-1,-1),'MIDDLE'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   193
                        ('TEXTCOLOR',(0,-1),(-1,-1),colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   194
                        ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   195
                        ('BOX', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   196
                        ]))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   197
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   198
heading3("""$TableStyle$ Line Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   199
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   200
    Line commands begin with the identifier, the start and stop cell coordinates
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   201
    and always follow this with the thickness (in points) and color of the desired lines. Colors can be names,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   202
    or they can be specified as a (R, G, B) tuple, where R, G and B are floats and (0, 0, 0) is black. The line
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   203
    command names are: GRID, BOX, OUTLINE, INNERGRID, LINEBELOW, LINEABOVE, LINEBEFORE
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   204
    and LINEAFTER. BOX and OUTLINE are equivalent, and GRID is the equivalent of applying both BOX and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   205
    INNERGRID.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   206
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   207
CPage(4.0)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   208
disc("""We can see some line commands in action with the following example.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   209
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   210
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   211
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   212
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   213
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   214
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   215
t=Table(data,style=[('GRID',(1,1),(-2,-2),1,colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   216
                    ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   217
                    ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   218
                    ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   219
                    ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   220
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   221
disc("""Line commands cause problems for tables when they split; the following example
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   222
shows a table being split in various positions""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   223
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   224
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   225
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   226
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   227
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   228
t=Table(data,style=[
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   229
                ('GRID',(0,0),(-1,-1),0.5,colors.grey),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   230
                ('GRID',(1,1),(-2,-2),1,colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   231
                ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   232
                ('BOX',(0,0),(-1,-1),2,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   233
                ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   234
                ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   235
                ('BACKGROUND', (0, 0), (0, 1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   236
                ('BACKGROUND', (1, 1), (1, 2), colors.lavender),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   237
                ('BACKGROUND', (2, 2), (2, 3), colors.orange),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   238
                ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   239
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   240
t=getStory()[-1]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   241
getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   242
for s in t.split(4*inch,30):
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   243
    getStory().append(s)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   244
    getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   245
getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   246
for s in t.split(4*inch,36):
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   247
    getStory().append(s)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   248
    getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   249
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   250
disc("""When unsplit and split at the first or second row.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   251
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   252
CPage(4.0)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   253
heading3("""Complex Cell Values""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   254
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   255
As mentioned above we can have complicated cell values including $Paragraphs$, $Images$ and other $Flowables$
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   256
or lists of the same. To see this in operation consider the following code and the table it produces.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   257
Note that the $Image$ has a white background which will obscure any background you choose for the cell.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   258
To get better results you should use a transparent background.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   259
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   260
import os, reportlab.platypus
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   261
I = '../images/replogo.gif'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   262
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   263
I = Image('%s')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   264
I.drawHeight = 1.25*inch*I.drawHeight / I.drawWidth
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   265
I.drawWidth = 1.25*inch
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   266
P0 = Paragraph('''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   267
               <b>A pa<font color=red>r</font>a<i>graph</i></b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   268
               <super><font color=yellow>1</font></super>''',
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   269
               styleSheet["BodyText"])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   270
P = Paragraph('''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   271
       <para align=center spaceb=3>The <b>ReportLab Left
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   272
       <font color=red>Logo</font></b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   273
       Image</para>''',
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   274
       styleSheet["BodyText"])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   275
data=  [['A',   'B', 'C',     P0, 'D'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   276
        ['00', '01', '02', [I,P], '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   277
        ['10', '11', '12', [P,I], '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   278
        ['20', '21', '22',  '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   279
        ['30', '31', '32',  '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   280
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   281
t=Table(data,style=[('GRID',(1,1),(-2,-2),1,colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   282
                    ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   283
                    ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   284
                    ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   285
                    ('BACKGROUND', (0, 0), (0, 1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   286
                    ('BACKGROUND', (1, 1), (1, 2), colors.lavender),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   287
                    ('BACKGROUND', (2, 2), (2, 3), colors.orange),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   288
                    ('BOX',(0,0),(-1,-1),2,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   289
                    ('GRID',(0,0),(-1,-1),0.5,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   290
                    ('VALIGN',(3,0),(3,0),'BOTTOM'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   291
                    ('BACKGROUND',(3,0),(3,0),colors.limegreen),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   292
                    ('BACKGROUND',(3,1),(3,1),colors.khaki),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   293
                    ('ALIGN',(3,1),(3,1),'CENTER'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   294
                    ('BACKGROUND',(3,2),(3,2),colors.beige),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   295
                    ('ALIGN',(3,2),(3,2),'LEFT'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   296
                    ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   297
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   298
t._argW[3]=1.5*inch
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   299
"""%I)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   300
heading3("""$TableStyle$ Span Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   301
disc("""Our $Table$ classes support the concept of spanning, but it isn't specified in the same way
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   302
as html. The style specification
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   303
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   304
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   305
SPAN, (sc,sr), (ec,er)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   306
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   307
disc("""indicates that the cells in columns $sc$ - $ec$ and rows $sr$ - $er$ should be combined into a super cell
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   308
with contents determined by the cell $(sc, sr)$. The other cells should be present, but should contain empty strings 
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   309
or you may get unexpected results.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   310
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   311
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   312
data=  [['Top\\nLeft', '', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   313
        ['', '', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   314
        ['20', '21', '22', 'Bottom\\nRight', ''],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   315
        ['30', '31', '32', '', '']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   316
t=Table(data,style=[
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   317
                ('GRID',(0,0),(-1,-1),0.5,colors.grey),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   318
                ('BACKGROUND',(0,0),(1,1),colors.palegreen),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   319
                ('SPAN',(0,0),(1,1)),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   320
                ('BACKGROUND',(-2,-2),(-1,-1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   321
                ('SPAN',(-2,-2),(-1,-1)),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   322
                ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   323
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   324
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   325
disc("""notice that we don't need to be conservative with our $GRID$ command. The spanned cells are not drawn through.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   326
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   327
heading3("""Special $TableStyle$ Indeces""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   328
disc("""In any style command the first row index may be set to one of the special strings
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   329
$'splitlast'$ or $'splitfirst'$ to indicate that the style should be used only for the last row of
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   330
a split table, or the first row of a continuation. This allows splitting tables with nicer effects around the split.""")  
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   331
3090
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   332
heading1("""Programming $Flowables$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   333
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   334
disc("""The following flowables let you conditionally evaluate and execute expressions and statements at wrap time:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   335
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   336
heading2("""$DocAssign(self, var, expr, life='forever')$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   337
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   338
disc("""Assigns a variable of name $var$ to the expression $expr$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   339
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   340
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   341
DocAssign('i',3)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   342
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   343
                
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   344
heading2("""$DocExec(self, stmt, lifetime='forever')$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   345
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   346
disc("""Executes the statement $stmt$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   347
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   348
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   349
DocExec('i-=1')
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   350
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   351
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   352
heading2("""$DocPara(self, expr, format=None, style=None, klass=None, escape=True)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   353
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   354
disc("""Creates a paragraph with the value of expr as text.
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   355
If format is specified it should use %(__expr__)s for string interpolation
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   356
of the expression expr (if any). It may also use %(name)s interpolations
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   357
for other variables in the namespace. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   358
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   359
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   360
DocPara('i',format='The value of i is %(__expr__)d',style=normal)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   361
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   362
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   363
heading2("""$DocAssert(self, cond, format=None)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   364
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   365
disc("""Raises an $AssertionError$ containing the $format$ string if $cond$ evaluates as $False$.""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   366
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   367
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   368
DocAssert(val, 'val is False')
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   369
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   370
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   371
heading2("""$DocIf(self, cond, thenBlock, elseBlock=[])$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   372
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   373
disc("""If $cond$ evaluates as $True$, this flowable is replaced by the $thenBlock$ elsethe $elseBlock$.""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   374
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   375
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   376
DocIf('i>3',Paragraph('The value of i is larger than 3',normal),\\
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   377
        Paragraph('The value of i is not larger than 3',normal))
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   378
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   379
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   380
heading2("""$DocWhile(self, cond, whileBlock)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   381
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   382
disc("""Runs the $whileBlock$ while $cond$ evaluates to $True$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   383
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   384
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   385
DocAssign('i',5)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   386
DocWhile('i',[DocPara('i',format='The value of i is %(__expr__)d',style=normal),DocExec('i-=1')])
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   387
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   388
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   389
disc("""This example produces a set of paragraphs of the form:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   390
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   391
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   392
The value of i is 5
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   393
The value of i is 4
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   394
The value of i is 3
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   395
The value of i is 2
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   396
The value of i is 1
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   397
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   398
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   399
heading1("""Other Useful $Flowables$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   400
heading2("""$Preformatted(text, style, bulletText = None, dedent=0)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   401
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   402
Creates a preformatted paragraph which does no wrapping, line splitting or other manipulations.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   403
No $XML$ style tags are taken account of in the text.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   404
If dedent is non zero $dedent$ common leading
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   405
spaces will be removed from the front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   406
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   407
heading2("""$XPreformatted(text, style, bulletText = None, dedent=0, frags=None)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   408
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   409
This is a non rearranging form of the $Paragraph$ class; $XML$ tags are allowed in
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   410
$text$ and have the same meanings as for the $Paragraph$ class.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   411
As for $Preformatted$, if dedent is non zero $dedent$ common leading
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   412
spaces will be removed from the front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   413
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   414
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   415
from reportlab.lib.styles import getSampleStyleSheet
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   416
stylesheet=getSampleStyleSheet()
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   417
normalStyle = stylesheet['Normal']
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   418
text='''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   419
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   420
   This is a non rearranging form of the <b>Paragraph</b> class;
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   421
   <b><font color=red>XML</font></b> tags are allowed in <i>text</i> and have the same
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   422
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   423
      meanings as for the <b>Paragraph</b> class.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   424
   As for <b>Preformatted</b>, if dedent is non zero <font color=red size=+1>dedent</font>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   425
       common leading spaces will be removed from the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   426
   front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   427
   You can have &amp;amp; style entities as well for &amp; &lt; &gt; and &quot;.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   428
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   429
'''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   430
t=XPreformatted(text,normalStyle,dedent=3)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   431
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   432
heading2("""$Image(filename, width=None, height=None)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   433
disc("""Create a flowable which will contain the image defined by the data in file $filename$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   434
The default <b>PDF</b> image type <i>jpeg</i> is supported and if the <b>PIL</b> extension to <b>Python</b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   435
is installed the other image types can also be handled. If $width$ and or $height$ are specified
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   436
then they determine the dimension of the displayed image in <i>points</i>. If either dimension is
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   437
not specified (or specified as $None$) then the corresponding pixel dimension of the image is assumed
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   438
to be in <i>points</i> and used.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   439
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   440
I=os.path.join(os.path.dirname(reportlab.__file__),'docs','images','lj8100.jpg')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   441
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   442
Image("lj8100.jpg")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   443
""",after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   444
disc("""will display as""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   445
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   446
    getStory().append(Image(I))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   447
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   448
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   449
disc("""whereas""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   450
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   451
im = Image("lj8100.jpg", width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   452
im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   453
""", after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   454
disc('produces')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   455
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   456
    im = Image(I, width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   457
    im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   458
    getStory().append(Image(I, width=2*inch, height=2*inch))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   459
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   460
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   461
heading2("""$Spacer(width, height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   462
disc("""This does exactly as would be expected; it adds a certain amount of space into the story.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   463
At present this only works for vertical space.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   464
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   465
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   466
heading2("""$PageBreak()$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   467
disc("""This $Flowable$ represents a page break. It works by effectively consuming all vertical
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   468
space given to it. This is sufficient for a single $Frame$ document, but would only be a
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   469
frame break for multiple frames so the $BaseDocTemplate$ mechanism
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   470
detects $pageBreaks$ internally and handles them specially.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   471
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   472
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   473
heading2("""$CondPageBreak(height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   474
disc("""This $Flowable$ attempts to force a $Frame$ break if insufficient vertical space remains
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   475
in the current $Frame$. It is thus probably wrongly named and should probably be renamed as
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   476
$CondFrameBreak$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   477
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   478
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   479
heading2("""$KeepTogether(flowables)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   480
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   481
This compound $Flowable$ takes a list of $Flowables$ and attempts to keep them in the same $Frame$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   482
If the total height of the $Flowables$ in the list $flowables$ exceeds the current frame's available
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   483
space then all the space is used and a frame break is forced.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   484
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   485
CPage(1)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   486
heading2("""$TableOfContents()$""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   487
disc("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   488
A table of contents can be generated by using the $TableOfContents$ flowable.
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   489
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   490
The following steps are needed to add a table of contents to your document:
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   491
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   492
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   493
disc("""Create an instance of $TableOfContents$. Override the level styles (optional) and add the object to the story:""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   494
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   495
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   496
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   497
PS = ParagraphStyle
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   498
toc.levelStyles = [
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   499
    PS(fontName='Times-Bold', fontSize=14, name='TOCHeading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   500
            leftIndent=20, firstLineIndent=-20, spaceBefore=5, leading=16),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   501
    PS(fontSize=12, name='TOCHeading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   502
            leftIndent=40, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   503
    PS(fontSize=10, name='TOCHeading3',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   504
            leftIndent=60, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   505
    PS(fontSize=10, name='TOCHeading4',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   506
            leftIndent=100, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   507
]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   508
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   509
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   510
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   511
disc("""Entries to the table of contents can be done either manually by calling
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   512
the $addEntry$ method on the $TableOfContents$ object or automatically by sending
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   513
a $'TOCEntry'$ notification in the $afterFlowable$ method of the $DocTemplate$
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   514
you are using.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   515
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   516
The data to be passed to $notify$ is a list of three or four items countaining
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   517
a level number, the entry text, the page number and an optional destination key
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   518
which the entry should point to.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   519
This list will usually be created in a document template's method
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   520
like afterFlowable(), making notification calls using the notify()
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   521
method with appropriate data like this:
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   522
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   523
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   524
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   525
def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   526
    """Detect Level 1 and 2 headings, build outline,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   527
    and track chapter title."""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   528
    if isinstance(flowable, Paragraph):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   529
        txt = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   530
        if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   531
            # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   532
            self.notify('TOCEntry', (0, txt, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   533
        elif style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   534
            # ...
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   535
            key = 'h2-%s' % self.seq.nextf('heading2')
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   536
            self.canv.bookmarkPage(key)
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   537
            self.notify('TOCEntry', (1, txt, self.page, key))
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   538
        # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   539
''')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   540
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   541
disc("""This way, whenever a paragraph of style $'Heading1'$ or $'Heading2'$ is added to the story, it will appear in the table of contents.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   542
$Heading2$ entries will be clickable because a bookmarked key has been supplied.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   543
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   544
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   545
disc("""Finally you need to use the $multiBuild$ method of the DocTemplate because tables of contents need several passes to be generated:""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   546
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   547
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   548
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   549
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   550
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   551
disc("""Below is a simple but working example of a document with a table of contents:""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   552
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   553
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   554
from reportlab.lib.styles import ParagraphStyle as PS
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   555
from reportlab.platypus import PageBreak
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   556
from reportlab.platypus.paragraph import Paragraph
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   557
from reportlab.platypus.doctemplate import PageTemplate, BaseDocTemplate
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   558
from reportlab.platypus.tableofcontents import TableOfContents
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   559
from reportlab.platypus.frames import Frame
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   560
from reportlab.lib.units import cm
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   561
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   562
class MyDocTemplate(BaseDocTemplate):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   563
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   564
    def __init__(self, filename, **kw):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   565
        self.allowSplitting = 0
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   566
        apply(BaseDocTemplate.__init__, (self, filename), kw)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   567
        template = PageTemplate('normal', [Frame(2.5*cm, 2.5*cm, 15*cm, 25*cm, id='F1')])
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   568
        self.addPageTemplates(template)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   569
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   570
    def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   571
        "Registers TOC entries."
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   572
        if flowable.__class__.__name__ == 'Paragraph':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   573
            text = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   574
            style = flowable.style.name
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   575
            if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   576
                self.notify('TOCEntry', (0, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   577
            if style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   578
                self.notify('TOCEntry', (1, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   579
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   580
h1 = PS(name = 'Heading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   581
       fontSize = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   582
       leading = 16)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   583
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   584
h2 = PS(name = 'Heading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   585
       fontSize = 12,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   586
       leading = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   587
       leftIndent = delta)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   588
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   589
# Build story.
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   590
story = []
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   591
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   592
# For conciseness we use the same styles for headings and TOC entries
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   593
toc.levelStyles = [h1, h2]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   594
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   595
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   596
story.append(Paragraph('First heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   597
story.append(Paragraph('Text in first heading', PS('body')))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   598
story.append(Paragraph('First sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   599
story.append(Paragraph('Text in first sub heading', PS('body')))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   600
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   601
story.append(Paragraph('Second sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   602
story.append(Paragraph('Text in second sub heading', PS('body')))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   603
story.append(Paragraph('Last heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   604
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   605
doc = MyDocTemplate('mintoc.pdf')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   606
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   607
''')
3173
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   608
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   609
CPage(1)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   610
heading2("""$SimpleIndex()$""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   611
disc("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   612
An index can be generated by using the $SimpleIndex$ flowable.
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   613
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   614
The following steps are needed to add an index to your document:
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   615
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   616
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   617
disc("""Use the index tag in paragraphs to index terms:""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   618
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   619
eg('''
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   620
story = []
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   621
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   622
...
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   623
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   624
story.append('The third <index item="word" />word of this paragraph is indexed.')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   625
''')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   626
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   627
disc("""Create an instance of $SimpleIndex$ and add it to the story where you want it to appear:""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   628
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   629
eg('''
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   630
index = SimpleIndex(dot=' . ', headers=headers)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   631
story.append(index)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   632
''')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   633
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   634
disc("""The parameters which you can pass into the SimpleIndex constructor are explained in the reportlab reference. Now, build the document by using the canvas maker returned by SimpleIndex.getCanvasMaker():""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   635
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   636
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   637
doc.build(story, canvasmaker=index.getCanvasMaker())
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   638
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   639
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   640
disc("""To build an index with multiple levels, pass a comma-separated list of items to the item attribute of an index tag:""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   641
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   642
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   643
<index item="terma,termb,termc" />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   644
<index item="terma,termd" />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   645
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   646
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   647
disc("""terma will respresent the top-most level and termc the most specific term. termd and termb will appear in the same level inside terma.""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   648
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   649
disc("""If you need to index a term containing a comma, you will need to escape it by doubling it. To avoid the ambiguity of three consecutive commas (an escaped comma followed by a list separator or a list separator followed by an escaped comma?) introduce a space in the right position. Spaces at the beginning or end of terms will be removed.""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   650
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   651
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   652
<index item="comma(,,), ,, ,...   " />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   653
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   654
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   655
disc("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   656
This indexes the terms "comma (,)", "," and "...".
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   657
""")