Set Page Layout Options

Sets page-level properties: paper size, orientation, margins, font, and pagination controls. Only the arguments you explicitly supply are changed — all others retain their current values. This allows incremental updates anywhere in a pipeline.

Usage

fr_page(
  spec,
  orientation = NULL,
  paper = NULL,
  margins = NULL,
  font_family = NULL,
  font_size = NULL,
  orphan_min = NULL,
  widow_min = NULL,
  continuation = NULL,
  col_gap = NULL,
  tokens = NULL
)

Arguments

spec

An fr_spec object from fr_table().

orientation

"landscape" (default, 11 × 8.5 in for Letter) or "portrait" (8.5 × 11 in).

paper

"letter" (default, 8.5 × 11 in), "a4" (210 × 297 mm), or "legal" (8.5 × 14 in).

margins

Margin(s) in inches. Accepts:

Scalar: 1 — all four sides equal.
Length 2: c(vertical, horizontal) — top/bottom vs left/right.
Length 4: c(top, right, bottom, left) — CSS order.
Named list: list(top=1, bottom=1, left=0.75, right=0.75).

font_family

Font family name. Defaults to the OS monospace font ("Courier New" on Windows/macOS, "Latin Modern Mono" on Linux). Regulatory submissions typically use Courier New 9pt. Set the ARFRAME_FONT_DIR environment variable to a directory containing .ttf/.otf files to make custom fonts available for PDF rendering without system-wide installation. Ideal for Docker, CI, or project-local fonts. See vignette("automation") for examples.

font_size

Font size in points. Default 9. Typical pharma range: 7–10 pt.

orphan_min

Minimum body rows to keep at the bottom of a page before forcing a page break. Default 3L. Set to 1L to disable.

widow_min

Minimum body rows to carry to the top of the next page. Default 3L. Set to 1L to disable.

continuation

Character scalar appended to the column header block on continuation pages, e.g. "(continued)". NULL (default) disables.

col_gap

Inter-column padding in points (total gap between adjacent columns). Default 4 (2 pt left + 2 pt right per cell). Increase to 6 or 8 if long text in adjacent columns runs together. Set to 0 for zero padding (cells flush, legacy behaviour). Applied symmetrically as half the value on each side of every cell in both RTF and PDF output.

tokens

Named list of custom {token} values for use in page headers/footers. E.g. list(study = "TFRM-2024-001", pop = "FAS"). Use these tokens in fr_pagehead() and fr_pagefoot() strings.

Value

A modified fr_spec. Page settings stored in spec$page.

Regulatory conventions

FDA/US submissions (eCTD): landscape Letter (8.5 × 11 in), Courier New 9 pt, 1 in margins on all sides. This is the most common regulatory RTF standard and the package default.

EMA/European submissions: A4 paper (210 × 297 mm) is acceptable; landscape A4 is common for wide safety tables.

Database cutoff date is a mandatory element in every CSR table. The standard practice is to define it as a custom token:

fr_page(tokens = list(cutoff = "31DEC2024")) |>
fr_pagehead(left  = "Study: {study}",
            right = "Database Cutoff: {cutoff}")

Continuation label: multi-page tables must indicate continuation. Regulatory convention is to append "(continued)" to the column header block on all pages after the first:

fr_page(continuation = "(continued)")

Tips

tokens are the clean way to inject study-level metadata (study number, cutoff date, population) into running headers without repeating the value in every fr_pagehead() call.
orphan_min = 3 means: if fewer than 3 rows would remain at the bottom of a page before a group_by group, move the group to the next page.

Examples

## ── Standard pharma RTF setup ────────────────────────────────────────────

tbl_demog |>
  fr_table() |>
  fr_page(
    orientation = "landscape",
    paper       = "letter",
    font_family = "Courier New",
    font_size   = 9,
    margins     = 1
  )
#> 
#> ── fr_spec: Table 
#> Data: 28 rows x 6 columns
#> Page: landscape letter, 9pt Courier New
#> Header: valign=bottom

## ── A4 portrait for European submissions ─────────────────────────────────

tbl_demog |>
  fr_table() |>
  fr_page(orientation = "portrait", paper = "a4", font_size = 9)
#> 
#> ── fr_spec: Table 
#> Data: 28 rows x 6 columns
#> Page: portrait a4, 9pt Courier New
#> Header: valign=bottom

## ── Narrow margins to fit wide table ─────────────────────────────────────

tbl_demog |>
  fr_table() |>
  fr_page(margins = c(1, 0.5))   # top/bottom = 1in, left/right = 0.5in
#> 
#> ── fr_spec: Table 
#> Data: 28 rows x 6 columns
#> Page: landscape letter, 9pt Courier New
#> Header: valign=bottom

## ── Custom tokens for running header ─────────────────────────────────────

tbl_demog |>
  fr_table() |>
  fr_page(tokens = list(study = "TFRM-2024-001", pop = "FAS")) |>
  fr_pagehead(left  = "Study: {study}  Population: {pop}",
              right = "Page {thepage} of {total_pages}")
#> 
#> ── fr_spec: Table 
#> Data: 28 rows x 6 columns
#> Page: landscape letter, 9pt Courier New
#> Header: valign=bottom

## ── Continuation label on multi-page tables ──────────────────────────────

tbl_ae_soc |>
  fr_table() |>
  fr_page(continuation = "(continued)")
#> 
#> ── fr_spec: Table 
#> Data: 96 rows x 7 columns
#> Page: landscape letter, 9pt Courier New
#> Header: valign=bottom

## ── Tight orphan/widow control ────────────────────────────────────────────

tbl_ae_soc |>
  fr_table() |>
  fr_page(orphan_min = 2L, widow_min = 2L)
#> 
#> ── fr_spec: Table 
#> Data: 96 rows x 7 columns
#> Page: landscape letter, 9pt Courier New
#> Header: valign=bottom

## ── Wider inter-column padding ─────────────────────────────────────────

tbl_demog |>
  fr_table() |>
  fr_page(col_gap = 8)   # 4 pt each side (generous spacing)
#> 
#> ── fr_spec: Table 
#> Data: 28 rows x 6 columns
#> Page: landscape letter, 9pt Courier New, col_gap=8pt
#> Header: valign=bottom

## ── Legal paper size (8.5 x 14 in) ─────────────────────────────────────

tbl_ae_soc |>
  fr_table() |>
  fr_page(paper = "legal", orientation = "landscape", margins = 1)
#> 
#> ── fr_spec: Table 
#> Data: 96 rows x 7 columns
#> Page: landscape legal, 9pt Courier New
#> Header: valign=bottom

## ── Custom fonts via ARFRAME_FONT_DIR (Docker/CI) ────────────────────

# Set ARFRAME_FONT_DIR to a directory of .ttf/.otf files;
# XeLaTeX discovers them by name --- no system install needed.
# Sys.setenv(ARFRAME_FONT_DIR = "/path/to/fonts")