Skip to contents

Export procr_table Objects to an Excel workbook

Source: R/export_excel.R
to_wb.Rd

This function exports one or more procr_table objects to an Excel workbook using openxlsx2. Each table is written to its own worksheet. Optional arguments allow the creation of a table of contents (TOC), an additional set of accessible worksheets and CSV‑style worksheets.

Usage

to_wb(
  ...,
  template = NULL,
  add_acc = FALSE,
  add_csv = FALSE,
  alt_tabnames_prefix = "Tabelle_",
  acc_tabnames = function(nms) sprintf("%sb", nms),
  csv_tabnames = function(nms) sprintf("csv-%s", nms),
  toc = FALSE,
  toc_tabname = "Inhalt",
  toc_title = "Tabellen",
  toc_acc_title = "Barrierefreie Tabellen",
  toc_csv_title = "Daten zur Weiterverarbeitung (\"CSV-Tabellen\")",
  sheet_position = -1L
)

Arguments

...

One or more procr_table objects to be exported. If objects are passed unnamed, they receive default sheet names Tabelle1, Tabelle2 and so on. If they are named, the names are used as worksheet titles (see example).

template

A wbWorkbook object or path to an Excel template file. If NULL (default), a new workbook is created.

add_acc

Logical. Should an additional accessible worksheet (with suffix "b") be created for each table?

add_csv

Logical. Should an additional CSV-style worksheet be created for each table?

alt_tabnames_prefix

Prefix to generate alternative sheet names for tables that were passed as unnamed arguments to .... Default is "Tabelle". Sheet names are generated by concatenating alt_tabnames_prefix and a running index starting at 1.

acc_tabnames

Function to generate sheet names for accessible worksheets. Must take an input character vector as its first argument and return a character vector. By default, adds suffix "b".

csv_tabnames

Function to generate sheet names for CSV-style worksheets. Must take an input character vector as its first argument and return a character vector. By default, adds prefix "csv-".

toc

Table of contents specification. Three possibilities are supported:

FALSE

No TOC is written, the default.

TRUE

A TOC is generated automatically from the supplied tables. Table labels are taken from the tables' subtitles, whereby footnotes are stripped.

list(...)

A manually constructed TOC. The list must be named: Each element corresponds to a heading in the TOC and contains a list of character vectors. Vectors may be named, in which case the name is used to fill the "Detail" column. See examples.

toc_tabname

Name of TOC tab. By default, "Inhalts\u00fcbersicht".

toc_title

Title of tables section. By default, "Tabellen".

toc_acc_title

Title of accessible tables section. By default, "Barrierefreien Tabellen".

toc_csv_title

Title of CSV-style tables section. By default, "Daten zur Weiterverarbeitung ("CSV-Tabellen")".

sheet_position

Integer specifying the position at which newly created sheets should be inserted. If >= 1 and less than the number of existing sheets, the new sheets are inserted before the sheet at that position. Default is -1L, which appends new sheets at the end.

Value

An openxlsx2 workbook object containing the exported tables and (optionally) a TOC, accessible worksheets and CSV worksheets.

Details

  • A hyperlink back to the TOC sheet is added to cell A1 of each generated worksheet.

  • When a TOC is supplied, the function checks whether all referenced sheets exist and whether all tables have been referenced in the TOC.

Examples

if (FALSE) { # \dontrun{
# Simple export of a single table
to_wb(my_table)

# Export multiple tables with a template workbook
to_wb(tab1, tab2, template = "template.xlsx")

# Export with named arguments (names become sheet titles)
to_wb(`12345-01` = tab1, `12345-02` = tab2)

# Export with automatically generated TOC and additional worksheets
to_wb(
  `12345-01` = tab1,
  `12345-02` = tab2,
  add_acc = TRUE,
  add_csv = TRUE,
  toc = "auto"
)

# Manual TOC specification (see tests for full structure)
toc_manual <- list(
  Tabellen = list(
    c(`The first table` = "12345-01",
      `The second table` = "12345-02",
      "12345-03")
  ),
  `Barrierefreie Tabellen` = list(
    c(`The first accessible table` = "12345-01b",
      `The second accessible table` = "12345-02b",
      "12345-03b")
  ),
  `Daten zur Weiterverarbeitung ("CSV-Tabellen")` = list(
    c(`The first CSV-Table` = "csv-12345-01",
      `The second CSV-Table` = "csv-12345-02",
      "csv-12345-03")
  )
)
to_wb(
  `12345-01` = tab1,
  `12345-02` = tab2,
  `12345-03` = tab3,
  add_acc = TRUE,
  add_csv = TRUE,
  toc = toc_manual
)
} # }