Layout
layout is the flow container inside a section. Elements flow top to bottom and paginate automatically — when content overflows a page, it continues on the next. A section has at most one layout. For content at a fixed place on the page, use a layer.
<lpdf version="1"> <document size="letter"> <section> <layout margin="48pt"> <column gap="16pt"> <text font-size="18pt">Title</text> <divider/> <text>Body text goes here.</text> </column> </layout> </section> </document></lpdf>L.document({ size: 'letter' }, [ L.section(NoAttr, [ L.layout({ margin: '48pt' }, [ L.column({ gap: '16pt' }, [ L.text({ fontSize: '18pt' }, ['Title']), L.divider(NoAttr), L.text(NoAttr, ['Body text goes here.']), ]), ]), ]),])L.document(DocumentAttr(size='letter'), [ L.section(NoAttr, [ L.layout(LayoutAttr(margin='48pt'), [ L.column(ColumnAttr(gap='16pt'), [ L.text(TextAttr(font_size='18pt'), ['Title']), L.divider(NoAttr), L.text(NoAttr, ['Body text goes here.']) ]) ]) ])])L.document(new DocumentAttr().size("letter"), List.of( L.section(NoAttr, List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.column(new ColumnAttr().gap("16pt"), List.of( L.text(new TextAttr().fontSize("18pt"), List.of("Title")), L.divider(NoAttr), L.text(NoAttr, List.of("Body text goes here.")) )) )) ))))L.Document(new() { Size = "letter" }, [ L.Section(NoAttr, [ L.Layout(new() { Margin = "48pt" }, [ L.Column(new() { Gap = "16pt" }, [ L.Text(new() { FontSize = "18pt" }, ["Title"]), L.Divider(NoAttr), L.Text(NoAttr, ["Body text goes here."]), ]), ]), ]),])L::document(new DocumentAttr(size: 'letter'), [ L::section(NoAttr, [ L::layout(new LayoutAttr(margin: '48pt'), [ L::column(new ColumnAttr(gap: '16pt'), [ L::text(new TextAttr(fontSize: '18pt'), ['Title']), L::divider(NoAttr), L::text(NoAttr, ['Body text goes here.']), ]), ]), ]),])Margin
Section titled “Margin”margin is the space between the edges of the page and the flowing content and its regions. It takes one value for all four sides, or two to four in the order top, right, bottom, left, written like CSS: 48pt, a space token such as l, "48pt 24pt". Without it the layout has a margin of 36pt on every side: half an inch.
The margin belongs to the layout because only the flow uses it. The document and the section have none, and a layer ignores it and measures from the page edges.
<layout margin="48pt 36pt"> <text>Flows inside a 48pt margin at the top and bottom, and 36pt at the sides.</text></layout>L.layout({ margin: '48pt 36pt' }, [ L.text(NoAttr, ['Flows inside a 48pt margin at the top and bottom, and 36pt at the sides.']),])L.layout(LayoutAttr(margin='48pt 36pt'), [ L.text(NoAttr, ['Flows inside a 48pt margin at the top and bottom, and 36pt at the sides.'])])L.layout(new LayoutAttr().margin("48pt 36pt"), List.of( L.text(NoAttr, List.of("Flows inside a 48pt margin at the top and bottom, and 36pt at the sides."))))L.Layout(new() { Margin = "48pt 36pt" }, [ L.Text(NoAttr, ["Flows inside a 48pt margin at the top and bottom, and 36pt at the sides."]),])L::layout(new LayoutAttr(margin: '48pt 36pt'), [ L::text(NoAttr, ['Flows inside a 48pt margin at the top and bottom, and 36pt at the sides.']),])Elements
Section titled “Elements”| Element | Purpose |
|---|---|
column |
Children top to bottom, with a gap between them |
row |
Children side by side, wrapping onto new lines. A child with width="fill" takes what the others leave, and justify="between" pushes them apart |
text |
Text block with optional span children |
divider |
Horizontal or vertical rule |
frame |
Atomic box around one child — will not split across pages |
img |
Image asset |
shape |
Rectangle, circle or ellipse that takes room in the flow: a status dot, a swatch, a progress bar |
grid |
Equal columns, filled left to right |
table |
Table with rows, cells, and repeating header |
barcode |
A QR code, Data Matrix, PDF417, Code 128, Code 39, EAN-13, EAN-8, UPC-A or GS1-128 barcode |
link |
Clickable hyperlink wrapper |
bookmark |
Entry in the PDF’s outline and target for links. Draws nothing |
list |
Bulleted or numbered list. Its li items hold a layout, a list inside an item nests, and the engine writes the numbers |
fn |
Footnote inside a text: a raised number in the line, the note at the bottom of the page |
code |
Code in a box that keeps its spaces and lines, wraps what is long and splits across pages. code-span is the same look inside a text |
field |
Interactive PDF form element |
Pagination rules
Section titled “Pagination rules”column— splits between childrentable— splits between rows, and repeats thetheadrow on each pagerow— splits between lines, and through a line: each child stops at its last line above the page edge and goes on at the top of the next page, at the same width. See Rows across pagesgrid— splits between its rows: a grid row is never cut in twolist— splits between items, and through an item: the marker stays with its first part, and the lines after the break stand under the words. See Listtext— splits between lines, keeping at least two lines on each page: see widows and orphansbookmark— stays with the element after itframe— atomic; moves whole to the next page if it doesn’t fit- An element taller than a page that can’t split, such as an image, a frame or a box with
paginate="no", starts a page and is cut at the bottom of it, above the footer. What follows it starts the next page - Setting
heighton a box (a length,fillorfull) also stops it splitting - So does
paginate="no", and the other values ofpaginatestart new pages: see Page breaks
Page breaks
Section titled “Page breaks”paginate sets where an element falls in the page flow. The boxes (column, row, grid, frame), text, img, barcode and table take it.
| Value | Effect |
|---|---|
no |
Never split the element. When it doesn’t fit, it moves whole to the next page |
break-before |
Start the element on a new page |
break-after |
Start the element that follows it on a new page |
keep-next |
Keep the element on one page with the element that follows it: when that one doesn’t fit and can’t start on this page, both move to the next page. One that splits starts here: a table after its header and a row, a text after a few lines, and the element stays with that first part |
break-before, break-after and keep-next only take effect on elements directly inside layout. Inside a column or any other box they are accepted and ignored. no works at any depth: a column with paginate="no" inside another column stays whole. In a section whose page grows in height, the flow is one page, so break-before, break-after and keep-next start no new page.
<layout> <text font-size="xl">Chapter 1</text> <text>The first chapter starts on the first page.</text> <text font-size="xl" paginate="break-before">Chapter 2</text> <text>Each later chapter starts on a new page.</text> <text font-size="l" paginate="keep-next">Summary</text> <column gap="s" padding="m" background="#f5f5f5" paginate="no"> <text>The heading stays on the same page as this box,</text> <text>and the box is never split.</text> </column></layout>L.layout(NoAttr, [ L.text({ fontSize: 'xl' }, ['Chapter 1']), L.text(NoAttr, ['The first chapter starts on the first page.']), L.text({ fontSize: 'xl', paginate: 'break-before' }, ['Chapter 2']), L.text(NoAttr, ['Each later chapter starts on a new page.']), L.text({ fontSize: 'l', paginate: 'keep-next' }, ['Summary']), L.column({ gap: 's', padding: 'm', background: '#f5f5f5', paginate: 'no' }, [ L.text(NoAttr, ['The heading stays on the same page as this box,']), L.text(NoAttr, ['and the box is never split.']), ]),])L.layout(NoAttr, [ L.text(TextAttr(font_size='xl'), ['Chapter 1']), L.text(NoAttr, ['The first chapter starts on the first page.']), L.text(TextAttr(font_size='xl', paginate='break-before'), ['Chapter 2']), L.text(NoAttr, ['Each later chapter starts on a new page.']), L.text(TextAttr(font_size='l', paginate='keep-next'), ['Summary']), L.column(ColumnAttr(gap='s', padding='m', background='#f5f5f5', paginate='no'), [ L.text(NoAttr, ['The heading stays on the same page as this box,']), L.text(NoAttr, ['and the box is never split.']) ])])L.layout(NoAttr, List.of( L.text(new TextAttr().fontSize("xl"), List.of("Chapter 1")), L.text(NoAttr, List.of("The first chapter starts on the first page.")), L.text(new TextAttr().fontSize("xl").paginate("break-before"), List.of("Chapter 2")), L.text(NoAttr, List.of("Each later chapter starts on a new page.")), L.text(new TextAttr().fontSize("l").paginate("keep-next"), List.of("Summary")), L.column(new ColumnAttr().gap("s").padding("m").background("#f5f5f5").paginate("no"), List.of( L.text(NoAttr, List.of("The heading stays on the same page as this box,")), L.text(NoAttr, List.of("and the box is never split.")) ))))L.Layout(NoAttr, [ L.Text(new() { FontSize = "xl" }, ["Chapter 1"]), L.Text(NoAttr, ["The first chapter starts on the first page."]), L.Text(new() { FontSize = "xl", Paginate = "break-before" }, ["Chapter 2"]), L.Text(NoAttr, ["Each later chapter starts on a new page."]), L.Text(new() { FontSize = "l", Paginate = "keep-next" }, ["Summary"]), L.Column(new() { Gap = "s", Padding = "m", Background = "#f5f5f5", Paginate = "no" }, [ L.Text(NoAttr, ["The heading stays on the same page as this box,"]), L.Text(NoAttr, ["and the box is never split."]), ]),])L::layout(NoAttr, [ L::text(new TextAttr(fontSize: 'xl'), ['Chapter 1']), L::text(NoAttr, ['The first chapter starts on the first page.']), L::text(new TextAttr(fontSize: 'xl', paginate: 'break-before'), ['Chapter 2']), L::text(NoAttr, ['Each later chapter starts on a new page.']), L::text(new TextAttr(fontSize: 'l', paginate: 'keep-next'), ['Summary']), L::column(new ColumnAttr(gap: 's', padding: 'm', background: '#f5f5f5', paginate: 'no'), [ L::text(NoAttr, ['The heading stays on the same page as this box,']), L::text(NoAttr, ['and the box is never split.']), ]),])- A break never adds an empty page:
break-beforeon the first element of a page andbreak-afteron the last element of the layout do nothing. - An element with
break-afterthat splits across pages breaks after its last part. - On an element repeated with
data-source, the break applies to each copy, sobreak-beforeputs every item on a page of its own. keep-nextholds only when the two elements fit on one page together. When they don’t, both stay where they would be without it. Withdebug="true"on the element, a red note in the PDF says the rule was ignored.- An element with
nothat is taller than a page starts on a new page and is cut at the bottom of it, above the footer. Withdebug="true"on the element, a red note at the top of the next page says so. Usenoon elements shorter than a page. - On a
td,paginatehas no effect: a table row never splits.
Text color in a box
Section titled “Text color in a box”A box can set the color of the text inside it. color on a column, row, grid, frame or td is taken by every text inside that sets none of its own, however deep. A text takes the color of the nearest box that sets one, else the text color of tokens, which is #1a1a1a unless the document redefines it. A divider or a barcode in the box keeps its own color.
font and font-size on a box are inherited the same way. align is not: on a box it places the children, so a text does not take its alignment from the box around it.
<column gap="xs" padding="m" background="#1763cf" color="#ffffff" radius="s"> <text font-size="l" font="Helvetica-Bold">White on blue</text> <text>Every text in the card takes the white.</text> <text color="#ffd54f">Except one that sets its own.</text></column>L.column({ gap: 'xs', padding: 'm', background: '#1763cf', color: '#ffffff', radius: 's' }, [ L.text({ fontSize: 'l', font: 'Helvetica-Bold' }, ['White on blue']), L.text(NoAttr, ['Every text in the card takes the white.']), L.text({ color: '#ffd54f' }, ['Except one that sets its own.']),])L.column(ColumnAttr(gap='xs', padding='m', background='#1763cf', color='#ffffff', radius='s'), [ L.text(TextAttr(font_size='l', font='Helvetica-Bold'), ['White on blue']), L.text(NoAttr, ['Every text in the card takes the white.']), L.text(TextAttr(color='#ffd54f'), ['Except one that sets its own.'])])L.column(new ColumnAttr().gap("xs").padding("m").background("#1763cf").color("#ffffff").radius("s"), List.of( L.text(new TextAttr().fontSize("l").font("Helvetica-Bold"), List.of("White on blue")), L.text(NoAttr, List.of("Every text in the card takes the white.")), L.text(new TextAttr().color("#ffd54f"), List.of("Except one that sets its own."))))L.Column(new() { Gap = "xs", Padding = "m", Background = "#1763cf", Color = "#ffffff", Radius = "s" }, [ L.Text(new() { FontSize = "l", Font = "Helvetica-Bold" }, ["White on blue"]), L.Text(NoAttr, ["Every text in the card takes the white."]), L.Text(new() { Color = "#ffd54f" }, ["Except one that sets its own."]),])L::column(new ColumnAttr(gap: 'xs', padding: 'm', background: '#1763cf', color: '#ffffff', radius: 's'), [ L::text(new TextAttr(fontSize: 'l', font: 'Helvetica-Bold'), ['White on blue']), L::text(NoAttr, ['Every text in the card takes the white.']), L::text(new TextAttr(color: '#ffd54f'), ['Except one that sets its own.']),])Opacity
Section titled “Opacity”opacity fades a box and everything in it as one, from 1 (the default) to 0. Where the children overlap they do not show through each other, and a box inside a faded box is faded further: 0.5 inside 0.5 is drawn at 0.25. A link in the box stays clickable, and a form field in it is not faded. A box at 0 draws nothing.
<column gap="s"> <column padding="m" background="#1763cf" opacity="0.4"> <text color="#ffffff">A box at 40%, text and all.</text> </column> <column padding="m" background="#1763cf" opacity="0.5"> <column padding="m" background="#cc0000" opacity="0.5"> <text color="#ffffff">0.5 inside 0.5, drawn at 0.25.</text> </column> </column></column>L.column({ gap: 's' }, [ L.column({ padding: 'm', background: '#1763cf', opacity: 0.4 }, [ L.text({ color: '#ffffff' }, ['A box at 40%, text and all.']), ]), L.column({ padding: 'm', background: '#1763cf', opacity: 0.5 }, [ L.column({ padding: 'm', background: '#cc0000', opacity: 0.5 }, [ L.text({ color: '#ffffff' }, ['0.5 inside 0.5, drawn at 0.25.']), ]), ]),])L.column(ColumnAttr(gap='s'), [ L.column(ColumnAttr(padding='m', background='#1763cf', opacity=0.4), [ L.text(TextAttr(color='#ffffff'), ['A box at 40%, text and all.']) ]), L.column(ColumnAttr(padding='m', background='#1763cf', opacity=0.5), [ L.column(ColumnAttr(padding='m', background='#cc0000', opacity=0.5), [ L.text(TextAttr(color='#ffffff'), ['0.5 inside 0.5, drawn at 0.25.']) ]) ])])L.column(new ColumnAttr().gap("s"), List.of( L.column(new ColumnAttr().padding("m").background("#1763cf").opacity(0.4), List.of( L.text(new TextAttr().color("#ffffff"), List.of("A box at 40%, text and all.")) )), L.column(new ColumnAttr().padding("m").background("#1763cf").opacity(0.5), List.of( L.column(new ColumnAttr().padding("m").background("#cc0000").opacity(0.5), List.of( L.text(new TextAttr().color("#ffffff"), List.of("0.5 inside 0.5, drawn at 0.25.")) )) ))))L.Column(new() { Gap = "s" }, [ L.Column(new() { Padding = "m", Background = "#1763cf", Opacity = 0.4 }, [ L.Text(new() { Color = "#ffffff" }, ["A box at 40%, text and all."]), ]), L.Column(new() { Padding = "m", Background = "#1763cf", Opacity = 0.5 }, [ L.Column(new() { Padding = "m", Background = "#cc0000", Opacity = 0.5 }, [ L.Text(new() { Color = "#ffffff" }, ["0.5 inside 0.5, drawn at 0.25."]), ]), ]),])L::column(new ColumnAttr(gap: 's'), [ L::column(new ColumnAttr(padding: 'm', background: '#1763cf', opacity: 0.4), [ L::text(new TextAttr(color: '#ffffff'), ['A box at 40%, text and all.']), ]), L::column(new ColumnAttr(padding: 'm', background: '#1763cf', opacity: 0.5), [ L::column(new ColumnAttr(padding: 'm', background: '#cc0000', opacity: 0.5), [ L::text(new TextAttr(color: '#ffffff'), ['0.5 inside 0.5, drawn at 0.25.']), ]), ]),])A layer has opacity too. A shape or a -at element in a layer has none: put it in a layer of its own.
Shadow
Section titled “Shadow”shadow draws a hard-edged copy of a box under it: "x y color", with an optional opacity from 0 to 1 after the color that fades the shadow alone. x and y are signed lengths: positive is right and down, and negative is left and up. shadow="3pt 3pt #000000 0.2" is a black shadow 3pt right and down, at 20%. The color takes any form: shadow="3pt 3pt cmyk(0, 0, 0, 100)" is a shadow in black ink. A shadow with an opacity is blended in RGB, its cmyk() color too, so keep a print shadow opaque.
- There is no blur. The copy has the box’s
radius. - A shadow takes no room in the layout. It can run into a margin or a neighbor, and the siblings after the box are drawn over it, so leave the space yourself.
- A box with no background shows its shadow only outside it.
- The box’s own
opacityfades the box and its shadow together.
The shapes of a layer (rect, circle and ellipse) take shadow too.
<column gap="xs" padding="m" background="#ffffff" border="xs #e0e0e0" radius="m" shadow="3pt 3pt #000000 0.15"> <text font-size="m" font="Helvetica-Bold">Card title</text> <text font-size="s" color="#666666">A card with a border, rounded corners and a shadow.</text></column>L.column({ gap: 'xs', padding: 'm', background: '#ffffff', border: 'xs #e0e0e0', radius: 'm', shadow: '3pt 3pt #000000 0.15' }, [ L.text({ fontSize: 'm', font: 'Helvetica-Bold' }, ['Card title']), L.text({ fontSize: 's', color: '#666666' }, ['A card with a border, rounded corners and a shadow.']),])L.column(ColumnAttr(gap='xs', padding='m', background='#ffffff', border='xs #e0e0e0', radius='m', shadow='3pt 3pt #000000 0.15'), [ L.text(TextAttr(font_size='m', font='Helvetica-Bold'), ['Card title']), L.text(TextAttr(font_size='s', color='#666666'), ['A card with a border, rounded corners and a shadow.'])])L.column(new ColumnAttr().gap("xs").padding("m").background("#ffffff").border("xs #e0e0e0").radius("m").shadow("3pt 3pt #000000 0.15"), List.of( L.text(new TextAttr().fontSize("m").font("Helvetica-Bold"), List.of("Card title")), L.text(new TextAttr().fontSize("s").color("#666666"), List.of("A card with a border, rounded corners and a shadow."))))L.Column(new() { Gap = "xs", Padding = "m", Background = "#ffffff", Border = "xs #e0e0e0", Radius = "m", Shadow = "3pt 3pt #000000 0.15" }, [ L.Text(new() { FontSize = "m", Font = "Helvetica-Bold" }, ["Card title"]), L.Text(new() { FontSize = "s", Color = "#666666" }, ["A card with a border, rounded corners and a shadow."]),])L::column(new ColumnAttr(gap: 'xs', padding: 'm', background: '#ffffff', border: 'xs #e0e0e0', radius: 'm', shadow: '3pt 3pt #000000 0.15'), [ L::text(new TextAttr(fontSize: 'm', font: 'Helvetica-Bold'), ['Card title']), L::text(new TextAttr(fontSize: 's', color: '#666666'), ['A card with a border, rounded corners and a shadow.']),])Pinned regions
Section titled “Pinned regions”region pins content to the top or bottom of the content area, reserving space from the flow. Useful for per-page headers and footers. It is only allowed directly inside layout. pin chooses the edge wherever the region is written among the flow, and regions on one edge stack in the order they are written: a header and a first-page banner can both be pin="top".
<layout> <region pin="top"> <row> <text font-size="9pt">My Company</text> <text font-size="9pt" width="fill" align="right">Confidential</text> </row> </region> <region pin="bottom"> <text font-size="9pt" align="center" color="#aaaaaa">Page {page} of {pages}</text> </region> <column gap="16pt"> <text font-size="18pt">Main content</text> <text>Body text flows here, between the two regions.</text> </column></layout>L.layout(NoAttr, [ L.region({ pin: 'top' }, [ L.row(NoAttr, [ L.text({ fontSize: '9pt' }, ['My Company']), L.text({ fontSize: '9pt', width: 'fill', align: 'right' }, ['Confidential']), ]), ]), L.region({ pin: 'bottom' }, [ L.text({ fontSize: '9pt', align: 'center', color: '#aaaaaa' }, ['Page {page} of {pages}']), ]), L.column({ gap: '16pt' }, [ L.text({ fontSize: '18pt' }, ['Main content']), L.text(NoAttr, ['Body text flows here, between the two regions.']), ]),])L.layout(NoAttr, [ L.region(RegionAttr(pin='top'), [ L.row(NoAttr, [ L.text(TextAttr(font_size='9pt'), ['My Company']), L.text(TextAttr(font_size='9pt', width='fill', align='right'), ['Confidential']) ]) ]), L.region(RegionAttr(pin='bottom'), [ L.text(TextAttr(font_size='9pt', align='center', color='#aaaaaa'), ['Page {page} of {pages}']) ]), L.column(ColumnAttr(gap='16pt'), [ L.text(TextAttr(font_size='18pt'), ['Main content']), L.text(NoAttr, ['Body text flows here, between the two regions.']) ])])L.layout(NoAttr, List.of( L.region(new RegionAttr().pin("top"), List.of( L.row(NoAttr, List.of( L.text(new TextAttr().fontSize("9pt"), List.of("My Company")), L.text(new TextAttr().fontSize("9pt").width("fill").align("right"), List.of("Confidential")) )) )), L.region(new RegionAttr().pin("bottom"), List.of( L.text(new TextAttr().fontSize("9pt").align("center").color("#aaaaaa"), List.of("Page {page} of {pages}")) )), L.column(new ColumnAttr().gap("16pt"), List.of( L.text(new TextAttr().fontSize("18pt"), List.of("Main content")), L.text(NoAttr, List.of("Body text flows here, between the two regions.")) ))))L.Layout(NoAttr, [ L.Region(new() { Pin = "top" }, [ L.Row(NoAttr, [ L.Text(new() { FontSize = "9pt" }, ["My Company"]), L.Text(new() { FontSize = "9pt", Width = "fill", Align = "right" }, ["Confidential"]), ]), ]), L.Region(new() { Pin = "bottom" }, [ L.Text(new() { FontSize = "9pt", Align = "center", Color = "#aaaaaa" }, ["Page {page} of {pages}"]), ]), L.Column(new() { Gap = "16pt" }, [ L.Text(new() { FontSize = "18pt" }, ["Main content"]), L.Text(NoAttr, ["Body text flows here, between the two regions."]), ]),])L::layout(NoAttr, [ L::region(new RegionAttr(pin: 'top'), [ L::row(NoAttr, [ L::text(new TextAttr(fontSize: '9pt'), ['My Company']), L::text(new TextAttr(fontSize: '9pt', width: 'fill', align: 'right'), ['Confidential']), ]), ]), L::region(new RegionAttr(pin: 'bottom'), [ L::text(new TextAttr(fontSize: '9pt', align: 'center', color: '#aaaaaa'), ['Page {page} of {pages}']), ]), L::column(new ColumnAttr(gap: '16pt'), [ L::text(new TextAttr(fontSize: '18pt'), ['Main content']), L::text(NoAttr, ['Body text flows here, between the two regions.']), ]),])| Attribute | Type | Default | Description |
|---|---|---|---|
pin |
string | — | Required. top or bottom, or inset for a block inside the section’s columns. left and right pass validation but are not implemented yet |
page |
string | each |
Which pages show the region: each, first, last, odd, even, or a range like 2-last. odd and even follow the number printed on the page: see Odd and even pages |
col, colspan, top, height |
— | — | Where an inset is in the columns: see Insets. An error on a region pinned to an edge |
debug |
boolean | false | Render the region’s box for debugging |
With pin="inset", a region is a block at a spot inside the flow instead, which the flow goes around: top and height place it, and in a section with columns, col and colspan say which columns it covers. See Insets.
In the text of a region, {page} becomes the page number and {pages} the total number of pages. Use them for “Page 2 of 5” footers. They are replaced in a region and in a layer’s text-at, and count on from one section to the next unless a section starts them again: see Page numbers. A region takes its space out of the flow, inside the margin. For a page number that takes no space, or sits in the margin, use a layer.
<region pin="top" page="first"> <text font-size="22pt">Cover page title</text></region>L.region({ pin: 'top', page: 'first' }, [ L.text({ fontSize: '22pt' }, ['Cover page title']),])L.region(RegionAttr(pin='top', page='first'), [ L.text(TextAttr(font_size='22pt'), ['Cover page title'])])L.region(new RegionAttr().pin("top").page("first"), List.of( L.text(new TextAttr().fontSize("22pt"), List.of("Cover page title"))))L.Region(new() { Pin = "top", Page = "first" }, [ L.Text(new() { FontSize = "22pt" }, ["Cover page title"]),])L::region(new RegionAttr(pin: 'top', page: 'first'), [ L::text(new TextAttr(fontSize: '22pt'), ['Cover page title']),])Odd and even pages
Section titled “Odd and even pages”page="odd" and page="even" follow the number printed on the page, in any page-format and after any page-prefix, so a book’s right-hand and left-hand running heads stay on their side when a section starts on an even page. A chapter that starts on page 4, by page-start or by counting on from the section before, shows its even head on 4 and 6 and its odd head on 5:
<section page-start="4"> <layout margin="48pt"> <region pin="top" page="even"> <text font-size="9pt">{page} · The Lamplighter's Almanac</text> </region> <region pin="top" page="odd"> <text font-size="9pt" align="right">Chapter 2 · {page}</text> </region> <text font-size="xl">Chapter 2</text> <text paginate="break-before">The chapter goes on.</text> <text paginate="break-before">It ends on page 6.</text> </layout></section>L.section({ pageStart: 4 }, [ L.layout({ margin: '48pt' }, [ L.region({ pin: 'top', page: 'even' }, [ L.text({ fontSize: '9pt' }, ['{page} · The Lamplighter\'s Almanac']), ]), L.region({ pin: 'top', page: 'odd' }, [ L.text({ fontSize: '9pt', align: 'right' }, ['Chapter 2 · {page}']), ]), L.text({ fontSize: 'xl' }, ['Chapter 2']), L.text({ paginate: 'break-before' }, ['The chapter goes on.']), L.text({ paginate: 'break-before' }, ['It ends on page 6.']), ]),])L.section(SectionAttr(page_start=4), [ L.layout(LayoutAttr(margin='48pt'), [ L.region(RegionAttr(pin='top', page='even'), [ L.text(TextAttr(font_size='9pt'), ['{page} · The Lamplighter\'s Almanac']) ]), L.region(RegionAttr(pin='top', page='odd'), [ L.text(TextAttr(font_size='9pt', align='right'), ['Chapter 2 · {page}']) ]), L.text(TextAttr(font_size='xl'), ['Chapter 2']), L.text(TextAttr(paginate='break-before'), ['The chapter goes on.']), L.text(TextAttr(paginate='break-before'), ['It ends on page 6.']) ])])L.section(new SectionAttr().pageStart(4), List.of( L.layout(new LayoutAttr().margin("48pt"), List.of( L.region(new RegionAttr().pin("top").page("even"), List.of( L.text(new TextAttr().fontSize("9pt"), List.of("{page} · The Lamplighter's Almanac")) )), L.region(new RegionAttr().pin("top").page("odd"), List.of( L.text(new TextAttr().fontSize("9pt").align("right"), List.of("Chapter 2 · {page}")) )), L.text(new TextAttr().fontSize("xl"), List.of("Chapter 2")), L.text(new TextAttr().paginate("break-before"), List.of("The chapter goes on.")), L.text(new TextAttr().paginate("break-before"), List.of("It ends on page 6.")) ))))L.Section(new() { PageStart = 4 }, [ L.Layout(new() { Margin = "48pt" }, [ L.Region(new() { Pin = "top", Page = "even" }, [ L.Text(new() { FontSize = "9pt" }, ["{page} · The Lamplighter's Almanac"]), ]), L.Region(new() { Pin = "top", Page = "odd" }, [ L.Text(new() { FontSize = "9pt", Align = "right" }, ["Chapter 2 · {page}"]), ]), L.Text(new() { FontSize = "xl" }, ["Chapter 2"]), L.Text(new() { Paginate = "break-before" }, ["The chapter goes on."]), L.Text(new() { Paginate = "break-before" }, ["It ends on page 6."]), ]),])L::section(new SectionAttr(pageStart: 4), [ L::layout(new LayoutAttr(margin: '48pt'), [ L::region(new RegionAttr(pin: 'top', page: 'even'), [ L::text(new TextAttr(fontSize: '9pt'), ['{page} · The Lamplighter\'s Almanac']), ]), L::region(new RegionAttr(pin: 'top', page: 'odd'), [ L::text(new TextAttr(fontSize: '9pt', align: 'right'), ['Chapter 2 · {page}']), ]), L::text(new TextAttr(fontSize: 'xl'), ['Chapter 2']), L::text(new TextAttr(paginate: 'break-before'), ['The chapter goes on.']), L::text(new TextAttr(paginate: 'break-before'), ['It ends on page 6.']), ]),])first, last, numbers and ranges count the section’s own pages, whatever is printed on them: page="2-last" leaves out the first page of the section wherever it starts, and page="2" is its second page, printed 5 here. A layer’s page works the same way. A section that sets page-start="1" counts its odd pages from its first.
Running headers
Section titled “Running headers”A header or a footer can show text from its own page, such as the title of the chapter it is on, or the first and last entry of a dictionary page. Mark the source in the flow with capture, and show it in a region with capture-ref.
| Attribute | On | Meaning |
|---|---|---|
capture="name" |
a text in the flow |
Records the words of the text under that name, as the pages are filled |
capture-ref="name" |
a text in a region |
Shows what was recorded under the name, as of the page it is drawn on. It has no words of its own |
capture-mode |
the capture-ref text |
first or last (default): which of the texts captured under the name on that page it shows |
capture-fallback |
the capture-ref text |
What it shows until something has been captured in the section. Nothing by default |
The chapter title in the header of every page:
<layout> <region pin="top"> <row gap="m"> <text width="fill" font-size="s" color="#737373" capture-ref="chapter" capture-fallback="Front matter"/> <text font-size="s" color="#737373">Page {page}</text> </row> </region> <column gap="m"> <text font-size="xl" capture="chapter">Chapter 1: The Lamp Room</text> <text>The text of the first chapter runs here, and onto as many pages as it needs. Every page of it shows its chapter in the header.</text> </column> <column gap="m" paginate="break-before"> <text font-size="xl" capture="chapter">Chapter 2: The Record</text> <text>The second chapter starts a page, and from there the header reads its title.</text> </column></layout>L.layout(NoAttr, [ L.region({ pin: 'top' }, [ L.row({ gap: 'm' }, [ L.text({ width: 'fill', fontSize: 's', color: '#737373', captureRef: 'chapter', captureFallback: 'Front matter' }), L.text({ fontSize: 's', color: '#737373' }, ['Page {page}']), ]), ]), L.column({ gap: 'm' }, [ L.text({ fontSize: 'xl', capture: 'chapter' }, ['Chapter 1: The Lamp Room']), L.text(NoAttr, ['The text of the first chapter runs here, and onto as many pages as it needs. Every page of it shows its chapter in the header.']), ]), L.column({ gap: 'm', paginate: 'break-before' }, [ L.text({ fontSize: 'xl', capture: 'chapter' }, ['Chapter 2: The Record']), L.text(NoAttr, ['The second chapter starts a page, and from there the header reads its title.']), ]),])L.layout(NoAttr, [ L.region(RegionAttr(pin='top'), [ L.row(RowAttr(gap='m'), [ L.text(TextAttr(width='fill', font_size='s', color='#737373', capture_ref='chapter', capture_fallback='Front matter')), L.text(TextAttr(font_size='s', color='#737373'), ['Page {page}']) ]) ]), L.column(ColumnAttr(gap='m'), [ L.text(TextAttr(font_size='xl', capture='chapter'), ['Chapter 1: The Lamp Room']), L.text(NoAttr, ['The text of the first chapter runs here, and onto as many pages as it needs. Every page of it shows its chapter in the header.']) ]), L.column(ColumnAttr(gap='m', paginate='break-before'), [ L.text(TextAttr(font_size='xl', capture='chapter'), ['Chapter 2: The Record']), L.text(NoAttr, ['The second chapter starts a page, and from there the header reads its title.']) ])])L.layout(NoAttr, List.of( L.region(new RegionAttr().pin("top"), List.of( L.row(new RowAttr().gap("m"), List.of( L.text(new TextAttr().width("fill").fontSize("s").color("#737373").captureRef("chapter").captureFallback("Front matter"), List.of()), L.text(new TextAttr().fontSize("s").color("#737373"), List.of("Page {page}")) )) )), L.column(new ColumnAttr().gap("m"), List.of( L.text(new TextAttr().fontSize("xl").capture("chapter"), List.of("Chapter 1: The Lamp Room")), L.text(NoAttr, List.of("The text of the first chapter runs here, and onto as many pages as it needs. Every page of it shows its chapter in the header.")) )), L.column(new ColumnAttr().gap("m").paginate("break-before"), List.of( L.text(new TextAttr().fontSize("xl").capture("chapter"), List.of("Chapter 2: The Record")), L.text(NoAttr, List.of("The second chapter starts a page, and from there the header reads its title.")) ))))L.Layout(NoAttr, [ L.Region(new() { Pin = "top" }, [ L.Row(new() { Gap = "m" }, [ L.Text(new() { Width = "fill", FontSize = "s", Color = "#737373", CaptureRef = "chapter", CaptureFallback = "Front matter" }), L.Text(new() { FontSize = "s", Color = "#737373" }, ["Page {page}"]), ]), ]), L.Column(new() { Gap = "m" }, [ L.Text(new() { FontSize = "xl", Capture = "chapter" }, ["Chapter 1: The Lamp Room"]), L.Text(NoAttr, ["The text of the first chapter runs here, and onto as many pages as it needs. Every page of it shows its chapter in the header."]), ]), L.Column(new() { Gap = "m", Paginate = "break-before" }, [ L.Text(new() { FontSize = "xl", Capture = "chapter" }, ["Chapter 2: The Record"]), L.Text(NoAttr, ["The second chapter starts a page, and from there the header reads its title."]), ]),])L::layout(NoAttr, [ L::region(new RegionAttr(pin: 'top'), [ L::row(new RowAttr(gap: 'm'), [ L::text(new TextAttr(width: 'fill', fontSize: 's', color: '#737373', captureRef: 'chapter', captureFallback: 'Front matter')), L::text(new TextAttr(fontSize: 's', color: '#737373'), ['Page {page}']), ]), ]), L::column(new ColumnAttr(gap: 'm'), [ L::text(new TextAttr(fontSize: 'xl', capture: 'chapter'), ['Chapter 1: The Lamp Room']), L::text(NoAttr, ['The text of the first chapter runs here, and onto as many pages as it needs. Every page of it shows its chapter in the header.']), ]), L::column(new ColumnAttr(gap: 'm', paginate: 'break-before'), [ L::text(new TextAttr(fontSize: 'xl', capture: 'chapter'), ['Chapter 2: The Record']), L::text(NoAttr, ['The second chapter starts a page, and from there the header reads its title.']), ]),])A dictionary page shows its first and last entry. Every entry carries the same name, and the header asks for each end: first and last are two texts on one name.
<layout> <region pin="top"> <row gap="s"> <text width="fill" align="right" font-size="s" capture-ref="entry" capture-mode="first"/> <text font-size="s">–</text> <text width="fill" font-size="s" capture-ref="entry" capture-mode="last"/> </row> </region> <column gap="xs" paginate="no"> <text font="Helvetica-Bold" capture="entry">Abacus</text> <text>A frame of rods and sliding beads used for counting.</text> </column> <column gap="xs" paginate="no"> <text font="Helvetica-Bold" capture="entry">Abbey</text> <text>A building where monks or nuns live, work and pray.</text> </column></layout>L.layout(NoAttr, [ L.region({ pin: 'top' }, [ L.row({ gap: 's' }, [ L.text({ width: 'fill', align: 'right', fontSize: 's', captureRef: 'entry', captureMode: 'first' }), L.text({ fontSize: 's' }, ['–']), L.text({ width: 'fill', fontSize: 's', captureRef: 'entry', captureMode: 'last' }), ]), ]), L.column({ gap: 'xs', paginate: 'no' }, [ L.text({ font: 'Helvetica-Bold', capture: 'entry' }, ['Abacus']), L.text(NoAttr, ['A frame of rods and sliding beads used for counting.']), ]), L.column({ gap: 'xs', paginate: 'no' }, [ L.text({ font: 'Helvetica-Bold', capture: 'entry' }, ['Abbey']), L.text(NoAttr, ['A building where monks or nuns live, work and pray.']), ]),])L.layout(NoAttr, [ L.region(RegionAttr(pin='top'), [ L.row(RowAttr(gap='s'), [ L.text(TextAttr(width='fill', align='right', font_size='s', capture_ref='entry', capture_mode='first')), L.text(TextAttr(font_size='s'), ['–']), L.text(TextAttr(width='fill', font_size='s', capture_ref='entry', capture_mode='last')) ]) ]), L.column(ColumnAttr(gap='xs', paginate='no'), [ L.text(TextAttr(font='Helvetica-Bold', capture='entry'), ['Abacus']), L.text(NoAttr, ['A frame of rods and sliding beads used for counting.']) ]), L.column(ColumnAttr(gap='xs', paginate='no'), [ L.text(TextAttr(font='Helvetica-Bold', capture='entry'), ['Abbey']), L.text(NoAttr, ['A building where monks or nuns live, work and pray.']) ])])L.layout(NoAttr, List.of( L.region(new RegionAttr().pin("top"), List.of( L.row(new RowAttr().gap("s"), List.of( L.text(new TextAttr().width("fill").align("right").fontSize("s").captureRef("entry").captureMode("first"), List.of()), L.text(new TextAttr().fontSize("s"), List.of("–")), L.text(new TextAttr().width("fill").fontSize("s").captureRef("entry").captureMode("last"), List.of()) )) )), L.column(new ColumnAttr().gap("xs").paginate("no"), List.of( L.text(new TextAttr().font("Helvetica-Bold").capture("entry"), List.of("Abacus")), L.text(NoAttr, List.of("A frame of rods and sliding beads used for counting.")) )), L.column(new ColumnAttr().gap("xs").paginate("no"), List.of( L.text(new TextAttr().font("Helvetica-Bold").capture("entry"), List.of("Abbey")), L.text(NoAttr, List.of("A building where monks or nuns live, work and pray.")) ))))L.Layout(NoAttr, [ L.Region(new() { Pin = "top" }, [ L.Row(new() { Gap = "s" }, [ L.Text(new() { Width = "fill", Align = "right", FontSize = "s", CaptureRef = "entry", CaptureMode = "first" }), L.Text(new() { FontSize = "s" }, ["–"]), L.Text(new() { Width = "fill", FontSize = "s", CaptureRef = "entry", CaptureMode = "last" }), ]), ]), L.Column(new() { Gap = "xs", Paginate = "no" }, [ L.Text(new() { Font = "Helvetica-Bold", Capture = "entry" }, ["Abacus"]), L.Text(NoAttr, ["A frame of rods and sliding beads used for counting."]), ]), L.Column(new() { Gap = "xs", Paginate = "no" }, [ L.Text(new() { Font = "Helvetica-Bold", Capture = "entry" }, ["Abbey"]), L.Text(NoAttr, ["A building where monks or nuns live, work and pray."]), ]),])L::layout(NoAttr, [ L::region(new RegionAttr(pin: 'top'), [ L::row(new RowAttr(gap: 's'), [ L::text(new TextAttr(width: 'fill', align: 'right', fontSize: 's', captureRef: 'entry', captureMode: 'first')), L::text(new TextAttr(fontSize: 's'), ['–']), L::text(new TextAttr(width: 'fill', fontSize: 's', captureRef: 'entry', captureMode: 'last')), ]), ]), L::column(new ColumnAttr(gap: 'xs', paginate: 'no'), [ L::text(new TextAttr(font: 'Helvetica-Bold', capture: 'entry'), ['Abacus']), L::text(NoAttr, ['A frame of rods and sliding beads used for counting.']), ]), L::column(new ColumnAttr(gap: 'xs', paginate: 'no'), [ L::text(new TextAttr(font: 'Helvetica-Bold', capture: 'entry'), ['Abbey']), L::text(NoAttr, ['A building where monks or nuns live, work and pray.']), ]),])How a header chooses what to show:
- The page that holds a capture counts it, the words above it on that page included.
- A page where nothing is captured under the name shows the latest value of an earlier page, whichever
capture-modeit has. Before any capture it showscapture-fallback. - A text that splits across pages is recorded on the page where it starts.
- A table’s
theadthat repeats on each page the table continues on records itscaptureonce, on the page where the table starts. The copies on the later pages are drawn but capture nothing, so they do not put the header’s words back over what the rows captured since. - Each section starts with nothing captured, so a header’s value does not carry from one section into the next.
capture,capture-ref,capture-modeandcapture-fallbackare attributes of the layout’stext, not of a layer’stext-at.- A text with
capture-refalways takes its line, whatever it shows, so the header is the same height on every page: one line, ormax-linesof them. A longer value is cut at that, and ends in dots withellipsis="true". A text cannot have bothcaptureandcapture-ref.