CSS Fragmentation Controls Module Level 3

Abstract

This module describes the fragmentation model that partitions a flow into pages. It builds on the Page model module and introduces and defines the fragmentation model. It adds functionality for pagination, breaking variable fragment size and orientation, widows and orphans.

Status of this document

Table of contents

Introduction

This section is not normative.

Paged media (e.g., paper, transparencies, photo album pages, pages displayed on computer screens as printed output simulations) differ from continuous media in that the content of the document is split into one or more discrete static display surfaces. To handle pages, CSS3 Paged Media describes how:

• page breaks are created and avoided;
• the page properties such as size, orientation, margins, border, and padding are specified;
• headers and footers are established within the page margins;
• content such as page counters are placed in the headers and footers; and
• orphans and widows can be controlled.

This module defines a page model that specifies how a document is formatted within a rectangular area, called the page box, that has finite width and height.

Although CSS3 does not specify how user agents transfer page boxes to sheets, it does include certain mechanisms for telling user agents about the intended page sheet size and orientation. In the general case, CSS3 assumes that one page box will be transferred to one surface of similar size.

All properties defined in this specification also accept the inherit keyword as their value, but for readability it has not been listed explicitly.

Module Interactions

This module replaces and extends the pagination controls defined in [[CSS21]] section 13.3 and in [[CSS3PAGE]].

Values

This specification follows the CSS property definition conventions from [[!CSS21]]. Value types not defined in this specification are defined in CSS Level 2 Revision 1 [[!CSS21]]. Other CSS modules may expand the definitions of these value types: for example [[CSS3COLOR]], when combined with this module, expands the definition of the <color> value type as used in this specification.

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the inherit keyword as their property value. For readability it has not been repeated explicitly.

Page Breaks

The following sections explain page breaking in CSS3 paged media. Five properties indicate where the user agent MAY or SHOULD break pages, and on what page (left or right) the subsequent content SHOULD resume. Each page break ends layout in the current page box and causes remaining pieces of the document tree to be laid out in a new page box.

When a page break splits a box, the box's bottom margins, borders, and padding have no visual effect where the split occurs; the box's background and left and right margins, border, and padding extend to the bottom of the page, through an ensuing blank page if one exists, and onto the top of the subsequent page.

Break before/after elements: 'page-break-before', 'page-break-after', 'page-break-inside'

Values for these properties have the following meanings:

auto

Neither force nor forbid a page break before / after / inside the generated box.

always

Always force a page break before / after the generated box.

avoid

Avoid a page break before / after / inside the generated box.

left

Force one or two page breaks before (after) the generated box so that the next page is formatted as a left page.

right

Force one or two page breaks before (after) the generated box so that the next page is formatted as a right page.

A potential page break location is typically under the influence of the parent element's 'page-break-inside' property, the 'page-break-after' property of the preceding element, and the 'page-break-before' property of the following element. When these properties have values other than 'auto', the values 'always', 'left', and 'right' take precedence over 'avoid'. See the section on allowed page breaks for the exact rules on how these properties affect page breaks.

User Agents must apply these properties to block-level boxes and to table rows, table row groups, and—in the case of 'page-break-inside'—table cells of block-level tables in the normal flow of the root element. User agents should also apply these properties to floated boxes whose containing block is in the normal flow of the root element. User agents may also apply these properties to other boxes.

Using named pages: 'page'

The 'page' property is used to specify a particular type of page where an element SHOULD be displayed.

@page rotated { size: landscape }
table { page: rotated; page-break-before: right }
        

The 'page' property works as follows: If a block box with inline content has a 'page' property that is different from the preceding block box with inline content, then one or two page breaks are inserted between them, and the boxes after the break are rendered on a page box of the named type. See "Forced page breaks" below.

The 'page' property does not inherit. However, if the 'page' value on an element is ''auto'', then it is treated as having the same name as its nearest ancestor with a non-auto value. When indicated on the root element, the effective name is the empty string.

Because a previous version of this specification indicated that the 'page' property is inherited, an implementation that inherits the 'page' property and treats ''auto'' as always naming the empty string remains conformant to CSS3 Paged Media. Therefore authors should not explicitly specify the ''auto'' value on a descendant of an element with a non-''auto'' 'page' value as the resulting behavior will be unpredictable.

Page names are case-sensitive identifiers. However the ''auto'' value, being a CSS keyword, is case-insensitive.

@page narrow { size: 9cm 18cm }
@page rotated { size: landscape }
div { page: narrow }
table { page: rotated }

<div>
<table>...</table>
<table>...</table>
<p>This text is rendered on a 'narrow' page</p>
</div>

Breaks inside elements: 'orphans', 'widows'

The 'orphans' property specifies the minimum number of line boxes in a block element that MUST be left at the bottom of a page. The 'widows' property specifies the minimum number of line boxes of a block element that MUST be left at the top of a page. Examples of how they are used to control page breaks are given below.

Only positive integers are allowed as values of 'orphans' and 'widows'. Negative values and zero are invalid must cause the declaration to be ignored.

If a block contains fewer lines than the value of 'widows' or 'orphans', the rule simply becomes that all lines in the block must be kept together.

Allowed page breaks

