Skip to contents

Add stub (spanning) column definition

Source: R/spec_context.R
add_span_header.Rd

Define a spanning header that covers multiple columns. Can be used to create multi-level headers by specifying different stubOrder values.

Usage

add_span_header(
  spec,
  cols,
  label,
  stubOrder = NULL,
  id = NULL,
  labelStyleRef = NULL
)

Arguments

spec

TFL spec object

cols

Columns to span using tidyselect syntax. Accepts:

  • Named columns: c("age", "sex")

  • Column ranges: age:sex

  • Helper functions: starts_with("age_"), contains("_pct")

  • Negation: -id or !matches("^temp")

label

Spanning header label

stubOrder

Order of stub header (auto-generated if NULL). Used to create multi-level headers: HIGHER numbers render HIGHER on the page. stubOrder = 1 is the band directly above the column-label row, stubOrder = 2 the band above that, and so on. Multiple stubs at the same order share one header row if their column sets do not overlap. Any numeric value is accepted (0 and negatives included) — bands simply sort by value; all of them still sit ABOVE the column-label row. When omitted, the order auto-increments, so each later call stacks above the previous one.

id

Stub column identifier (auto-generated if NULL)

labelStyleRef

List of style names to be applied. Provided styles will be merged with last-win strategy for report

Value

Updated spec object

Details

Column Overlap Rules

Stubs at the same stubOrder cannot share columns (to avoid ambiguous headers). However, stubs at different stubOrder values can overlap freely.

This allows hierarchical header structures:

  • stubOrder = 1: first-level grouping above the column headers

  • stubOrder = 2: next-level grouping above the first-level etc..

Multiple calls with the same stubOrder are allowed as long as their column sets do not overlap. This enables building complex header structures incrementally. A label spanning the complete set of report columns is rendered as a single full-width band (gridSpan), and the table title above it shares that band row.

Examples

data <- data.frame(
  id = 1:10,
  age = round(rnorm(10, 45, 10), 1),
  sex = sample(c("M", "F"), 10, TRUE),
  weight = round(rnorm(10, 70, 10), 1)
)

# Single-level spanning header
spec <- create_table(data) |>
  add_span_header(cols = c(age, sex), label = "Demographics")

# Two-level hierarchy: higher stubOrder = higher band; non-overlapping
# stubs may share a level (Demographics | Physical row, banner above it)
spec2 <- create_table(data) |>
  add_span_header(cols = c(age, sex), label = "Demographics", stubOrder = 1) |>
  add_span_header(cols = weight, label = "Physical", stubOrder = 1) |>
  add_span_header(cols = c(age, sex, weight), label = "All Measurements", stubOrder = 2)

# tidyselect helpers and negation
spec3 <- create_table(data) |>
  add_span_header(cols = -id, label = "Measurements")