Skip to contents

Update the session package settings

Source: R/pkg_settings.R
tfl_set_options.Rd

Update ksTFL session options. This function accepts:

  • Named scalar options (e.g. contentWidth = "95%", missings = ".").

  • Settings objects produced by helper constructors such as add_header(), add_footer(), add_body_text(), or page objects from p_page().

  • A mixture of both named values and settings objects.

Usage

tfl_set_options(
  ...,
  docTemplate = NULL,
  footnotePlace = NULL,
  isContinues = NULL,
  contentWidth = NULL,
  missings = NULL,
  figureWidth = NULL,
  figureHeight = NULL,
  figureDevice = NULL,
  figureScaleMode = NULL,
  autoColWidth = NULL,
  minColWidth = NULL,
  insertTOC = NULL,
  tocTitle = NULL,
  output_directory = NULL,
  meta_directory = NULL
)

Arguments

...

Named arguments OR settings objects returned from helper constructors.

  • Named scalar options (e.g. contentWidth = "95%", missings = ".").

  • Settings objects produced by helper constructors such as add_header(), add_footer(), add_style(), add_body_text(), and set_page_style(p_page(p_margins())).

  • A mixture of both named values and settings objects is accepted; the function routes each into the appropriate internal slot.

docTemplate

Character; name of a predefined bundled template (see tfl_list_templates(), e.g. "Default", "Navy_Pro") or a path to an external template JSON file. When NULL (default) the current session template is left unchanged. Use tfl_reset_options() to restore the built-in default ("Default"). Internally stored as the doc_style_template option (the name returned by tfl_get_options()).

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".

isContinues

Logical; override continuation behavior.

contentWidth

Character; width for content area (e.g. "100%", "95%").

missings

Character; default representation for missing values (e.g. "", ".", "NA", "—"). Default is an empty string ("").

figureWidth

Character; default width for figure output (e.g. "6in", "16cm"). Applied when create_figure() specs do not specify their own width.

figureHeight

Character; default height for figure output (e.g. "4in", "10cm"). Applied when create_figure() specs do not specify their own height.

figureDevice

Character; graphics device used when a ggplot2 object is rendered by create_figure(). One of "cairo" (default), "svg", "png", "jpeg"/"jpg" (other values, e.g. "pdf", are rejected). "cairo" exports a paths-only SVG via Cairo (text is converted to vector outlines) — the MS Word-safe vector format; Word's SVG engine corrupts svglite text-SVG (font substitution, text-anchor and px-scaling bugs), so plain "svg" emits a one-time warning. If Cairo is not installed the device falls back to "svg" and then "png" with a warning. dpi is ignored for "cairo" (vector output).

figureScaleMode

Character; how figures are scaled into the page content area. One of "fixed" (use figureWidth/figureHeight as given; a missing dimension is inferred from the default 6:4 ratio), "fitWidth" (stretch to the content-box width using the W/H-provided aspect ratio), or "fitPage" (largest size of the same aspect ratio that fits the remaining content area). Default "fixed".

autoColWidth

Logical; enable automatic column width recalculation when user sets colWidth via define_cols(). Default TRUE. When TRUE, locked columns maintain exact width while unlocked columns normalize to fill remaining space. Set FALSE to disable auto-recalculation and manage widths manually.

minColWidth

Numeric; minimum relative column width (%) for unlocked columns during recalculation. Default 0.5. Used to validate that relative widths don't squeeze columns below acceptable minimum.

insertTOC

Logical; when TRUE the renderer prepends a Table of Contents page (using a { TOC \f \h \z } field) before the first spec. Requires at least one add_title() or add_subtitle() call with toclevel set. Default FALSE. Can be overridden per-render via save_report(insertTOC = ).

tocTitle

Character; heading text placed above the TOC field on the TOC page. Default "Table of Contents". Set to "" to omit the heading. Can be overridden per-render via save_report(tocTitle = ).

output_directory

Character; path to default output directory of rendered document.

meta_directory

Character; path to default directory for intermediate metadata (JSON specs, data, and asset files) created during rendering.

Value

The updated settings list, returned invisibly. Use tfl_get_options() to inspect.

Details

The function tries to intelligently route each supplied object into the appropriate internal settings slot (headers, footers, styles, bodyText, page).

Examples

# (options are session-global; examples restore defaults at the end)
tfl_set_options(contentWidth = "95%", missings = ".")
tfl_get_option("contentWidth")   # "95%"
#> [1] "95%"
tfl_get_option("missings")       # "."
#> [1] "."

# Bundled template by name (see tfl_list_templates()); an external template
# path works the same way: docTemplate = "/path/to/my_template.json"
tfl_set_options(docTemplate = "Navy_Pro")

# Update page style via the helper objects
tfl_set_options(
  set_page_style(page = p_page(
    size = "Letter", orientation = "portrait",
    margins = p_margins(top = "1in", bottom = "1in",
                        left = "0.75in", right = "0.75in")))
)

# Session-default header / footer / body text for every spec
tfl_set_options(
  add_header(c("Left Header", "Center Header", "Right Header")),
  add_footer(c("Left Footer", "Center Footer", "Right Footer")),
  add_body_text("This is the default body text for all text specs.")
)

# Automatic column width recalculation (default TRUE): locking one
# column re-normalizes the rest; FALSE keeps manually given widths.
tfl_set_options(autoColWidth = TRUE)
spec <- create_table(mtcars) |> define_cols(cyl, colWidth = "20%")

tfl_reset_options()   # back to package defaults

# TOC workflow: enable for the session, then tag titles with toclevel
if (FALSE) { # \dontrun{
tfl_set_options(insertTOC = TRUE, tocTitle = "List of Tables")
spec <- create_table(mtcars) |> add_title("Table 1", toclevel = 1)
write_doc(create_report(spec), "toc_demo", outDir = tempdir(),
          metaPath = tempdir())
# In Word: click the TOC placeholder and press F9 to populate it.
} # }