Set document properties — set

Define document-level properties. Multiple calls merge with last-win strategy. Document type (docType) is set automatically by create_table(), create_figure(), or create_text() and cannot be changed here. Global document order (docOrder) is assigned by create_report().

Usage

set_document(
  spec,
  isContinues = NULL,
  continuousSection = NULL,
  contentWidth = NULL,
  footnotePlace = NULL,
  hasData = NULL,
  topEmptyLine = NULL,
  bottomEmptyLine = NULL,
  docTemplate = NULL,
  figureWidth = NULL,
  figureHeight = NULL,
  figureDevice = NULL,
  figureScaleMode = NULL
)

Arguments

spec

TFL spec object

isContinues

Logical. When TRUE, titles and subtitles are shown only on the first page of a multi-page spec instead of repeating on every page. Default FALSE (titles repeat on each page).

continuousSection

Logical. When TRUE on a spec that is not the first in a report, the page break before this spec is suppressed and it continues on the same page as the previous spec. Requires matching page size and margins with the previous spec; if they differ, Word may still force a page break. The paginator is not adjusted — Word handles natural overflow when content exceeds the remaining page space. Works best for short content (figures, text, small tables). Default FALSE.

contentWidth

Width of content, e.g. "100%", "25cm", "10in", "600pt", "240mm" (units: %, in, cm, mm, pt).

footnotePlace

Character; controls where footnotes are rendered. One of "doc_footer" (place inside the Word footer, below footer rows), "repeated" (place under the table on every page), or "last_page" (place under the table on the last page only). Default "repeated".

hasData

Logical. Whether this spec has data to render. Set to TRUE for tables with data rows. When FALSE, the body text (if any) is rendered instead.

topEmptyLine

Empty spacer row height after table header (table-level), e.g. "6pt". Use NULL to disable. "0pt" is treated as no spacer row.

bottomEmptyLine

Empty spacer row height before table bottom border (table-level), e.g. "6pt". Use NULL to disable.

docTemplate

Character. Template to use for rendering. Accepts either:

Name of a bundled template (see tfl_list_templates()).
Full path to a custom styles JSON file.

figureWidth

Figure width with units, e.g. "6in", "70%", "16.51cm". Only relevant for docType = "Figure".

figureHeight

Figure height with units. Same syntax as figureWidth.

figureDevice

Character. Image format used when create_figure() renders a ggplot2 object. One of "cairo" (default; Cairo paths-only SVG, MS Word-safe), "svg" (requires svglite; known to render incorrectly in MS Word — warns once), "png", "jpeg"/"jpg". If the chosen package-backed device is unavailable, create_figure() falls back cairo -> svg -> png with a warning.

figureScaleMode

Character. How the figure is scaled in the DOCX. One of "fixed" (exact figureWidth x figureHeight; a missing dimension is inferred from the 6:4 default ratio), "fitWidth" (figure box stretched to the page content width, aspect ratio taken from figureWidth/figureHeight — NOT from the source image), or "fitPage" (largest box of that same aspect ratio fitting the content area).

Value

Updated spec object

Examples

# Table spec with data
spec <- create_table(mtcars) |>
  set_document(hasData = TRUE)

# Text spec for narrative-only output
spec2 <- create_text() |>
  set_document(hasData = FALSE) |>
  add_body_text("No adverse events were reported.")

# Footnotes placed on last page only
spec3 <- create_table(mtcars) |>
  set_document(footnotePlace = "last_page") |>
  add_footnote("Source: Motor Trend, 1974.")

# Bundled template by name (see tfl_list_templates())
spec4 <- create_table(mtcars) |>
  set_document(docTemplate = "Navy_Pro")

if (FALSE) { # \dontrun{
# Figure spec with custom sizing (needs an existing image file)
spec <- create_figure("plot.png") |>
  set_document(
    figureWidth  = "7in",
    figureHeight = "5in",
    figureScaleMode = "fitWidth"
  )
} # }