In the normal flow, page breaks may occur at the following places:

1. In the vertical margin between sibling block boxes (or rows in a table). When an unforced page break occurs here, both the adjoining 'margin-top' and 'margin-bottom' are set to zero.
2. Between line boxes inside a block box.
3. Between the content edge of a block box and the outer edges of its child content (margin edges of block-level children or line box edges for inline-level children) if there is a (non-zero) gap between them.

These breaks are subject to the following rules:

• Rule A: Breaking at (1) is allowed only if the 'page-break-after' and 'page-break-before' properties of all the elements generating boxes that meet at this margin allow it, which is when at least one of them has the value 'always', 'left', or 'right', or when all of them are 'auto'.
• Rule B: However, if all of them are 'auto' and a common ancestor of all the elements has a 'page-break-inside' value of 'avoid', then breaking here is not allowed.
• Rule C: Breaking at (2) is allowed only if the number of line boxes between the break and the start of the enclosing block box is the value of 'orphans' or more, and the number of line boxes between the break and the end of the box is the value of 'widows' or more.
• Rule D: In addition, breaking at (2) or (3) is allowed only if the 'page-break-inside' property of all ancestors is ''auto''.

If the above doesn't provide enough break points to keep content from overflowing the page boxes, then rules A, B and D are dropped in order to find additional breakpoints. In this case the UA may use the 'avoid's that are in effect at those points to weigh the appropriateness of the new breakpoints; however, this specification does not suggest a precise algorithm.

If that still does not lead to sufficient break points, rule C is dropped as well, to find still more break points.

Forced page breaks

A page break MUST occur at (1) if, among the'page-break-after' and 'page-break-before' properties of all the elements generating boxes that meet at this margin, there is at least one with the value 'always', 'left', or 'right'.

When multiple 'page-break-before' and/or 'page-break-after' properties with values of "always", "left" or "right" apply at a margin, only one of them should generate page breaks. That is, no content-empty pages are generated by page-break properties, except for at most one content-empty page as may be required by 'right' and 'left' values to position ensuing content on a right- or left-facing page.

A page break MUST also occur at (1) if the last line box above this margin and the first one below it do not have the same value for 'page'.

When a forced page break occurs at (1), the used values of any adjoining 'margin-bottom' are set to zero.

"Best" page breaks

CSS3 does not define which of a set of allowed page breaks MUST be used; except as defined earlier in the section, CSS3 does not forbid a user agent to break at every possible break point, or to not break at all. But CSS3 does recommend that user agents observe the following guidelines (while recognizing that they are sometimes contradictory):

• Break as few times as possible.
• Make all pages that don't end with a forced break appear to have about the same height.
• Avoid breaking inside a replaced element.

Conformance

Document Conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [[!RFC2119]]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformance Classes

Conformance to CSS Fragmentation is defined for three conformance classes:

style sheet

A CSS style sheet.

renderer

A UA that interprets the semantics of a style sheet and renders documents that use them.

authoring tool

A UA that writes a style sheet.

A style sheet is conformant to CSS Fragmentation if all of its declarations that use properties defined in this module have values that are valid according to the generic CSS grammar and the individual grammars of each property as given in this module.

A renderer is conformant to CSS Fragmentation if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by CSS Fragmentation by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to CSS Fragmentation if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial Implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Experimental Implementations

To avoid clashes with future CSS features, the CSS2.1 specification reserves a prefixed syntax for proprietary and experimental extensions to CSS.

Prior to a specification reaching the Candidate Recommendation stage in the W3C process, all implementations of a CSS feature are considered experimental. The CSS Working Group recommends that implementations use a vendor-prefixed syntax for such features, including those in W3C Working Drafts. This avoids incompatibilities with future changes in the draft.

Non-Experimental Implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group's website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

CR Exit Criteria

For this specification to be advanced to Proposed Recommendation, there must be at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products, there is no requirement that all features be implemented by a single product. For the purposes of this criterion, we define the following terms:

independent

each implementation must be developed by a different party and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.

interoperable

passing the respective test case(s) in the official CSS test suite, or, if the implementation is not a Web browser, an equivalent test. Every relevant test in the test suite should have an equivalent test created if such a user agent (UA) is to be used to claim interoperability. In addition if such a UA is to be used to claim interoperability, then there must one or more additional UAs which can also pass those equivalent tests in the same way for the purpose of interoperability. The equivalent tests must be made publicly available for the purposes of peer review.

implementation

a user agent which:

1. implements the specification.
2. is available to the general public. The implementation may be a shipping product or other publicly available version (i.e., beta version, preview release, or “nightly build”). Non-shipping product releases must have implemented the feature(s) for a period of at least one month in order to demonstrate stability.
3. is not experimental (i.e., a version specifically designed to pass the test suite and is not intended for normal usage going forward).

The specification will remain Candidate Recommendation for at least six months.

Acknowledgments

The editors would like to extend special thanks to Michael Day, and the former [[CSS3PAGE]] editors Jim Bigelow (HP), Melinda Grant (HP), Håkon Wium Lie (Opera), and Jacob Refstrup (HP) for their contributions to this specification.

References

Normative references

Other references

Index

Property index