From an rtables table, produce a self-contained Word document or attach it to a template Word
file (template_file). This function is based on the tt_to_flextable() transformer and
the officer package.
export_as_docx(
tt,
file,
add_page_break = FALSE,
titles_as_header = TRUE,
integrate_footers = TRUE,
section_properties = section_properties_default(),
doc_metadata = NULL,
template_file = NULL,
...
)
section_properties_default(
page_size = c("letter", "A4"),
orientation = c("portrait", "landscape")
)
margins_potrait()
margins_landscape()(TableTree or related class)
a TableTree object representing a populated table.
(string)
output file. Must have .docx extension.
(flag)
whether to add a page break after the table (TRUE) or not (FALSE).
(flag)
Controls how titles are rendered relative to the table.
If TRUE (default), the main title (formatters::main_title()) and subtitles
(formatters::subtitles()) are added as distinct header rows within the
flextable object itself. If FALSE, titles are rendered as a separate paragraph
of text placed immediately before the table.
(flag)
Controls how footers are rendered relative to the table.
If TRUE (default), footers (e.g., formatters::main_footer(), formatters::prov_footer())
are integrated directly into the flextable object, typically appearing as footnotes
below the table body with a smaller font. If FALSE, footers are rendered as a
separate paragraph of text placed immediately after the table.
(officer::prop_section)
an officer::prop_section() object which sets margins and
page size. Defaults to section_properties_default().
(list of string)
any value that can be used as metadata by
officer::set_doc_properties(). Important text values are title, subject, creator, and description,
while created is a date object.
(string)
template file that officer will use as a starting point for the final
document. Document attaches the table and uses the defaults defined in the template file.
(any)
additional arguments passed to tt_to_flextable().
(string) page size. Can be "letter" or "A4". Defaults to "letter".
(string) page orientation. Can be "portrait" or "landscape". Defaults to "portrait".
No return value, called for side effects
Pagination Behavior for Titles and Footers (this behavior is experimental at the moment):
The rendering of titles and footers interacts with table pagination as follows:
Titles: When titles_as_header = TRUE (default), the integrated title
header rows typically repeat at the top of each new page if the table spans
multiple pages. Setting titles_as_header = FALSE renders titles as a
separate paragraph only once before the table begins.
Footers: Regardless of the integrate_footers setting, footers appear
only once. Integrated footnotes (integrate_footers = TRUE) appear at the
very end of the complete table, and separate text paragraphs
(integrate_footers = FALSE) appear after the complete table. Footers
do not repeat on each page.
section_properties_default(): Helper function that defines standard portrait properties for tables.
margins_potrait(): Helper function that defines standard portrait margins for tables.
margins_landscape(): Helper function that defines standard landscape margins for tables.
export_as_docx() has few customization options available. If you require specific formats and details,
we suggest that you use tt_to_flextable() prior to export_as_docx(). If the table is modified first using
tt_to_flextable(), the titles_as_header and integrate_footers parameters must be re-specified.
lyt <- basic_table() %>%
split_cols_by("ARM") %>%
analyze(c("AGE", "BMRKR2", "COUNTRY"))
tbl <- build_table(lyt, ex_adsl)
# See how the section_properties_portrait() function is built for customization
tf <- tempfile(fileext = ".docx")
export_as_docx(tbl,
file = tf,
section_properties = section_properties_default(orientation = "landscape")
)