RML for Idiots

[Pages:35]RML for Idiots

An easy introduction to

Report Markup Language

ReportLab Europe Ltd. Thornton House Thornton Road Wimbledon London SW19 4NG, UK

RML for Idiots

2019-08-22

1. 1.1. 1.2. 1.3. 1.4. 1.5. 2. 2.1. 2.2.

3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17.

Before You Start

2

Introduction

2

About RML

2

About this document

2

Running the examples

2

Reference Help

2

Using the DTD

2

Essential concepts

4

The structure of a document.

4

Common Conventions in RML

4

Lessons

6

Lesson 1: Hello World : One simple frame on a page 6

Lesson 2: Two frames, text flowing between them.

8

Lesson 3: Adding text in fixed positions

9

Lesson 4: First steps in styling fixed and flowing text 10

Lesson 5: Inserting images

11

Lesson 6: Drawing lines and shapes

13

Lesson 7: Tables

15

Lesson 8: Table Styles - pt. 1: the basics

17

Lesson 9: Table Styles - pt. 2: styling blocks of cells 19

Lesson 10: Table Styles - pt. 3: fixed columns and rows 21

Lesson 11: Controlling the flow

23

Lesson 12: Different pages with different layouts

25

Lesson 13: Putting it all together - "The Daily Planet" 27

Lesson 14: An introduction to dynamic documents.

30

Frequently Asked Questions

33

Page 2

RML for Idiots

2019-08-22

Introduction

About RML

? Report Markup Language is an XML-style language for describing the layout of documents. ? You define and manipulate any aspect of a document, including the content and the styling, by using tags. Many of the tags are similar to HTML. ? The PDF document output is generated from the RML using the python module 'rml2pdf'.

About this document

This document is designed to get you up and running with RML quickly. It demonstrates the basics of laying out simple documents and formatting the contents, with examples throughout. The idea is to show you how to do the stuff you are most likely to want to do, without getting bogged down in complexities; so each example presents a basic concept but doesn't go into too much detail about the niceties - for that, you can use the User Guide and the test documents. Work through this guide from start to finish, and you will cover all the major concepts, and end up with some nice looking pdf output.

Running the examples

You need a text editor and a working ReportLab PLUS setup - if you don't already have this, follow the installation instructions on our website, or ask a Reportlab employee. At the command line, create a directory where you want to keep your code, and cd into it. Cut and paste each example from this document into a text file, save it in the directory you just created, then run it through rml2pdf.pyc like this:

UNIX:

user@computer:~/rml-for-idiots$ python ~/path/to/rml2pdf.pyc example_xx.rml

WINDOWS:

C:\rml-for-idiots> C:\path\to\rml2pdf.pyc example_xx.rml

The result should be a document in the same directory called 'example_xx.pdf'.

The python module rml2pdf.pyc can also be used inside python scripts, like any other module. Import the module, read your RML into a string, and pass it into the 'go' method as follows:

>>> from rlextra.rml2pdf import rml2pdf >>> rml=open('inputfile.rml','r').read() >>> rml2pdf.go(rml,'outputfile.pdf')

A pdf named 'outputfile.pdf' will be created in the current directory.

Reference Help

? Use the rml2pdf-userguide.pdf located in rlextra/rml2pdf/doc to expand on what is presented here. ? Browse the test cases in rlextra/rml2pdf/test/ for a huge range of examples of RML functionality. ? The ultimate reference document for the RML tags is the Document Type Definition; located in 'rlextra/rml2pdf/rml.dtd'. This tells you about all the available RML tags, and their required and optional parameters. See the next section for more details.

Using the DTD

A 'Document Type Definition' is the standard way to define an XML dialect. It formally sets out the building blocks of an XML document, with a list of legal elements and attributes. You can find plenty of information on

Page 3

RML for Idiots

2019-08-22

the web about how to read a DTD - a good place to start is

Every tag available in RML is defined and described in rlextra/rml2pdf/rml.dtd - so if you're unsure about a tag or its parameters, search in this document for the tag name and you will see it's definition. There's more information about how to read the DTD in the FAQ at the end of this document.

Page 4

RML for Idiots

2019-08-22

Essential concepts

The structure of a document.

When designing a document in RML, the main concept to grasp is the difference between the static elements on the page, and 'flowables'.

The component parts that make up a document, ie. text, pictures, or primitives (like lines, rectangles and circles) can be either static or flowable, depending on whereabouts in the RML document they are described.

A static element is fixed into position on a page. You specify the x and y coordinates and the element appears at that position.

With flowables, however, you specify the position of a 'frame', which can be thought of as a box which contains flowable elements. The elements then flow into the frame until that frame is full. Then they start filling up the next frame. So the frames are static elements, but what the frames contain is 'flowable'.

The other main element of a document is the styling: the fonts, line weights and colours, etc..

These three elements are defined in the three main sections of a basic RML document like this:

this section contains the STATIC elements of the document, and the layout of the frames on each page.

this section contains the STYLE information for formatting text and tables.

this section contains the FLOWABLE elements of the document. This is usually where most of the text goes. This content will flow into the frames specified in the section.

As an example of the above concepts, imagine the front page of a newspaper. In terms of RML, the masthead (eg. "The Times") would be a static, fixed element - it's always the same text in the same place. There might be a solid line under the top banner, along with the price and the date, all of which would be fixed position elements. Most of the centre of the page would then be divided into frames containing text in various styles: headlines, subsection headings, and plain text. The text of these stories would 'fill up' each of these frames from top to bottom, in a series of paragraphs. Finally there might be an advert in a fixed position at the bottom of the page.

So, the section would contain details about the masthead and the position of the frames, the section would define the fonts used for headlines and body text, and the actual text of the news would be in the section. The news would flow from top to bottom, left to right, into each frame on the page.

This is a simplified version of the truth, and there are exceptions to all this, but that comes later...

Common Conventions in RML

1. Colours can be specified in three ways in RML: as html-style 'named' colours (eg. "red"); as rgb values (eg. "#004A8D") or as CMYK (eg. "#ff99001f")

2. X & Y co-ordinates generally refer to the bottom left corner of an element.

Page 5

RML for Idiots

2019-08-22

3. Measurements default to points, but can be millimetres(mm), centimetres(cm), or inches(in). They can be mixed and matched as you like eg(x="5" y="10mm" height="2cm" width="1in").

Page 6

RML for Idiots

2019-08-22

Lesson 1: Hello World : One simple frame on a page

Welcome to RML!

This is the "story". This is the part of the RML document where

your text is placed.

It should be enclosed in "para" and "/para" tags to turn it into

paragraphs.

Run the above example as outlined in the section above called 'Running the examples'. Open the output file ('example_01.pdf') and you will see a basic document with some text in the middle of the page. Note the following about the RML:

The section is where the layout is defined. In this case it defines one by giving it an id ("main"), followed by the x and y coordinates of the bottom left corner of the frame, and then its width and height.

All these values are specified in points, which is the default unit of measurement in RML, but you can mix and match mm, cm, inches and points like this: .

This frame is the fixed 'box' into which the text from the section will flow. Remember, coordinates in RML refer to the bottom left corner of the element. However, the text starts flowing from the top of the frame, so if you change the height of the frame, the text will start further up the page.

As it says in the comments, the section is empty. It has to be there because the document won't compile without it.

Page 7

RML for Idiots

2019-08-22

The section contains three paragraphs, each of which is contained inside tags. Note that the whitespace is ignored in the PDF output.

So for a basic bit of text on a page, you define a frame in a position you like, and then the text in the section fills up the frame.

Page 8

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download