Skip to contents

Add a title

Source: R/spec_context.R
add_title.Rd

Add a title to the specification. Multiple calls add multiple title groups. Calling with the same ID merges with last-win strategy.

Usage

add_title(
  spec,
  text,
  id = NULL,
  styleRef = NULL,
  order = NULL,
  toclevel = NULL
)

Arguments

spec

TFL spec object.

text

Character vector of title text lines. Multiple elements are rendered as separate lines within the same title paragraph.

id

Title identifier (auto-generated if NULL).

styleRef

Character vector of style names to apply. Styles are merged with last-win strategy.

order

Integer ordering key (auto-assigned if NULL).

toclevel

Optional integer 1–9. When set, the first page occurrence of this title is marked as a Table of Contents entry at the given level. Multi-line titles are concatenated with a space for the TOC entry text; inline styling tags (e.g. <b>, <i>) are stripped automatically.

To generate a TOC page, set toclevel here and either call tfl_set_options(insertTOC = TRUE) for the whole session or pass insertTOC = TRUE to save_report(). The renderer will prepend a "Table of Contents" page with a { TOC \f \h \z } field. Open the generated document in Word, click inside the TOC area, and press F9 to populate it.

Value

Updated spec object.

Examples

# Basic multi-line title (no TOC)
spec <- create_table(mtcars) |>
  add_title(c("Study ABC-123", "Table 1: Demographics"))

# Re-styling the same title group via its id (last-wins merge)
spec <- spec |> add_title("Study ABC-123 (rev)", id = names(spec$titles)[1])

if (FALSE) { # \dontrun{
# Full TOC workflow: tag titles with toclevel, enable insertTOC at save
t1 <- create_table(mtcars) |> add_title("Table 1: Demographics", toclevel = 1)
report <- create_report(t1)
save_report(report, docFileName = "tables.docx", insertTOC = TRUE)
# Open tables.docx in Word, click the TOC placeholder, press F9 to update.
} # }