Home

RML User Guide

1. Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Document generated on 2014 09 25 13 10 59 darkred darksalmon darkseagreen darkslateblue darkslategray darkturquoise darkviolet deeppink deepskyblue dimgray dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray grey same as green greenyellow honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon lightblue Page 109 Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex x8B0000 9967 x8FBC8B x483D8B x2F4F4F x00CFED1 x9400D3 1493 xOOBFFF x696969 xlE90FF xB22222 xFFFAFO x228B22 xFFOOFF xDCDCDC xF8F8FF xFFD700 520 x808080 x808080 x008000 xADFF2F xFOFFFO xFF69B4 xCD5C5C x4B0082 xFFFFFO xFOE68C xFFFOF5 00 xFFFACD xADD8E6 RML User Guide THES os FILE
2. 17 4 1 a dele Maradona dab Tale 17 42 Fill and eter Cuotas iata ae ef S S 20 4 3s Linesand meMod sranna ee ot o Et iacet 21 5 Graphics vs HIG Wal les dieere cueste vete Reis A ua SG aep ded unen 28 6 More about pages and page structures 29 6 1 More about template and 29 6 2 Frame and co pp e me UU eam ud 30 6 3 condPageBreak conditional page 30 6 4 storyPlace out of band 30 6 5 pto Please Turn Over 3l 6 6 keepInFrame fixed space control esiti 3l 6 7 imageAndFlowables tag ROI 32 6 8 More about stylesheets lastiku seek 32 35 A 35 edo Headinge hl h2 h3 a oh 35 7 3 Paragraphs and paragraph 92 36 RML User Guide Document generated on 2014 09 25 13 10 59 7 5 Superscripts and subscripts 36 TOs Pista m sua DP 37 7
3. ee ruam Fh Cuir asas eters rime ram asas FR E Mas ps iri ihn iiai amam baie HBA Mass ee High paan bizh tas mm Mah PAGE LOU inima EEE ren peel BP ce ge pi epi F HSS Cours pola pam kama cnin em kanaman rins bizh i Bir an irure iue HA Pas gh EU Ras ays as iar ids nins be dep binh F ran ae Dan Jue Hs Ua EE Pe pg lah blah blah blah blah uppercase blah blah right justified h blab blah flush right blah blah blah Blah blah blah blah lah blah spot colour blah Em Figure 8 Output from EXAMPLE 5 Page 43 RML User Guide Document generated on 2014 09 25 13 10 59 RML supports all of Adobe s Asian Font Packs You can display text in Japanese Traditional and Simplified Chinese and Korean using two different techniques The most robust technique is to include the standard Asian fonts Adobe specifies for use with Acrobat Reader These will already be installed on the end user s machine if they have a localized copy of Acrobat Reader or may be downloaded in the free Asian Font Packs from Adobe s
4. atemplate m astylesheet astory The template tells rml2pdf what should be on the page headers footers any graphic elements you use as background The stylesheet is where the styles for a document are set This tells the parser what fonts to use for paragraphs and paragraph headers how to format tables and other things of that nature The story is where the meat of the document is Just like in a newspaper the story is the bit you want people to read as opposed to design elements or page markup As such this is where headers paragraphs and the actual text is contained his is the story This is the part a the document where ycar text is placed It should be enclosed in para and para tags 0 indo paragraphs Figure 2 Output from EXAMPLE 2 EXAMPLE 2 IDOCTYPE document SYSTEM rml dtd document filename example 2 pdf template lt pageTemplate id main gt frame id first x1 72 yl 72 width 451 height 698 gt pageTemplate lt template gt lt stylesheet gt lt stylesheet gt lt The story starts below this comment gt Page 13 User Guide Document generated on 2014 09 25 13 10 59 lt story gt lt para gt This is the story This is the part of the RML document where your text is placed lt para gt lt para gt 1 should be enclosed in and tags to turn it into paragraphs lt
5. 10 4 Translations In a graphic operation i e pageGraphic oranillustration translate moves the origin of the drawing translate takes two optional attributes dx and dy Both can be given in any unit that RML understands dx is the distance that the to be moved in the X axis and dy is the distance it is to be moved in the Y axis They are optional to allow you to only give one of the pair so moving the origin in only one direction Examples translate dx 55 dy 91 gt translate dx lin translate dy 6 5cm gt This is what a translation with a dx of 50 anda dy of 50 looks like Page 70 User Guide Document generated on 2014 09 25 13 10 59 50 pt 50 pt Original dx 50 dy 50 Figure 13 An example of the lt translate gt tag in use And this is slightly simplified version of the relevant bit of RML lt illustration gt lt lines gt 6 40 116 40 6 40 16 140 56 40 256 40 56 40 156 140 lt lines gt setFont name Times Roman size 12 gt fill color black drawCentredString x 58 y 12 gt Original lt drawCentredString gt lt setFont name Helvetica Bold size 50 gt lt fill color red gt drawString x 16 y 41 gt X lt drawString gt translate dx 142 setFont name Times Roman size 8 gt fill color lightgray lt drawCentredString x 58 y 18 gt 50 pt lt drawCentredString gt lt setFont name Times Roman
6. The level specifies how deep in the outline the entry appears The default level is 0 closed if set hides any children of this outline entry by default Closed takes Boolean arguments Example lt outlineAdd gt First outline entry lt outlineAdd gt lt outlineAdd level 1 gt sub entry lt outlineAdd gt lt outlineAdd closed true gt Second outline entry 2 lt outlineAdd gt lt outlineAdd level 1 gt sub entry 2 lt outlineAdd gt A note about levels in order to add a level 3 outline entry the previous outline entry must be at least level 2 2 3 4 In other words you can move back any number of levels but you can only move forward one level at a time 8 10 Form field tags An important class of reports contains lots of fields to be traditionally filled in manually by users like for application forms and similar cases Sometimes though these fields are already filled in by some computational process and the user might only need to sign the entire form before leaving it with a bank clerk or sending it off to some destination RML supports creating both kind of reports by providing a set of special purpose tags to create such form elements or fields widgets quite easily These tags are named lt checkBox gt lt textBox gt and lt letterBoxes gt and are described in the rest of this section All these form elements share a lot of features when it comes to what they look like in the document They all appe
7. width 5cm height 3cm round 1 2cm fill true Stroke false xS 1in 2 3in 7 028 21 Ain Page 135 Document generated on 2014 09 25 13 10 59 measurement required measurement required measurement required truth value truth value measurement required measurement required measurement required measurement required measurement truth value truth value measurements required measurements required quadruples of measurements representing line segments User Guide curves lt curves gt lin lin 235 Zim 21 3in lin lin 2in 2in 3in 2in 4in lin 4in lin 2in 4in 2in lin lt curves gt image lt image file cute jpg x lin y Tin width 5cm height 3cm gt place lt place 1 y Tin width 5in height 3in gt lt para gt lt para gt lt illustration gt lt illustration gt lt place gt doForm lt doForm name logo gt 136 Document generated 2014 09 25 13 10 59 string measurement measurement measurement measurement measurement measurement measurement measurement string octtuples of measurements representing Bezier curves required required required required required required required Sequence of top level flowables required RML User Guide includePdfPages lt includePdfPages filename path pages 1 3 6 template
8. The image tag goes in lt pageGraphics gt section at the head of your RML document It has 5 attributes 3 of which are mandatory and two of which are optional The file attribute tells rml2pdf the name of the input file that you want to incorporate into your document the x and attributes give the co ordinates for the bottom left hand corner of where the image will be placed on the page The optional width and height attributes allow you to specify how big it should be on the page this means that you can over ride the normal size of the file and display it at any size that is appropriate The x y width and height attributes can all be gives in points mm cm or inches Be very careful when using the width and height attributes If misused these attributes can lead to you having a distorted ugly and out of proportion picture in your final document Whenever possible you should use a paint application e g Paintshop Pro Photoshop Graphics Converter GIMP to save the file at the correct size and use the correct height and width attributes to the lt image gt tag Using larger files and re sizing inside RML will also lead to the output PDF file being bloated and larger than it needs to be This example shows how these tags look in action lt pageGraphics gt image file myFile gif 72 y 72 gt image file myFile gif x 369 y 72 width 80 height 80 gt image file myFile2 jpg x 72 y 493 gt lt im
9. To set the font that you want a piece of text to be you need to use the lt setFont gt tag This has two arguments which are required you need to give it the name of the font and the size you want it displayed at A setFont tag looks like this To use all the drawString commands you need to use a tag called lt pageGraphics gt This tag appears at the start of a RML document in the pageTemplate section pageGraphics are the graphics that have to do with a whole page rather than just individual illustrations as we will see later pageGraphics can be used to provide a background to a page to place captions or other textual information on a page or to provide logos or other colorful elements Whatever you use them for they are always anchored to a spot on the page they do not wrap or flow with any text you might put into paragraphs Page 17 RML User Guide Document generated on 2014 09 25 13 10 59 4 Basic figures lines and shapes 4 1 Rect circle and ellipse As well as allowing you to place text on the page pageGraphics also allows you to place shapes and graphics on it The basic types of shape that RML allows you to use are rect rectangle circle and ellipse rect needs to have a list of attributes passed to it the co ordinates for the bottom left hand corner its width and height It also has optional 111 and stroke attributes anda round attribute which tell it if the corners should be rounded
10. i s mai 80 IBID PE 80 CHOSE MOUS Sal sa dat EE cesa 80 a onda kaa la a makana a pest d pM 81 IH S ARG Perens 81 83 MOERS qa 83 TNS aha qutuwa q 83 12 9 2 C MEI COL OT Sasa Ne ae he e M Dr uy an E 84 12 4 Images in CMYK Saas bss IAs ERR ROS 85 12 5 Overprint and knockout control dann aaa 85 12 6 s duoi tactics bt u as 86 I2 T PAST OH toc a 87 12 8 87 Part III Tables 98 13 Usim tables u CQ EON SSL 88 I3 Block TAD 88 13 2 Block table attrib te s tte ea esc HO 89 13 3 BoC table Styles d cbr e emo es eed waa em edad etat mbi 90 13 4 More about block tables it 91 13 5 Using block table styles oe eee eT anes 91 Appendix A Colors recognized RMLI 107 Appendix Glossary of terms and abbreviations 112
11. lt para gt lt illustration gt lt illustration gt lt story gt pagelnfo pageInfo pageSize 8 5in llin gt pageDrawing lt pageDrawing gt lt drawString drawString lt place gt lt 1 gt lt pageDrawing gt pageGraphics lt pageGraphics gt lt drawString gt lt drawString gt lt place gt lt place gt lt pageGraphics gt pair of lengths Page 119 optional any number of styles Sequence of top level flowables required Sequence of graphical operations Sequence of graphical operations RML User Guide Document generated on 2014 09 25 13 10 59 Generic Flowables Story Elements Spacer lt spacer length 1 2in gt illustration lt illustration height 1 2in width 5in gt lt drawString gt lt drawString gt lt place gt lt 1 gt lt illustration gt pre lt pre style myfavoritestyle gt Preformatted Text lt pre gt xpre lt xpre style myfavoritestyle gt Paragraph text which may contain lt xpre gt Page 120 measurement required measurement measurement required measurement required Sequence of graphical operations string paragraph style name also string forms getname string paragraph style name intraparagraph markup RML User Guide pluginFlowable plugInFlowable module mymodule function myf
12. lt tr gt lt td gt topPadding lt td gt lt td topPadding 10 gt 10 lt td gt lt tr gt lt tr gt lt td gt topPadding lt td gt lt td topPadding 24 gt 24 lt td gt lt tr gt lt tr gt lt td gt bottomPadding lt td gt lt td bottomPadding 10 gt 10 lt td gt lt tr gt lt tr gt lt td gt bottomPadding lt td gt lt td bottomPadding 24 gt 24 lt td gt lt tr gt lt tr gt lt td gt background lt td gt lt td background pink gt pink lt td gt lt tr gt lt tr gt lt td gt background lt td gt lt td background lightblue gt lightblue lt td gt lt tr gt tr td align td td align left gt left lt td gt lt tr gt lt tr gt lt td gt align lt td gt lt td align center gt center lt td gt lt tr gt Str gt ctd elign lt tde lt td align right e righe bd lt tr gt lt td gt vAlign lt td gt lt td vAlign top gt top lt td gt lt tr gt vAlign td td vAlign middle gt middle lt td gt lt tr gt vAlign td td vAlign bottom gt bottom lt td gt lt tr gt lt blockTable gt produces fontSize fontSize red fontColor fontColor Page 97 RML User Guide leading leftPadding leftPadding rightPadding rightPadding topPadding topPadding bottomPadding bottomPadding background background align align align vAlign vAlign Document generated on 2014 09 25 13 10 59 leading is 16 leading Figu
13. m preppyDictionary ifsetto a dictionary indicates that xm1InputText should be preprocessed using preppy with the preppyDictionary as argument If preppyDictionary is not None and preppyIterations 15 gt 1 then the preppy preprocessing will be repeated preppyIterations times max of 3 with the same dict to generate e g table of contents preppylterations seepreppyDictionary dynamicRml is optional boolean field for whether the RML can be dynamically altered dynamicRmlNameSpace is use with dynamicRml It s a dictionary which you can add variables to for processing a encryption ifsetit must be an encryption object for example rlextra utils pdfencrypt StandardEncryption User Owner canPrint 0 canModify 0 canCopy 0 canAnnotate 0 Page 7 RML User Guide Document generated on 2014 09 25 13 10 59 m SaveRml is useful for debugging dynamically generated RML Specify a filename where the should be saved a parseOnly if set to True will only parse the RML not generate a PDF It is also possible to call rml2pdf from other programming languages such C by using standard methods for calling a python callable See the Python Language Embedding and Extension manuals NB it is also possible to use userPass ownerPass permissions amp encryptionStrength attributes of the document tag to make rml2pdf create an encrypted PDF For further information regarding the installation
14. para textColor blue style pto gt See you on next frame lt para gt lt pto_trailer gt pto header para textColor blue style pto gt back from the previous frame lt para gt lt pto_header gt para style h1 gt A header lt para gt lt para style bt gt Many vast star fields in the plane of our Milky Way Galaxy are rich in clouds of dust and gas First and foremost visible in the above picture are millions of stars many of which are similar to our Sun Next huge filaments of dark interstellar dust run across the image and block the light from millions of more stars yet further across our Galaxy lt para gt lt pto gt 6 6 keepInFrame fixed space control The keepInFrame tag is flowable container that holds an arbitrary number of other flowables The intention is that the container controls the space allocated to the inner flowables Errors will be caused by attempts to use lt nextFrame gt and similar tags inside the lt keepInFrame gt container The keepInFrame tag takes several attributes naxWidth is the maximum width If zero then the available width will be used naxHeight is the maximum height If zero then the available height will be used frame if specified this should be the name or index of the frame in which the contents should be drawn The framechange takse place before widths etc are evaluated mergeSpace if code 1 endcode then adjacent pre and post space for the c
15. 10 5in 10 101 1007510 lt lines gt lt drawCentredString x 6 in y 9 75 in gt width 15 lt drawCentredString gt lt examples for the join attribute to LineMode gt lt lineMode width 5 gt lt lines gt lin Jin Zin 9in fin 9215 1 518 Jo Sanm 8 51m Loin 9 2510 lines fill coler black gt setFont name Helvetica size 9 gt amp drawCentredString x 1 5 in y 6 25 gt width 10 Page 24 User Guide Document generated on 2014 09 25 13 10 59 lt drawCentredString gt lt options for joun are round mitered or bevelled gt lt lineMode width 5 join round gt lt lines gt 2 5in 9 3 5in 9in S Sin 6 518 oan e Sin 9 251m lt lines gt lt drawCentredString x 3 in y 8 25 in gt width 5 join round lt drawCentredString gt lt lineMode width 5 join mitered gt lines 4in Jin 9in 91m 4 51m 8 5 1 5in 8 5 4 5in 9 25 lt lines gt lt drawCentredString x 4 5 in y 8 25 in gt width 5 join mitered lt drawCentredString gt lt lineMode width 5 join bevelled gt lt lines gt 5 5in Gin 6 5in Jin 6 5in Sin 6 51 9 51 9 25in lt lines gt lt drawCentredString x 6 in y 8 25 in gt width 5 join bevelled lt drawCentredString gt lt examples for the attribute to LineMode lt lineMode width 10 gt l
16. 90 gt image file images replogo gif 0 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt 10 104 User Guide Document generated on 2014 09 25 13 10 59 Ta 90 141 90 0 90 0090900 lines illustration td tr lt style paddingTableStyle gt lt b gt blockLeftPadding lt b gt with lt b gt blockTopPadding lt para gt lt td gt lt td gt lt style paddingTableStyle gt just blockTopPadding lt para gt lt td gt lt para style paddingTableStyle gt lt b gt blockRightPadding lt b gt with lt b gt blockTopPadding lt b gt lt para gt lt td gt lt tr gt L q gt lt illustration width 141 height 90 gt lt image file images replogo gif 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt 0 0 1410 121 90 141 900 90 0900 0 lt 1 gt illustration td stds lt illustration width 141 height 90 gt lt image file images replogo gif 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt 141 0 141 90 Tar o0 090 QUOD lines illustratijon td stas lt illustration width 141 height 90 gt Page 105 RML User Guide lt imag
17. Basic HTML is fine You do not have to be employed as a programmer or have extensive programming skills for this guide to make sense We have tried to keep it as simple as possible and to minimise confusion 1 6 Conventions used in this document It is more technically correct to call the various items in RML elements as you do in XML However since we re assuming that more people know basic HTML than XML we ll call them tags rather than elements in this guide There are also a couple of typographical conventions we ll be using constant width Throughout this User Guide well be using a constant width typeface to highlight any literal element of RML such as tag names or attributes for tags when they appear in the text 8 point Courier Page 8 RML User Guide Document generated on 2014 09 25 13 10 59 A smaller constant width font is used for code snippets short one or two line examples of what RML commands look like and code examples longer examples of RML which usually have an illustration of the output they produce Page 9 RML User Guide Document generated on 2014 09 25 13 10 59 Part The Basics 2 Pages and page structures 2 1 XML syntax and RML As with every XML dialect RML requires correct XML syntax If you are familiar with HTML you should pay special attention to the differences between XML syntax and some of the more forgiving constructs allowed in HTML Attribute values must be enclosed in q
18. D8BFD8 RML User Guide Text 123 Text 123 Text 123 OOO Text 123 Text 123 OO Document generated on 2014 09 25 13 10 59 tomato turquoise violet wheat white whitesmoke yellow yellowgreen Page 112 Hex Hex Hex Hex Hex Hex Hex Hex XFF 6347 40 DO OxEES82EE xF5F5F5 00 x9ACD32 RML User Guide Document generated on 2014 09 25 13 10 59 Appendix B Glossary of terms and abbreviations baseline In typography the imaginary line on which characters sit The x height of a font is measured from the baseline to the top of a lowercase x The descender for those characters that have one is defined as the portion of the character that falls below the baseline Bezier curves Named after the French mathematician Pierre Bezier curves utilize at least three points to define curve The endpoints are called the anchor points while any other point is known as a node The curves produced by RML s lt curves gt tag are Bezier curves bitmap A bitmap is a way of storing an image In bitmaps each pixel picture cell is stored as one or more bits of data in a map consisting of rows and columns This means that when you print them out at the size they were created at they look fine but shrinking or enlarging them leads to them looking blocky and ragged JPEG and GIF are both bitmapped
19. So the simplest blockTable in RML will look something like this lt blockTable gt lt td gt This lt td gt lt td gt is lt td gt lt td gt a lt td gt lt td gt blockTable lt td gt lt blockTable gt This produces a table that looks like this This is a blockTable Figure 19 A very simple blockTable In this short example we are just using plain old vanilla text in the table cells But we can do more lt blocktable gt allows you to use paragraphs and the lt para gt tag This means that you can use bold italics colors fonts greek anything you can use in a paragraph And you can use multiple paragraphs inside a table cell This is a more complex This is a more complex blockTable blockTable This more This is amp more complex complex blockTable blockTafle Figure 20 A slightly more complex blockTable The main thing that makes this slightly more complex than a very simple table is the fact that you must give rowHeights colWidths tothe lt blockTable gt to use paras This makes sense paragraphs fit into the available space on a page In a table they must fit into the available space in that cell If you haven t defined how high and wide that cell will be then there is no way for rml2pdf to know how to make it flow in that cell If you get an error message saying Flowables cell can t have auto width then this is the thing to check you have probably omit
20. first 1 72 1 72 width 451 height 698 gt lt pageTemplate gt lt template gt lt stylesheet gt lt stylesheet gt lt story gt lt para gt lt para gt lt story gt lt document gt This example has used the template stylesheet story form of document But the story is empty and we haven t used the stylesheet at all The following example shows how we can use the pageDrawing form EXAMPLE 7b lt xml version 1 0 encoding iso 8859 1 standalone no gt IDOCTYPE document SYSTEM rml dtd lt document filename example_7b pdf gt lt stylesheet gt lt stylesheet gt lt pageDrawing gt fib color red lt stroke color black gt lt path x 247 y 72 fill yes stroke yes close yes gt 247 172 147 172 147 272 247 272 247 372 347 372 347 372 347 272 69 User Guide Document generated on 2014 09 25 13 10 59 447 272 447 172 347 172 lt moveto gt 267 572 lt moveto gt 2 612 lt curvesto gt 147 585 147 687 297 192 447 687 447 585 317 612 lt curvesto gt SY lt path gt lt pageDrawing gt lt document gt 10 3 grids The grid isa graphics tag and hence lives in PageGraphics section of your RML document It produces a grid of lines It takes two arguments xs which is a list of x co ordinates separated by commas and ys which is a comma separated list of y co ordinates Example
21. gt lt pageNumber gt is where is defined lt namedString gt By default RML2PDF endcode will fail in this case also but it is possible to invoke the main processing function code RML2PDF go endcode to allow additional formatting passes For example as in rml2pdf go xmlInputText passLimit 3 to request that the processor execute a maximum of 3 formatting passes before signalling an error if more unresolved names remain WARNING A document that requires two formatting passes will take about twice as long to generate asa document that requires only one For time critical applications it is best to avoid the need for extra formatting passes if they are not needed RML documents that do not have references to names before they are defined will not require more than one formatting pass 9 3 Calculated Page Numbers evalString Some documents require the ability to give relative pagenumbers To meet this requirement code RML2PDF endcode includes the code JevalString endcode tag For example The following code para endcode lt para gt lt font color crimson gt The last page is lt getName id LASTPAGENO default 999 One less than that is evalString default XXXX gt lt getName id LASTPAGENO default 999 1 lt evalString gt The current page is lt pageNumber gt And there are lt evalString default XXXX gt lt getName id LASTPAGENO default
22. lt SUE td Cell LIER lt tr gt lt td gt Cell te lt gt lt td gt Cell Str td Cell qos SUE td Cell lt tr gt lt td gt Cell lt blockTable gt lt story gt lt document gt lWidths 4cm 4cm 4 0 0 lt td gt lt td gt Cell 0 1 lt td gt lt td gt Cell 0 2 lt td gt lt td gt Cell 0 3 lt td gt lt td gt Cell 0 4 lt td gt lt td gt Cell 0 5 lt td gt lt td gt Cell 0 6 td td Cell cm 4cm gt 0 lt td gt lt td gt Cell i lt td gt lt td gt Cell 2 lt td gt lt td gt Cell 3 lt td gt lt td gt Cell 4 lt td gt lt td gt Cell 255 gt lt gt 6 lt td gt lt td gt Cell Page 95 2 2 1 lt td gt lt td gt Cell 2 2 lt td gt lt td gt Cell 2 3 lt td gt lt td gt Cell 2 4 lt td gt lt td gt Cell 2 5 lt td gt lt td gt Cell 2 6 lt td gt lt td gt Cell 0 lt td gt 3 l lt td gt 3 3 lt tq gt 3 5 td Sesto RML User Guide Document generated on 2014 09 25 13 10 59 Example 10 colors and fonts in tables Cell 0 1 Cell 1 1 Cell 2 1 Cell 3 1 Cell 0 2 Cell 1 2 Cell 2 2 Cell 3 2 Cell 0 3 Cell 1 3 Cell 2 3 Cell 0 4 Cell 1 4 Cell 2 4 Cell 3 4 Cell 0 5 Cell 1 5 Cell 2 5 Cell 3 5 Cell 0 6 Cell 1 6 Cell 2 6 Cell 3 6 Figure 21 Output table from EXAMPLE
23. lt pageGraphics gt frame id first 72 1 72 width 451 height 698 gt lt pageTemplate gt lt template gt lt stylesheet gt lt paraStyle name style Title fontName Courier Bold fontSize 24 leading 36 gt lt stylesheet gt lt The story starts below this comment gt story title Example 9 title para This is a page which shows you how illustrations grids and the place tag work para illustration width 90 height 90 gt lt fill color red gt lt circle x 45 y 45 radius 30 fill yes gt lt setFont name Times Roman size 8 gt lt drawString x 0 y 0 gt This is an illustration lt drawString gt lt illustration gt lt para gt The red circle you can see is an lt i gt illustration lt i gt not a lt i gt pageGraphic lt i gt lt para gt lt illustration width 75 height 75 gt lt fill color teal gt lt circle x 30 y 30 radius 30 fill yes gt lt stroke color darkslategray gt grid 15 30 45 ys 5 10 15 20 25 30 35 40 45 50 gt lt illustration gt lt para gt So is the teal colored one lt para gt lt para gt These are all flowables in the story lt para gt lt story gt lt document gt Page 78 RML User Guide Document generated on 2014 09 25 13 10 59 10 13 spacer spacer is another tag which does just what the name suggests A spacer inserts an empty element
24. required required unformatted data required required measurement pairs representing points or path operations RML User Guide lt barCodeFlowable gt figure lt figure gt code Codell value somevalue fontName Helvetica tracking sometracking routing somerouting barStrokeColor blue barFillColor blue textColor plus barStrokeWidth lin 1 rataios IZor5 bearers barHeight lin barWidth lin fontSize 12 spaceWidth lin spaceHeight lin widthSize lin heightSize lin checksum 1 quiet yes lquiet 2 yes rquiet yes humanReadable yes stop yes showBoundary no shrinkToFit no growToFit no scaleFactor somescaleFactor Page 139 Document generated on 2014 09 25 13 10 59 2 1 Code128 Standand Biyr xktended93 Standard39 string required string font name string string string color name string color name string color name measurement measurement string string measurement measurement stringform font size measurement measurement measurement measurement 1101112 yes 0 1 yes 0 1 yes no 0 1 yes no 0 1 yes no 0 1 0 1 0 1 0 1 string RML User Guide imageFigure lt imageFigure imageName someimageName imageWidth lin imageHeight lin imageMask someimageMask preserveAspectRatio yes showBoun
25. string color name measurement measurement measurement measurement float string color name string color name string color name measurement string font name fontsize measurement unformatted data RML User Guide lt textBox style myboxstyle boxWidth lin boxHeight lin labelFontName Helvetica labelFontSize 12 labelTextColor blue labelOffsetX lin labelOffsetY lin boxStrokecColor blue boxFillColor blue textColor blue lineWidth 2 lin fontName Helvetica fontSize 12 align left shrinkToFit false Lapel lebel text gt box contents goes here lt textBox gt Document generated on 2014 09 25 13 10 59 string box style name measurement required measurement required measurement required measurement required string font name fontsize measurement string color name measurement measurement string color name string color name string color name measurement string font name fontsize measurement left right or center Graphical State Change Operations fill fill color blue gt stroke lt stroke color blue gt truth value string unformatted data string name required string name required RML User Guide setFont lt setFont name Helvetica size l1cm gt form lt form name logo gt lt drawString gt lt drawString gt lt place gt lt 1 gt lt form gt catchForms lt
26. 10 Page 96 RML User Guide Document generated on 2014 09 25 13 10 59 1 2 Colors and fonts in table cells As an alternative to specifying cell properties using block table styles RML also allows some cell styles to be specified as attributes of the lt td gt tag lt blockTable colWidths 5cm 5cm style myBlockTableStylel lt tr gt lt td gt fontName lt td gt lt td fontName Courier gt Courier lt td gt lt tr gt lt tr gt lt td gt fontName lt td gt lt td fontName Helvetica gt Helvetica lt td gt lt tr gt lt tr gt lt td gt fontSize lt td gt lt td fontSize 8 gt 8 lt td gt lt tr gt lt tr gt lt td gt fontSize lt td gt lt td fontSize 14 gt 14 lt td gt lt tr gt tr td fontColor td td fontColor red gt red lt td gt lt tr gt tr td fontColor td td fontColor blue gt blue lt td gt lt tr gt lt tr gt lt td gt leading lt td gt lt td leading 16 gt leading is 6 lt td gt lt tex lt tr gt lt td gt leading lt td gt lt td leading 12 gt leadi is 2 lt td gt lt tr gt lt tr gt lt td gt leftPadding lt td gt lt td leftPadding 10 gt 10 lt td gt lt tr gt lt tr gt lt td gt leftPadding lt td gt lt td leftPadding 16 gt 16 lt td gt lt tr gt lt tr gt lt td gt rightPadding lt td gt lt td rightPadding 10 align right gt 10 lt td gt lt tr gt lt tr gt lt td gt rightPadding lt td gt lt td rightPadding 24 align right gt 24 lt td gt lt tr gt
27. 2 Bleed Following on from the above remember that printers often cut the paper to size In addition if they are creating a booklet they sometimes have to allow for the thickness of inner pages so they need a little flexibility in where to make the cut If you have a design with solid colour straight to the edge of the page cutting can sometimes leave a very fine white line where the colour runs out Therefore when a designer wants an area of colour to go straight to the edge they work on a slightly larger page size and allow the colour to overflow or bleed out In general printers often ask for at least 3mm of bleed or about 8 points So if you needed to draw a blue background on an A4 sized page 595x842 points you would be well advised to draw the rectangle from x 10 to x 605 ten points bigger than needed This will be completely invisible to an end user in a document created for the web but when you turn on crop marks and the page is enlarged it will be visible There no features RML to automatically detect areas of colour near the edge of the page and add bleed it s your job to do it This also applies to bitmap images If an image runs to the edge of the page it needs to be sized to very slightly overflow so that it can be cut without risking a white edge 5 _ 12 3 CMYK Colours For professional presses colours need to be specified either as CMYK or as spot colours such as those in t
28. 2014 09 25 13 10 59 string font name string color name fontsize measurement RML User Guide super lt super gt lt super gt strike lt strike gt sup lt sup gt seq lt seq id SecNum template Ch 5 35 s gt seqDefault seqDefault id SecNum gt seqReset lt seqReset id SecNum gt seqChain lt seqChain order id id id id gt Page 128 Document generated on 2014 09 25 13 10 59 string string string string string RML User Guide seqFormat lt seqFormat 1 value format char gt onDraw lt onDraw name somename label somelabel gt br lt br gt bullet lt bullet bulletColor blue bulletFontName bulletFontSize lin bulletIndent lin bulletOffsetY lin gt link lt link destination somedestination color blue gt setLink lt setLink destination somedestination color blue gt Page 129 Document generated on 2014 09 25 13 10 59 string 1lillla A string string string color name string measurement measurement measurement string string color name string string color name RML User Guide unichar lt unichar name somename code somecode gt Page Level Flowables nextFrame lt nextFrame name frameindex gt setNextFrame lt setNextFrame name frameindex gt nextPage lt nextPage gt setNextTem
29. 999 gt lt pageNumber gt lt evalString gt pages to go lt font gt lt para gt Performs arithmetic calculations subtractions using the current page number and a forward reference to the code LASTPAGENO endcode which is presumably defined on the last page In the context of this document the paragraph evaluates to the following The last page is 1 One less than that is 0 The current page is 64 And there are 63 pages to go RML document can make use of arbitrary arithmetic calculations using the code evalString endcode tag but in practice addition endcode and subtraction code endcode over page numbers are the most useful 9 4 Generated RML Although the code namedString getName endcode and code evalString endcode tags can be used to build tables of contents and indices it is not easy to directly edit RML documents that includes cross reference structures of this kind Page 64 RML User Guide Document generated on 2014 09 25 13 10 59 For example to directly add a new section to the this document in RML text it would be necessary to add a new table of contents entry at the top something like this lt para style contents2 gt lt getName id chapterNumber gt lt seq id sectionNumber gt Installation lt para gt As well as the text of the section itself lt condPageBreak height 144 gt lt h2 gt lt getNa
30. API Since any external program with the ability to print can produce PDF files this means that a ReportLab document can include graphical elements created by virtually any program These imported elements can be combined freely with text or graphics drawn directly into the document For example an application can import pages from a government tax form and draw text in the spaces provided to fill in the form The resulting document can then be combined with a cover letter at the beginning and supporting tabular data at the end all in a single PDF document 1 2 Installation and Use To avoid duplication the full installation instructions are always on ReportLab s web site at this address http www reportlab com software installation RML2PDF is a compiled Python programming language module It can be used with options from a command line and also has a programmable API interface and may be used as a component of a larger Python language installation Since Python integrates with a wide variety of other languages it is also possible to access RML2PDF from C and C programs COM and many other environments RML2PDF is delivered as part of ReportLab s rlextra package and licensed under the name ReportLab PLUS This package depends on our reportlab package and some other open source libraries all detailed on the above Page 5 RML User Guide Document generated on 2014 09 25 13 10 59 installation page RML2PDF requires a license ke
31. Blah blah bug report blah blah blah blah blah memory blah blah TeX TCP IP SMTP blah lt para gt lt para style body gt Blah blah blah blah blah Em blah letterform blah blah blah blah blah blah blah blah blah letterform blah blah Blah blah blah blah leader blah blah blah blak para para style body gt para para style body gt Blah dingbat blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah Blah blah blah blah blah drop cap blah blah blah blah blah blah blah para story document Exampin kezrgytstes and page Templates Tih Ri ckama Dus LIT DS LIC LN Tics ba The TIT II m 1 7 10 Asian Fonts Dats binn orci ma ad I Mns Pe Ae Pas wars mars kim KA Mo FRA piss Lg rain Hik bsk ars ty binis iini saman bier tas P biah biar binh mars bisi Pana binh bini an tir
32. This is the case which lt includePdfPages gt tag was designed for Page 52 RML User Guide Document generated on 2014 09 25 13 10 59 lt includePdfPages gt 15 generic flowable which means that it can appear at any point in the story In its simplest form an includePdfPages tag will look like this lt includePdfPages filename mypdffile pdf This will take the PDF file called mypdffile pdf use pageCatcher behind the scenes and include every page in the PDF file in your output There is also an optional pages attribute This can have either individual pages or ranges The following are all valid providing the PDF file is long enough lt includePdfPages filename mypdffile pdf lt includePdfPages filename mypdffile pdf pages 1 gt lt includePdfPages filename mypdffile pdf pages 1 2 3 gt lt includePdfPages filename mypdffile pdf pages 2 1 1 2 2 gt includePdfPages filename mypdffile pdf pages 1 5 gt includePdfPages filename mypdffile pdf pages 1 2 4 5 gt There are a number of differences between this tag and the other PageCatcher related tags Unlike the others includePdfPages doesn t require you to pre pagecatch the file you intend to use so saving you an additional step It also differs in that the imported PDF gets drawn over the top of your exiting document rather than being used as a background underneath your existing page So if you have a header or footer in your page t
33. User Guide M 4 2101019100 O O O 618 4 OV OVVU V 6 4 6 0900 000500 000000005060 123 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Document generated on 2014 09 25 13 10 59 olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray Snow springgreen steelblue tan teal thistle Page 111 Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex x6B8E23 500 xFF4500 x DA70D6 XEEE8AA x98FB98 XAFEEEE X DB7093 xFFEFDS5 xC xFFC X DDA xBOE X 800 xFFO DAB9 D853F ODD 0 6 080 000 4169 1 8 4513 72 xF4A460 x2E8B57 xFFF5EE XA0522D xCOCOCO x87CEEB X6A5DACD x708090 xOOFF7F x4682B4 X X X D2B48C 008080
34. Using two seqs independently We have just done a lt seqReset id testOne gt We have just done lt seqReset id testTwo First seq for testOne 1 Second seq for testOne 2 First seq for testT wo 1 Second seq for testT wo 2 We have just done lt seqReset id testOne gt First seq after seqReset for testOne 1 second seq after seqReset for testOne 2 First seq after seqReset for testTwo 3 second seq after seqReset for testTwo 4 Notice how resetting testOne doesn t affect testT wo at all Figure 9 The output from EXAMPLE 6 One more sophisticated use for using these tags is for multiple page counters If you have a document where you need different sections numbered separately from the main body of a document perhaps for introductory matter such as the contents and preface of a book this can be done with a named seq tag The page counter as used by the pageNumber tag is a unique value which depends on the actual physical number of pages If rather than using a pageNumber tag you instead use something like seq id pageCounter gt you have the ability to use lt seqReset id pageCounter gt in between sections so that each chapter has pages numbered from the start of that chapter rather than the start of the document If you use a different template for each chapter this can then give you page numbers in the format 71 12 rather than just 12 where you are on page 12 of the document which is page 12 of chapt
35. catchForms storageFile storage data gt scale lt scale sx 0 8 3 translate lt translate dx 0 8in aya 1 3in gt rotate lt rotate degrees 45 gt Page 145 Document generated on 2014 09 25 13 10 59 string name measurement string name string name scale factor scale factor measurement measurement angle in degrees required required required Sequence of graphical operations required required required required required required RML User Guide skew lt skew alpha 15 beta 5 gt transform lt transform gt 1 00 3 0 2 1 1 10 1 15 lt transform gt lineMode lt lineMode width 0 2cm dasHe lom ccm join round cap square gt Style Elements initialize lt initialize gt lt alias gt lt name gt lt color gt lt initialize gt paraStyle Page 146 Document generated on 2014 09 25 13 10 59 angle in degrees required angle in degrees required six number affine transformation matrix measurement measurements round mitered or bevelled default round or square sequence of alias name or color tags RML User Guide lt paraStyle gt boxStyle lt boxStyle gt name mystyle alias pretty parent oldstyle fontname Courier Oblique fontsize 13 leading 20 leftIndent 1 25in rightIndent 2 5in firstLineIndent 0 5in spaceBefore 0 2in spa
36. drawCentredString lt options for dash are sequences of numbers gt lineMode width 2 dash 5 5 gt lt lines gt 2 5in 4 5 3 5 4 5 3 5in 4 5in 4in din 4751 lt lines gt lt drawCentredString x 3 in y 3 75 in gt width 2 dash 5 5 drawCentredString lt lineMode width 2 dash 2 10 gt lt lines gt 4in 4 5in 5in 4 5in 4 5 4 5 Ain 4 5in 4in 4 5 4 75in lt lines gt lt drawCentredString x 4 5 in y 3 75 in gt width 2 dash 2 10 lt drawCentredString gt lt lineMode width 2 dash 5 5 2 10 gt lt lines gt 5 5in 4 5 6 5 4 5 6 5in 4 5 4in 6in 4in 4 75in lt lines gt lt drawCentredString x 6 in y 3 75 in gt width 2 dash 5 5 2 10 lt drawCentredString gt lt pageGraphics gt frame id first 1 72 1 72 width 451 height 698 gt lt pageTemplate gt lt template gt lt stylesheet gt lt stylesheet gt lt story gt lt para gt lt para gt lt story gt Page 27 User Guide Document generated on 2014 09 25 13 10 59 Lines in RML 18 and peed Figure 7 Output from EXAMPLE 4 Page 28 RML User Guide Document generated on 2014 09 25 13 10 59 5 Graphics vs Flowables Both the basic graphical figures and the basic text operations we have seen so far share some properties All of them require you to specifically position them a
37. forms annual reports and so on Extracting the required pages with PageCatcher will most Page 51 RML User Guide Document generated on 2014 09 25 13 10 59 often be a one off design time step Once PageCatcher has extracted a page it archives it in a data file as formatted form data The default name for this file is storage data If you have full production versions of both RML2PDF and PageCatcher you can use the lt catchForms gt tag to import all forms from a PageCatcher storage file for use in your RML document Example This example takes the form called PFO a page caught by PageCatcher and stored in the file storage data and draws it into your document as a page backdrop lt pageDrawing gt lt catchForms storageFile storage data gt lt doForm name PF0 lt pageDrawing gt The lt catchForms gt tag is a drawing operation and can occur anywhere in your RML document where a lt doForm gt tag occur For example you can use a lt catchForms gt inside the flow of a story by using it inside an lt illustration gt The lt catchForms gt tag has one mandatory argument storageFile which gives the name of the PageCatcher storage file to extract the form from One small point to remember is that if you are using multiple forms from the same data file you only need to use the actual lt catchForms gt tag once To actually put the captured data into your document you would use multiple instances
38. graphics formats as are BMP PICT and PNG You can use gifs and jpegs in your RML document with the lt image gt tag see also gif JPEG image Boolean Named after the nineteenth century mathematician George Boole Boolean logic is a form of algebra in which all values are reduced to either TRUE or FALSE or 0 and 1 CMYK A way of specifying a color by its Cyan Magenta Yellow and Black Key components Usually used when referring to pigments such as in printing DTD Document Type Definition A term from XML that refers to the file that defines the legal building blocks of an XML document and the permissible ways to structure it empty elements Empty elements are those tags that don t have any content and are closed with a gt at the end of the same tag rather than having a separate closing tag e g getName id Header Title gt doesn t havea separate lt getName gt tag the gt serves to close it so it doesn t need one Empty elements are also sometimes known as singletons fill In RML the color that a graphic or text item is filled with as opposed to that of its outline or st roke flowables In RML flowables are items which appear in a story such as paragraph spacer and tables Flowables are positioned in sequence running down a frame until there is no more room left in that frame when they are placed in the next frame or on the next page if necessary They can not be mixed with g
39. gt lt h3 gt tags in the same way 7 3 Paragraphs and paragraph styles As well as explicitly placing a piece of text into a certain position on a page using the drawSt ring commands RML also allows you to use paragraphs of text Paragraphs are flowables This means that you don t need to tell RML exactly where every line is going to go on the page you let rml2pdf worry about that To do this you place your text inside the story section of an RML document and use the para and para tags to tell the parser where each paragraph starts and ends As well as delineating where paragraphs begin and end the para tag can also have a number of optional attributes style If you have set up a style in the stylesheet section of a document you can refer to them by name by using the style attribute For example if you have defined a style called Norma you can have your paragraph appear in that style by using para style Normal alignment How the text is aligned within the paragraph It can be LEFT RIGHT CENTER or CENTRE or JUSTIFY fontName fontSize Page 36 RML User Guide Document generated on 2014 09 25 13 10 59 fontName and fontSize set name and size of the font that you want this paragraph displayed in This can often be better done using lt paraStyle gt tag inside stylesheet and then using the style tag to apply it to that paragraph Example para fontName Hel
40. how you can use more that one attribute to lt 11 gt at same time EXAMPLE 4 lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM rzml dtd lt document filename example_4 pdf gt lt template gt lt pageTemplate id main gt lt pageGraphics gt Page User Guide Document generated on 2014 09 25 13 10 59 lt il lt setFont name Helvetica size 24 gt lt drawCentredString x 297 5 y 800 gt Lines in RML lt drawCentredString gt lt notice that each of these empty tags are teminated lt 1 with a slash gt lt lineMode width 1 gt slines lim 10 5in Zin 10 5in Zin 10 5in 1 5in TOTR l0in 1 51m Sar lt lines gt fill coloer black gt lt setFont name Helvetica size 9 gt amp drawCentredString x 1 5 in y 9 75 gt width 1 lt drawCentredString gt lt lineMode width 5 gt lt lines gt 2 5in 10 5 3 5in 3 5 10 811 1010 Oam lt lines gt lt drawCentredString x 3 in y 9 75 in gt width 5 lt drawCentredString gt lt lineMode width 10 gt lt lines gt 4in 10 5in 10 5in 10 5in 4 5in 10in 4 5in 1041 4 5in 10 75im lt lines gt lt drawCentredString x 4 5 in y 9 75 in gt width 10 lt drawCentredString gt lt lineMode width 15 gt lt lines gt 5 5in 10 5 6 5 10 5in 51
41. in this tutorial can be found as rml files in the same directory as this tutorial Hello World Figure 1 Output from EXAMPLE 1 Page 12 User Guide Document generated on 2014 09 25 13 10 59 This is the most basic RML document you can get It is the traditional Hello World All it does is place the string of text Hello World into the middle of your A4 page Not very useful in the real world but enough to show you how simple RML can be Notice how it does have a stylesheet but it is empty Stylesheets are mandatory but they don t need to actually contain anything Also notice how in the drawCenteredString tag the co ordinates are enclosed in quotation marks they are attributes and so need to live inside quotes And if you look at the drawCenteredString tag these attributes are inside the tag actually inside the angle brackets then the content of the string comes after it then the tag is closed by its matching lt drawCenteredString gt tag All tags with content need their matching closing tag document and lt stylesheet gt tags are also parts of matching pairs One last thing to notice is the DOCTYPE line for all these examples we are assuming that the DTD is in the same directory as the example file itself This may not always be the case For a more complex RML document you can use the more powerful template stylesheet story form of document In this a file contains the following three sections
42. into the page to force other elements downwards or sideways The spacer tag has two attributes length is mandatory and refers to the length down the page and width is optional Example To produce a spacer 15 points in height and one inch wide you could do the following 10 14 Form and doForm form isa group of graphical operations stored together and given a name This allows you to group complex graphics together and to re use them in more than one place with ease To do this you would use the doForm tag Your form would appear in the pageGraphics section of your RML document inside the pageTemplate lt doForm gt also appears in pageGraphics section The form tag has one attribute a mandatory one called name which identifies the form The lt doForm gt tag executes the sequence of graphical operations defined with a lt form gt tag It also has only one mandatory attribute called name Example lt pageGraphics gt lt form name myForm gt lt drawString x 0 y 24 gt Your graphic operations would go here lt drawString gt lt drawString x 0 12 gt There would probably be a lot of them to make up something useful lt drawString gt lt form gt lt doForm name myForm gt lt pageGraphics gt 10 15 Why use forms Why use forms when you can just cut and paste big chunks of text inside your RML document with your favorite text editor or word processor The benefi
43. it any numbers it defaults to A4 the international standard page size which differs from the American standard page size of letter but is a standard in other places such as the UK While this is a sensible default it s usually best to explicitly specify a size Common sizes are 21cm 29 7cm or 595 842 for A4 8 5in 11in for letter and 8 5in 17in for legal rotation sets angular orientation of the page This is a float or integer number that should be multiple of 90 The default value is zero leftMargin rightMargin set the horizontal margins for the page topMargin and bottomMargin setthe vertical margins for the page You can also set the title of the document with the title attribute which defaults to untitled and the author with the author attribute which defaults to unauthored There are also the optional showBoundary andallowSplitting attributes which can both be set to 0 or 1 or true and false The showBoundary attribute is off by default but when it is set to true it shows a black border around any frames on the page template allows you to set options for the whole document The lt pageTemplate gt tag allows you to set options for individual pages You can have more than one pageTemplate inside the template section This allows you to have different pageTemplates for each page that requires a different structure For example the title page of a report could have a number o
44. letterBox or checkBox boxStrokeColor An optional tag specifying the colour to be used for the lines making up a textBox letterBox or checkBox cellWidth An optional tag specifying the width of a cell in a form element Must be a measurment but may in cm mm or pt see the section on Coordinates measurements for more details on measurements cellHeight An optional tag specifying the width of a cell in a form element Must be a measurment but may in mm or pt Some Examples As an example of them in use let s set up two boxStyles and see what effect they have on letterBoxes textBoxes and a checkBox Firstly the boxStyles boxStyle name speciall labelFontName Helvetica fontSize 10 alignment RIGHT textColor regd fontName Helvetica labelFontSize 10 labelAlignment RIGHT labelTextColor blue boxStrokeColor red boxFillColor pink gt lt boxStyle name special2 parent speciall fontName Courier Page 60 RML User Guide Document generated on 2014 09 25 13 10 59 fontSize 12 textColor green labelFontName Courier labelFontSize 12 labelTextColor green boxFillColor yellow boxStrokeColor red gt With the style special 1 style special1 style special1 F And with style special2 style special2 style special2 Barcodes One other tag that may often find use on f
45. name outlineText text outlineLevel 1 outlineClose 0 leadingFrame no isdata yes orientation auto Bast 9 sy 0 9 ax 2in dy 2in degrees 45 gt textField lt textField id name value initial 34 500 width 72 height 12 maxlen 1200 Multi line 0 1 gt lt textField gt textAnnotation lt textAnnotation gt lt textAnnotation gt Page 137 Document generated on 2014 09 25 13 10 59 string string string string int int bool bool string float float measurement measurement angle in degrees name of field field initial value x coord y coord width height maximum chars 1 for multiline text required path to included file optional separated page list optional pagetemplate name optional text for outline entry optional outline level default 0 optional 0 for closed outline entry optional no if you don t want a pa optional true if filename is a optional 0 90 180 270 auto lands required optional RML User Guide pluginGraphic plugInGraphic module mymodule function myfunction gt string data for plug in plugInGraphic path path Tin Glose rtrue fill true stroke false gt lin 6in lin Vin lt path gt barCodeFlowable Page 138 Document generated on 2014 09 25 13 10 59 string string measurement measurement truth value truth value truth value
46. no gt This line is the XML declaration This is optional but recommended version 1 0 This attribute tells the parser which version of XML it should use in this case 1 0 standalone no This tells the parser that it needs an external Document Type Definition more on DTDs below encoding iso 8859 1 The encoding attribute sets the encoding you want the PDF file to use The ISO 8859 1 encoding covers the character set known as US ASCII plus things like the accented characters used in most Western European Languages and some control characters and graphical characters ISO 8859 1 is also known as Latin 1 or Latin Alphabet No 1 Other common encodings are ut 8 same as US ASCII for normal characters like A Z and 0 9 but also covers the whole Unicode character set and cp1252 a Microsoft Windows variant of ISO 8859 1 You may use any encoding you wish with RML as long as the encoding attribute here matches the encoding you actually used to write the RML file Page 10 RML User Guide Document generated on 2014 09 25 13 10 59 lt DOCTYPE rml dtd gt This line tells the parser where the Document Type Definition is located The DTD formally specifies the syntax of RML For documents written in RML the DTD should always be the current version of rml dtd The rml DTD should always be called rml dtd Unlike other dialects of XML RML does not allow you to provide relative paths to the DTD nor a full URL I
47. of how a lt path gt looks in action Page 67 User Guide Document generated on 2014 09 25 13 10 59 The stroke isn t completed here since used Figure 12 The output from EXAMPLE 7 EXAMPLE 7a lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM rml dtd document filename example 7a pdf template lt pageTemplate id main gt lt pageGraphics gt lt fill color red gt lt stroke color black gt lt path x 247 y 72 fill yes stroke yes close yes gt 247 172 147 172 14971272 241 212 247 372 SNC 212 447 272 447 172 347 172 347 72 lt This completes the first shape red 8 2 moveto 267 572 moveto lt This moves the pen position Page 68 User Guide Document generated on 2014 09 25 13 10 59 lt Notice that because we have used a moveto the lt final line at the base of the cross is not completed even gt lt 1 though the close attribute of the path set to gt lt 277 612 lt this acts the start point for the Bezier curves below lt curvesto gt 147 585 147 687 207 TOS 447 687 447 585 317 612 lt curvesto gt lt We don t need to give the last point because close is gt lt 1 set to ves lt path gt lt pageGraphics gt frame id
48. of the lt doForm gt tag Notice how this works in the example below lt illustration width 451 height 698 gt lt pageGraphics gt lt catchForms storageFile samples data gt doForm gt lt pageGraphics gt lt illustration gt lt illustration width 451 height 698 gt lt pageGraphics gt lt doForm name PF1 gt lt pageGraphics gt illustration If you do use repeated cat chForms tags to point at the same data file you will get an error message similar to the one below ValueError redefining named object FormXob PFO0 If this is the case find the places where you are using the second and subsequent lt catchForms gt tags and delete them leaving only the lt doForm gt tags Of course this doesn t apply to any doForms which are pointing at other data files They would still need their own initial lt catchForms gt tags Note For the lt catchForms gt tag to work you must have PageCatcher installed In addition your PageCatcher must be the full version with a py or pyc file The exe version of PageCatcher will not work with RML2PDF If you get the error message ImportError catchForms tag requires the PageCatcher product http www reportlab com then you either do not have PageCatcher installed or have the wrong version The includePdfPages tag In some circumstances you may not know how many pages there will be in the PDF file you need to pageCatch
49. of the cell for a block of cells in your table It has one required attribute length It has two optional attributes start and stop m blockRightPadding This sets the padding between the contents of a cell and right hand edge of the cell for a block of cells in your table It has one required attribute length It has two optional attributes start and stop m blockBottomPadding This sets the padding between the contents of a cell and bottom edge of the cell for a block of cells It has one required attribute Length It has two optional attributes start and stop blockTopPadding This sets the padding between the contents of a cell and top edge of the cell for a block of cells It has one required attribute length It has two optional attributes start and stop m blockBackground This sets the color to be used for the background for a block of cells in your table It has one required attribute colorName It has two optional attributes start and stop a lineStyle This allows you to use lines to border your table It has two required attributes kind with the options of GRID BOX OUTLINE INNERGRID LINEBELOW LINEABOVE LINEBEFORE and LINEAFTER and colorName which must be the name of a color It has three optional attributes thickness start and stop 13 4 More about block tables A few final things to be aware about when using tables in RML table cells as contained by
50. of the frame which you wish to switch to The lt setNextFrame gt 15 empty or singleton tag it doesn t take any content Put in setNextFrame name F5 and your text will flow into the frame specified It should appear outside your paragraphs between one lt para gt and next para tag If you have defined more than one kind of template by using pageTemplate in template section at the head of the RML document you can also force RML into using a new template for the next page You do this by using the setNextTemplate tag This tag has only one attribute the mandatory one of name which tells RML which template it should use In practice you would usually set the next template and then use a next Frame setNextTemplate name yetAnotherTemplate lt nextFrame gt 7 8 Preformated text pre and xpre One tag that is also a flowable but that can t be used inside the lt para gt lt para gt tagsis lt pre gt Just as in HTML the lt pre gt tag denotes pre formatted text It displays text exactly as you typed it with the line breaks exactly where you put them and no line wrapping If you want to keep any formatting in your text such as tabs and extra whitespace enclose it in lt pre gt tags rather than para tags You can also pass a style to the lt pre gt tag If you don t use the optional style attribute anything between the lt pre gt tag andthe lt pre gt tag wi
51. of your version of RML2PDF please see the release notes and READMEs that come with the package 1 3 What is RML RML is the Report Markup Language a member of the XML family of languages and the XML dialect used by rml2pdf to produce documents in Adobe s Portable Document Format PDF RML documents can be written automatically by a program or manually using any word processor that can output text files e g using a Save as Text option from the save menu Since RML documents are basic text files they can be created on the fly by scripts in Python Perl or almost any other language RML makes creating documents in PDF as simple as creating a basic web page RML is as easy to write as HTML and uses tags just like HTML It is much easier than trying to write PDF programmatically 1 4 What is this document This document is a user guide and tutorial for RML It deals with RML as specified in the RML DTD rml dtd If your installation of RML uses a later version you will need a later version of the DTD and of this tutorial Look on the ReportLab website http www reportlab com for more details This document has been generated from RML If you need another example of RML in action look at the file rml user guide rml to see how this file was produced 1 5 Who is this document aimed at This document is aimed at anyone who needs to write RML It assumes that you have some experience with some form of programming or scripting
52. off The circle needs the following attributes passed to it the x and y co ordinates of the point where its center should be its radius If you imagine the e11ipse inside a rectangle the x and y attributes give the co ordinates for the bottom left hand corner and the width height attributes give the co ordinates for the top right hand corner of the box shapes also have two optional attributes fill which tells the parser if the shape should be filled in or not and stroke which tells it if the shape should have its outline displayed Both these attributes take Boolean values as arguments You can uses either 1 or yes to set them as on or 0 or no to set them as off The following example shows various combinations of attributes for each of the basic shapes Notice how this example starts with the XML definition you can get away with not using it but it is still better to make sure it is there Page 18 User Guide Document generated on 2014 09 25 13 10 59 Simple Text and Graphics with RML Figure 3 Output from EXAMPLE 3 EXAMPLE 3 lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM rml dtd document filename example 3 pdf template lt pageTemplate id main gt lt pageGraphics gt lt set the font and fill colour for the title gt lt fill color red gt lt setFont name Helvetica size 24 gt l
53. on ol or ul tags Definition lists are not yet implemented A simple example of nested ordered unordered lists story ol bulletColor red bulletFontName Times Roman li bulletColor blue bulletFontName Helvetica gt lt para gt Welcome to RML 1 lt para gt lt li gt la lt ul bulletColor red bulletFontName Times Roman bulletFontSize 5 rightIndent 10 gt Page 38 RML User Guide Document generated on 2014 09 25 13 10 59 lt li bulletColor blue bulletFontName Helvetica gt lt para gt unordered 1 lt para gt 1 lt li gt lt para gt unordered 2 lt para gt dex ul lt li gt lt ol gt lt story gt For more examples of how to use lists see test 046 lists rml in rlextra rml2pdf test 7 7 Using multiple frames If you have split your page into more than one frame you can flow text between frames To do this you use the nextFrame tag This is an empty or singleton tag it doesn t take any content Put in lt nextFrame gt and your text will continue into the next frame It should appear outside your paragraphs between one lt para gt and next para tag An optional name attribute can be used to specify the name or index of the frame which you wish to switch to You can control the automatic switch of frames by using lt setNextFrame gt tag The required name attribute can be used to specify the name or index
54. p lt greek gt r lt greek gt P lt greek gt R lt greek gt lt greek gt s lt greek gt gt lt greek gt S lt greek gt lt greek gt t lt greek gt T lt greek gt T lt greek gt v lt greek gt u lt greek gt Y lt greek gt U lt greek gt w lt greek gt v lt greek gt lt greek gt V lt greek gt 0 lt greek gt w lt greek gt Q lt greek gt W lt greek gt lt greek gt x lt greek gt lt greek gt X lt greek gt lt greek gt y lt greek gt lt greek gt Y lt greek gt 5 lt greek gt z lt greek gt Z lt greek gt Z lt greek gt Page 116 RML User Guide Appendix D Command reference All attributes are optional unless otherwise specified document lt document filename myfile pdf compression 0 1 default invariant 0 1 default debug 0 1 userPass uuserpw ownerPass ownerpw encryptionStrength 128 40 permissions print annotate gt lt document gt Above is the story based form for the document tag Encryption will only take place if a userPass is specified document lt document filename myfile pdf gt lt pageInfo gt lt pageInfo gt lt pageDrawing gt lt pageDrawing gt lt document gt Above is the PageDrawing based form for the document tag Document generated on 2014 09 25 13 10 59 string required PDF compression default PDF invariance default Debug document production 0 Encryption user password Encryption owner password Encr
55. pdf return response The function has the following interface def go xmlInputText outputFileName None outDir None dtdDir None passLimit 2 permitEvaluations 1 ignoreDefaults 0 pageCallBack None progressCallBack None preppyDictionary None preppyIterations 1 dynamicRml 0 dynamicRmlNameSpace encryption None saveRml None parseOnly False xmlInputText must a string which contains the RML specification for the PDF document to be generated outputFileName when specified overrides any output file name specified in the xml input text You may also pass in file like object e g a StringIO file object or web request buffer in which case nothing is written to disk outDir output directory parameter when present specifies the directory in which to place the output file a dtdDir is an optional DTD directory parameter which specifies the directory containing the DTD for the current version of RML a passLimit of None means keep trying until done of 3 means try 3 times then quit permitEvaluations when false disallows the evalString tag for security e g web apps a ignoreDefaults 1 means do one pass and use the default values where values not found pageCallBack isacallback to execute on final formatting of each page used for counting number of pages m progressCallBack is acleverer callback see the progressCB function in reportlab platypus doctemplate
56. precise layout of a printed document and RML2PDF converts this to a finished document in one step In a dedicated reporting application other components of our toolkit handle data acquisition and preparation of the RML document RML2PDF on its own also fills a key technology gap Our full toolkit relies heavily on the Python scripting language Nevertheless we recognize that IT departments and software houses have their own distinct skill sets and development tools A company may already have developed a rich 3 tier architecture with the key business data in Java or COM objects on an application server All they need is the formatting component They can use exactly the same techniques they use to generate HTML XSLT JSP ASP or anything else to generate an RML file and the program turns this into a finished document Fast Unlike a number of other formatting languages RML aims squarely at corporate needs Paragraph table and page styles are kept in independent stylesheets allowing reuse and global changes across a family of documents The table model has been designed for efficient rendering of business data And a plug in architecture lets you easily develop and add in custom vector graphics or page templates within the same tool set RML2PDF can also work in tandem with our PageCatcher product PageCatcher is a support tool which extracts graphical elements from PDF files for inclusion in documents generated by RML2PDF or the ReportLab core
57. rotate a graphic rotate takes one mandatory attributes called degrees which is the number of degrees to rotate the object A positive number for degrees rotates it anti clockwise a negative number rotates it clockwise When using rotate objects are rotated around the current origin If you want to rotate a specific element ofapageGraphic or illustration you will have to usea translate to move the origin before you do the rotate If yu translate to middle of the page rotate by 90 degrees and then draw the string hello the hello will appear starting in the middle of the page going upwards Examples rotate degrees 90 lt ANTI clockwise gt rotate degrees 90 lt clockwise gt This is whata rotate looks like with degrees set to 45 and 45 Page 72 Document generated on 2014 09 25 13 10 59 RML User Guide Original degrees 45 Figure 15 A rotate with a positive value for degrees ple Original degrees 45 Figure 16 A rotate with a negative value for degrees 10 7 Skew lt skew gt isa transform which distorts both axes of a graphic It is non orthagonal in other words it is a transformation that does not preserve right angles lt skew gt has two mandatory attributes alpha and beta Both are angles look at the example below to see how they work Example lt skew alpha 10 beta 10 gt This is what a skew withan alpha of 10andabeta of
58. size 12 gt fill colors black drawCentredString x 58 y 12 gt dx 50 dy 50 drawCentredString lt This is relative to the origin of the black lines in the illustration which is why it doesn t match the actual translate performed it is what the translate would be if the origin was at 15 40 gt setFont name Helvetica Bold size 50 gt fill color red gt lt translate dx 55 dy 91 gt lt drawString x 0 y 0 gt X lt drawString gt illustration 10 5 scaling lt scale gt as its name suggests allows you to stretch or shrink a graphic Page 71 RML User Guide Document generated on 2014 09 25 13 10 59 The scale tag takes two optional attributes sx sy sx is how much to scale X axis and sy is how much to scale the Y axis The scaling does not have to be proportional omitting one allows you to change the scaling in one direction only And you can shrink the shape as well as scale it up an sx or sy of 2 doubles the size of it butan sx or sy of 0 5 halves it Scale factors can also be negative Using an sx of 1 and an sy of produces a mirror image Examples lt scale sx 2 sy 0 25 gt scale gx 2 gt scale 5 5 This is what a scale with a sx of 2 sy of 2 looks like Original sx 2 sy 2 Figure 14 An example of the lt scale gt tag in use 10 6 rotations The rotate tag allows allows you to
59. size in points to be used imageHeight the height of the image using 0 will cause the pixel size in points to be used imageMask a transparency colour or the word auto this only works for image types that support transparency imageLeftPadding space to be used on the left of the image imageRightPadding space to be used on the right of the image imageTopPadding space to be used on the top of the image imageBottomPadding space to be used on the bottom of the image imageSide which side the image should go on left or right Example lt imageAndFlowables imageName doc images replogo gif imageWidth 141 imageHeight 90 imageSide left gt para style hl Test imageAndFlowables tag with paras lt para gt para style stylel gt We should have an image on the lt b gt right lt b gt side of the paragraphs here para para style stylel Summarizing then we assume that the fundamental error of regarding functional notions as categorial may remedy and at the same time eliminate the levels of acceptability from fairly high e g 99a to virtual gibberish e g 98d This suggests that the theory of syntactic features developed earlier delimits a descriptive fact We have already seen that any associated supporting element is not quite equivalent to the traditional practice of grammarians From Cl it follows that the theory of syntactic features developed earlier can be defined in such a way as to impos
60. something to such a small size that it shrinks to nothing Be especially careful when doing scaling with large factors Something that may have been a small error without the scaling may put your object off the page entirely once you have performed the scale wm scaling operation scales everything including line widths If you are taking a huge diagram and scaling it down the lines may be scaled out of existence Conversely if you take something microscopic and enlarge it you may end up just getting a blob due to the width of the lines being scaled up as well a Another thing to remember is that these transformations are incremental in a series of transforms each one will modify the output of the one before it So the order you carry the operations out in is very important The result of the sequence translate rotate scale is very different to that of scale rotate translate Page 74 RML User Guide Document generated on 2014 09 25 13 10 59 If performing multiple operations use the order translate gt rotate gt scale or skew whenever possible Using a different order may result in the axes being distorted or other results that lead to an ugly output that isn t what you were trying to do 10 10 Bitmapped images RML also allows you to insert pre existing images into your PDF files If you have a graphic file in either the gif format you can use the image tag to insert it into your document
61. td gt LEEF td lt td gt td 5t td a RIGHT lt td gt usos xor td lt td gt a tes td a RIGHT lt td gt lt blockTable gt lt spacer length 15 gt lt para gt a value for lt i gt blockAlignment lt i gt lt para gt lt para gt VA value for lt i gt blockValign lt i gt lt para gt lt para gt lt i gt MDLE MIDDLE for VA in cells 3 2 and 3 3 lt 1 gt lt gt lt Sstory gt lt document gt Page 100 RML User Guide Document generated on 2014 09 25 13 10 59 Example 11 lines and alignment in tables a LEFT VA TOP VA TOP VA TOP a RIGHT VA TOP a LEFT 1 1 Cell 2 1 VA MIDDLE a LEFT 1 2 VA MIDDLE a LEFT 1 3 a LEFT 1 4 2 4 a LEFT 1 5 2 5 a LEFT 1 6 2 6 Figure 23 Output table from EXAMPLE 11 a value for blockAlignment VA value for blockValign MDLE MIDDLE for VA in cells 3 2 and 3 3 Page 101 a RIGHT VA MDL a RIGHT VA MDL a RIGHT a RIGHT a RIGHT a RIGHT User Guide Document generated on 2014 09 25 13 10 59 1 4 Example 12 images and padding in tables This example shows images in a table and the way to use the various padding attributes For comparison purposes The cells that contain pictures in this table are all 166 pixels in height and 161 pixels in width Where padding is used it has a value of 20 pixel
62. you to use objects from outside your RML document plugInGraphic AplugInGraphic identifies a function callable in a module which takes a canvas and a data string as arguments and presumably draws something on the canvas using information in the data string Example lt plugInGraphic module mymodule function myfunction gt data string plugInGraphic when executed results in effectively the following execution sequence import mymodule mymodule myfunction canvas data string using the current canvas object lt PlugInGraphic gt has two mandatory attributes module and function It is used in the lt pageGraphics gt section of your document plugInFlowable AplugInFlowable identifies a function callable in a module which takes a canvas data string as an argument and returns a flowable object Example plugInFlowable module mymodule function myfunction gt data string lt plugInFlowable gt when executed results in effectively the execution sequence import mymodule flowable mymodule myfunction data string story append flowable using the current canvas object plugInFlowable has two mandatory attributes module and function It is also used in the lt pageGraphics gt section of your document 8 8 Integrating with PageCatcher catchForms doForm and includePdfPages You can use our product PageCatcher to capture individual pages from an external PDF file e g application forms government
63. 0 stop 1 0 gt lt blockTopPadding length 40 start 0 2 stop 1 2 lt set the top and bottom padding for the last row gt lt blockBottomPadding length 40 start 1 4 stop 1 4 gt lt blockTopPadding length 40 start 0 4 stop 0 4 gt lt Use of 15 lt lineStyle kind GRID colorName darkblue gt lt blockTableStyle gt lt paraStyle name paddingTableStyle fontName Helvetica BoldOblique fontSize 10 textColor white Page 102 User Guide Document generated on 2014 09 25 13 10 59 alignment CENTER es lt stylesheet gt lt story gt lt title gt Example 12 images and padding in tables lt title gt spacer length 1cm gt lt blockTable style myBlockTableStyle rowHeights 166 28 166 28 166 28 colWidths 161 161 161 gt Sie stas lt illustration width 141 height 90 gt lt image file images replogo gif x 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt Quoc 141 0 141 90 141 90 0 90 0590000 lines lt illustration gt lt td gt stas lt illustration width 141 height 90 gt lt image file images replogo gif x 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt 0 0 141 0 90 90 0 90 90 00 lt 11 gt lt illustration gt lt td gt
64. 0 stop 3 0 gt lt This sets a textColor for all the text in the table gt lt blockTextColor colorName black gt lt 1 This sets textColor for the first row gt lt Since it comes arter the above setting 2 n ievernrdes dt for this cow lt blockTextColor colorName white start 0 0 stop 3 0 gt This sets textGolor column als overriding gt amp the first textColor setting for this row gt lt blockTextColor colorName blue start 1 1 stop 1 6 gt This sets a background color for the first row gt lt blockBackground colorName red start 0 0 stop 3 0 gt lt This sets a background color for the rest of the table gt lt blockBackground colorName cornsilk start 0 1 stop 1 1 lt This sets a background color for an individual cell lt This has to go AFTER the above blockBackground lt otherwise it would be overpainted by the cornsilk color gt lt blockBackground colorName lightcoral start 3 3 stop 3 3 gt lt blockTableStyle gt lt stylesheet gt lt SEOry Page 94 RML User Guide Document generated on 2014 09 25 13 10 59 lt title gt Example 10 colors and fonts in tables lt title gt spacer length 1cm gt lt blockTable style myBlockTableStyle rowHeights 3 5cm 2cm 2cm 2cm 2cm 2cm 2cm col lt tr gt lt td gt Cell
65. 1 Using multiple RE el are Poe a RR UR 38 7 8 Preformated text and xpre 38 sat aS Sha ML u a s 39 POMS ia ua Mes RN 42 Part II Advanced Features 44 8 Miscellaneous useful features 44 Space NUM ioo sama aa opo dad RE MEE 44 amp 2 asnu e 44 8 3 Seq segReset segChain and 44 S4 Entities o S ea Ut Mau 48 ILC accra TETTE 49 8 6 CDATA unparsed character data tn e viso ven 49 8 7 Plug ins plugInGraphic and 50 8 8 Integrating with PageCatcher catchForms doForm and includePdfPages 50 NNNM 53 BPO Eormdielq Ag Sues 53 8 11 Colorspace Glee king Sho 61 9 About Cross References and Page Numbetrs 62 9 1 the namedString tag and forward references J aa 62 92 Multiple pass pdf f
66. 30 looks like Page 73 RML User Guide Document generated on 2014 09 25 13 10 59 beta alpha Original alpha 10 beta 30 Figure 17 An example of the lt skew gt tag in use 10 8 Generic affine transforms A transform allows the coordinate space to be filtered through a general two dimensional affine transform All the other coordinate transformations can be defined in terms of a transform A transform requires 6 numbers a b c d e and f to define the transformation x ax cy e y bx dy f For example to specify a 1 b 1 2 c 1 3 d 1 4 e 1 5 and f 1 6 write lt stranstorm gt l 1 2 1 5 1 4 2 5 1 6 NOTE examples from this section are gathered together in file example 8 rml 10 9 About scale rotate and skew m tis very easy to move objects off the page If you are doing a translate asa lt pageGraphic gt it is possible to put the origin off the visible area of the page If you are doing a translate illustration checks are performed about whether object is inside the limits of the illustration or not so it is still possible to put it outside the limits of the page and lose it If you expect to see a diagram and all you get is a blank page this is the most common cause Scaling has its own version of the same problem It is possible to scale an object so that most or all of it is off the page but it is also possible to scale
67. Appendix C Letters used by the Greek tag 115 Appendix D Command reference 116 Page 4 RML User Guide Document generated on 2014 09 25 13 10 59 1 Introduction 1 1 ReportLab PLUS ReportLab s solution solves several central problems that ebusinesses face in creating publishing caliber reports that are customized produced in real time in volume and platform independent Existing reporting tools are limited to database reports are typically Windows based have problematic restrictions on layout and graphic design and go straight to a printer More complex publishing systems involve pipelines of applications which are simply too unwieldy for real time use in large scale environments ReportLab s product suite allows direct creation of rich PDF reports on web or application servers in real time The tools run on any platform can actively acquire data from any source XML flat files databases COM Corba Java place no limits on the output and facilitate electronic delivery and archival The ReportLab suite lets you define your own business rules to automatically create custom online reports catalogs business forms and other documents RML2PDF is a central component of the toolkit a translator which converts high level XML markup into PDF documents Report Markup Language describes the
68. Bei RML User Guide Report Markup Language Document generated on 2014 09 25 13 10 59 ReportLab Europe Ltd Thornton House Thornton Road Wimbledon London SW19 4NG UK RML User Guide Document generated on 2014 09 25 13 10 59 1 Introducti n RR eA 4 S oeste 4 1 2 Installati n and Ue scs ettet EUR Nm obtu rout em eb Cb alae 4 13 Whatas R MIS uu seit ntu Su 7 1 4 What is this eL ANE RT e 7 1 5 Who is this document aimed p eite IH 7 1 6 Conventions used in this 1 7 Part I The Basics 9 2 Pages and pag SCF CDUFES oues ceder etri uuu 9 21 X MI syntax and RMG inten tetas adel ack 9 2 2 Le DEOLOB n ss anus At 9 2 3 Document forms stylesheet pageDrawing vs template stylesheet story 11 3 Basic Text Operations 14 3 1 Coordinates and measurements assa ir RUE Te or RO AS RU nsi tad 14 SUUS MIS 14 2 9 Berne TOR Son esau l u SS Pr b 14 3 4 Basic text operations setFont and 15 4 Basic figures lines and shapes
69. CMYK colour values SEP Spot Colors only all colour values must define a spotName value SEP_BLACK spot colors plus shades of grey only SEP CMYK spot colors plus values only The use of any color definitions outside the specified type will result in an exception when you try to compile the document thereby ensuring that for instance a document can be produced for CMYK or spot color printing without containing any RGB color definitions Any named colours see appendix or reportlab lib colors py for black or shades of grey are automatically converted to cmyk rgb as required So you can use lowercase black as a color in all models except However any other RML named colors such as aqua or hotpink will not be converted Page 62 RML User Guide Document generated on 2014 09 25 13 10 59 9 About Cross References and Page Numbers Many documents such as this one require page cross references For example the table of contents of this user guide lists the page numbers of the beginnings of each part chapter and section RML provides several features that support cross referencing and page number calculations The code name endcode and code NamedString endcode tags allow forward referencing and the code evalString endcode tag allows computations of page numbers or other computations inside an RML text Furthermore these techniques may be combined with preprocessing me
70. O10 018 00 09090 91000 61916016 Text 123 Text 123 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Document generated on 2014 09 25 13 10 59 lightcoral lightcyan lightgoldenrodyellow lightgreen lightgrey lightpink lightsalmon lightseagreen lightskyblue lightslategray lightsteelblue lightyellow lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive Page 110 Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex OxFFDEAD 0x000080 OxFDF5E6 0x808000 xF08080 xEOFFFF 2 0 90 90 xD3D3D3 6 x20B2AA Ox87CEFA 0x778899 xBOCADE xFFFFEO xOOFFOO0 x32CD32 OxFAFOE6 x800000 X66CDAA x0000CD XBA55D3 x9370DB 0x3CB371 x 7BO8EE 4 801 0xC71585 0x191970 OxF5FFFA xFFEAEI XFFE4B5 RML
71. Size 14 label horiz resizing gt some more text lt textBox gt lt textBox x 2 7cm y 0cm boxWidth 3cm boxHeight lcm shrinkToFit 1 fontSize 14 label vert resizing gt some text text lt textBox gt textBox x 10 5cm y 0cm boxWidth 3cm boxHeight lcm shrinkToFits 1 fontSize 14 label horiz vert resizing gt some more text Le text text lt textBox gt no resizing horiz resizing vert resizing horiz vert resizing some text some more text some text some more text 5222 some text some text Letterboxes Letterboxes are intended for single line text fields where each letter is contained in a subcell clearly seperated from neighbouring cells This is often seen on official forms where people are expected to write letters of a word at predefined positions RML provides such letterboxes too and they behave mostly like textboxes but show some significant differences too Usually the overall width of a form field element is defined by the mandatory boxWidth attribute For letterboxes though this is an optional attribute and specifies the width of a subcell containing one letter The resulting width of the entire box is defined as a multiple of that boxWidth attribute with another one named count which is a mandatory attribute The following code creates a row of sample letterboxes showing basic attributes lt letterBoxes x 0cm y 7 5cm count 12 gt letterboxes lt letterBoxes
72. Two gt lt para gt lt para gt Second seq for testTwo lt seq id testTwo gt lt para gt lt spacer length 6 gt lt para gt lt seqReset id testOne gt We have just done a amp lt seqReset id testOne amp gt lt para gt spacer length 6 gt lt para gt First seq after seqReset for testOne lt seq id testOne gt lt para gt lt para gt second seq after seqReset for testOne lt seq id testOne gt lt para gt spacer length 6 gt lt para gt First seq after seqReset for testTwo lt seq id testTwo gt lt para gt lt para gt second seq after seqReset for testTwo lt seq id testTwo gt lt para gt spacer length 15 gt lt para gt Notice how resetting testOne doesn t affect testTwo at all lt para gt lt story gt lt document gt Page 48 RML User Guide Document generated on 2014 09 25 13 10 59 seq in seq seqDefault and seqReset copied 1 2 3 Reset 1 2 3 simple use of seq First seq 1 Second seq 2 We have just done lt gt First seq after seqReset 1 second seq after seqReset 2 If you are going to use multiple seq tags you need to use the id attribute Better use of seq We have just done a lt seqDefault id test gt We have just done a lt seqReset id test gt First seq 1 Second seq 2 We have just done a lt seqReset id test gt First seq after seqReset 1 second seq after seqReset 2
73. age file myFile2 jpg x 369 y 493 width 80 height 80 gt lt pageGraphics gt 10 11 Text Fields To allow the creation of forms we have a graphics tag that allows us to specify that the page should display an entry box The lt textField gt tag goes in the lt pageGraphics gt section at the at the start of the RML document It has the following optional attributes id the field name value the field initial value x the field x coordinate y the field y coordinate width the field width height the field height maxlen maximum allowd number of field characters amp multiline whether the field may contain more than one line As a convenience the attributes may instead be specified using lt param gt tags within the body of the lt textField gt tag The name attribute of the lt param gt tag should be one of the above attribute names If no value attribute or lt param gt is seen then the contents of the lt textField gt becomes the initial value of the field It is an error to define an attribute more than once 10 12 place and illustration place Page 75 User Guide Document generated on 2014 09 25 13 10 59 We have seen how graphics and flowables do not mix RML The only exceptions to this are place tag and lt illustration gt tag lt place gt allows you to put a flowable inside a pageGraphic or illustration You can include a paragraph inside a grid or a table insi
74. ageTemplate gt lt template gt lt stylesheet gt lt initialize gt lt name id FileTitle value Example 5 templates and pageTemplates gt lt name id ColumnOneHeader value This is Column One gt lt name id ColumnTwoHeader value This is Column Two gt lt initialize gt lt paraStyle name titleBox fontName Helvetica Bold fontSize 18 spaceBefore 0 4 cm alignment CENTER gt lt paraStyle name body fontName Helvetica fontSize 10 leftIndent 5 spaceAfter 5 lt stylesheet gt lt story gt lt para style titleBox gt lt b gt lt getName id FileTitle gt lt b gt lt para gt lt nextFrame gt lt condPageBreak height 144 gt lt h2 gt lt getName id ColumnOneHeader gt h2 para This is the contents for b column one lt b gt para Page 41 User Guide Document generated on 2014 09 25 13 10 59 lt para gt It uses the default style for paragraph lt para gt lt para gt Does it come out OK lt para gt lt para gt There now follows some random text to see how these paragraphs look with longer content lt para gt lt para gt Blah blah morale blah benchmark blah blah blah blah blah blah communication blah blah blah blah blah blah blah blah blah blah stretch the envelope blah blah blah lt para gt lt para gt Blah blah blah blah blah blah blah blah blah blah blah blah hitect blah inter acti
75. also an optional density attribute which allows you to print with a thinner or half tone layer of ink If you set a density lower than 1 0 you don t need to fiddle with the CMYK values for on screen preview we do that for you document filename test 045 separations pdf invariant 1 colorSpace SEP gt Soocdmd to color id BLACK CMYK 0 0 0 1 Page 87 RML User Guide Document generated on 2014 09 25 13 10 59 lt color id BLUE CMYK 1 0 67 0 0 23 spotName PANTONE 288 CV gt color id BLUE75 1 0 67 0 0 23 spotName PANTONE 288 CV density 75 gt docinit If you have access to Adobe Acrobat Professional or other print pre flight tool you will be able to preview each of the plates separately and the inks that are used The overprint tag is perhaps even more useful when working with spot colours for example we have worked with pie charts where the overall document was limited to black and a specific Pantone blue and the designer was able to create some new tints by stacking the blue and black on top of each other Composite Black plate Blue plate 12 7 Pagination A document that is intended to be printed as a bound booklet on a press must always have a page count that is a multiple of four Even with a different binding technique documents laid out for print may make use of left and right facing pages which go together RML documents with dynamic content will in man
76. ar as a rectangular shape with some background and border colour plus some width for the border itself They also have some sort of text label attached to this rectangle to describe the field s purpose in the context of Page 54 RML User Guide Document generated on 2014 09 25 13 10 59 the report to the human reader The text inside the field as well as the one in the attached label also should have the usual properties like fontname and size and colour All form field elements have a boxStyle attribute that can be used to group attribute names and values and reuse them in many field elements with much less typing effort But there are also specific features that distinguish these form elements from each other A checkbox does not contain text but only a cross when checked and a textbox contains one or more lines of text with different possible alignments while letterboxes are used for single line mono space text with visible subcompartments for each letter Checkboxes By default checkboxes have a very simple style similar to UK bank application forms an outer rectangle and a cross which exactly fills it when checked The attributes control the appearance It is also possible to supply your own pair of bitmap images which will be used instead of the default drawing mechanism this could be used to provide 3d effects tick and cross icons or whatever is needed To make use of this set the two attributes graphicOn and graphicOff to point
77. at deal of information on fonts which needs adding to this manual including embedded Type 1 fonts and encodings and use of embedded subsetted TrueType fonts Page 44 RML User Guide Document generated on 2014 09 25 13 10 59 Part Il Advanced Features 8 Miscellaneous useful features 8 1 pageNumber As you d expect from the name this tag adds page numbers to your document This has nothing tricky to remember all you have to do is put the pageNumber tag where you want the page number to appear 8 2 name and getName The lt name gt tag allows you to set a variable as you would in a programming language You can then retrieve this to put in another place by using lt getName gt tag You can do this as many or as few times as you need so it is handy for things like headers and footers or for items that you see changing many times over the life of your document such as version or revision numbers If you set them using a name tag you only have to revise them in one place every time they change rather than having to plough through the document changing them manually in each location and inevitably missing one name has three attributes id and value are required but type is optional lt getName gt only has one attribute id and this is required so that it knows which name to yank In practice it would look something like this example lt stylesheet gt lt initialize gt lt name id YourVariableName
78. ate tags completely The nextFrame tag is used because the includedPdfPages places you at the top of the last included PDF page This allows you to flow paragraphs or other flowables down your last page This may be useful if you want to place text in a form or use some other pre prepared background for your text If all you want to do is just drop in a pre made page you need this nextFrame to kick you into the next normal page and continue Page 53 RML User Guide Document generated on 2014 09 25 13 10 59 with your document normally Look in section 7 6 Using multiple frames for more info on the nextFrame and setNextTemplat tags Look at the file test test_016_pagecatcher rml for an example of this tag in use These attributes control the lt includePdfPages gt tag filename filename to include pages The page list template optional page template name outlineText optional outline text outlineLevel optional outline level outlineClosed true for closed outline leadingFrame yes 10 1 1 notAtTop if you don t want a page throw before the first page isdata boolean true if the file is a pageCatcher data file orientation 0 portrait 90 landscape 1801 270 auto auto means use the file implied layout 8 9 Outlines It can go in either graphics or in a story Assigning outline levels to parts of your document such as paragraphs allows you to build up a hierarchical structure for your document
79. basic shapes such as rect and circle and an additional one called close If the close attribute is set to yes or 1 then once the path is completed the stroke is finished off by painting a line from the last point given to the first point enclosing the figure The path tag has its paired lt path gt tag Between these two tags you a number of things a You have a list of pairs of X Y co ordinates If this is the case a straight line is drawn to each point in turn m You can have a paired lt moveto gt lt moveto gt tag If this is the case you need to give an x y co ordinate pair between these two tags The pen or brush then moves to this point and any further points or instructions given after this while still inside the path tag continue onwards from this new point You can have a paired lt curvesto gt lt curvesto gt tag This is similar to both the curves tag and the lt moveto gt tag discussed above Inside the pair of lt curvesto gt tags you need to give rml2pdf sets of 3 pairs of X Y co ordinates at a time Like lt curves gt lt curvesto gt creates a Bezier curve However since it is inside a path object it already knows one of the points the start point is assumed to be the last point in the path before the lt curvesto gt tag In other words the pen or brush is already in a position and this is taken as the first point for your Bezier curve Here is an example
80. bleWidth and availableHeight give you the remaining height and width of the current frame doc frame id returns the id of the current frame doc pageTemplate id returns the id of the current page template doc page returns the current page number 11 2 Tags The docIf docElse and docWhile tags allow you to control which content is included and excluded while or if a condition is true or false The docPara tag allows you to include the value of an expression in the output text This is useful for debugging document layouts e g temporarily inserting paragraphs like you are 3 inches down the left frame of the chapter first page template on page 19 but you can also use it to display facts you stored earlier The value can be formatted using Python format strings see the test case above for details lt docAssign gt assigns a value to a variable and lt docExec gt executes a statement or expression The docAssert tag allows you to test an expression and raise an exception if it is not true This can be a useful quality assurance technique As with the docPara example for debugging you can include assertions like I should now be at the top of page 3 or I should now be in the footer frame 11 3 Operators When using docIf or docWhile tags you can use the following operators to evaluate your conditions Page 81 RML User Guide Document generated on 2014 09 25 13 10 59 However bear in mind
81. boxWidth 0 75cm boxHeight 1cm lineWidth 0 1cm checked 1 gt lt checkBox x 6cm y 0cm lineWidth 0 1cm boxFillColor yellow boxStrokeColor green checked 1 gt lt checkBox x 7 5cm y O0cm lineWidth 0 1cm boxFillColor yellow boxStrokeColor green checkStrokeColor red checked 1 gt Page 55 User Guide Document generated on 2014 09 25 13 10 59 lt checkBox x 9cm y 0 linel desc 1 line2 desc 2 checked 1 gt lt checkBox x 11 5cm y 0 linel desc 1 line2 desc 2 line3 desc 3 checked 1 gt X B b Dx ces dese 2 desc 2 desc 3 Textboxes A textbox contains one but often more lines of text like in an address field Of course it can also contain no text at all like for a signature field Sometimes it is not clear in advance exactly how much text will go into one such field Therefore textbox fields in RML provide a means for automatically resizing the fontsize to shrink the contained text by exactly what is needed to make it fit into the box This is a two step process that first tries to shrink the fontsize to make the text fit horizontally If that is not enough it is further shrinked to make it also fit vertically This process is controlled using the attribute shrinkToFit Because human readers are very sensible to reading text and get quickly irritated when it does not feel right there is a default amount of space 1 point left betw
82. ceAfter 3cm alignment justify bulletFontname Courier bulletFontsize 13 bulletIndent 0 2in textColor red backColor cyan name mystyle alias pretty parent oldstyle fontname Courier Oblique Fontsize 13 alignment left textColor blue labelFontName Courier labelFontSize 13 labelAlignment left label TextColor 5lue boxFillColor blue boxStrokecolor blue cellWidth lin cellHeight lin Page 147 Document generated on 2014 09 25 13 10 59 string string string string measurement measurement measurement measurement measurement measurement measurement left right center or justify string measurement measurement string string string string string string measurement left right or center string color name string measurement left right or center string color name string color name string color name measurement measurement required RML User Guide blockTableStyle lt blockTableStyle id mytablestyle gt lt blockFont gt lt blockLeading gt lt blockTableStyle gt Table Style Block Descriptors blockFont lt blockFont name TimesRoman size 8 leading 10 start 4 stop 11 gt blockLeading lt blockLeading length 10 start 4 stop 11 gt blockTextColor lt blockTextColor colorName pink start 4 stop 11 gt Page 148 Document generated on 2014 09 25 13 10 59 string
83. ced figures section later in this manual For example this draws a simple line lt lines gt 250m TO oam Soden DE SONT lt lines gt And this starts with the same line then draws an extra couple of lines below it lt lines gt 2 10 510 3 51m 10 51m 292m 10 251m 3 5148 10 254 2 odm 3511 lines It doesn t matter how you arrange the sets of co ordinates but it helps to keep it human readable if you keep co ordinates to do with the same line on the same line of RML This second example could have been written like this but it would be much harder to follow lines 2 099m TO Sim S Sum TO Sim 2 Sam RO rar y Sum osoin Oin lines One more thing to notice before we move on is that these co ordinates are separated by spaces They are not separated by commas as you might expect As well as just drawing lines there are a number of attributes you can modify to change the appearance of lines This is done with the lt LineMode gt tag The most obvious attribute to lt lineMode gt is width You give 1 a number for the width attribute to change the line width to that number of points Page 22 RML User Guide Document generated on 2014 09 25 13 10 59 width 1 width 5 width 10 width 15 Figure 4 Example of lineMode attribute width The join attribute to lt 11 gt adjusts how what happens when lines meet They can either come to poi
84. change it in one alias rather than in every individual paragraph that uses that style 8 6 CDATA unparsed character data CDATA is standard XML tag which indicates to the parser in this case rml2pdf to ignore anything inside the CDATA section It shouldn t parse it or process it in any way just display it CDATA section is started with the characters lt CDATA and is closed off with the characters gt It can appear inside any flowable though it is most useful inside a pre tag CDATA may be useful in places where you have large quantities of and gt characters that you want to display in your PDF and that you would rather not have to convert them all to amp 1t amp gt entities Quoting sections of RML XML or HTML code is an example of a good place to use CDATA if you needed to revise the code example at a later date you would have to convert the characters in every tag into entities CDATA saves you having to do this However you should only use CDATA when necessary If you are using other XML tools they will also ignore anything inside a CDATA section Example Page 50 RML User Guide Document generated on 2014 09 25 13 10 59 lt xpre gt lt CDATA Anything could go here lt non_existant_tags gt amp signs Whatever you want RML ignores it rm xpre 8 7 Plug ins pluginGraphic and pluginFlowable Both plugInGraphics and plugInFlowables allow
85. dary yes pdfBoxType MediaBox pdfPageNumber 4 showBoundary no shrinkToFit no growToFit no caption sSomecaption CaptionFont 12 captionSize lin captionGap sSomecaptionGap captionColor blue spaceAfter 4 spaceBefore 4 Document generated on 2014 09 25 13 10 59 string measurement measurement string yes no 0 1 yes no 0 1 MediaBox CropBox TrimBox BleedBox ArtBox integer 011 yes no 011 yes no 011 yes no string stringform font name measurement string string color name integer integer align center centre left right cermemcerdtryteftirigati CEN TERIOBNTRE LEFTIRIGHT gt img lt img src somesrc width lin height lin valign top gt Path Operations moveto lt moveto gt 5in 3in lt moveto gt Page 140 string measurement measurement top middle bottom measurement pair RML User Guide curvesto lt curvesto gt lin lin lin 4in 4in 4in 2in 2in 2in 5in 5in 5in lt curvesto gt Form Field Elements barCode lt barCode code Code 11 gt 01234545634563 lt barCode gt checkBox Page 141 Document generated on 2014 09 25 13 10 59 sextuples of measurements for bezier curves measurement required measurement required Code11 required Code128 2015 Standard39 Standard93 Extended39 Extended93 MSI FIM POSTNET unformat
86. dding float imageSide left gt lt para gt lt para gt lt table gt lt table gt lt imageAndFlowables gt pto lt pto gt lt pto_trailer gt lt pto_trailer gt lt pto_header gt lt pto_header gt lt para gt lt para gt lt table gt lt table gt lt pto gt pto_trailer lt pto_trailer gt lt para gt lt para gt lt table gt lt table gt lt pto_trailer gt pto_header lt pto_header gt lt para gt lt para gt lt table gt lt table gt lt pto_header gt Page 132 Document generated on 2014 09 25 13 10 59 path to image file or url image width or 0 image height or 0 image transparency color or auto space on left of image space on right of image space on top of image space on bottom of image hrizontal image location left right Sequence of top level flowables optional optional Sequence of top level flowables Only in PTO Sequence of top level flowables Only in PTO Sequence of top level flowables RML User Guide indent lt indent left lin right 1cm gt lt para gt lt para gt lt table gt lt table gt lt indent gt frameBackground lt frameBackground color pink right 1cm start 1 gt fixedSize lt fixedSize width lin height 1cem gt lt para gt lt para gt lt table gt lt table gt lt fixedSize gt Document generated o
87. de a path lt place gt takes 4 attributes all of which are required x and y are the x and y co ordinates for where you want the flowable placed width and height are the width and height of the flowable Example lt pageGraphics gt place x 10 5cm y 10 5cm width 9cm height 9cm gt lt para gt Your flowables would go here lt para gt lt place gt lt pageGraphics gt illustration You can think of an illustration as like one of the illustrations in a book It is a box of space on the page which can contain any of the graphics that you would normally expect to find ina lt pageGraphics gt tag The position of this box depends purely on its place in the story which means that it can appear anywhere on the page depending on the paragraphs and other flowables around it This is in contrast to the pageGraphics which are always placed in a specific place measured from the origin Example lt illustration width 90 height 90 gt lt fill color red gt lt circle x 45 y 45 radius 30 fill yes gt setFont name Times Roman size 8 gt lt drawString x 0 0 gt Any graphics could go here lt drawString gt lt illustration gt Page 76 User Guide Document generated on 2014 09 25 13 10 59 illustrations in the story a place inside a grid Figure 18 Output from EXAMPLE 9 Notice the symmetry place tag lets you use flowables within a lt pa
88. e them make sure they are on the appropriate path and then register them in the lt docinit gt section at the top of the RML file Use the lt registerTTFont gt and registerFont tags to register them To use a common set of fonts together as bold italic etc you need to put them into a common grouping using the lt registerFontFamily gt tag An example of how to use these tags with different font types and styles can be found in the file rml2pdf test test 005 fonts rml 3 4 Basic text operations setFont and drawString The simplest way to put text on a page is using lt drawString gt tag This places the string of text on the page at the co ordinates you give it The only attributes you can give it are a pair of X and Y co ordinates After the tag itself comes the string of text you want put on the page and then you need the closing drawString tag DrawString has pair of companions DrawRightString drawCentredString both work in the same way but right justify the string and center it respectively This is how they look in practice drawString x 523 y 800 gt This is a drawString example lt drawString gt lt drawRightString x 523 y 800 gt This is a drawRightString example lt drawRight String gt lt drawCentredString x 523 y 800 gt Page 16 User Guide Document generated on 2014 09 25 13 10 59 This is a drawCentredString example lt drawCentredString gt
89. e 156 Document generated on 2014 09 25 13 10 59 font name string measurement integer measurement integer DEBUG INFO WARNING ERROR CRITICAL RML User Guide Document generated on 2014 09 25 13 10 59 info lt info gt lt info gt warning lt warning gt lt warning gt error lt error gt lt error gt critical lt critical gt critical logConfig logConfig level DEBUG DEBUG INFO WARNING ERROR CRITICAL format The value of is efgrmatstring filename somefilename string filemode WRITE WRITE APPEND datefmt somedatefmt string gt Not implemented The following tags are allowed for in the DTD but are not implemented by the current version of RML2PDF li ol u ul dd dl dt Page 157
90. e file images replogo gif x 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt 0 0 1410 141 0 141 90 141 90 0 90 o 9000 lt lines gt illustratiomn td seo lt t q gt lt style paddingTableStyle gt blockLeftPadding with blockTopPadding lt para gt lt td gt stas lt para style paddingTableStyle gt no padding lt para gt lt td gt lt style paddingTableStyle gt blockRightPadding with blockBottomPadding lt para gt lt td gt lt tr gt lt blockTable gt lt story gt lt document gt Page 106 Document generated on 2014 09 25 13 10 59 User Guide Document generated on 2014 09 25 13 10 59 Example 12 images and padding in tables blockLeftPadding with blockBottomPadding blockRightPadding with just blockBottomPadding blockBottomPadding blockLeftPadding with blockTopPadding blockRightPadding with just blockTopPadding blockTopPadding blockLeftPadding with blockTopPadding blockRightPadding with no padding blockBottomPadding Figure 24 Output from EXAMPLE 12 Page 107 RML User Guide Appendix A Colors recognized by RML Document generated on 2014 09 25 13 10 59 In this table the Color column gives the name of the color as recognised in the HTML standard and RML The hexadecimal number in the Hex Value column corresponds to the red green a
91. e irrelevant intervening contexts in selectional rules So far a descriptively adequate grammar is rather different from a general convention regarding the forms of the grammar para imageAndFlowables 6 8 More about stylesheets Page 33 RML User Guide Document generated on 2014 09 25 13 10 59 Just like in a word processor RML allows you to define a stylesheet at the start of your document and then apply it to paragraphs later on This means that you can define a complicated mixture of settings that you want to apply to paragraphs only define it in one place and refer to it with a simple name at the start of each paragraph rather than having to type or cut and paste large blocks of text over and over for each paragraph Each stylesheet starts with the lt stylesheet gt tag There may then be an optional initialisation section where aliases can be set bounded by the pair of tags lt initialize gt lt initialize gt After that come a number of lt paraStyle gt tags each one defining a style that you want to use for paragraphs The lt paraStyle gt tag must have an attribute name and then may have as many optional attributes as you want each one setting one feature of the appearance of a paragraph Each one of these lt paraStyle gt tags is an empty element i e it is closed with gt rather than a separate closing tag but you might want to indent the tag so that each of the options is on a separate line T
92. e two endpoints or anchor points and two nodes Figure 11 A Bezier Curve In RML if you give a curve 4 control points which we shall call x1 y 1 x2 y2 x3 y3 and x4 y4 the start point of the curve will be specified by x1 y1 and the endpoint specified by x4 y4 The line segment from x1 y1 to x2 y2 forms a tangent to the curve The line segment from x3 y3 to x4 y4 also forms a tangent to the curve If you look at an illustration of a Bezier curve you will see that the curve is entirely contained within the convex figure with its vertices at the control points Example template lt pageTemplate id main gt lt pageGraphics gt 198 560 198 280 396 280 396 560 66 RML User Guide Document generated on 2014 09 25 13 10 59 lt curves gt lt pageGraphics gt frame id first x1 0 5in 1 0 5 width 20cm height 28cm gt lt pageTemplate gt lt template gt 10 2 paths To connect lines and curves you need to use the lt path gt tag This allows you to make complex figures Like the other graphics RML path lives lt pageGraphics gt section at the start of the document Initially you must give a path tag x and y attributes to tell it the co ordinates for the point where this path is going to start You may also at the same time give it attributes called stroke and fill which do the same as their counterparts for the
93. ea lt illustration width 141 height 90 gt lt image file images replogo gif x 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt o O MALY 141 0 141 90 9070790 0 50 0 0 lt lines gt illustration td Page 103 User Guide Document generated on 2014 09 25 13 10 59 lt tr gt lt t q gt lt style paddingTableStyle gt lt b gt blockLeftPadding lt b gt with lt b gt blockBottomPadding lt para gt lt td gt clos lt style paddingTableStyle just blockBottomPadding para lt td gt stas lt para style paddingTableStyle gt lt b gt blockRightPadding lt b gt with lt b gt blockBottomPadding lt b gt lt para gt lt td gt rc lt a gt lt illustration width 141 height 90 gt lt image file images replogo gif x 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt 0 0 141 0 141 0 141 90 900 90 lt 11 gt lt illustration gt lt td gt lt illustration width 141 height 90 gt lt image file images replogo gif x 0 y 0 width 141 height 90 gt lt stroke color deepskyblue gt lt lineMode width 3 gt lt lines gt 0 0 141 0 141 0 141 90 141 90 0 90 9000 lt lines gt lt Lilustratien gt lt td gt xtd illustration width 141 height
94. een the text and any of the borders of the box which will be respected by the resizing mechanism This is hardcoded now but might become another attribute in the future The following code creates a row of sample textboxes illustrating different values for the most relevant attributes as well as the auto resizing text feature textBox x 0cm y 0cm boxWidth 3cm boxHeight 1cm label labeled textbox gt some text lt textBox gt textBox x 3 5cm y 0cm boxWidth 3cm boxHeight lcm boxFillColor yellow boxStrokeColor blue label colorful textbox gt some text lt textBox gt lt textBox x 2 7cm y 0cm lineWidth 0 1cm boxWidth 3cm boxHeight 1cm boxFillColor yellow boxStrokeColor blue label bold textbox gt some text lt textBox gt textBox x 10 5cm y 0cm boxWidth 3cm boxHeight lcm lineWidth 0 1cm boxFillColor yellow boxStrokeColor blue fontName Times Bold fontSize 14 label textfancy textbox gt some text lt textBox gt Page 56 RML User Guide Document generated on 2014 09 25 13 10 59 labeled textbox colorful textbox bold textbox textfancy textbox F gt 7 The following code creates a row of sample textboxes illustrating the auto resizing text feature textBox y 0cm boxWidth 3cm boxHeight 1cm fontSize 14 label no resizing gt some text lt textBox gt textBox x 3 5cm y 0cm boxWidth 3cm boxHeight lcm font
95. emplate the included PDF page will overwrite it How includePdfPages works with templates When you have an includePdfPages tag in your RML file RML outputs a page break before the first new page leaving you on the same page as the last imported one This allows you to do template switching lt setNextTemplate gt lt setNextTemplate name myIncludePagesTemplate gt lt includePdfPages filename mypdffile pdf pages 1 2 3 gt lt setNextTemplate name myNormalTemplate gt lt nextFrame gt lt para gt This text appears on the next normal non included page of your document lt para gt This snippet switches to a new page template for use with your included pages adds in the first three pages from your PDF file switches back to what is presumably the template you have been using throughout the rest of the document and outputs a line of text into the next normal page of your document If you don t want any headers or footers behind your PDF pages define a page template called something like blank in the template section at the head pf your document with a single frame and no decoration on it and use that If you are content for your included pages to appear over the template you have been using on the previous pages Gif the included pages don t have any headers and footers and have large enough margins not clash with the ones you are using in your document for example then you can skip both of the secNextTempl
96. er 1 8 4 Entities Page 49 RML User Guide Document generated on 2014 09 25 13 10 59 Wom mow In example 6 we saw our first use of entities In RML you can t use the characters lt gt or amp inside any display elements such as drawString or para If you do rmD2pdf will assume that they are tags and attempt to interpret them Since they won t be valid RML tags you will just end up getting an error message along the lines of Error Start tag for undeclared element lt YourNonValidTag gt To get around this you should use entities When you need to use lt replace it with amp lt when you need to use replace it with amp gt and when you need to use amp replace it with amp amp 8 5 Aliases Aliases allow you to assign more than one name to a paragraph style The alias tag has two required attributes id and value Example alias id alreadyDefinedStyleName value myNewStyleName This can be useful in a number of ways You can give a more descriptive name to a style So you can define a number of paragraph styles called things like ItalicBold or DesignerOneParagraphStyleTwo inthe stylesheet for your document You can then assign aliases to these styles using names that describe the role they fill in your document such as pictureCaption abstract acknowledgement and so If at any point you decide to change the style for that kind of paragraph you can then
97. ess top line colour top cap butt round square top line count top line spacing left line thickness left line color left line cap butt round square left line count left line spacing right line thickness right line color right line cap butt round square right line count right line spacing User Guide Document generated on 2014 09 25 13 10 59 docAssert lt docAssert cond i 3 condition string required format The value of i is 5 __efgrmatstring gt docAssign lt docAssign string expr availableWidth expression string gt docElse lt docElse gt lt docIf cond i 3 condition string 7 gt docExec lt stmt i 1 statement string J gt docPara lt docPara expr availableWidth expression string format The value of i is __ style string escape yes yes 0 1 gt Page 123 RML User Guide docWhile docWhile cond i 3 gt drawing lt drawing module python_module baseDir function module_function hAlign CENTER showBoundary no gt widget lt widget baseDir module python_module function module_function name somename initargs someinitargs gt Paragraph like Elements para lt para style myfavoritstyle lt para gt Page 124 Document generated on 2014 09 25 13 10 59 condition string pa
98. f graphics on it while the rest of the pages are more text orientated Each pageTemplate tag must have the mandatory attribute id This gives the template a name and allows both rml2pdf and you to refer to it by name The lt pageTemplate gt tag also allows you to override the rotation and pageSize set by lt template gt tag As well as these attributes you can put any number of lt pageGraphics gt intoa lt pageTemplate gt lt pageGraphics gt are containers for the lt drawString gt and shape drawing commands we saw earlier In practice you may have two lt pageGraphics gt sections inside a pageTemplate The way this is interperted by RML2PDF is that the first one is carried out before the contents of the story for that page and the second one is carried out after the story This may be of use when you need some elements to overlap others and particularly useful when you are using the lt includePdfPages gt tag IncludePdfPages places a number of pages imported from another PDF file into your document placing them over the content you already have including any header and footers you have designed This may mean it obscures headers footers or something else you need on very page The way around this is to place your headers and footers in a second pageGraphics section which ensures that it will appear over anything in your story Provided you have sensibly defined frames it won t appear over the main content of y
99. few pages show a number of examples of blockTables Each one shows a page with RML listing followed by a separate page with the result of that table Each listing contains comments to point out what each tag involved with the blockTable is doing Page 93 User Guide Document generated on 2014 09 25 13 10 59 1 1 Example 10 Colors and fonts in tables This example show various ways of setting the text color ob lockTextColor font blockFont background color 01 for regions ina blockTable Notice the various ways of specifying a region within the table Also notice the way we have defined heights for the rows and widths for the columns in the blocktable tag EXAMPLE 10 lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM rml dtd gt lt document filename example_10 pdf gt lt template gt lt pageTemplate id main gt lt pageGraphics gt lt pageGraphics gt frame id first 1 72 1 72 width 451 height 698 gt pageTemplate template lt stylesheet gt lt blockTableStyle id myBlockTableStyle gt lt This sets a font for every cell from the start of the gt lt second row down to the bottom right hand corner gt lt blockFont name Courier Bold start 0 1 stop 1 1 gt lt 1 This sets a font for the first lt blockFont name Helvetica BoldOblique size 24 start 0
100. ficult layout cases The tags documented here have the potential to cause hard to understand exceptions if not used correctly Conditional formatting allows you to include expressions in your RML text which are evaluated or executed when the pdf is actually being built This means that you can vary the content of your document depending on conditions such as where you are on the page which you do not know in advance For instance you may be including dynamic content in your document which is likely to be of variable length You could use the value of one of the document s internal formatting variables to include or exclude certain content based on the remaining height of a page or the current page number One common use is in the case of creating documents for printing these could be padded with optional content to make sure that they are always a 4 page spread Another useful application would be deciding whether there is space to include a large image or diagram in the present location A working example using all of these tags be found in rlextra rml2pdf test test 039 doc programming rml Basic programming primitives assignment loop if while etc have been made available as tags These can be given expressions which can use your own variables as well as built in ones available during rendering expressions must be valid python literal expressions The following internal variables are available to use as conditions availa
101. geGraphic gt the illustration tag lets you do graphics operations in a box within the flow of the story or story like context such as a table cell The following example shows the use of both place and illustration EXAMPLE 9 lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM gt lt document filename example_9 pdf gt lt template gt lt pageTemplate id main gt lt pageGraphics gt grid xs lem Zem Jem Acem 5cm 10cm 20cm Zem Jem 4cm 5cm 10cm 20cm gt place x 10 5cm y 10 5cm width 9cm height 9cm gt lt title gt This is a use of lt i gt place lt i gt lt title gt lt spacer length 15 gt lt para gt This 18 flowable In this case it is in a amp lt para amp gt tag but it could be any flowable It has been placed inside grid but you could put it inside any graphic or pageGraphics Using the place tag you can have complete control over where you want your flowables to appear para spacer length 12 gt Page 77 User Guide Document generated on 2014 09 25 13 10 59 lt para gt You can include Greek lt greek gt abgd lt greek gt lt para gt spacer length 12 gt lt blockTable gt lt tr gt lt td gt Or lt td gt lt td gt even lt td gt lt tr gt E r lt td gt a lt td gt lt td gt blockTable lt td gt xn lt blockTable gt lt place gt
102. gt lt expr format style creates a paragraph containing the value of format is an optional attribute which can contain the value of expr using the Python string formatting conventions eg expr Js The style attribute is optional eg docPara expr i format The value of is style style txt So if i 2 this results in the text The value of i is 2 docAssert cond format raises an error containing the value of format if cond is false eg eg docAssert cond val format val is false gt docWhile cond gt lt docIf cond Page 82 RML User Guide Document generated on 2014 09 25 13 10 59 docElse these tags allow flow control while or if the cond attribute evaluates to true See the example above Page 83 RML User Guide Document generated on 2014 09 25 13 10 59 12 Printing This chapter covers things you will need to know when creating documents for professional printing Many development projects start off targeting an electronic document which users will either keep on disk or print out on an office or home printer Once you start targeting professional printing presses things get more complicated We have tried to write this in a manner accessible to developers with little prior knowledge of print apologies to professional printers for anything we have glossed over too lightly The topics covered in
103. gt Page 57 RML User Guide Document generated on 2014 09 25 13 10 59 lt letterBoxes x 0cm count 12 gt more letterboxes lt letterBoxes gt lt letterBoxes y 4 5cm boxWidth 0 75cm count 12 gt letterboxes lt letterBoxes gt lt letterBoxes x 0cm y 3cm lineWidth 0 1cm boxFillColor yellow boxStrokeColor blue label some label count 12 gt letterboxes lt letterBoxes gt lt letterBoxes x 0cm y 1 5cm lineWidth 0 1cm boxFillColor yellow boxStrokeColor blue label some label fontName Courier Bold fontSize 14 count 12 gt letterboxes lt letterBoxes gt lt letterBoxes y 0cm lineWidth 0 1cm boxWidth 0 75cm boxHeight 0 75cm boxFillColor yellow boxStrokeColor blue label some label fontName Times Bold fontSize 14 count 12 gt letterboxes lt letterBoxes gt Fb 808 some label some label some label There may also be instances where you want obvious dividers between each subcell but you don t want entirely separate boxes Letterboxes have something that allows for this the optional combHeight attribute In a standard letterBoxes element ie one where the combHeight isn t specified the divider between each individual subcell is a line which fills the whole height of the letterBoxes box If you specify the combHeight you can vary the height of this line Th
104. he Pantone Color Matching System The CMYK process is a method of printing colour by using four inks cyan magenta yellow and black White is the absence of any colour The Pantone system is a popular spot colour system which describes a set of completely standardized colours allowing different manufacturers in different locations to ensure that their colours match The majority of printed material is produced using the CMYK process Many Pantone colours have good well known CMYK equivalents RML allows you to specify colours as CMYK or by spot name and also provides a mechanism for ensuring that your document sticks to a particular set of colour definition types Starting in ReportLab 2 5 a colorSpace attribute can be defined in the lt document gt tag This is a declaration of your intent and it lets us carry out some useful checks on your behalf It will raise an error if you accidentally use a colour that is not allowed in your colorSpace Then to declare a CMYK colour use the lt color gt tag within the lt docinit gt section at the top lt document filename test_045_separations pdf invariant 1 colorSpace CMYK gt color id BLUE CMYK 1 0 67 0 0 23 lt color id CYAN CMYRSUDTLOLOLO S Page 85 RML User Guide Document generated on 2014 09 25 13 10 59 Note that each colour component ranges from 0 to 1 not 0 to 100 you can use any floating point number in between Designers tend to thi
105. his is the case then rml2pdf will count backwards from the end of the last cell So 1 1 is the bottom right hand cell in a table 2 2 is the one up and to the left of that and so on The tags that blockTableStyle can contain are blockFont blockfont sets font to be used in a block of your table It has one mandatory attribute name It has four optional attributes size leading start and stop blockTextColor This sets the color that will be used for the text in a block of your table It has one required attribute colorName It has two optional attributes start and stop a blockLeading This sets the leading that will be used for the text in a block of your table It has one required attribute Length It has two optional attributes start and stop m blockAlignment This sets the alignment of the text in a block of your table It has one required attribute value This can be LEFT RIGHT CENTER or CENTRE It has two optional attributes start and stop m blockValign This sets how the contents of a block of cells in your table are aligned in the vertical direction It has one required attribute value This can be TOP MIDDLE or BOTTOM and defaults to BOTTOM It has two optional attributes start and stop Page 91 RML User Guide Document generated on 2014 09 25 13 10 59 blockLeftPadding This sets the padding i e blank space between the contents of a cell and left hand edge
106. his makes it easier to see what each style is defining see the example below for how this looks One attribute for paraStyle that isn t the same as those used by para 15 parent attribute Once you have defined a style using a lt paraStyle gt tag you can use those settings as a basis for other styles parent allows one style to inherit from another The other attribute that isn t shared by para tag is backColor As you can probably guess this attribute sets a background color for the paragraph it is describing The following optional attributes for paraStyle the same as those for the para tag you can find more description of them in the Advanced text section below fontName fontSize leading leftIndent rightIndent firstLineIndent alignment spaceBefore spaceAfter bulletFontName bulletFontSize bulletIndent textColor Here is an example of how the lt stylesheet gt tag might look in use lt stylesheet gt lt initialize gt lt alias id style normal value style Normal gt lt initialize gt lt paraStyle name h1 fontName Courier Bold fontSize 12 spaceBefore 0 5 cm 55 lt paraStyle name 2 stylel fontName Courier fontSize 10 lt paraStyle name style2 parent stylel leftIndent lin lt paraStyle name style7 parent stylel leading 15 leftIndent lin rightIndent lin lt stylesheet gt Page 34 RML User Guide Docu
107. how the document would appear when printed The default for is usually to for the topmost colour to knock out the colour underneath overprint mode overprint turns on overprint for the drawing operations that follow You can then set this property to its original value with lt overprint mode knockout gt when you want to go back into the default knock out mode Page 86 User Guide Document generated on 2014 09 25 13 10 59 The sample first example above shows cyan magenta and yellow circles overlapping one another set to overprint and rendered in Acrobat Professional Without overprint set in the second example the inks do not mix on top of each other Instead the circles on top knock out the areas that they cover underneath 12 6 Colour separations When a PDF document is printed professionally layers of coloured ink plates will be printed one at a time on top of each other laying down microscopic dots on different angled paths so that more than one colour can be visible The process colours CMYK will normally have a plate each for full colour printing but you can define your own spot colour plates to be printed with a specialist bucket of ink One common use is for companies to have completely standardised colours in their corporate literature and to be able to print with just 3 plates instead of the usual 4 which saves money and increases consistency Another case is using metallic foils or fluorescent paints
108. ibute which allows you to refer to your style by another name parent If this is supplied it must refer to the name of another style This style with then inherit from the style named fontName An optional attribute this refers to the font to be used for the main contents of letterboxes or a textbox it is ignored for checkBoxes fontSize This optional attribute sets the size for the main contents of letterboxes or a textbox it is ignored for checkBoxes Page 59 RML User Guide Document generated on 2014 09 25 13 10 59 alignment For letterboxes or a textbox this optional attribute sets the alignment of the contents of the box It may be either LEFT RIGHT CENTER or CENTRE It is ignored for checkBoxes textColor An optional attribute that sets the colour for the main contents in the letterboxes or textbox labelFontName The optional tag specifying the font to be used for the label of the letterboxes textbox or checkBox labelFontSize The optional tag specifying the size of the font to be used for the label of the letterboxes textbox or checkBox labelAlignment The optional specifying the alignment of the label may be LEFT RIGHT CENTER or CENTRE labelTextColor An optional attribute specifying the colour to be used for the text of the label of an textBox letterBox or checkBox boxFillColor An optional tag specifying the colour to be used for the background for a textBox
109. id someid type sometype default somedefault gt Page 154 Document generated on 2014 09 25 13 10 59 string measurement measurement string XYZ Fit FitH FitV FitR measurement measurement measurement measurement string string string integer string string string RML User Guide param lt param name somename gt registerCidFont lt registerCidFont faceName VeraBold encName WinAnsiEncoding gt registerFont lt registerFont name somename faceName VeraBold encName WinAnsiEncoding gt registerFontFamily lt registerFontFamily normal VeraBold bolda yeraBold italic VeraBold boldItalic VeraBold gt registerTTFont registerTTFont faceName VeraBold fileName somefileName gt registerType1Face lt registerTypelFace afmFile DarkGardenMK afm pfbFile DarkGardenMK pfb gt Page 155 Document generated on 2014 09 25 13 10 59 string font name string string string font name string string font name string font name string font name string font name string font name string string string string RML User Guide restoreState lt restoreState gt saveState lt saveState gt setFont lt setFont name somename size lin leading 4 gt setFontSize lt setFontSize size lin leading 4 gt Log tags log lt log lt log gt debug lt debug gt lt debug gt Pag
110. ion although you cannot separate an illustration from its frame as you can with lt storyPlace gt storyPlace takes 4 required attributes and one optional one x and y are the x and y co ordinates for where you want the flowables placed width and height are the width and height of the flowable Finally Page 31 RML User Guide Document generated on 2014 09 25 13 10 59 the origin canbe one of pagelframellocal If not specified local is assumed The origin attribute specifies where the x and y attributes are based Examples lt storyPlace x 0 width 18cm height 1cm origin page gt lt para gt This is at the bottom of the page lt para gt lt storyPlace gt lt storyPlace x 0 width 18cm height l1cm origin frame gt para Ihis is at the bottom of the current frame lt para gt lt storyPlace gt lt storyPlace x 0 width 18cm height 1cm origin local lt para gt This is at the current frame position lt para gt lt storyPlace gt 6 5 pto Please Turn Over Control The lt pto gt tag is a flowable container that holds an arbitrary number of other flowables The first two may be special pto trailer or pto header tags each of which may contain arbitrary flowables The idea is that the trailer flowables are issued at the bottom of the page whenever the main container flowables split the header flowables appear at the top of the next frame pto pto trailer
111. ipse x 417 y 382 25 width 507 height 552 25 fill yes stroke yes gt color black gt lt drawCentredString x 127 5 y 357 gt Ellipse with stroke but fill lt drawCentredString gt lt drawCentredString x 297 5 y 357 gt Ellipse with fill but no stroke drawCentredString drawCentredString x 467 5 y 357 gt Ellipse with both stroke and fill lt drawCentredString gt lt rect x 84 5 y 214 3 width 1 in height 1 15 in fill no stroke yes gt lt fill color green gt lt stroke color black gt rect 254 5 yc 214 3 wadth 1 an herzght 1 15 in fill yes stroke no gt lt fill color blue gt lt stroke color black gt rect 424 5 yc 214 3 wudth l an herzght 1 15 in fill yes stroke yes gt fill color black gt lt drawCentredString x 127 5 199 1 gt Rect with stroke dut me Eili lt drawCentredString gt lt drawCentredString x 297 5 y 199 1 gt Rect with 51 11 but stroke drawCentredString Page 20 User Guide Document generated on 2014 09 25 13 10 59 lt drawCentredString x 467 5 199 1 gt Rect with both stroke and fill lt drawCentredString gt rect 84 5 56 5 width 1 in height 1 15 fill no stroke yes round 0 15 in gt lt fill color green gt lt stroke color black gt rect 254 5 y 56 5
112. is attribute must be a number between zero and one where 0 means no Page 58 RML User Guide Document generated on 2014 09 25 13 10 59 divider at all and 1 means one that is the whole height of the letterboxes element and therefore 0 25 is a quarter of the height and so on The following code creates a row of sample letterboxes showing the combHeight attribute in use lt letterBoxes y 0cm combHeight 0 count 4 gt comb lt letterBoxes gt lt letterBoxes x 3 75cm combHeight 0 25 count 4 gt comb lt letterBoxes gt lt letterBoxes x 7 5cm combHeight 1 count 4 gt comb lt letterBoxes gt lt letterBoxes x 11 25cm lineWidth 0 1cm boxWidth 0 75cm boxHeight 0 75cm boxFillColor yellow boxStrokeColor blue label combHeight fontName Times Bold fontSize 14 combHeight 0 5 count 4 gt comb lt letterBoxes gt combHeight Using styles with form field elements As we ve already mentioned checkBox textBox and letterBoxes all allow you to re use styles ina similar way to the way you can re use styles with paragraphs with the boxStyle tag Like the other style tags paraStyle and blockTableStyle boxStyle lives stylesheet section near the start of your document boxStyle style can have the following attributes name This is the required attribute which allows you to refer this style by name alias An optional attr
113. ll appear in the default style for pre formatted text This uses a fixed width typewriter font such as courier and is useful for things such as program listings but may not be what you want for your quotation or whatever If you have already defined a style in the stylesheet section of your document then you can make the lt pre gt tag use this for your pre formatted text Page 39 User Guide Document generated on 2014 09 25 13 10 59 Example lt xpre style myStyle gt this is pre formatted text lt xpre gt The code endcode is similar to code pre endcode tag in that it preserves line breaks where they are placed in the text but code endcode also permits paragraph annotations such as bold face and italics and font changes For example the following mark up lt xpre gt this is an lt i gt xpre lt i gt lt b gt example lt b gt lt font color red gt including red text lt font gt lt xpre gt generates the following text this is an xpre example including red text 7 9 Greek letters The lt greek gt tag is used for producing Greek letters in RML This is of most use for equations and formulae Example In physics Planck s formula for black body radiation can be expressed as RA c 4 8x X hc A 1 e T In RML this is expressed as R greek l greek c 4 8 lt greek gt p lt greek gt lt greek gt 1 lt greek gt
114. lt super gt 4 lt super gt hc greek l greek 1 e lt super gt hc lt greek gt 1 lt greek gt kT lt super gt 1 For a table of the Greek letters used by the lt greek gt tag and their representations in RML look in Appendix C at the end of this manual This next example show features from several of the commands describes in the previous sections such as the use of frames the options to the template tag stylesheets and so on See the next section for information on using the lt name gt getName tags EXAMPLE 5 lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCIYPE document SYSTEM rml dtd gt lt document filename example_5 pdf gt template pageSize 21cm 29 7cm leftMargin 2 5cm rightMargin 2 5cm topMargin 2 5cm bottomMargin 2 5cm Page 40 User Guide Document generated on 2014 09 25 13 10 59 title Example 5 templates and pageTemplates author Reportlab Inc Documentation Team showBoundary 1 allowSplitting 20 gt lt showBoundary means that we will be able to see the lt limits of frames lt pageTemplate id main gt lt pageGraphics gt lt pageGraphics gt frame id titleBox x1 2 5cm 1 27 7 width 16cm height 1cem gt frame id columnOne 1 2 5 yl 2 5cm width 7 5cm height 24 7cm gt frame id columnTwo 1 11 yl 2 5cm width 7 5cm height 24 7cm gt lt p
115. me id chapterNumber gt lt seq id sectionNumber gt Installation and Use h2 para RML2PDF is available in several formats etcetera para And unless the creator takes great care it may be necessary to adjust various section or chapter numbers in other entries as well To avoid this complexity this document is not directly written in RML per se but is written using a text preprocessor called code endcode which automatically builds the table of contents and inserts the appropriate entries at the top while keeping track of chapter and section numbers For very complex documents using a preprocessor of some sort may be advisable Page 65 RML User Guide Document generated on 2014 09 25 13 10 59 10 More graphics 10 1 curves We have seen how you can use the lt lines gt tag to create a number of straight lines with one command Not all the lines you want to draw will be straight which is why we have the lt curves gt tag Like lt lines gt lt curves gt must appear inthe pageGraphics section of your template Unlike lines you need to specify 4 points as X Y co ordinate pairs i e you need to feed curves sequences of 8 numbers at a time rather than the 4 you need for 1ines The curves tag produces a Bezier curve Bezier curves are named after the French mathematician Pierre and are curves that utilize at least three points to define a curve RML curves use th
116. ment generated on 2014 09 25 13 10 59 stylesheets also allow you to define styles for other tags you can define styles for blockTables with the lt blockTableStyle gt tag or the various form creation elements checkBoxes let terBoxes and textBoxes with the boxStyle tag Refer to the sections on blockTables and Form Field Tags later in this document for details on how to use these Page 35 RML User Guide Document generated on 2014 09 25 13 10 59 7 Advanced text 7 1 Title The lt title gt tag sets the title for a document or a section of a document and displays it on the page By default this is set in a larger typeface than the body text in a similar way that headers are You can change the way title is set by setting a style called style Title inthe stylesheet section of your document Note This tag does not affect what is displayed in the title bar at the top of a document Example lt stylesheet gt lt paraStyle name style Title fontName Courier Bold fontSize 36 leading 44 Wes lt stylesheet gt lt title gt This is the Title lt title gt lt para gt And it should be set in 36 pt Courier Bold lt para gt lt story gt 7 2 Headings h1 h2 h3 Headings are also handled in the same way as in HTML The most important heading level has its text enclosed by lt 1 gt and lt 1 gt tags and less important sub headings use the lt h2 gt lt h2 gt and lt h3
117. n 2014 09 25 13 10 59 measurement measurement color measurement measurement boolean measurement measurement Graphical Drawing Operations drawString lt drawString x lin ge Tin gt lt drawString gt measurement measurement Page 133 optional optional Sequence of top level flowables optional optional optional optional optional optional Sequence of top level flowables required required RML User Guide drawRightString lt drawRightString 1 ye rn drawRightString drawCentredString lt drawCentredString lt drawCentredString gt drawCenteredString lt drawCenteredString Ape lt drawCenteredString gt ellipse lt ellipse 1 2d y E in width 5cm height 3cm fill true stroke false gt Document generated on 2014 09 25 13 10 59 measurement measurement measurement measurement measurement measurement measurement measurement measurement measurement truth value truth value Page 134 required required required required required required required required required required RML User Guide circle lt circle gt rect lt rect gt grid lt grid gt lines lt lines gt lin lin 2in lin Zan zum lin 3in 2in lt lines gt x y Din radius 3cm fill true stroke false 11
118. n referring to lights such as on a computer screen RML Report Markup Language An XML dialect created by ReportLab Inc and and used by their software rml2pdf to produce documents in PDF singletons See empty elements story The part of an RML document where the main content of a document goes if it uses the template stylesheet story form This is where text split into paragraphs by para tags is put Page 114 RML User Guide Document generated on 2014 09 25 13 10 59 stroke In RML the color of the outline of a graphic or text item as opposed to that of its inside or 111 stylesheet This is an obligatory part of an RML document It is where the styles for paragraphs and blockTables are defined though it can be empty template In those RML documents that use template stylesheet story form this is the part of the document where any headers footers or background graphic elements are defined vanilla Plain ordinary or standard from the default flavor of ice cream in the U S In RML you can put in letters numbers and punctuation in places which allow you to use vanilla text but tags such as para or lt b gt are not allowed whitespace For programmers whitespace refers to all the characters that appear as blanks on your screen This includes the space and tab characters linefeeds carriage returns and other more specialised characters For designers whitespace is any areas on a
119. nd blue RGB components in the color the first two digits represent red the next two green and the last two the blue The 0x just shows it s a hexadecimal number Text 123 Text 123 OO Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 Text 123 0000090000050 000005000 aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflower cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen darkkhaki darkmagenta darkolivegreen darkorange darkorchid Page 108 Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex Hex xFOFSFF xOOFFFF x FFFDA xFOFFFF xF5F5DC 4 4 x000000 xFFEBCD x0000FF x8A2BE2 52 2 x5F9FA0 7 xD2691E xFF7F50 x6495ED xDC143C xOOFFFF x00008B x008B8B xB8860B XA9A9A9 x006400 xBDB76B x8B008B x556B2F 8 00 x9932CC RML User Guide
120. nk in terms of 0 100 but we have chosen to follow the PDF specification The 14 is a string you specify You will then be able to refer to these colours name elsewhere a document for example you can then set a table cell background or paragraph style to be BLUE The colorSpace attribute is particularly important when dealing with blacks Many objects in our framework have default colour of black and this is an RGB black under the hood If you set the colorSpace our framework will auto convert blacks for you thus if a table s gridlines or a chart axis is normally drawn in black or a shade of grey implemented originally as RGB it will be autoconverted to CMYK black or grey Many printing presses are able to handle RGB and autoconvert blacks these days but printers will appreciate it if the PDFs are pure CMYK as it won t raise alarms in their proofing tools 12 4 Images in CMYK documents Most bitmap images use an RGB colour model We do NOT yet have safeguards to check images that you include in a CMYK document the colorSpace checks won t warn you We might add this checking in a future version If you are working with a limited number of images the best approach is to use a professional tool like Photoshop to create CMYK versions of those images and check you are happy with the colours when printed Printers can often handle RGB images in a print job but it s best to check with them first 12 5 Overprint and knock
121. nt or the vertex can be rounded or squared off into a bevelled join The possible values for join are round mitered or bevelled The cap attribute to 1ineMode adjusts how the ends of lines appear The end of a line can have a square end exactly at the vertex a square end that is extended so it is over the vertex or a half circle a rounded cap These possible values for cap are default square or round P Y cap default cap round cap square Figure 5 Example of lineMode attribute cap Both the join and cap attributes for lt lineMode gt are only really visible if the line you are applying them to is thick Another attribute to lt lineMode gt is dash This allows you to specify if the line is dotted or dashed You supply it a series of numbers separated by commas and it takes them as a pattern for how many pixels the line is on for and then how many pixels the line is off i e not displayed for This can be a simple pattern such as 1 2 which gives you a plain dotted line or 5 5 which makes the lines sections equal with the spaces or as complex as 1 1 3 3 1 4 4 1 a complex pattern of dots and dashes QU i 3 4 i wv dash z 55 dash z 2 10 dash 5 5 2 10 Figure 6 Example of lineMode attribute dash The following example shows examples of most of the attributes that you can use with lt 11 gt and lineMode Notice
122. ode attribute must be present In order to prevent possible formatting anomalies the default value should be approximately the same size as the expected final value 9 2 Multiple pass pdf formatting RML2PDF resolves names that are referenced before they have been defined by making by default at most two passes through the text If the first pass does not define all names before they have been referenced then RML2PDF formats the document twice On the first pass the default value for any undefined name is used for formatting the document and it may under some circumstances effect the placement of the page breaks On the second the program uses the resolved value determined on the first pass where the name is referenced It is possible to create a chain of references that cannot be resolved such as namedString id a gt lt name id b default XXX namedString namedString id b gt lt name id a default XXX namedString In this case code RML2PDF endcode will signal an error and fail It is also possible to have a chain of references which requires more than one pass to resolve such as Page 63 RML User Guide Document generated on 2014 09 25 13 10 59 namedString id a gt lt pageNumber gt is where is defined and name id b default XXX namedStrinc namedString id b gt lt pageNumber gt is where B is defined and name id c default XXX namedStrinc namedString id c
123. ontent elements will be merged onOverflow this specifies the action to be taken if the contents is too large Allowed values are code Jerror endcode ie raise an error Page 32 User Guide Document generated on 2014 09 25 13 10 59 code overflow endcode just scrawl all over the page code shrink endcode shrink the contents to fit the allowed space amp code overflow endcode truncate the contents at the borders of the allowed space The example below shows how to cram star fields into a one inch square XkeepInFrame maxWidth 72 maxHeight 72 gt para style h1 gt A header lt para gt lt para style bt gt Many vast star fields in the plane of our Milky Way Galaxy are rich in clouds of dust and gas First and foremost visible in the above picture are millions of stars many of which are similar to our Sun Next huge filaments of dark interstellar dust run across the image and block the light from millions of more stars yet further across our Galaxy lt para gt lt keepInFrame gt 6 7 imageAndFlowables tag The lt imageAndFlowables gt tag allows flowables to flow around an image Errors will be caused by attempts to use lt nextFrame gt and similar tags inside the lt imageAndFlowables gt container The lt imageAndFlowables gt tag takes several attributes imageName the name of the image file or path imageWidth the width of the image using 0 will cause the pixel
124. ormatting rtis ese tbe eH OP de 62 9 3 Calculated Page Numbers evalString 63 9 4 Generated RM sioe pt cbe toi nitidi dirt ae 63 10 More graphics 65 TIO TAG Be oed deine 65 102 pc M E M EE M acc RE 66 pri sta onte da beds tease aaa uae eet a late 69 y alaq aqu NL eo DA en bdo 69 TO SCALING na a h us luu e Rete tote Pao etse fO s 70 quinua an eie 71 ou 12 10 8 Generic affine transforms ei rs os 73 10 9 About scale rotate and skew 73 10 10 Bitmapped images aes e t 74 TOT Test ema o dU abt tib UM M dE 74 10 12 placeand a 74 RML User Guide Document generated on 2014 09 25 13 10 59 edel ata 76 10 14 Formand ined 78 10 15 W Sc Se TOTS ate t 76 11 Conditional Formattinsg 80 T3 Introeduetioliaya a D S SS yu
125. orms is the barCode tag As its name implies this creates a barcode in one of a number of different symbologies The three attributes you need to supply for this tag are x and y to position it on the page and code to inform rml2pdf which form of barcode you require This is a brief example of what a barcode tag looks like in use and what it actually produces 0 code Codell 123456 barCode Figure 10 The 11 barcode This table shows you the allowed names for the code attribute along with an example of the barcode produced come 7o mmo CU CU idi Page 61 User Guide Document generated on 2014 09 25 13 10 59 i EVER USPS FIM 8 11 Colorspace Checking 2 5 supports a way to ensure the consistent enforcement of color models within a document For more information on this topic and examples of when you might want to use different scenarios please refer to the Printing chapter later in this document RGB CMYK and the use of spot colors such as Pantone can be allowed or disallowed using the colorSpace parameter to the document tag which can be set to the following values MIXED The default As in RML versions before 2 5 rgb cmyk spot colors and named colors can all be used RGB Permits only the use of RGB colour values CMYK Permits only the use of
126. our page but it will appear over the top of your included PDFs Page 30 RML User Guide Document generated on 2014 09 25 13 10 59 allowing you to have the same look and feel for these pages as you do for the rest of your document See section 8 8 Integrating with PageCatcher catchForms doForm and includePdfPages for more info on the lt includePdfPages gt tag 6 2 Frame and nextFrame As well as containing lt pageGraphics gt each pageTemplate also contain frames These frames can split the page into more than one region For each frame pageTemplate you must supply an id the X and Y co ordinates of the bottom left hand corner as well as the width andheight of the frame You can have one frame ina page or use two or more to split it into multi column layout Frames really come into their own when you use paragraphs and flowables see the section on Advanced text below This is how it looks in practice When you are using text in lt gt lt gt tags you can use the lt nextFrame gt tag to force it into the next frame on the page Look at the section on Advanced text later in this document for more details on this An additional attribute overlapAttachedSpace canbesetto 0 or1 to force the frame to overlap space that is implicitly attached to flowables by their styles See section 6 5 on styles The default value for this attribute is set using the site wide configuration for re
127. out control When you create a document with two colours layered on top of one another there are different ways to combine them The two alternatives are known as overprint and knockout Non primary CMYK colours are of course already implemented with a mix of up to four inks problem arises when you decide to stack two colours on top of each other Imagine you have a red and a blue CMYK colour which are each made up of say 6096 black the K in CMYK and you want to draw one on top of the other Should the software merge the colours It can t achieve 120 coverage with the black So a decision is needed Either the topmost colour knocks out and replaces anything drawn underneath it or it overprints allowing the colours to mix in a manner similar to transparency When working with separated colours see below the printing mechanics are a little different as each colour is really a bottle of ink but again a statement of intent is needed when they overlap does the top colour replace what s underneath or allow both to be laid down on the page The overprint versus knockout choice is rarely used and works in slightly different ways for CMYK and for separated colours see the section below Designers will know when they need it and the developer merely needs to set a flag Some PDF viewing software can simulate this effect on screen Adobe Reader is one of them it s necessary to go into the preferences and check a box to see
128. own as JFIF JFI and JPG as well as JPEG You can use JPEG files in your RML document with the image tag see also bitmap cif image jpg See JPEG leading Leading pronounced ledding is the amount of vertical space allotted for a line of type the distance between the baseline of one line to the baseline of the next The name comes from the way that printers used to use thin strips of lead or brass to separate the lines of metal type In RML leading can be supplied as an attribute for the para and paraStyle tags It is expressed as the height of the line plus the space between lines So for example using a 12 point font with a leading of 18 gives you a space between lines of 6 points You can also have negative leading By giving a number smaller than the size of font you are using you can arrange it so that the lines overlap each other orthogonal An adjective from mathematics meaning relating to or composed of right angles A non orthogonal transformation is one which does not preserve right angles skew is a non orthogonal transformation PDF The Portable Document Format format created by Adobe this is a standard for electronic documents which is platform independent due to the freely available Acrobat reader The PDF file format is a complex indexed binary format with a specification 600 pages long RML is much easier RGB A way of specifying a color by its Red Green and Blue components Usually used whe
129. page that aren t the content the bits that are free of text or artwork XML The Extensible Markup Language a document processing standard set by the World Wide Web Consortium W3C the people who defined the standard for HTML Page 115 User Guide Document generated on 2014 09 25 13 10 59 Appendix C Letters used by the Greek tag Greek Letter RML Representation Greek Letter RML Representation lt greek gt a lt greek gt A lt greek gt A lt greek gt lt greek gt b lt greek gt B lt greek gt B lt greek gt 7 lt greek gt c lt greek gt x lt greek gt C lt greek gt lt greek gt d lt greek gt A lt greek gt D lt greek gt lt greek gt e lt greek gt lt greek gt E lt greek gt lt greek gt f lt greek gt lt greek gt F lt greek gt Y lt greek gt g lt greek gt lt greek gt G lt greek gt n lt greek gt h lt greek gt H lt greek gt H lt greek gt 1 lt greek gt i lt greek gt I lt greek gt I lt greek gt lt greek gt j lt greek gt 9 lt greek gt J lt greek gt K lt greek gt k lt greek gt K lt greek gt K lt greek gt lt greek gt l lt greek gt lt greek gt L lt greek gt H lt greek gt m lt greek gt M lt greek gt M lt greek gt lt greek gt n lt greek gt N lt greek gt N lt greek gt o lt greek gt o lt greek gt O lt greek gt O lt greek gt T greek p greek II greek P greek 0 lt greek gt q lt greek gt lt greek gt Q lt greek gt
130. para spacer length 6 gt para If you are going to use multiple seq tags you need to use the id attribute lt gt lt h2 gt lt i gt Better use of seq lt i gt hao para seqDefault id test gt We have just done amp lt seqDefault id test gt para para seqReset id test We have just done a amp lt seqReset id test amp gt para spacer length 6 gt para First seq seq id test para para Second seq seq id test para spacer length 6 gt para seqReset id test We have just done a amp lt seqReset id test amp gt para spacer length 6 gt para First seq after seqReset seq id test gt para para second seq after seqReset seq id test para lt h2 gt lt i gt Using two seqs independently lt i gt lt h2 gt lt para gt lt seqReset id testOne gt We have just done amp lt seqReset id testOne amp gt para para lt seqReset id testTwo gt We have just done amp lt seqReset id testTwo amp gt para Page 47 User Guide Document generated on 2014 09 25 13 10 59 lt spacer length 6 gt lt para gt First seq for testOne lt seq id testOne gt lt para gt lt para gt Second seq for testOne lt seq id testOne gt lt para gt lt spacer length 6 gt lt para gt First seq for testTwo lt seq id test
131. para gt lt story gt lt document gt The lt pageTemplate gt lt pageGraphics gt lt frame gt and lt paraStyle gt tags will all be covered in more detail later on in this guide Paragraphs start with a para tag and are closed witha lt para gt tag Their appearance can be controlled with the lt paraStyle gt tag RML allows you to use comments in the RML code These are not displayed in the output PDF file Just like in HTML they start with a lt and are terminated with a gt Unlike other tags comments cannot be nested In fact you can t even have the characters inside the lt gt section Page 14 RML User Guide Document generated on 2014 09 25 13 10 59 3 Basic Text Operations 3 1 Coordinates and measurements In RML the page origin is in the bottom left hand corner 0 0 Any point on the page can be specified by a pair of numbers a pair of X Y co ordinates The X co ordinate states how far to the right the point is and the Y co ordinate states how far up it is When an RML element has co ordinates the co ordinate origin is the lower left corner In the case of elements in a pageGraphic the origin of the lower left corner of the page For elements within an lt illustration gt the origin is the lower left corner of the bounding box declared by the lt illustration gt These co ordinates and any other measurements in an RML document can be given in one of four
132. plate lt setNextTemplat name indextemplate gt condPageBreak lt condPageBreak height 10cm gt Page 130 Document generated on 2014 09 25 13 10 59 string string int or string frame index int or string frame index required string template name required measurement required RML User Guide storyPlace lt storyPlace x y Tin height 3in origin page gt lt para gt lt para gt lt table gt lt table gt lt storyPlace gt maxWidth int maxHeight int frame frameindex mergeSpace 1 0 onOverflow error overflow shrink truncate id name gt lt para gt lt para gt lt table gt lt table gt lt keepInFrame gt imageAndFlowables Page 131 Document generated on 2014 09 25 13 10 59 measurement required measurement required measurement required measurement required page frame or local optional Sequence of top level flowables maximum width or 0 maximum height or 0 optional frameindex to start in whether padding space is merged over flow behaviour name for identification purposes Sequence of top level flowables RML User Guide lt imageAndFlowables imageName path imageWidth float imageHeight float imageMask color imageLeftPadding float imageRightPadding float imageTopPadding float imageBottomPa
133. portlab in reportlab rl config py 6 3 condPageBreak conditional page breaks The condPageBreak isa CONDitional Page Break To use it you give it a height in any units that RML can handle It then compares this height with the remaining available space on a page If the space is sufficient then the next elements are placed on the current page but if there is less space than the height you have given it anything following the lt condPageBreak gt tag is continued on the next page That is what happens on pages with only one frame On pages that have multiple frames this tag acts as a conditional frame break If the space in the current frame isn t enough it will break and place what follows in the next frame rather than on the next page The tag and its syntax still remain the same This tag is particularly useful with large tables where you want the whole table to be presented on one page rather than split between two It can also be used where you have a collection of images and you want them all to be on the same page condPageBreak has only one attribute the mandatory one of height Examples condPageBreak height lin gt condPageBreak height 72 gt 6 4 storyPlace out of band flowables The lt storyPlace gt container is a flowable story that s placed This allows for dynamically specified frames to be constructed in the story This tag is like having an illustration amp place combinat
134. r row gt lt blockValign value TOP start 0 0 stop 1 0 gt lt This sets the vertical alignment for cell gt lt blockValign value MIDDLE start 2 2 stop 2 2 gt 1 Use of linestyles gt lt lineStyle kind GRID colorName silver gt lt lineStyle kind LINEBELOW colorName orangered start 0 0 stop 1 0 thickness 5 gt lt lineStyle kind LINEAFTER colorName maroon start 1 1 stop 1 6 thickness 1 gt lt blockTableStyle gt lt stylesheet gt Sg y lt title gt Example 11 lines and alignment tables lt title gt spacer length 1cm gt Page 99 User Guide Document generated on 2014 09 25 13 10 59 lt blockTable style myBlockTableStyle rowHeights 2cm 2cm 2cm 2cm 2cm 2cm 2cm colWidths 4cm 3cm 3cm 4cm gt lt td gt a LEFT VA TOP lt td gt td VA TOP lt td gt td VA TOP lt td gt lt td gt a RIGHT VA TOP lt td gt td lt td gt 2 1 lt td gt td a RIGHT lt td gt lt td lt td gt dd ode ic td VA MIDDLE lt td gt td a RIGHT lt td gt td lt td gt lt a td VA MIDDLE lt td gt td VA MDL a RIGHT lt td gt lt xor td lt td gt clc ds ta lt td gt a RIGHT lt
135. rString gt color lt color id footerString RGB 77aa00 gt pageNumber lt pageNumber countingFrom 2 gt Page 152 Document generated on 2014 09 25 13 10 59 string required string required string required string required string required string required hexidecimal red green blue values integer RML User Guide outlineAdd lt outlineAdd level 1 closed true gt Chapter 1 section 2 lt outlineAdd gt cropMarks lt cropMarks borderWidth 36 markWidth 0 5 1 markLength 18 gt startindex lt startIndex name somename offset 0 format ABC gt index lt index name somename offset 0 format ABC gt showlndex lt showIndex name somename style somestyle tableStyle sometablestyle gt Page 153 Document generated on 2014 09 25 13 10 59 integer truth value outline entry text integer float color integer string integer 123 string integer 123 string string string string RML User Guide bookmark lt bookmark name somename 11 lin gt bookmarkPage lt bookmarkPage name somename fare XYE IPIEtDIEPITEHIFAEV ERZEB T tope 115 bottom lin left lin lan zoom somezoom gt join lt join type sometype gt length lt length id someid value 4 gt lt namedString
136. raphics Flowables include the following tags para blockTable title hl h2 h3 spacer illustration pre andplugInFlowable see also graphics GIF GIF Graphics Interchange Format is a bit mapped graphics file format created by CompuServe in 1987 It is still in common use on the World Wide Web and many other places today You can use gifs in your RML document with the image tag see also bitmap JPEG image graphics In RML graphics are items which can appear inside the pageGraphics andillustration tags Unlike flowables graphics are explicitly positioned on the page by co ordinates They can not be mixed with Page 113 RML User Guide Document generated on 2014 09 25 13 10 59 flowables see also flowables HTML The Hyper Text Markup Language The language used for writing pages on the World Wide Web image In RML the image tag allows you to use existing graphics files in your document Currently image supports the GIF and JPEG formats the two most common formats on the World Wide Web Most paint applications support both the GIF and JPEG standards see also bitmap GIF JPEG JPEG A lossy compression technique for color images created by the Joint Photographic Experts Group JPEG Better for photos than the GIF format it can use up to 24 bit color and reduce file sizes to about 5 of their normal size JPEG files are widely used on the World Wide Web and many other places The JPEG format is sometimes kn
137. re 22 Output table from EXAMPLE 10 Page 98 User Guide Document generated on 2014 09 25 13 10 59 1 3 Example 11 lines and alignment in tables This example shows the various vertical and horizontal alignments you can give text in a table as well as a few ways to use lines EXAMPLE 11 lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM rml dta gt document filename example_11 pdf gt lt template gt lt pageTemplate id main gt lt pageGraphics gt lt pageGraphics gt frame id first 1 72 yl 72 width 451 height 698 gt lt pageTemplate gt lt template gt lt stylesheet gt lt blockTableStyle id myBlockTableStyle gt lt Set fonts 2 lt blockFont name Courier Bold size 10 start 0 1 stop 1 1 gt lt blockFont name Helvetica BoldOblique size 10 start 0 0 stop 3 0 gt lt This sets a textColor for all the text in the table gt lt blockTextColor colorName black gt lt Another example of blockTextColor gt lt blockTextColor colorName green start 2 2 stop 3 3 gt lt This sets a blockAlignment for the whole table gt lt blockAlignment value CENTER gt lt These overrides the above gt lt blockAlignment value RIGHT start 3 0 stop 3 1 gt lt blockAlignment value LEFT start 0 1 stop 0 1 gt lt This sets the vertical alignment fo
138. ree other attributes compression specifies whether the produced PDF should be compressed if at all possible It can take the values 0 1 default for off on or use the site wide default as specified in reportlab rl config invariant determines whether the produced PDF should be invariant with respect to the date and the exact contents It can take the values 0 1 default foroff on or use the site wide default as specified in reportlab rl config debug determines whether debugging logging mode should be used during document production It can take the values O 1 foroffor on Page 11 User Guide Document generated on 2014 09 25 13 10 59 2 3 Document forms stylesheet pageDrawing vs template stylesheet story There are two possible valid structures for your document to have depending on how simple you want it to be For very simple documents you need the prolog followed by a stylesheet and any number of pageDrawings A pageDrawing isa graphical element on the page or simple text string i e it is just placed onto the page in the location you specify and no attempt is made to check if it flows off the page EXAMPLE 1 lt DOCTYPE document SYSTEM rml dtd document filename example_1 pdf gt lt stylesheet gt lt stylesheet gt lt pageDrawing gt draw Cent redstring x 4 lin ya s Hello World lt drawCentredString gt lt pageDrawing gt lt document gt the examples given
139. rent working directory Calling RML2PDF from Python RML2PDF can also be called directly from your own Python program using the rml2pdf go entry point There are two main ways the go function can be used either to generate the resulting PDF file on disk in the file system or to generate it in memory useful for web applications returning the PDF directly to the user This example uses the go function to create the output PDF file on disk from rlextra rml2pdf import rml2pdf rml getRML Use your favorite templating laguage here to create the RML string output tmp output pdf rml2pdf go rml outputFileName output This is an example Django web application view generating a PDF in memory and returning it as the result of an HTTP request from django http import HttpResponse from rlextra rml2pdf import rml2pdf import cStringIO def getPDF request Returns PDF as a binary stream Use your favourite templating language here to create the RML string The generated document might depend on the web request parameters database lookups and so on we ll leave that up to you Page 6 RML User Guide Document generated on 2014 09 25 13 10 59 rml getRML request buf cStringIO StringIO rml2pdf go rml outputFileName buf buf reset pdfData buf read response HttpResponse mimetype application pdf response write pdfData response Content Disposition attachment filename output
140. roducing a muddy brown so to get black printers use a direct black ink rather than use the CMY pigments The name CMYK comes from the name of the four colors used Cyan Magenta Yellow and Key a term sometimes used by printers to refer to black Because CMYK maps more directly to the way printer hardware works it may be the case that colors specified in CMYK will provide better fidelity and better control when printed The color names which RML recognizes are mostly drawn from the HTML specification For a list of these color names recognized by RML see Appendix A NOTE Currently while RML supports specifying colors by CMYK value rml2pdf hasn t yet implemented it If you try you well get a ValueError and the error message cmyk not implemented yet Page 15 RML User Guide Document generated on 2014 09 25 13 10 59 3 3 Using fonts Font names are given in the following format Fontname style where fontname is the name of the font e g Courier and the style is its appearance eg Oblique BoldOblique The only fonts supplied with Adobe s Acrobat Reader are the 14 standard fonts These 14 standard fonts are Courier Courier Bold Courier BoldOblique Courier Oblique Helvetica Helvetica Bold Helvetica BoldOblique Helvetica Oblique Symbol Times Bold Times Boldltalic Times Italic Times Roman ZapfDingbats Custom fonts can also be used in your document RML supports TrueType and Type 1 fonts In order to us
141. s horizontally or 40 pixels vertically EXAMPLE lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM rml dtd document filename example 12 pdf template lt pageTemplate id main gt lt pageGraphics gt lt pageGraphics gt frame id first 1 72 1 72 width 451 height 698 gt lt pageTemplate gt lt template gt lt stylesheet gt lt blockTableStyle id myBlockTableStyle gt lt blockBackground colorName silver start 0 0 stop 1 0 gt lt blockBackground colorName darkslategray start 0 1 stop 1 1 gt lt blockBackground colorName silver start 0 2 stop 1 2 gt lt blockBackground colorName darkslategray start 0 3 stop 1 3 gt lt blockBackground colorName silver start 0 4 stop 1 4 gt lt blockBackground colorName darkslategray start 0 5 stop 1 5 gt lt blockAlignment value CENTER gt lt blockValign value MIDDLE gt 1 Set fonts gt lt blockFont name Helvetica BoldOblique size 10 gt lt the left and right padding tor cells first and lt third columns remember cell numbering starts from ZERO not ONE gt lt blockLeftPadding length 20 start 0 0 stop 0 1 gt lt blockRightPadding length 20 start 2 0 stop 2 1 gt lt s the top and bottom padding for cells in first third rows gt lt blockBottomPadding length 40 start 0
142. sed paragraphs Therefore if you want to get normal typography it s very important to define a lt listStyle gt with font names size and spacing matching that of the lt paraStyle gt you use for the enclosed text You should also be aware that RML s lt para gt tag already has a flexible feature named the bullet which can provide bulleted numbered and definition lists which match the corresponding text In general lists should only be used when you are transforming in a mapping from HTML or when you need to place arbitrary flowables such as tables or images in the body of a list Lists and list items can be styled using tag attributes or with lt listStyle gt tags in the stylesheet section See the rml dtd for the full list of attributes on the lt ul gt lt ol gt and lt li gt tags using LIST MAIN ATTRS In ordered lists you can use the following types of enumeration in the bulletT ype attribute Roman numerals capitals 1 Roman numerals lower case 1 Arabic numerals Capital letters Lowercase letters For unordered lists bulletType must be set to bullet Unordered lists can use bullet types of the following shapes by setting the value attribute in lt ul gt or lt li gt tags square disc diamond arrowhead The size colour and position indenting space before after etc of bullets and enumerations can be adjusted with the relevant tag attributes List item attributes override the attributes
143. site In these cases there is no need to embed any fonts or to have any special software on the server The first stage is to declare the fonts you need in the optional docinit tag at the beginning of the document as follows document filename test 015 japanese pdf registerCidFont faceName HeiseiMin W3 lt docinit gt lt template Note The encName attribute of registerCidFont is deprecated you should not use it with new documents You may then declare paragraph styles use string drawing operations or blockTable fonts referring to the font you have defined lt paraStyle name jtext fontName HeiseiMin fontSize 12 leading 14 spaceBefore 12 gt The test directory includes a file test_015_japanese rml containing a working simplified example in Japanese Warning You will need to have a number of CMap files available on your system These are files provided by Adobe which contain information on the encodings of all the glyphs in the font RML2PDF looks for these in locations defined in code CMapSearchPath endcode variable in the file code reportlab rl_config py endcode which knows where to find Acrobat Reader on most Windows and Unix systems If you wish to use Asian fonts on another system you can copy these files which may be redistributed freely from a machine with Acrobat Reader on to your server Editor s note at 28 12 2002 there is a gre
144. string measurement measurement integer integer measurement integer integer string integer integer table style block descriptors required required required RML User Guide blockAlignment lt blockAlignment value left start 4 stop 11 gt blockLeftPadding lt blockLeftPadding length 0 2in start 4 stop 11 gt blockRightPadding lt blockRightPadding length 0 2in start 4 11 blockBottomPadding lt blockBottomPadding length 0 2in start 4 stop 11 gt blockTopPadding lt blockTopPadding length 0 2in start 4 11 gt Document generated 2014 09 25 13 10 59 left right or center integer integer measurement required integer integer measurement required integer integer measurement required integer integer measurement required integer integer RML User Guide blockBackground lt blockBackground colorName indigo start 4 stop 11 gt blockValign lt blockValign value left start 4 st p 11 gt blockSpan lt blockSpan start 4 stop 4 gt lineStyle lt lineStyle kind BOX thickness 4 colorName magenta start 4 stop 11 2 2 2 gt Document generated on 2014 09 25 13 10 59 string required integer integer top middle or bottom integer integer integer integer line command required measurement req
145. t Use drawCentredString to place a title on the page gt drawCentredString x 297 5 y 800 gt Simple Text and Graphics with RML lt drawCentredString gt till color red y lt 1 the output though a full color rs set tede lt is produced since fill is set to no for the circle gt circle x 127 5 y 672 75 yadius l in fill no Stroke west fill color green gt stroke color black gt circle x 297 5 y 672 75 radius 1 in fill yes stroke no Page 19 User Guide Document generated on 2014 09 25 13 10 59 lt fill color blue gt lt stroke color black gt lt circle 467 5 y 672 75 radius 1 in fill yes Stroke vest fiblocolors blackt setFont name Helvetica size 9 gt drawCentredString x 127 5 y 567 5 gt Circle with stroke but fill drawCentredString drawCentredString x 297 5 y 567 5 gt Circle with Eill but no stroke lt drawCentredString gt lt drawCentredString x 467 5 y 567 5 gt Circle with both stroke and fill drawCentredString Still colors red lt 111 77 y 382 25 width 177 height 552 25 fill no stroke yes gt lt fill color green gt lt stroke color black gt lt 11 x 247 382 25 width 347 height 552 25 fill yes stroke no gt lt fill color blue gt lt stroke color black gt lt ell
146. t a certain point on a page or inside a frame using co ordinates In RML operations which position elements explicitly on the page using X Y co ordinates and other geometric parameters are called graphics operations or just graphics The other major group of tags in RML are the flowables Flowables like paragraphs spacers and tables can appear ina story orinthe place tag Graphics appear in lt pageGraphics gt and illustration These two categories cannot be mixed flowables are positioned in sequence running down a frame until the frame has no more room and then placed on the next frame on the next page if necessary graphics are explicitly positioned by co ordinates Page 29 RML User Guide Document generated on 2014 09 25 13 10 59 6 More about pages and page structures 6 1 More about template and pageTemplate We have already seen that the template has to appear at the start of an RML document after the prolog This section sets out to explain it more fully A template 15 section where the layout of a document is set out both for the whole document and for individual pages within it Up to now we have just been using template without any options But the template tag has number of optional attributes that you can use to set settings for the whole document pageSize sets the size of the page This takes a pair of numbers for the width and the height of the page If you don t give
147. t drawCentredString x 1 5 in y 5 25 gt width 5 join mitered lt drawCentredString gt lt lineMode width 5 join mitered miterLimit 10 gt lt lines gt 2 5in 3 5 5 518 5 5 Sin 6 2520 lt lines gt lt drawCentredString x 3 in y 5 25 in gt width 5 join mitered lt drawCentredString gt lt drawCentredString x 3 in y 5 1 gt miterLimit 10 drawCentredString lt lineMode width 10 join mitered gt lt lines gt 4in 6in 5in 6in Sin 4 5im 5 510 4 5 oan 4r oan 6 2 bu lt lines gt lt drawCentredString x 4 5 y 5 25 in gt width 10 join mitered lt drawCentredString gt lt lineMode width 10 join mitered miterLimit 20 gt lt lines gt 5 5in 6 5 Gam 5 DOTT 5 5 6 25 lt lines gt lt drawCentredString x 6 in y 5 25 in gt width 10 join mitered drawCentredString Page 26 User Guide Document generated on 2014 09 25 13 10 59 lt drawCentredString x 6 in y 5 1 in gt miterLimit 20 lt drawCentredString gt lt examples for the dash attribute to LineMode gt lt lineMode width 2 gt lt lines gt lin 4 5in 2in 4 5in Zin 4 5in 1 5in 1 5 Ain 1 5in 4 75in lt lines gt lt fill color black gt lt setFont name Helvetica size 9 gt lt drawCentredString x 1 5 in y 3 75 in gt width 2
148. t id myID value i gt is used to associate a numbering format to my ID The allowed values for the value attribute are given in the table below pe 7 Uppercase Roman Lowercase Alphabetic Uppercase Alphabetic Here is an example that shows lt seq gt lt seqReset gt and lt seqDefault gt inuse EXAMPLE 6 lt xml version 1 0 encoding iso 8859 1 standalone no gt IDOCTYPE document SYSTEM rml dtd document filename example 6 pdf template lt pageTemplate id main gt frame id first 72 1 72 width 451 height 698 gt lt pageTemplate gt lt template gt lt stylesheet gt lt stylesheet gt lt story gt dx seq in seq seqDefault and seqReset h1 lt para gt copied seq id spam seq id spam gt seq id spam gt Reset seqReset id spam gt seq id spam seq id spam gt seq id spam gt lt para gt lt i gt simple use seq lt i gt lt h2 gt lt para gt First seq lt seq gt lt para gt lt para gt Second lt seq gt lt para gt lt spacer length 6 gt lt para gt Page 46 User Guide Document generated on 2014 09 25 13 10 59 seqReset We have just done amp lt seqReset gt para spacer length 6 gt para First seq after seqReset lt seq gt para para second seq after seqReset lt seq gt
149. t lines gt lin 7 Sim 2in 7 5in Zin 2 53m 1 510 7320 1 518 7 1510 lt lines gt fill coler black gt lt setFont name Helvetica size 9 gt lt drawCentredString x 1 5 in y 6 75 in gt width 10 lt drawCentredString gt lt options for are detauli round or square gt lt lineMode width 10 cap default gt lines22 bi1m 7 5 3 5i1m 7 5in S Sir 3im 721518 lt lines gt lt drawCentredString x 3 in y 6 75 in gt width 10 cap default drawCentredString lt lineMode width 10 cap round gt lt liness4in Sim Sam 50g 4 SIn Page 25 User Guide Document generated on 2014 09 25 13 10 59 4 Tin 4 5 m 7 75 lt lines gt lt drawCentredString x 4 5 in y 6 75 in gt width 10 cap round lt drawCentredString gt lt lineMode width 10 cap square gt lt lines gt 5 51m 7 5in 6 5in 7 5in 56 5im T 5 m 7 751m lt lines gt lt drawCentredString x 6 in y 6 75 in gt width 10 cap square drawCentredString lt lineMode width 5 cap default gt lt examples for the miterLimit attribute to LineMode gt lt lineMode width 5 join mitered gt Alines gt lin 2im 2in l 5im Sesin JT Sun Ge 251m lt lines gt fill color black gt lt setFont name Helvetica size 9 gt l
150. t must always be the name of the DTD which must live in the same directory as the exe or python program rml2pdf This makes it easy to predict where the RML DTD will be and prevents you using an old DTD that happens to be sitting around your disk somewhere It also allows us to make sure that when you create a file with RML the PDF document will be created in the same directory as the RML file and to allow relative pathnames in the document tag The prolog section is common to all XML documents In addition to this RML requires another line following the prolog lt document filename outfile pdf This line gives the name that you want the output PDF file created with This line also starts the document proper and must be matched by a lt document gt tag as the last line in the document in the same way that an HTML file is bracketed by lt HTML gt and lt HTML gt The filename you give just be a simple filename a relative path eg myDoc pdf_ will create it in the directory two levels up from the one your RML document is in or a full pathname eg C output_files pdf myProject myDocument pdf tmp userl myScratchFile pdf_ If you just supply a filename the output file will be created in the same directory as your RML file The same principle works with anywhere else you may need to give a filename they are relative to where the document lives on your disk not to where rml2pdf is The document tag has th
151. t there s lot more to blockTables than that The actual blockTable tag number of optional attributes Style blockTables can have a style set in the stylesheet in the same way as paragraphs can If you have set a style for your you can refer to it by name with this attribute and apply it to your table More details on how to do it appear in the section on the lt blockTableStyle gt tag below a colWidths If you use this attribute it takes a comma separated list of the width of each column in your blockTable This allows you to vary the widths to match the width of the content of each column If you do use it you should be careful to make sure that there is one width given for every column in your table rowHeights Page 90 RML User Guide Document generated on 2014 09 25 13 10 59 As colWidths is to columns rowHeights is to rows It also takes a comma separated list in this case for the heights of the rows in your table m repeatRows If you have a large table that splits over multiple pages you may well want certain information appearing on all of them Column headers are one example of this sort of information The repeatRows attribute allows you to do this repeatRows takes one single number as an argument All the rows up to and including this row are repeated as headers on each section of the table that appears on a new page 13 3 Block table styles blockTables area flo
152. ted barcode data RML User Guide lt checkBox gt letterBoxes style myboxstyle 11 labelFontName Helvetica labelFontSize 12 labelTextColor blue boxWidth lin boxHeight lin checkStrokeColor blue boxStrokeColor blue boxFillColor blue lineWidth 1 linel label text 1 line2 label text 2 line3 label text 3 checked talse bold false graphicOn cute_on jpg graphicOff oute off jpg Page 142 Document generated on 2014 09 25 13 10 59 string box style name measurement measurement string font name fontsize measurement string color name measurement measurement string color name string color name string color name measurement string string string truth value truth value string file name string file name required required RML User Guide lt letterBoxes gt style myboxstyle 11 count 10 label label text labelFontName Helvetica labelFontSize 12 labelTextColor blue labelOffsetX lin labelOffsetY lin DoxWidth 1in boxHeight 1in combHeight 0 25 boxStrokeColor blue boxFillColor blue btextoolor blue lineWidth lin fontName Helvetica fontSize 12 box contents goes here lt letterBoxes gt textBox Page 143 Document generated on 2014 09 25 13 10 59 string box style name measurement required measurement required integer required string string font name fontsize measurement
153. ted the rowHeights orcolWidths When you are using paragraphs inside a table you must not put any text outside the lt para gt lt para gt tags The only exception to this rule is whitespace you can put spaces and tabs outside the para tag but Page 89 RML User Guide Document generated on 2014 09 25 13 10 59 nothing else One other thing to be aware of is that if you use a para inside a table it will ignore the text attributes you have used for that table and instead use the attributes for paragraphs This can be a plus since it allows you to use already defined paragraph styles but can take you by surprise if weren t expecting it As an example here is the RML that generated the above table lt blockTable rowHeights 1 25cm 1 25em colWidths 4cm 4cm lt td gt lt para gt This is a lt b gt more lt b gt complex lt font color red gt blocktable lt font gt lt para gt lt td gt lt td gt lt para gt This is a more lt i gt complex lt i gt blocktable lt para gt lt td gt sp lt td gt lt para gt lt font face Helvetica gt This is a more complex blockTable lt font gt lt para gt lt td gt lt para gt This is lt greek gt a lt greek gt more lt font color blue gt lt i gt complex lt i gt lt font gt blockta lt greek gt b lt greek gt le lt para gt pda lt tr gt lt blockTable gt 13 2 Block table attributes This is useful bu
154. th string string string center centre left right CENTER CENTRE LEFT RIGHT 0 1 yes no path string string string string string string paragraph style name RML User Guide title lt title style myfavoritstyle lt title gt style myfavoritstyle h1 h2 lt h2 style myfavoritstyle h2 h3 lt h3 style myfavoritstyle lt h3 gt h4 lt h4 style myfavoritstyle h4 Page 125 Document generated on 2014 09 25 13 10 59 string paragraph style name string paragraph style name string paragraph style name string paragraph style name string paragraph style name RML User Guide h5 lt h5 style myfavoritstyle gt h5 h6 h6 style myfavoritstyle gt h6 a a color blue fontSize 12 fontName Helvetica name somename backColor cyan href someurl gt lt gt evalString lt evalString imports someimports default somedefault gt Intra Paragraph Markup Document generated on 2014 09 25 13 10 59 string paragraph style name string paragraph style name string color name stringform font size string font name string string color string string string string RML User Guide lt b gt lt b gt font lt font face Helvetica color blue size 34 lt font gt greek lt greek gt lt greek gt sub lt sub gt lt sub gt Page 127 Document generated on
155. that the greater than and less than operators must be written in RML as amp gt and amp lt 11 4 Examples Some sample code demonstrating several of the conditional formatting tags lt docAssign var i expr 3 gt doclf icond i16 9t 2 gt lt para style normal gt The value of i is greater than 2 lt para gt lt docElse gt lt para style normal gt The value of i is less than or equal to 2 lt para gt gt lt docWhile cond i gt lt docPara expr i format The value of i is __expr__ d gt lt stmt i 1 lt docWhile gt results in the output The value of i is greater than 2 The value of i 3 The value of i is 2 The value of i is 1 As an example of a practical use of conditional formatting supposing you wanted all your documents to be a certain number of pages You could use the value of doc page to decide whether to include or exclude an external filler pdf in your output and so pad the size of your document docIf cond doc page 3 includePdfPages filename fillerpage pdf 1 leadingFrame yes 11 5 Reference Conditional formatting is implemented with the following tags lt docAssign var gt assigns the value of expr to eg to make 1 3 lt docAssign var i expr 3 lt docExec stmt executes the statement stmt eg to subtract 1 from the value of i docExec stmt i 1
156. the td and td tags can only contain one of two different sets of data Either a table cell can contain string forms text andthe getName and pageNumber tags or it can contain a sequence of flowables tags such as lt gt lt gt and various heading tags It is not possible to mix both of these forms in the same cell though you can mix them in the same table Putting strings into table cells is quicker than using paragraphs Paragraphs need to work out when to wrap text strings don t So you should avoid using paragraphs inside tables unless you really need to or you don t mind things slowing down When you are doing a big database report wherever possible use separate smaller tables to contain parts of your data rather than one huge table If you don t use many mini tables to contain small groups of rows but instead decide to do a big 1 000 row table you will notice a significant loss of speed in the generation of your output PDF This also makes it much easier to design complex grouped reports for each group header footer or detail block you can design one table style and keep them all independent of each other 13 5 Using block table styles Now that we have seen what the blockTable s attributes are and seen a summary of blockTableStyle here are some examples that show you how they can be used together Page 92 RML User Guide Document generated on 2014 09 25 13 10 59 The following
157. there are fill or stroke tags a document both the fill and the stroke for all shapes default to black If youhavea fill tag before a shape it allows you to change the color that that shape is filled with Similarly a stroke tag before a shape allows you to set the color that the outline of that shape will be drawn in If there is fill or stroke tag in front of a shape it will be filled and stroked with the most recently defined 111 orstroke or failing that the default black Page 21 User Guide Document generated on 2014 09 25 13 10 59 This means that you can use one fill tag to refer to many shapes while changing the stroke for each of them Or vice versa Another brief example how the 111 and stroke tags look fill color olivedrab gt lt stroke color khaki gt 4 3 Lines and lineMode The other basic drawing element is the line To draw a simple line you use the lt 11 gt tag For each line you want to draw you pass lt lines gt two pairs of X Y co ordinates one pair of co ordinates for the start point of the line the other for the end point If you want to draw more than one line you can keep passing 1ines more sets of 4 co ordinates lines then draws those other separate lines on the page The lines ina lt lines gt command are just lumped together in one lt lines gt tag for your convenience If you want lines that follow from each other look at the Advan
158. this chapter are Crop Marks Bleed CMYK colours Overprint knockout control Colour separations Pagination 12 1 Crop Marks The first difference is the size of the page Let s say you are in Europe or Asia and have been creating A4 electronic documents from a web site using ReportLab You then need to produce a different version of the same document for professional printing The printer wants to be given a slightly larger document with lines pointing at the corners of the A4 area They will often be printing on a much larger sheet or roll of paper and cutting it afterwards To automatically create crop marks use the useCropMarks attribute of the lt docinit gt tab This will enlarge the underlying page and draw the needed marks lt docinit useCropMarks 1 gt The intent is that it s reasonable easy now to have a single template which generates print and web versions of the same document wrapping lt if gt statement around the extra attribute in your favourite templating system without needing to recalculate all the frame and graphics positions for every element on the page There is also a separate lt cropMarks gt tag which you can use within the lt docinit gt tag if you wish to modify the page size increase colour length dash pattern and so on for the crop marks however we ve found the defaults to work fine Page 84 User Guide Document generated on 2014 09 25 13 10 59 12
159. thods such as XSL the C preprocessor or the Preppy preprocessor to allow the convenient construction of structures such as tables of contents indices or bibliographies 9 1 the namedString tag and forward references The code namedString endcode tag is similar to code name endcode tag it associates name to a string of text The code namedString endcode tag is more general than the code name endcode tag in the sense that it allows other string constructs such as code getName endcode in the named text For example the following snippet associates the name code Introduction endcode with the current page number at the time of formatting namedString id Introduction gt The Introduction starts at lt pageNumber gt lt namedString gt The code endcode tag does not permit other tags inside the string it names in this manner Elsewhere the RML text may substitute the page number for the introduction using the construct name id Introduction default this is a default placeholder used if Introduction is undefined and this reference to code Introduction endcode name may occur before the code endcode name is defined For example the reference may occur at the beginning of the document in the Table of Contents Whenever a name is referenced before it has been defined the code default endc
160. to enhance areas of your publication so you might use extra spot colours as well as the CMYK ones Bear in mind that spot colour inks are usually opaque We mentioned above that a colorSpace attribute can be defined in the lt document gt tag There are two more of these color spaces which will be useful for those who are going to use spot colours will only let you use spot colours you define and will let you define spot colours to use along with the normal CMYK process colours If using SEP_CMYK our framework will again auto convert blacks for you thus if a table s gridlines or a chart axis is normally drawn in black or a shade of grey implemented originally as RGB it will be autoconverted to CMYK black or grey An equivalent CMYK colour value needs to be supplied along with a spot name for each printing plate The CMYK values are usually just to provide an on screen representation and do not need to be accurate more important is the spot name which is a string that printers can identify the ink such as PANTONE 288 or PMS 288 Your printer may advise you on what spot names to use You will need to define your spot colours in the lt docinit gt section of your document The 14 is what you will use later in the document to refer to that colour allows you to see an approximation of your colour in a PDF reader spotName is how the printer will identify which ink to use for the plate There is
161. to two bitmap files on the disk these will be used in preference to the default appearance Note that they will be stretched to the box Width and boxHeight stated so it is important to set the same aspect ratio as the underlying image Also remember the printing intent a 24 pixel bitmap drawn to occupy a 12 point space on a form will be visibly grainy on a good quality printer but may be fine on an inkjet Because checkboxes do not contain text it can be argued that when they are to be displayed as checked the cross colour should be the same as the border colour Equally well it can be argued that it should be the same colour used for text in textboxes To provide both options checkboxes have an additional colour attribute named checkStrokeColor which will be used for the cross instead of the border colour if the former is provided Note that the label attached to a checkbox is limited to three lines of text now and always appears at the right margin of the box but this might be generalised in future versions The label is expected to be vertically centered with the box no matter how many lines it is composed of The following code creates a row of sample checkboxes providing different values for the most relevant attributes lt checkBox y 0cm checked 0 gt checkBox x 1 5cm y Ocm checked 1 gt lt checkBox y 0cm boxWidth 0 75cm boxHeight 1cm checked 1 gt lt checkBox 4 5 y 0cm
162. ts are dramatically cut file sizes reduced production time and apparently even speeding things up on the printer If you are going to be using PDF files in any situation where people will be downloading them massively reduced file sizes will be appreciated by your users These advantages become even more obvious with multiple similar documents If you are dealing with a run of 5000 repetitive forms perhaps payslips or single page invoices you only need to store the backdrop once and simply draw the changing text on each page Page 79 RML User Guide Document generated on 2014 09 25 13 10 59 forms should be used whenever you have a graphic that is used repeatedly It may be something as small as your company logo or some sort of symbol you want to flag interesting bits of text with or something as large as a whole page backdrop As long as you use it repeatedly it s worth using a form to do it forms don t even have to be created in RML You can use another application such as Adobe Illustrator Word and distil the output to PDF You can then use our PageCatcher product to generate the forms which can then be used from RML Look on our web site for more information on PageCatcher http www reportlab com pageCatcher index html Page 80 RML User Guide Document generated on 2014 09 25 13 10 59 11 Conditional Formatting 11 1 Introduction WARNING this is an advanced topic intended for programmers trying to deal with dif
163. uired string required integer integer integer integer integer integer The line command names are GRID BOX OUTLINE INNERGRID LINEBELOW LINEABOVE LINEBEFORE and LINEAFTER BOX and OUTLINE are equivalent and GRID is the equivalent of applying both BOX and INNERGRID RML User Guide bulkData lt bulkData stripBlock yes stripLines yes stripFields yes fieldDelim recordDelim gt excelData lt excelData fileName somefileName sheetName somesheetName ranges Al B7 rangeName somerangeName gt Page Layout Tags pageTemplate lt pageTemplate id frontpage pageSize 8 5in llin rotation 270 gt lt pageGraphics gt lt pageGraphics gt lt frame gt lt pageTemplate gt frame lt frame id left 1 E width 50cm height 90cm gt Page 151 Document generated on 2014 09 25 13 10 59 yes no yes no yes no string string string string string string string required override template page size override template page angular orientation string measurement measurement measurement measurement optional 1 or 2 one or more required required required required required RML User Guide pageGraphics lt pageGraphics gt Special Tags name lt name id chapterName value Introduction gt alias lt alias id footerString value chapterName gt getName lt getName id foote
164. unction gt string data for plug in plugInFlowable Table Elements blockTable lt blockTable style mytablestyle rowHeights 23 20 30 10 ecolWidthge 50 90 35 119 gt lt tr gt tr tr blockTable tr lt tr gt lt tr gt td Page 121 Document generated on 2014 09 25 13 10 59 string required string required unformatted data string style name sequence of measurement sequence of measurement rows of same length RML User Guide lt td fontName Helvetica fontSize 12 fontColor red leading 12 leftPadding 3 raightPagddinge s topPadding 3 bottomPadding 3 background pink align right vAlign bottom lineBelowThickness lineBelowColor lineBelowCap lineBelowCount lineBelowSpace lineAboveThickness lineAboveColor lineAboveCap lineAboveCount lineAboveSpace lineLeftThickness lineLeftColor lineLeftCap lineLeftCount lineLeftSpace lineRightThickness lineRightColor lineRightCap lineRightCount lineRightSpace td Page 122 Document generated on 2014 09 25 13 10 59 stringform font name stringform font size stringform font color stringform line spacing cell left padding cell right padding cell top padding cell bottom padding background color cell horizontal alignment vertical alignment bottom line thickness bottom line color bottom cap butt round square bottom line count bottom line spacing topline thickn
165. units Inches use the term in centimetres use the term and millimetres use the term mm If no unit is specified will assume that you are giving a measurement in points one point is 1 72 of an inch You can also explicitly use points with the term pt As an example the following pairs of co ordinates all refer to the same point Notice that there is no space between the number and any unit that follows it 4 5in lin 11 43cm 2 54cm 324 72 You can mix and match these units within RML though it generally isn t a good idea to do so The co ordinate pair 3 5in 3 5cm is valid and won t confuse the RML parser but it may well confuse you 3 2 Using Colors There are three ways to specify colors in RML a red green blue value e g ff0000 0 0 0 0 1 0 a cyan magenta yellow black value e g ff99001f or 1 0 0 6 0 0 0 1 m by color name using standard HTML names The RGB or additive color specification follows the way a computer screen adds different levels of the red green or blue light to make any color White is formed by turning all three lights on full 1 1 1 The CMYK or subtractive method follows the way a printer mixes three pigments cyan magenta and yellow to form colors Because mixing chemicals is more difficult than combining light there is a fourth parameter for darkness A chemical combination of the CMY pigments almost never makes a perfect black instead p
166. uotation marks e g you would have to use lt document filename outfile pdf gt since you couldn t get away with lt document filename outfile pdf gt non empty element must have both an opening and a closing tag e g document tag must be matched by a matching lt document gt tag Empty elements are those that don t have any content and are closed with a at the end of the same tag rather than having a separate closing tag e g lt getName id Header Title gt a Tags must be nested correctly i e lt b gt lt i gt text lt b gt lt i gt isn t valid but lt b gt lt i gt text lt i gt lt b gt is the whole whitespace is ignored in RML Except inside strings you can format and indent your RML documents in whatever way you consider most readable Inside text strings whitespace is seen as equivalent to a single space and line breaks are added automatically as needed during formatting Other than that what you type is what is displayed on the page a RML is case sensitive Upper Case is different from upper case UPPER CASE and UpPeR CaSe The capitalization in the tag names is important 2 2 The prolog Every RML document must start with a number of lines lt xml version 1 0 encoding iso 8859 1 standalone no gt lt DOCTYPE document SYSTEM rml dtd This is called the prolog you can think of it as the document header lt xml standalone
167. value Type anything you want between these quotes gt lt initialize gt lt stylesheet gt sstoryv gt lt para gt lt b gt lt getName id YourVariableName gt lt b gt lt para gt story You can also use the lt name gt tag inside the story of a document In this case as well as setting the value for the variable it is also displayed on the page i e the name has a textual value 8 3 Seq seqReset seqChain and SeqFormat The seq in seq lt seqDefault gt and lt seqReset gt stands for sequence These tags are all used for paragraph numbering or indeed anything that requires numbering items in a sequence such as list items or figures and illustrations This is how they look in use lt seq gt lt seqDefault id myID gt lt seqReset gt or lt seqReset id myID gt lt seqChain 190 idl id2 idn gt lt seqFormat id myID value i gt Page 45 RML User Guide Document generated on 2014 09 25 13 10 59 Each time you call lt seq gt its value is automatically incremented With lt seqReset gt the id is an optional attribute However it is still best to use it to save confusion The lt seqChain order id0 191 id2 gt tag is used to make multi sequence use easier When sequence 140 is changed sequence 141 is reset likewise when sequence 191 is changed sequence 192 is reset and so on for the identifiers in the order attribute The tag lt seqForma
168. ve backward compatible blah blah blah blah blah Blah blah blah blah value added lt para gt lt para gt Blah blah blah blah blah blah blah blah blah re factoring phase blah knowledge management blah blah Blah blah blah blah interactive blah vision statement blah lt para gt lt para gt Blah blah blah blah blah blah conceptualize blah downsize blah blah bleh blah Blah blah blah blah blah blah blah blah bilan blah blah blah synergy client centered vision statement para para Blah blah dysfunctional blah blah blah blah blah blah blah appropriate blah blah blah blah blah blah blah blah re factoring go the extra mile blah blah blah blah para nextFrame condPageBreak height 144 gt lt getName id ColumnTwoHeader gt lt h2 gt lt para style body gt This is the contents for lt i gt column two lt i gt lt para gt lt para style body gt It uses the paragraph style we have called body lt para gt lt para style body gt Does it come out OK lt para gt lt para style body gt There now follows some random text to see how these paragraphs look with longer content lt para gt lt para style body gt Blah OS 2 blah blah blah blah coffee blah blah blah blah Page 42 RML User Guide Document generated on 2014 09 25 13 10 59 Windows blah blah blah blah blah blah blah Blah blah blah blah blah blah blah Modula 3 blah blah blah
169. vetica fontSize 12 gt leading leading is used is used to alter the space between lines In RML it is expressed as the height of a line PLUS the space between lines So if you are using 10 point font a leading of 15 will give you a space between lines of 5 points If you use a number that is smaller than the size of font you are using the lines will overlap leftIndent rightIndent leftIndent and rightIndent apply space to the left or right of a paragraph which is in addition to any margin you have set firstLineIndent firstLineIndent 15 used when you want your paragraph to have an additional indent on the first line on top of anything set with left Indent spaceBefore spaceAfter spaceBefore and spaceAfter as you would expect set the spacing before a paragraph or after it textColor This sets the color to be used in displaying a paragraph bulletText bulletColor bulletFontName bulletFontSize bulletIndent These are all used to set the characteristics for any bullets to be used in the paragraph Inside the story you can also do a number of things that you can t do with the drawString commands Fora start you can use bold italics and underlining If you are familiar with HTML you will recognize these tags i and lt i gt start and stop italics lt b gt and lt b gt start and stop the text being set as bold and lt u gt u start and stop underlining 7 4 The font tag You can also explicitl
170. wable so the actual lt blockTable gt tag will appear in the story section of your RML document You can use the lt blockTableStyle gt tag to set the appearance of your blockTable This appears in the stylesheet section of your document and can be used for more than one table You can set up how all the blockTables in your document will look in one blockTableStyle tag if you want The lt blockTableStyle gt tag is container for a number of other tags and needs to be paired with a terminal lt blockTableStyle gt tag This works in the same way as styleSheet styleSheet lt pageGraphics gt lt pageGraphics gt and other tags of that sort For all of the attributes in blockTableStyle they refer to a square or rectangular block inside the table This can be as many or as few cells as you want not necessarily a single cell This block aspect to the attributes is reflected in their names and gave the table style its name for consistency It was felt that since most of these attributes started with block the table tag should itself be called blockTable to keep things simple The way the block is described may seem unusual to you if you are not used to programming The x and y co ordinates are still given as X Y or if you like Row Column rather than the spreadsheet model but the numbering starts from 0 rather than 1 This makes the top left hand cell 0 0 As well as this the numbers may also be negative If t
171. width an height 1 15 in fill yes stroke no round 0 15 in gt lt fill color blue gt lt stroke color black gt rect x 424 5 y 56 5 width 1 height 1 15 in fill yes stroke yes round 0 15 in gt fill color black gt lt drawCentredString x 127 5 y 41 25 gt Rect with stroke and round but lt drawCentredString gt lt drawCentredString x 297 5 y 41 25 gt Rect with fill and round but no stroke drawCentredString drawCentredString x 467 5 41 25 gt Rect with stroke fill and round drawCentredString lt pageGraphics gt frame id first 1 0 5 yl 0 5in width 20cm height 28cm gt lt pageTemplate gt lt template gt lt stylesheet gt lt stylesheet gt s oy y gt lt para gt lt para gt lt story gt lt document gt 4 2 Fill and stroke If you look at the example 3 you will see that as well as having 111 and stroke attributes for the shapes there are separate 8111 and stroke tags Inside the tag for a shape such as rect fill and stroke simply tell rml2pdf whether those qualities should be turned on Should there be a 111 or not Should there be a st roke or not That is why the argument is Boolean yes or no though 1 or 0 are also allowed The fill and stroke tags do a different job The only argument that these tags are allowed is a color If
172. y cases be of highly variable length and not guided by designer s common sense It is possible to use the conditional formatting tags in RML to add extra pages and pad out your document to the required length as necessary For example we maintain one solution which has a number of optional half page and full page advertisements which can be used to ensure the right pagination occurs See the Conditional Formatting chapter of this guide for more information on this technique 12 8 More information We manage a number of solutions which generate documents for professional printing and have helped clients achieve some interesting effects but we have limited space here to discuss all of the techniques used If you are a commercial customer and are seeking to achieve something not documented here please contact us and we will be happy to assist further Page 88 RML User Guide Document generated on 2014 09 25 13 10 59 Part Ill Tables 13 Using tables 13 1 Block tables If you are familiar with HTML you will understand the basic tags for use with tables in RML Just as in HTML you use a tag to tell rml2pdf that a table is on the way in this case blockTable rather than lt table gt and another one to end it Within the blockTable and lt blockTable gt tags tr and tr enclose the rows from Table Row and within each table row td and td enclose each individual cell from Table Data
173. y file to work in production mode Without the license key each page produced by RML2PDF will be visibly marked as an evaluation copy and the file will be annotated invisibly as produced for evaluation purposes as well With a valid license key file present RML2PDF will run in production mode and the PDF file generated will contain the licensing information You can purchase a ReportLab PLUS license using your user account on our website http www reportlab com Once we issue you license file you will need to install it somewhere on your PYTHONPATH so that 2 can find it Running RML2PDF from the command line RML2PDF can be run from the command line provided that you place it on your path We normally ship this module in compiled pyc format so you need a Python interpreter of the correct version to run it and need to know where it was installed The installation process does not currently register a script for you On Unix you may wish to add the directory to your path or create a wrapper script in your bin directory python path to rlextra rml2pdf rml2pdf pyc filename rml On Windows pyc files are normally associated with most recently installed Python interpreter so you could execute this Ntemp c python26 lib site packages rlextra rml2pdf rml2pdf pyc filename rml After completing successfully rml2pdf program will return to a command prompt The output PDF file should be created in the cur
174. y set the font using the lt font gt tag This has the optional attributes of face color and size which are all pretty self explanatory You need to lt font gt tag to close this before the end of the paragraph Example That example produces this line of text This is courier in crimson 7 5 Superscripts and subscripts Another thing you can do inside the story is using superscripts and subscripts You do this with the lt super gt lt super gt and lt sub gt lt sub gt tags Superscript is where the text is raised up on the line such as in the mathematical symbol for squared or cubed and subscript is where it is lowered relative to the rest of the line in the same way Example para lt sub gt This subscript sub This is normal text super This is superscript lt super gt para Page 37 RML User Guide Document generated on 2014 09 25 13 10 59 That example produces this This i ipt T _ This is normal text 518 9UPerserp This is subscript 7 6 Lists RML supports ordered and unordered lists using the tags lt ol gt lt ul gt and lt li gt They work in a similar way to their HTML equivalents A list item can be any normal flowable element but there can be only one such item within a pair of list item tags Lists can be nested WARNING The contents of a list are flowable objects and the list itself does not know what font sizes or spacing you will use in the enclo
175. yption strength defaults to 128 Encryption permissions optional optional allowed are print copy modify annotate default is print string required optional one or more The document tag is the root tag for RML docuoments Every RML document must contain on and only one document tag There are two forms for a document the story form and the pageDrawing form Page 117 RML User Guide docinit lt docinit pageMode pageLayout useCropMarks gt lt docinit gt template lt template pageSize 8 5in 1111 rotation 270 firstPageTemplate main leftMargin lin rightMargin lin topMargin 1 5in bottomMargin 1 5in showBoundary false allowSplitting true title my title author yours truly gt lt pageTemplate gt lt pageTemplate gt lt template gt Page 118 Document generated on 2014 09 25 13 10 59 UseNone UseOutlines UseThumbs FullScreen SinglePage OneColumn TwoColumnLeft TwoColumnRight yes 0 1 true false pair of lengths page angular orientation multiple of 90 default 0 page template id length length length length truth value truth value string string 1 or more RML User Guide stylesheet lt stylesheet gt lt initialize gt lt initialize gt lt paraStyle gt Document generated on 2014 09 25 13 10 59 lt blockTableStyle gt lt blockTableStyle gt lt stylesheet gt story lt story gt lt para gt

RML User Guide

Contents

Download Pdf Manuals

Related Search

Related Contents