Getting Started with ksTFL

High-level pipeline

Data Frame / Image File
       ↓
create_table() / create_figure() / create_text()
       ↓
TFL_spec (customize with define_cols(), add_style(), add_title(), compute_cols())
       ↓
create_report() (assemble specs, consolidate styles)
       ↓
TFL_report
       ↓
write_doc()  ← recommended: one-step save + render
  or
save_report() → replay_report()  ← two-step: inspect JSON before rendering
       ↓
Styled .docx (C++ engine, deterministic HarfBuzz pagination)

Anatomy of a TFL spec

Each TFL_spec contains:

Table spec (from data frame)

# Simple: all columns
spec_tbl <- create_table(mtcars)

# Select specific columns with tidyselect
spec_tbl <- create_table(mtcars, cols = c(mpg, cyl, hp, wt))

What happens:

- Data is shadow-copied into the spec’s internal environment (not modifiable)

- Columns are auto-analyzed (type detection, width calculation)

- A TFL_spec object is returned ready for customization

Understanding the cols parameter:

The cols argument controls which columns appear in the rendered document and in what order — it does not filter or mutate the input data frame. Think of it as a presentation lens: the full dataset is still stored inside the spec, but only the columns listed in cols are emitted to the final report.

This distinction matters when you use compute_cols() later in the pipeline. Because the original data frame is preserved intact, compute_cols() conditions can reference any column in the data — including columns that are not listed in cols and will never appear in the output. For example, you might exclude a flag column from the report but still use it to drive conditional styling:

# Only age, sex, trt go to the document; flag stays hidden
spec <- create_table(demog, cols = c(age, sex, trt))

# But flag is still available for conditional logic
spec <- compute_cols(spec, trt,
  c_style("highlight"),
  when = flag == "Y")

The order in which columns are passed to cols also determines their left-to-right order in the rendered table, so cols doubles as a convenient column-reordering mechanism — no need to rearrange the underlying data frame.

Figure spec (from image file)

# From a file path — any image format your renderer supports (PNG, JPEG, etc.)
spec_fig <- create_figure("path/to/plot.png")

# From a ggplot2 object — rendered automatically to a temporary image file
library(ggplot2)
p <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point()
spec_fig <- create_figure(p)          # uses configured defaults
spec_fig <- create_figure(p, dpi = 150L) # custom resolution (dpi)

# Control output size/format via options
# tfl_set_options(figureWidth = "8in", figureHeight = "5in", figureDevice = "jpeg")
# spec_fig <- create_figure(p)

What happens:

- If a file path is given: it is validated (must exist and be readable); the file is used as-is

- If a ggplot2 object is given: rendered via ggplot2::ggsave() to tempdir() using package defaults (figureWidth, figureHeight, figureDevice); the resulting path is stored in the spec

- The dpi parameter applies when a ggplot2 object is passed; width/height/device are configured through package options

- The image file is copied to metaPath when the report is saved

Text spec (narrative content)

spec_txt <- create_text()

# Add narrative content
spec_txt <- add_body_text(spec_txt, "This analysis includes all subjects in the safety population.")

What happens: - Empty spec with no data - Ready for narrative content via add_body_text()

Single column

spec <- define_cols(spec, mpg,
  label = "Miles per Gallon",
  type = "numeric",
  format = "%.1f",
  colWidth = "20%")

Batch update (multiple columns with single values)

# Apply same label format to all columns
spec <- define_cols(spec, c(mpg, cyl, hp),
  label = c("MPG", "Cylinders", "HP"),
  type = "numeric",        # Recycled to all 3
  format = "%.0f")         # Recycled to all 3

Per-column customization

# Different format for each column
spec <- define_cols(spec, c(mpg, cyl, hp),
  label = c("MPG", "Cylinders", "HP"),
  type = c("numeric", "numeric", "numeric"),
  format = c("%.1f", "%.0f", "%.0f"))

Key parameters:

- label: Column header text

- type: “numeric” or “string” (auto-detected if omitted)

- format: Format string (e.g., “%.2f”, “0.00”)

- colWidth: Column width (e.g., “20%”, “2cm”) - When set, column is locked to that width - Other unlocked columns auto-recalculate to sum to 100% - Disable auto-recalculation with tfl_set_options(autoColWidth = FALSE)

- isVisible: TRUE (default) or FALSE - Set to FALSE to hide column from output - Invisible columns show width “0.0cm” - Cannot set colWidth on invisible columns - Invisible columns excluded from width recalculation

- isID: TRUE if column repeats on page breaks

- dedupe: TRUE to clear consecutive repeating values in a column

- isColBreak: TRUE on a column that needs to be moved on the next page (break long tables)

- labelStyleRef: Style(s) to apply to column header

- valueStyleRef: Style(s) to apply to cell values

Hiding Columns:

