Add save_flex_docx() to save gtsummary tables and flextables to Word

NAMESPACE

@@ -214,6 +214,7 @@ export(remove_row_type)
 export(remove_source_note)
 export(remove_spanning_header)
 export(reset_gtsummary_theme)
+export(save_flex_docx)
 export(scope_header)
 export(scope_table_body)
 export(select)

NEWS.md

@@ -1,5 +1,7 @@
 # gtsummary (development version)
 
+* Added `save_flex_docx()` to save a gtsummary table or a flextable to a Word (`.docx`) file via flextable. The `header` and `footer` arguments place the table caption in the Word document's page header and the footnotes, source notes, and abbreviations in the page footer. The `page` and `page_location` arguments add a page-number line (e.g. `"Page {PAGE} of {NUMPAGES}"`) to a chosen header/footer region and alignment. A collection of tables is also accepted—a `tbl_split` object (from `tbl_split_by_rows()`/`tbl_split_by_columns()`) or a plain list of flextables—writing each table to its own Word section and page. For a flextable, its caption (`flextable::set_caption()`) is relocated to the Word header and its footer part (`flextable::add_footer_lines()`) to the Word footer. The caption, footnotes, source notes, abbreviations, and page-number line in the Word header/footer match the table body font (family and size) instead of the Word template default. Each Word region also inherits the styling applied to the corresponding flextable part, so e.g. `flextable::fontsize(size = 6, part = "footer")` yields a size-6 Word footer. The `pr_section` argument (and the `save_flex_docx-lst:pr_section` theme element) accepts an `officer::prop_section()` object for fine-grained control of the Word section—page margins, page size, orientation, and columns—while the header/footer regions remain managed by `save_flex_docx()`; for a collection the same section is applied to every table with the paging `type` fixed to `"nextPage"`.
+
 * `modify_abbreviation()` and `remove_abbreviation()` now accept a character vector of abbreviations, allowing multiple abbreviations to be added or removed in a single call. `modify_abbreviation()` also gains `prefix`, `sep1`, and `sep2` arguments to customize the abbreviation source note's leading text (e.g. `c("Abbr.", "Abbrs.")`), the separator between the prefix and the abbreviations (e.g. `": "`), and the separator between abbreviations (e.g. `"; "`). Defaults are also configurable via the `modify_abbreviation-arg:prefix`, `modify_abbreviation-arg:sep1`, and `modify_abbreviation-arg:sep2` theme elements. (#2172)
 
 * The `missing` argument of `tbl_summary()` and `tbl_svysummary()` now accepts the formula-list-selector syntax (e.g. `missing = list(age ~ "always", grade ~ "no")`), allowing the missing row to be shown for some variables and not others. A bare string (e.g. `missing = "no"`) remains supported. (#2283)

data-raw/gtsummary_theme_elements.csv

@@ -24,6 +24,7 @@ FALSE,add_q,add_q-arg:method,TRUE,FALSE,,
 FALSE,add_q,add_q-arg:pvalue_fun,TRUE,FALSE,,
 FALSE,add_stat_label,add_stat_label-arg:location,TRUE,FALSE,,
 FALSE,as_flex_table,as_flex_table-lst:addl_cmds,FALSE,TRUE,"named list of expressions of {flextable} package commands inserted in the `as_flex_table()` call; do not include the `data=` argument; the list of expressions is inserted after the named call, e.g. if the named list element is `""tab_spanner""` the expressions will be inserted after expressions named `""tab_spanner""`; to see the names of the expressions run `as_flex_table(x, return_calls = TRUE)` and check the names.","list(autofit = list(rlang::expr(flextable::font(fontname = ""Bodoni 72"", part = ""all"")), rlang::expr(flextable::fontsize(size = 8, part = ""all""))))"
+FALSE,save_flex_docx,save_flex_docx-lst:pr_section,FALSE,TRUE,"an {officer} `prop_section()` object used as the base Word section for `save_flex_docx()`, controlling page margins, page size, orientation, and section columns; the section's header/footer defaults are always managed by `save_flex_docx()` (the relocated caption/notes) and cannot be set here, and in a collection the paging `type` is fixed to `""nextPage""`; the `pr_section` argument overrides this element.","officer::prop_section(page_margins = officer::page_mar(top = 0.5, bottom = 0.5))"
 FALSE,as_gt,as_gt-lst:addl_cmds,FALSE,TRUE,"named list of expressions of {gt} package commands inserted in the `as_gt()` call; do not include the `data=` argument; the list of expressions is inserted after the named call, e.g. if the named list element is `""tab_spanner""` the expressions will be inserted after expressions named `""tab_spanner""`; to see the names of the expressions run `as_gt(x, return_calls = TRUE)` and check the names.",list(tab_spanner = rlang::expr(gt::tab_options(table.font.size = 'small')))
 FALSE,as_hux_table,as_hux_table.gtsummary-lst:addl_cmds,FALSE,TRUE,"named list of expressions of {huxtable} package commands inserted in the `as_hux_table()` call; do not include the `data=` argument; the list of expressions is inserted after the named call, e.g. if the named list element is `""tab_spanner""` the expressions will be inserted after expressions named `""tab_spanner""`; to see the names of the expressions run `as_hux_table(x, return_calls = TRUE)` and check the names.",
 FALSE,as_kable,as_kable-arg:dots,TRUE,FALSE,"named list of arguments passed to `knitr::kable()`, which also applies to calls from `as_kable_extra()`","list(booktabs = TRUE, longtable = TRUE, linesep = """")"

pkgdown/_pkgdown.yml

@@ -160,6 +160,7 @@ reference:
       - as_kable_extra
       - as_hux_table
       - as_tibble.gtsummary
+      - save_flex_docx
 
   - title: Other Functions
   - subtitle: Head or Tail Tables