Skip to contents

Save and Render a TFL Report to DOCX

Source: R/write_doc.R
write_doc.Rd

Convenience wrapper around save_report() and the internal DOCX renderer that saves a TFL_report object to JSON (plus any required data/figure files) and immediately renders it to a DOCX file in a single call.

Usage

write_doc(
  report,
  name,
  outDir = tfl_get_option("output_directory"),
  metaPath = tfl_get_option("meta_directory") %||% tempdir(),
  prettify = FALSE,
  toc = tfl_get_option("insertTOC"),
  tocTitle = tfl_get_option("tocTitle"),
  overrideTemplate = NULL,
  font_dirs = NULL,
  fallback_font = NULL,
  verbose = FALSE
)

Arguments

report

A TFL_report object created by create_report().

name

Character(1). Base file name (without extension) for the output DOCX document. The .docx extension is appended automatically.

outDir

Character(1). Directory where the final DOCX file will be written. Defaults to tfl_get_option("output_directory").

metaPath

Character(1). Directory where the intermediate specification JSON and associated data/figure files will be stored. Defaults to tfl_get_option("meta_directory"); when that option is unset, tempdir() is used as fallback — note that a tempdir-based meta folder disappears with the session, so replay_report() later needs a persistent metaPath.

prettify

Logical. When TRUE, pretty‑prints the JSON written by save_report() for easier inspection. Default FALSE (compact JSON).

toc

Logical. When TRUE, enables automatic insertion of a Table of Contents page via save_report() (named toc here, insertTOC in save_report() / tfl_set_options()). Defaults to tfl_get_option("insertTOC").

tocTitle

Character(1). Heading placed above the TOC field on the TOC page. Defaults to tfl_get_option("tocTitle").

overrideTemplate

Optional character string. Global template override used by the internal renderer for all specs. Accepts either:

  • A predefined bundled template name (e.g. "Navy_Pro").

  • A file path (absolute or relative) to an external template JSON file.

If NULL (default), templates are resolved per-spec from each spec's docTemplate value (allowing mixed templates in multi-spec reports). If a provided name/path cannot be resolved, a warning is emitted and Default is used.

font_dirs

Optional character vector of additional directories to search for fonts during rendering.

fallback_font

Optional character string. Path to a fallback font file used by the renderer. If NULL, the package default is used.

verbose

Logical. If TRUE, prints renderer progress messages.

Value

Invisibly returns the full path to the generated .docx file.

Details

This mirrors the helper used in the example inst/examples/init.R script (previously called save_and_render()), but is provided as a public, documented API function named write_doc().

See also

create_report(), save_report(), replay_report(), tfl_set_options(), tfl_get_option()

Examples

# Basic end-to-end workflow (writes to tempdirs so it is self-contained) --
out <- file.path(tempdir(), "kstfl_out")
meta <- file.path(tempdir(), "kstfl_meta")
dir.create(out, showWarnings = FALSE); dir.create(meta, showWarnings = FALSE)

tbl <- create_table(mtcars) |>
  add_title("Table 1: Motor Trend Car Road Tests")

doc_path <- write_doc(create_report(tbl), name = "mtcars_demo",
                      outDir = out, metaPath = meta, verbose = FALSE)
#> ✔ Report saved successfully
#> ℹ Spec file: f5760fdaf6c37d8d.json
#> ℹ Data files saved to: /tmp/Rtmps6dpU5/kstfl_meta
#> ✔ DOCX rendered: /tmp/Rtmps6dpU5/kstfl_out/mtcars_demo.docx (1 page)
#>   [OK] mtcars_demo -> /tmp/Rtmps6dpU5/kstfl_out/mtcars_demo.docx
doc_path   # full path of the generated .docx
#> [1] "/tmp/Rtmps6dpU5/kstfl_out/mtcars_demo.docx"

if (FALSE) { # \dontrun{
# Session defaults instead of per-call arguments --------------------------
tfl_set_options(output_directory = "output", insertTOC = TRUE,
                tocTitle = "List of Tables")
write_doc(create_report(tbl), name = "mtcars_with_toc",
          metaPath = file.path(tempdir(), "ksTFL_meta"), prettify = TRUE)
} # }