# Hide a column (e.g., for conditional logic that doesn't display)
spec <- create_table(data) |>
  define_cols(group_id, isVisible = FALSE)
  # Result: group_id is hidden, other columns recalculated to fill 100%

See Reporting Examples for detailed column customization patterns.

Page size, orientation, and margins

Use set_page_style() with p_page() and p_margins() to control the physical page layout:

spec <- create_table(mtcars) |>
  set_page_style(
    page = p_page(
      size        = "A4",        # "A4", "Letter", or "Legal"
      orientation = "landscape",  # "portrait" or "landscape"
      margins     = p_margins(
        top    = "1in",
        bottom = "1in",
        left   = "0.75in",
        right  = "0.75in",
        header = "0.5in",
        footer = "0.5in"
      )
    )
  )

p_page() parameters:

- size: Page size — "A4" (default), "Letter", or "Legal"

- orientation: "portrait" (default) or "landscape"

- margins: A margins object from p_margins()

p_margins() parameters (all accept dimension strings like "1in", "2.54cm", "72pt", "25.4mm"):

- top, bottom, left, right: Page margins

- header, footer: Distance from page edge to header/footer content

Document templates

Templates control the visual appearance (colours, fonts, borders) of the rendered DOCX:

# List all bundled templates
tfl_list_templates()

# Apply a bundled template
spec <- create_table(mtcars) |>
  set_page_style(docTemplate = "Navy_Pro")

# Or apply via set_document()
spec <- create_table(mtcars) |>
  set_document(hasData = TRUE, docTemplate = "Carbon_Dark")

# Use a custom external template (JSON file)
spec <- create_table(mtcars) |>
  set_page_style(docTemplate = "path/to/my_custom_template.json")

Use docTemplate on the spec when different sections of one report should keep different looks. Use write_doc(..., overrideTemplate = ...) or replay_report(..., overrideTemplate = ...) when you want one global template to override every spec in the rendered document.

Use run_styles_editor() to interactively create and edit template JSON files.

Passing a named list of specs

You can also build specs into a named list and pass the whole list at once — useful when the set of outputs is assembled dynamically:

specs <- list(
  t_dm   = spec_table,
  t_text = spec_text,
  t_fig  = spec_fig
)

report <- create_report(specs)
# names(report): "t_dm_<hash>", "t_text_<hash>", "t_fig_<hash>"

List and variadic arguments may be freely mixed:

extra <- create_text() |> add_body_text("Appendix.")
report <- create_report(extra, specs)

6. Returns a TFL_report object

Result: A single report combining all specs in input order. Additionally a Table of Contents can be auto-generated in such documents that allows to create a production ready TFL reports.

Option A: One step with write_doc() (recommended)

write_doc() combines save + render into a single call:

report <- create_report(spec_table, spec_text)

# Returns the full path to the generated .docx (invisibly)
doc_path <- write_doc(report,
  name     = "demographics",          # Output file name (no extension)
  outDir   = "./output",              # Where the final .docx is written
  metaPath = tempdir())               # Where JSON metadata is written (temp is fine)

Additional parameters:

- toc: If TRUE, prepends a Table of Contents page (requires toclevel on titles - see ?add_title)

- tocTitle: Heading above the TOC field (default "Table of Contents")

- prettify: If TRUE, writes human-readable JSON (useful for debugging)

- verbose: If TRUE, prints renderer progress messages to R console

This is the recommended approach for production use. Set session defaults once:

tfl_set_options(
  output_directory = "./output",
  meta_directory   = "./meta"
)

# Then write_doc() uses those defaults automatically
write_doc(report, name = "demographics")

Option B: Two steps with save_report() + replay_report()

Use this when you need to inspect or version-control the JSON metadata separately:

report <- create_report(spec_table, spec_text)

# Step 1: Serialize to JSON + data files
result <- save_report(report,
  docFileName = "my_report.docx",
  outDir      = "./output",
  metaPath    = tempdir(),
  prettify    = TRUE)              # prettify = TRUE for readable JSON (debugging)

# Step 2: Re-render the DOCX from the saved JSON metadata
replay_report(
  spec_json   = result$spec_file,
  meta_dir    = result$metaPath,
  output_path = file.path("./output", "my_report.docx"))

save_report() output files:

- {metaPath}/{spec_hash}.json — Main specification (consumed by renderer)

- {metaPath}/{dataRef}.json — Table data files (one per table spec) - Figure files copied to metaPath as-is

What is the metadata folder?

Every time write_doc() (or save_report()) runs, it writes intermediate files to metaPath:

• {hash}.json — The main spec file: document structure, column definitions, styles, titles, footnotes, headers/footers. This is what the C++ renderer reads.
• {dataRef}.json — One data file per table spec, containing the actual row data.
• Figure files — Copied from their original paths into metaPath.
• _index.json — An index of all spec files written to this folder (auto-maintained).

