Named pages

Sometimes it is necessary to style pages depending on their content; named pages allow us to select pages that contain particular elements. We used this in Restarting page numbering, to apply a style to the table of contents pages to print their page numbers using roman numerals.

The element containing the table of contents has a page property applied, specifying that this element's pages are table-of-contents pages. The page property may be applied to any block-level element within a non-floating environment in the normal flow.

.contents {
    display: block;
    page: table-of-contents;
}

Then using this page name to apply a different @page rule to the table-of-contents pages:

@page table-of-contents {
    @top { content: "Table of Contents" }
    @bottom {
        content: counter(page, lower-alpha)
    }
}

More than one element can belong to the same name, in other words, page names behave like CSS classes.

Prince will create a page break between elements belonging to different named pages, including elements without a named page. So in Restarting page numbering, a page break will be inserted after the the table of contents, because the next element has the page name main rather than table-of-contents.

Selectors such as :first, :Nth, :left and :right also work with named pages. For example:

@page preface {
    @bottom {
        content: counter(page, lower-alpha)
    }
}
@page preface:first {
    @bottom {
        content: normal;
    }
}

This example only works when a page name is used only once within a document, such as for the preface of a document (documents only have one preface). If you wish to apply a style to the first page of every chapter then you must use the prince-page-group property to create page groups:

div.chapter {
    page: chapter;
    page-break-before: right;
    prince-page-group: start;
}
@page chapter {
    @bottom {
        content: counter(page);
    }
}
@page chapter:first {
    @bottom {
        content: normal;
    }
}

The property prince-page-group: start instructs Prince to start a new page group. This is necessary for the div.chapter:first selector to match the first page of each chapter, instead of only the first page in the first chapter. See Page groups.

Page groups

When consecutive elements belong to the same named page but logically separate structures (such as individual chapters) Prince combines them into one page group. This causes it to apply the :first page selector to the first page of the whole page group only (the first page of chapter 1). Instead we usually want :first applied to the first page of each chapter.

This can happen either:

• when chapters are separated by an element, such as h1 which may have page-break-before: right applied (this can be seen in Fancy headers);
• or when each chapter is a block element such as a div.

Prince provides the prince-page-group property that can be used to start a new page group. It can be seen in Fancy headers applied to h1 elements in the body of the document.

div.body h1 {
    page-break-before: right;
    prince-page-group: start;
    ...
}

prince-page-group also forces a page break, overriding any properties that attempt to avoid page breaks. The more specific left and right page take precedence over prince-page-group.

Page breaks and decoration

Box decoration break sample

This figure shows the result of using the box-decoration-break property. On the left the clone value is used while on the right slice is used. The PDF and HTML are available for download.

When a page (or column) break occurs within a box (such as a div) its bottom and top borders are cloned so that they also appear at the bottom of the first section and the top of the second section of the box. This is shown in the left of Box decoration break sample. This is the default but may be set with the box-decoration-break property, setting its value to clone.

div.box1 {
    box-decoration-break: clone
}

If instead you wish the borders to remain open, as if the box were simply sliced in half, as in the right of Box decoration break sample, then you can set this property to slice.

div.box2 {
    box-decoration-break: slice
}

Printing wide content sideways

Printing a big table sideways

This table is too wide to fit on the paper, so we use prince-rotate-body in a named page to print it sideways. Download the PDF or the HTML.

Sometimes it is necessary to rotate a block element so that it fits on the page. This is common with tables. Figure Printing a big table sideways shows a table, rotated so that its width fits within the page's length. This can be acheived with the following rules:

@page big_table {
    prince-rotate-body: landscape;
    prince-shrink-to-fit: auto;
}

table.big {
    page: big_table
}

The prince-rotate-body property works within @page rules only, so this example uses a named page to place the table on a page of its own. Then the @page rule for big_table pages uses the prince-rotate-body property to tell prince that the body of the page, but not the headers and footers, should be rotated. The table in this example is still too wide so we also use the prince-shrink-to-fit property to make it a little smaller.

If you download the full example (HTML or PDF) you will see that the paragraphs before and after the table are not placed on the same page. This is because they do not belong to the same named page (see Named pages). However on page four there are two tables, both tables belong to the same named page and therefore Prince will try to place them together on the same page.

Another way of rotating content is by changing the writing mode with the writing-mode property, or by transforming an element with transform: rotate() - see Rotating content in table cells.