RML Example 48: Paragraph flow controls
RML Example 48: Paragraph flow controls
RML (Report Markup Language) is ReportLab's own language for specifying the appearance of a printed page, which is converted into PDF by the utility rml2pdf.
These RML samples showcase techniques and features for generating various types of ouput and are distributed within our commercial package as test cases. Each should be self explanatory and stand alone.
Paragraph flow controls
One of the most common uses of RML is the creation of dynamic documents from raw content. However, variable content lengths can cause problems around page and frame breaks. RML has a number of built in features to deal with these.
keepTogether
The keepTogether tag may be wrapped around flowables and indicates that everything within should remain on the same frame. See below a paragraph WITHOUT a keepTogether tag enclosing it. Notice that the paragraph is allowed to overflow into the next frame:
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo. Proin sit amet felis convallis velit laoreet semper ut id felis.
Now see the exact same paragraph with <keepTogether> tags used. Note the entire paragraph goes together onto the next frame.
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo. Proin sit amet felis convallis velit laoreet semper ut id felis.
Using the tag <nextPage/> will now break to the next page
keepWithNext
The keepWithNext attribute is assigned to paragraph styles and tells them to stay in the same frame as the following content. If subsequent content overflows, keepWithNext will cause the preceding paragraph to overflow as well.
Below is a paragraph heading that does NOT have keepWithNext turned on. It's styles are defined as below:
]]>
Note how the following paragraph of text (using keep together) overflows onto the next page without bringing the heading with it:
Heading with no "keep with next"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis vel nunc a purus ullamcorper fermentum id nec felis. Sed suscipit, elit quis bibendum gravida, mauris tortor iaculis justo, id pharetra neque nisi ut turpis. Nulla sit amet risus tortor. Integer congue ullamcorper nisi vitae elementum. Pellentesque eget justo nec lacus porta placerat. Sed nunc ligula, tempus nec ultrices non, posuere nec magna. Quisque laoreet magna sed erat congue euismod. Phasellus libero nisi, volutpat vel sagittis vel, dapibus sed neque.
Now see the same example using keepWithNext. Note that the heading goes to the next frame with the following paragraph.
Heading with "keep with next"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis vel nunc a purus ullamcorper fermentum id nec felis. Sed suscipit, elit quis bibendum gravida, mauris tortor iaculis justo, id pharetra neque nisi ut turpis. Nulla sit amet risus tortor. Integer congue ullamcorper nisi vitae elementum. Pellentesque eget justo nec lacus porta placerat. Sed nunc ligula, tempus nec ultrices non, posuere nec magna. Quisque laoreet magna sed erat congue euismod. Phasellus libero nisi, volutpat vel sagittis vel, dapibus sed neque.
We will use the <nextFrame/> tag this time to move on. Note that because we are on the last frame of the page, this has the same effect as <nextFrame/>.
pageBreakBefore and frameBreakBefore
Paragraphs can also be given the attribute of pageBreakBefore, which will enforce a page break before rendering the content. See a heading below without this attribute.
Heading without a page break
And now one below with pageBreakBefore set. Not surprisingly, it appears on the next page.
Heading with a page break
A similar attribute allows for automatic frame breaks. See a normal heading below:
Normal heading
And now one with frameBreakBefore set
Heading (in the next frame)
<nextPage/> again.
Widow control
Widows are single lines of text which overflow into the next frame. A paragraph style, allowWidows, can be set to "0" in order to prevent this from happening. See a paragraph below which allows a widow:
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo. Proin sit amet felis convallis velit laoreet semper ut id felis. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Pellentesque quis urna id neque adipiscing ultricies. Integer sem mauris, venenatis eget ornare vel, varius eu sapien.
Isn't that single line above ugly?
Let's try again with a new paragraph style whose settings prevent widows:
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo. Proin sit amet felis convallis velit laoreet semper ut id felis. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Pellentesque quis urna id neque adipiscing ultricies. Integer sem mauris, venenatis eget ornare vel, varius eu sapien.
As shown, allowWidows="0" means that a second line of text will overflow as well.
Orphan control
Orphas are single lines of text which remain at the end of a frame. Unlike widows, orphan control is on by default and the allowOrphans tag can be used to turn it off. Let's put in a some sample text to get near the end of the paragraph
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo.
And now show that, with the normal paragraph style, orphans are not possible:
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo. Proin sit amet felis convallis velit laoreet semper ut id felis. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Pellentesque quis urna id neque adipiscing ultricies. Integer sem mauris, venenatis eget ornare vel, varius eu sapien.
Now let's try that again, copying the last frame exactly, but with a paragraph style with orphans allowed
Orphan control
Orphas are single lines of text which remain at the end of a frame. Unlike widows, orphan control is on by default and the allowOrphans tag can be used to turn it off. Let's put in a some sample text to get near the end of the paragraph
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo.
And now show that, with the new paragraph style, orphans ARE possible:
Etiam fringilla faucibus libero, at bibendum risus luctus ac. Aliquam erat volutpat. Curabitur at odio non erat tincidunt semper. Proin pulvinar volutpat dolor, viverra blandit neque blandit in. Ut augue quam, vehicula et iaculis vitae, vehicula eu ligula. Aliquam erat volutpat. Donec ultrices magna vel massa rhoncus sed laoreet nunc posuere. Sed sed auctor felis. Vivamus lacinia sem sed mi molestie at malesuada velit consequat. Vestibulum malesuada mauris vel libero tempor hendrerit. Vivamus vel quam sem, sit amet tincidunt metus. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Mauris vel quam nibh, vel posuere justo. Proin sit amet felis convallis velit laoreet semper ut id felis. Phasellus nibh turpis, varius et feugiat ac, pharetra id leo. In laoreet gravida lorem, sit amet laoreet mi pretium nec. Integer ultricies est at odio tincidunt gravida. Maecenas convallis tellus nec nisl volutpat volutpat. Pellentesque quis urna id neque adipiscing ultricies. Integer sem mauris, venenatis eget ornare vel, varius eu sapien.