For most workflows, metaPath = tempdir() is fine — you only care about the final .docx. But there are real reasons to use a persistent metaPath.

Why use a persistent metaPath?

Reproducibility / audit trail: In regulated environments (FDA, EMA submissions), you may need to prove that a specific DOCX was generated from a specific dataset at a specific time. The spec JSON + data JSON together form a complete, reproducible snapshot.

Re-rendering without R: Once the JSON files exist, you can re-render the DOCX without any R objects or data frames — just the JSON files. This is useful for: - Regenerating a document after a template change - Rendering on a different machine or in a CI/CD pipeline - Reproducing an output months later

Version management: Each write_doc() call writes a new hash-named spec file. You can keep multiple versions and compare them.

Managing metadata files

meta_dir <- "./meta"

# List all spec JSONs in the meta folder
df <- list_reports(meta_dir)
print(df[df$is_latest, c("doc_file", "datetime", "spec_file")])

# Re-render a DOCX from stored JSON (no R objects needed)
replay_report("demographics.docx", meta_dir = meta_dir)

# Or replay a specific version by spec hash
replay_report("abc123def456.json", meta_dir = meta_dir,
              output_path = "./output/demographics_v2.docx")

# Clean up obsolete spec files (keeps latest version per document)
clean_reports(meta_dir, dry_run = TRUE)   # Preview what would be deleted
clean_reports(meta_dir, dry_run = FALSE)  # Actually delete

list_reports() returns a data frame with columns: doc_file, datetime, is_latest, n_specs, spec_file, data_refs.

replay_report() re-renders from JSON — no R spec objects, no data frames required. Pass either the target .docx name (re-renders the latest version) or the exact spec hash filename.

clean_reports() removes obsolete JSON files. By default keeps 1 version per document (keep_versions = 1). Always run with dry_run = TRUE first.

Recommended production setup

# Set persistent meta directory once per session
tfl_set_options(
  output_directory = "./output",
  meta_directory   = "./meta"   # Persistent — survives session restarts
)

# All write_doc() calls now use these directories automatically
write_doc(report1, name = "tbl_demographics")
write_doc(report2, name = "tbl_labs")

# Later: re-render without R if needed
replay_report("tbl_demographics.docx", meta_dir = "./meta")

Column widths (auto-calculation)

When you create a table, widths are auto-calculated based on data characteristics:

# Auto-calculated widths (example)
# id = 20%, description = 50%, value = 30%
spec <- create_table(my_data)

# Lock id to 15%; others recalculate to fill 85%
spec <- define_cols(spec, id, colWidth = "15%")

See Reporting Examples for detailed width customization.

Data references (dataRef)

Each table spec gets a dataRef name for its data file:

# Auto-generated: "0001_abc123def456" (docOrder + hash)
report <- create_report(spec_table1, spec_table2)

# Manual control not needed — handled automatically by write_doc()
write_doc(report, name = "my_report", outDir = "./output", metaPath = "./meta")

Styles Editor

Launches a Shiny application for creating and editing style templates interactively. You can load any bundled template from tfl_list_templates(), modify fonts, borders, spacing, and colours in a WYSIWYG editor, then download the result as a JSON file ready for use with set_page_style() or write_doc(). This is especially useful when you need to fine-tune a template visually rather than writing s_font() / s_paragraph() / s_table_style() calls by hand.

Requires the shiny package.

# Equivalent programmatic call:
run_styles_editor()

Replay Reports

Opens a Shiny application for selecting, reordering, and combining previously saved reports into a single DOCX document. You point the app at one or more meta-data folders (produced by save_report() or write_doc()), drag-and-drop reports into the desired order, optionally enable a table of contents, and render the combined output — all without writing any R code.

Requires shiny, sortable, and shinyFiles packages.

# Equivalent programmatic call:
run_replay_app()

# Pre-populate a meta folder:
run_replay_app(meta_dir = "./output/meta")

TFL Spec Preview (Selection)

Evaluates the currently selected code in the source editor and, if the result is a TFL_spec, renders an HTML preview in the RStudio Viewer pane. This lets you highlight a pipeline expression (e.g., create_table(...) |> add_title(...)) and instantly see what the spec looks like — a quick visual check without saving or rendering to DOCX.

TFL Spec Preview (by name)

Same HTML preview, but instead of evaluating selected text the addin prompts you for the name of a TFL_spec object that already exists in .GlobalEnv. Handy when the spec was built interactively in the console and you want to preview it without re-selecting code.

Style Atoms Catalog

Prints all built-in style atoms to the console with colour-coded categories (font decoration, font family, font size, text colour, highlight, alignment, indentation, spacing, borders, backgrounds, row height, and more). Each atom is a short name you can reference directly in add_style() or define_cols() via f_combine(). Running this catalog helps you discover what is available without consulting documentation.

# Equivalent programmatic call:
tfl_style_atoms_catalog()
# — or —
tfl_print_style_atoms()