Package 'officerExtras'

Description

This function assumes that the input docx object has a list style. Use read_docx_ext() with allow_null = TRUE to create a new rdocx object with the "List Bullet" and "List Number" styles. "List Paragraph" can be used but the resulting formatted list will not have bullets or numbers.

Usage

add_list_to_body(
  docx,
  values,
  style = "List Bullet",
  keep_na = FALSE,
  before = NULL,
  after = "",
  ...
)

Arguments

Value

A modified rdocx object.

See Also

add_to_body(), vec_add_to_body()

Description

Wrappers for officer::body_add_par(), officer::body_add_gg(), and officer::body_add_xml() that use the cursor_docx() helper function to allow users to pass the value and keyword, id, or index value used to place a "cursor" within the document using a single function. If pos = NULL, add_to_body() calls officer::body_add() instead of officer::body_add_par(). If value is a gt_tbl object, value is passed as the gt_object parameter for add_gt_to_body().

• add_text_to_body() passes value to glue::glue() to add support for glue string interpolation.

• add_gt_to_body() converts gt tables to OOXML with gt::as_word().

• add_gg_to_body() adds a caption following the plots using the labels from the plot object.

Usage

add_to_body(
  docx,
  keyword = NULL,
  id = NULL,
  index = NULL,
  value = NULL,
  str = NULL,
  style = NULL,
  pos = "after",
  ...,
  gt_object = NULL,
  call = caller_env()
)

add_text_to_body(
  docx,
  value,
  style = NULL,
  pos = "after",
  .na = "NA",
  .null = NULL,
  .envir = parent.frame(),
  ...
)

add_xml_to_body(docx, str, pos = "after", ..., call = caller_env())

add_gt_to_body(
  docx,
  gt_object,
  align = "center",
  caption_location = c("top", "bottom", "embed"),
  caption_align = "left",
  split = FALSE,
  keep_with_next = TRUE,
  pos = "after",
  tablecontainer = TRUE,
  ...,
  call = caller_env()
)

add_gg_to_body(
  docx,
  value,
  caption = "title",
  caption_style = style,
  autonum = NULL,
  style = "Normal",
  pos = "after",
  ...
)

add_value_with_keys(docx, value, ..., .f = add_text_to_body)

add_str_with_keys(docx, str, ..., .f = add_xml_to_body)

Arguments

Details

Using add_value_with_keys() or add_str_with_keys()

add_value_with_keys() supports value vectors of length 1 or longer. If value is named, the names are assumed to be keywords indicating the cursor position for adding each value in the vector. If value is not named, a keyword parameter with the same length as value must be provided. When named = FALSE, no keyword parameter is required. Add add_str_with_keys() works identically but uses a str parameter and .f defaults to add_xml_to_body().

Note, as of July 2023, both add_value_with_keys() and add_str_with_keys() are superseded by vec_add_to_body().

Value

A rdocx object with xml, gt tables, or paragraphs of text added.

Author(s)

Ellis Hughes [email protected] (ORCID)

Examples

if (rlang::is_installed("gt")) {
  docx_example <- read_docx_ext(
    filename = "example.docx",
    path = system.file("doc_examples", package = "officer")
  )

  tab_1 <-
    gt::gt(
      gt::exibble,
      rowname_col = "row",
      groupname_col = "group"
    )

  add_gt_to_body(
    docx_example,
    tab_1,
    keyword = "Title 1"
  )

  tab_str <- gt::as_word(tab_1)

  add_str_with_keys(
    docx_example,
    str = c("Title 1" = tab_str, "Title 2" = tab_str)
  )
}

Description

brand_reference_docx() creates a Word document for use as a Quarto or Pandoc reference document (the reference-doc option for docx output) using the colors and typography from a brand.yml file.

By default, the function starts from Pandoc's default reference.docx (so every style Pandoc uses exists) and merges the brand settings into the existing style definitions. Styles are edited with xml2, rather than with officer::docx_set_paragraph_style(), because that function replaces a style wholesale and drops properties the brand doesn't set (e.g. the heading outline levels Word uses for the table of contents).

pandoc_reference_docx() writes Pandoc's default reference.docx to a file using Quarto's bundled Pandoc (if Quarto is installed) or Pandoc.

Usage

brand_reference_docx(
  brand = NULL,
  path = NULL,
  reference = NULL,
  overwrite = TRUE,
  quiet = FALSE
)

pandoc_reference_docx(path = tempfile(fileext = ".docx"))

Arguments

Value

brand_reference_docx() returns a rdocx object (invisibly if path is supplied). pandoc_reference_docx() returns path.

Brand settings

The following brand.yml settings are used:

• color: palette and color roles (e.g. primary or foreground). Wherever a color is used, it can be a hex value, a CSS color name, an rgb() value, a palette name, or a color role.

• typography.base: family, size, weight, and line-height for the document defaults and the Normal style.

• typography.headings: family, weight, style, color, and line-height for the Heading 1-9, TOC Heading, and Title styles.

• typography.link: color, background-color, weight, and decoration for the Hyperlink style.

• typography.monospace-inline (inheriting from typography.monospace): family, size, weight, color, and background-color for the Verbatim Char style.

• typography.monospace-block (inheriting from typography.monospace): background-color (as paragraph shading), line-height, color, family, size, and weight for the Source Code style used for code blocks. Pandoc's default reference document has no Source Code style, so it is created if monospace-block sets background-color, line-height, or color; otherwise, Pandoc creates the style when rendering (with shading from the highlight style).

Pandoc formats the text in code blocks with the Verbatim Char style (or syntax highlighting styles based on it), which takes precedence over the Source Code style. As a result, monospace-block values for family, size, weight, and color only apply if monospace-inline doesn't set a different value, and highlighted code keeps the token colors and shading from the highlight style (set with the Quarto highlight-style option).

brand.yml has no Word-specific options, so additional settings are read from defaults.docx (the brand.yml section for format-specific options):

• defaults.docx.styles: a list of style settings named by style ID (e.g. Heading1 or BodyText) or style name (e.g. ⁠Body Text⁠). Each style supports the typography fields family, size, weight, style, color, background-color, decoration, and line-height plus the paragraph fields space-before, space-after, indent-left, and keep-with-next. The Table style supports border-color, border-width, cell-padding (with top, bottom, left, and right), and header (typography fields for the first row).

• defaults.docx.page: size ("letter", "legal", or "a4"), margins (with top, bottom, left, right, header, footer, and gutter), and footer (with text, align, size, color, and family). In the footer text, {page} and {pages} are replaced with the page number and page count. Margins that aren't set keep the reference document's value (or Word's default of 1in for the page and 0.5in for the header and footer).

Field names can use hyphens (as in the brand.yml spec) or underscores (as in objects from brand.yml::read_brand_yml()).

Sizes can use pt, in, cm, mm, px, rem, or em units (bare numbers are treated as pt). Following CSS, ⁠1rem⁠ and ⁠1em⁠ are 16px (12pt). A unitless line-height is a multiple of the font size; a line-height with units sets an exact line height. Font weights can be numbers (100-900) or CSS weight names (e.g. "semi-bold"); a weight of 600 or more is bold.

These brand.yml settings are not used: color.background (Word documents don't have a page color by default), typography.fonts (fonts are not embedded, so the font families must be installed wherever the document is opened), and decoration: overline (Word has no overline).

See system.file("extdata", "_brand.yml", package = "officerExtras") for an example.

Table borders and other details that the brand doesn't cover can be edited by hand in Word afterwards (but re-creating the reference document overwrites those edits).

Page settings and sections

The defaults.docx.page settings (page size, margins, and footer) are stored in the reference document's section properties. Pandoc copies them to the last section of the rendered document, so they don't always apply to every page:

• Quarto's .landscape divs add section breaks with no footer, no margins, and an A4 landscape page size, so the pages before and in a landscape section lose the footer and page settings.

• A custom Pandoc OpenXML template (the template option for docx output, e.g. as used by the better-word Quarto extension) replaces the section properties if it doesn't use the ⁠$sectpr$⁠ variable.

Use docx_sync_sections() on the rendered document (e.g. in a Quarto post-render script) to copy the footer and page settings from the last section to every other section. The reference document only controls styles and these defaults, not the document structure (e.g. the title block or table of contents), which a custom template controls.

Examples

if (nzchar(Sys.which("quarto")) || nzchar(Sys.which("pandoc"))) {
  brand_path <- system.file("extdata", "_brand.yml", package = "officerExtras")

  withr::with_tempdir({
    brand_reference_docx(brand_path, path = "reference.docx")
  })
}

Description

Check file path for a docx, pptx, or xlsx file extension

Usage

check_office_fileext(
  x,
  arg = caller_arg(x),
  fileext = c("docx", "pptx", "xlsx"),
  allow_null = FALSE,
  call = caller_env(),
  ...
)

check_docx_fileext(x, arg = caller_arg(x), call = caller_env(), ...)

check_pptx_fileext(x, arg = caller_arg(x), call = caller_env(), ...)

check_xlsx_fileext(x, arg = caller_arg(x), call = caller_env(), ...)

Arguments

Value

Invisibly returns NULL if x passes the check (or is NULL and allow_null is TRUE). Otherwise, errors.

Description

Check if x is a rdocx, rpptx, or rxlsx object

Usage

check_officer(
  x,
  arg = caller_arg(x),
  what = c("rdocx", "rpptx", "rxlsx"),
  call = caller_env(),
  ...
)

check_docx(x, arg = caller_arg(x), call = caller_env(), ...)

check_pptx(x, arg = caller_arg(x), call = caller_env(), ...)

check_xlsx(x, arg = caller_arg(x), call = caller_env(), ...)

check_block_list(
  x,
  arg = caller_arg(x),
  allow_empty = FALSE,
  allow_null = FALSE,
  call = caller_env()
)

Arguments

Value

Invisibly returns NULL if x passes the check. Otherwise, errors.

Description

Check an object and error if an object is not a data.frame with the required column names to be a summary data.frame created from a rdocx or rpptx object. Optionally check for the number of rows, a specific content_type value, or if tables are included in the document the summary was created from.

Usage

check_officer_summary(
  x,
  n = NULL,
  content_type = NULL,
  summary_type = "doc",
  tables = FALSE,
  ...,
  arg = caller_arg(x),
  call = parent.frame()
)

Arguments

Value

Invisibly returns NULL if x passes the checks. Otherwise, errors.

See Also

Other summary functions: officer_summary(), officer_summary_levels()

Description

combine_docx() is a variant of officer::body_add_docx() that allows any number of input files and supports rdocx objects as well as Word file paths. Optionally use a separator between files or objects.

Please note that when you create a new rdocx object with this function (or officer::body_add_docx()) the added content will not appear in a summary data frame created with officer_summary() and is not accessible to other functions until the document is opened and edited with Microsoft Word. This is part of how the OOXML AltChunk Class works and can't be avoided.

Usage

combine_docx(
  ...,
  docx = NULL,
  .list = list2(...),
  pos = "after",
  sep = NULL,
  call = caller_env()
)

Arguments

Value

A rdocx object.

See Also

officer::body_add_docx()

Examples

## Not run: 
if (interactive()) {
  docx_path <- system.file("doc_examples", "example.docx", package = "officer")
  docx <- read_officer(docx_path)

  combine_docx(
    docx,
    docx_path
  )
}

## End(Not run)

Description

convert_docx() uses rmarkdown::pandoc_convert() to convert a rodcx object or Word file to another format with pandoc. If the "to" parameter contains a file extension, it is assumed to be an output file name. If you want to convert a file to a Word document, use the input parameter for the path to the Markdown, HTML, or other file.

Usage

convert_docx(
  docx = NULL,
  to = NULL,
  input = NULL,
  output = NULL,
  path = NULL,
  options = NULL,
  extract_media = TRUE,
  overwrite = TRUE,
  quiet = TRUE,
  ...
)

Arguments

Details

Supported input and output formats are described in the pandoc user guide.

The system path as well as the version of pandoc shipped with RStudio (if running under RStudio) are scanned for pandoc and the highest version available is used.

Value

Executes a call to pandoc using rmarkdown::pandoc_convert() to create a file from an officer object or a docx file.

See Also

rmarkdown::pandoc_convert()

Examples

docx_example <- read_officer(
  system.file("doc_examples/example.docx", package = "officer")
)

convert_docx(
  docx_example,
  to = "markdown"
)

withr::with_tempdir({
  convert_docx(
    docx_example,
    output = "docx_example.html"
  )
})

Description

A combined function for setting cursor position with officer::cursor_reach(), officer::cursor_bookmark(), or using a doc_index value from officer::docx_summary(). Defaults to using officer::cursor_end(), officer::cursor_begin(), officer::cursor_backward(), or officer::cursor_forward() if keyword, id, and index are all NULL.

Usage

cursor_docx(
  docx,
  keyword = NULL,
  id = NULL,
  index = NULL,
  default = "end",
  quiet = FALSE,
  call = caller_env()
)

Arguments

Value

A rdocx object with the cursor repositioned. If keyword can't be found, docx is returned unmodified.

See Also

officer::cursor_begin(), officer::docx_summary()

Description

This function extends officer::docx_dim() by also returning the body text dimensions within the margins, the aspect ratio of the page and body, and the page orientation as a string ("landscape" or "portrait").

Usage

dims_docx_ext(docx)

Arguments

Value

A list with page, landscape, margins, orientation, and body elements describing the page and body text dimensions.

See Also

officer::docx_dim()

Description

docx_sync_sections() copies the header and footer references, page margins, and page size from the last section of a Word document to the other sections, filling in what each section is missing.

This fixes documents rendered by Quarto or Pandoc where section breaks don't carry the reference document's page settings, for example when using Quarto's .landscape divs (which add section breaks with no footer, no margins, and an A4 landscape page size) or a custom OpenXML template. See the "Page settings and sections" section of brand_reference_docx().

For each section other than the last:

• If the section has no header or footer references, the last section's references are added.

• If the section has no page margins, the last section's margins are added.

• If the section has no page size, the last section's page size is added. If page_size = TRUE, landscape sections also get the last section's page size with the width and height swapped (and portrait sections get the last section's page size).

To use docx_sync_sections() in a Quarto project, add a post-render script to ⁠_quarto.yml⁠:

project:
  post-render: post-render.R

With a post-render.R file:

output_files <- strsplit(Sys.getenv("QUARTO_PROJECT_OUTPUT_FILES"), "\n")[[1]]

for (file in output_files[grepl("\\.docx$", output_files)]) {
  officerExtras::docx_sync_sections(file)
}

Usage

docx_sync_sections(x, path = NULL, page_size = TRUE)

Arguments

Value

A rdocx object (invisibly if a file is written).

Examples

docx <- officer::read_docx()
docx <- officer::body_add_par(docx, "Portrait")
docx <- officer::body_end_section_portrait(docx)
docx <- officer::body_add_par(docx, "Landscape")
docx <- officer::body_end_section_landscape(docx)

docx_sync_sections(docx)

Description

This function uses vctrs::vec_fill_missing() to convert hierarchically nested headings and text into a rectangular data.frame. It is an experimental function that may be modified or removed. At present, it is only used by officer_tables().

Usage

fill_with_pattern(
  x,
  pattern = "^heading",
  pattern_col = "style_name",
  fill_col = "text",
  col = "heading",
  direction = c("down", "up", "downup", "updown"),
  call = caller_env()
)

Arguments

Value

A data.frame with an additional column taking the name from col and the values from the column named in fill_col.

See Also

vctrs::vec_fill_missing()

Description

is_officer() and variants are basic wrappers for inherits() to check for object classes created by functions from the officer package. These functions are intended for internal use but are exposed for use by other extension developers.

Usage

is_officer(x, what = c("rdocx", "rpptx", "rxlsx"))

is_rdocx(x)

is_rpptx(x)

is_block_list(x)

Arguments

Value

TRUE or FALSE.

Description

make_block_list() extends officer::block_list() by supporting a list of inputs and optionally combining parameters with an existing block list (using the blocks parameter). Unlike officer::block_list(), make_block_list() errors if no input parameters are provided.

combine_blocks() takes any number of block_list objects and combined them into a single block_list. Both functions are not yet working as expected.

Usage

make_block_list(blocks = NULL, ..., allow_empty = FALSE, call = caller_env())

combine_blocks(...)

Arguments

Value

A block_list object.

See Also

Other block list functions: officer_add_blocks()

Description

officer_add_blocks() supports adding a list of blocks to rdocx (using add_blocks_to_body()) or rpptx objects (using officer::ph_with()). add_blocks_to_body() is a variant of officer::body_add_blocks() that allows users to set the cursor position before adding the block list using cursor_docx().

Usage

officer_add_blocks(
  x,
  blocks,
  pos = "after",
  location = NULL,
  level_list = integer(0),
  ...,
  call = caller_env()
)

add_blocks_to_body(
  docx,
  blocks,
  pos = "after",
  keyword = NULL,
  id = NULL,
  index = NULL,
  ...
)

Arguments

Value

A rdocx or rpptx object with the block list added.

See Also

Other block list functions: make_block_list()

Description

Unzip a docx or pptx file to a temporary directory, check if the directory contains a media folder, and copy media files to the directory set by dir. If a rdocx or rpptx object is provided, files are copied from the temporary package_dir associated with the object (accessible via x[["package_dir"]]).

Usage

officer_media(
  filename = NULL,
  path = NULL,
  x = NULL,
  target = "media",
  list = FALSE,
  overwrite = TRUE
)

Arguments

Value

Invisibly returns the paths of the copied (or, if list is TRUE, listed) media files, or NULL if no media files are found.

See Also

officer::media_extract()

Examples

officer_media(
  system.file("doc_examples/example.pptx", package = "officer"),
  list = TRUE
)

Description

officer_open() uses officer::open_file() to open a file ceated from a rdocx, rpptx, or rxlsx object.

Usage

officer_open(
  x,
  path = NULL,
  ...,
  overwrite = FALSE,
  interactive = is_interactive()
)

Arguments

Value

Input object x without modification.

Description

officer_properties() is a variant on officer::doc_properties() that will warn instead of error if document properties can't be found

Usage

officer_properties(x, values = list(), keep.null = FALSE, call = caller_env())

Arguments

Value

A named list of existing document properties or (if values is supplied) modified document properties.

Description

officer_summary() extends officer::docx_summary() and other officer summary functions by handling multiple input types within a single function.

Usage

officer_summary(
  x,
  summary_type = "doc",
  index = NULL,
  preserve = FALSE,
  as_tibble = TRUE,
  call = caller_env()
)

Arguments

Value

A tibble or data frame object.

See Also

Other summary functions: check_officer_summary(), officer_summary_levels()

Examples

docx_example <- read_officer(
  system.file("doc_examples", "example.docx", package = "officer")
)

officer_summary(docx_example)

pptx_example <- read_officer(
  "example.pptx", system.file("doc_examples", package = "officer")
)

officer_summary(pptx_example)

officer_summary(pptx_example, "slide", 1)

Description

officer_summary_levels() works with fill_with_pattern() to help convert hierarchically organized text, e.g. text with leveled headings or other styles into a data.frame where new columns hold the value of the preceding (or succeeding) heading text.

Usage

officer_summary_levels(
  x,
  levels = NULL,
  levels_from = "style_name",
  exclude_levels = NULL,
  fill_col = "text",
  direction = c("down", "up", "downup", "updown"),
  ...,
  strict = FALSE,
  call = caller_env()
)

Arguments

Value

A summary data frame with additional columns based on the supplied levels.

See Also

Other summary functions: check_officer_summary(), officer_summary()

Description

Get one or more tables from a rdocx or rpptx object. officer_tables() returns a list of data frames and officer_table() returns a single table as a data frame. These functions are based on example code on extracting Word document and PowerPoint slides in the officeverse documentation. Some additional features including the type_convert parameter and the addition of doc_index values as the default names for the returned list of tables are based on this blog post by Matt Dray.

Usage

officer_tables(
  x,
  index = NULL,
  has_header = TRUE,
  col = NULL,
  preserve = FALSE,
  ...,
  stack = FALSE,
  type_convert = FALSE,
  nm = NULL,
  call = caller_env()
)

officer_table(
  x,
  index = NULL,
  has_header = TRUE,
  col = NULL,
  ...,
  call = caller_env()
)

Arguments

Value

A list of data frames or, if stack is TRUE, a single data frame.

A single data.frame, or (if the table has more than one header row) a list of two data.frames: the table body and the table header.

See Also

docxtractr::docx_extract_all()

Examples

docx_example <- read_docx_ext(
  filename = "example.docx",
  path = system.file("doc_examples", package = "officer")
)

officer_tables(docx_example)

pptx_example <- read_pptx_ext(
  filename = "example.pptx",
  path = system.file("doc_examples", package = "officer")
)

officer_tables(pptx_example)[[1]]

Description

Uses the Google Docs, Slides, or Sheets URL to export a file locally, read to an officer object. If filename is NULL, exported file is removed after export.

Usage

read_docs_url(
  url,
  format = NULL,
  filename = NULL,
  path = NULL,
  overwrite = TRUE,
  quiet = TRUE
)

Arguments

Value

A rdocx, rpptx, or rxlsx object.

See Also

read_officer()

Description

read_officer() is a variant of officer::read_docx(), officer::read_pptx(), and officer::read_xlsx() that allows users to read different Microsoft Office file types with a single function. read_docx_ext(), read_pptx_ext(), and read_xlsx_ext() are wrappers for read_officer() that require the matching input file type. All versions allow both a filename and path (the officer functions only use a path). If a rdocx, rpptx, or rxlsx class object is provided to x, the object is checked based on the fileext parameter and then returned as is.

Usage

read_officer(
  filename = NULL,
  path = NULL,
  fileext = c("docx", "pptx", "xlsx"),
  x = NULL,
  arg = caller_arg(x),
  allow_null = TRUE,
  quiet = TRUE,
  call = parent.frame(),
  ...
)

read_docx_ext(
  filename = NULL,
  path = NULL,
  docx = NULL,
  allow_null = FALSE,
  quiet = TRUE
)

read_pptx_ext(
  filename = NULL,
  path = NULL,
  pptx = NULL,
  allow_null = FALSE,
  quiet = TRUE
)

read_xlsx_ext(
  filename = NULL,
  path = NULL,
  xlsx = NULL,
  allow_null = FALSE,
  quiet = TRUE
)

Arguments

Value

A rdocx, rpptx, or rxlsx object.

See Also

officer::read_docx()

Description

reduce_officer() is a wrapper for purrr::reduce().

Usage

reduce_officer(
  x = NULL,
  .f = function(x, value, ...) {
     vec_add_to_body(x, value = value, ...)
 },
  value = NULL,
  ...,
  .path = NULL
)

Arguments

Value

A rdocx, rpptx, or rxlsx object.

See Also

purrr::reduce(), vec_add_to_body()

Examples

## Not run: 
if (interactive()) {
  x <- reduce_officer(value = LETTERS)

  officer_summary(x)
}

## End(Not run)

Description

set_flextable_brand_defaults() sets flextable::set_flextable_defaults() from a brand.yml file, so tables created with flextable match the Table style in a reference document created with brand_reference_docx(). flextable formats each table directly (rather than using the reference document's Table style), so the defaults are needed for tables to match.

Usage

set_flextable_brand_defaults(brand = NULL, theme_fun = NULL, ...)

Arguments

Details

The following brand.yml settings are used:

• typography.base: family, size, and line-height (if unitless) for the table text.

• color.foreground for the text color.

• defaults.docx.styles.Table: border-color, border-width, cell-padding, and header (family, size, weight, style, color, and background-color for the header row).

Value

The previous flextable defaults, invisibly. Pass them to do.call(flextable::set_flextable_defaults, old) to restore them.

Examples

if (rlang::is_installed(c("flextable", "yaml12"))) {
  brand_path <- system.file("extdata", "_brand.yml", package = "officerExtras")

  old <- set_flextable_brand_defaults(brand_path)
  flextable::flextable(head(mtcars, 3))

  do.call(flextable::set_flextable_defaults, old)
}

Description

use_doc_version() is inspired by usethis::use_version() and designed to support semantic versioning for Microsoft Word or PowerPoint documents. The document version is tracked as a custom file property and a component of the document filename. If filename is supplied and the filename contains a version number, the function ignores any version number stored as a document property and overwrites the property with the new incremented version number.

doc_version() is a helper function that returns the document version based on a supplied filename or document properties.

The internals for this function are adapted from the internal idesc_bump_version() function authored by Csárdi Gábor for the {desc} package.

Usage

use_doc_version(
  filename = NULL,
  x = NULL,
  which = NULL,
  save = TRUE,
  sep = ".",
  property = "version",
  prefix = NULL,
  path = NULL,
  ...,
  call = caller_env()
)

doc_version(
  filename = NULL,
  x = NULL,
  sep = ".",
  property = "version",
  allow_new = TRUE,
  .default = c(0, 1, 0),
  call = caller_env()
)

Arguments

Value

Invisibly return a rdocx or rpptx object with an updated version property.

A string with the document version.

Description

vec_add_to_body() is a vectorized variant add_to_body() that allows users to supply a vector of values or str inputs to add multiple blocks of text, images, plots, or tables to a document. Alternatively, the function also supports adding a single object at multiple locations or using multiple different styles. All parameters are recycled using vctrs::vec_recycle_common() so inputs must be length 1 or match the length of the longest input vector. Optionally, the function can apply a separator between each element by passing a value to add_to_body() or passing docx to a function, such as officer::body_add_break().

Usage

vec_add_to_body(
  docx,
  ...,
  .sep = NULL,
  .pos = "after",
  .size = NULL,
  .call = caller_env()
)

Arguments

Value

A rdocx object with each recycled element added in sequence.

Examples

docx_example <- read_officer()

docx_example <- vec_add_to_body(
  docx_example,
  value = c("Sample text 1", "Sample text 2", "Sample text 3"),
  style = c("heading 1", "heading 2", "Normal")
)

docx_example <- vec_add_to_body(
  docx_example,
  value = rep("Text", 5),
  style = "Normal",
  .sep = officer::body_add_break
)

officer_summary(docx_example)

if (rlang::is_installed("gt")) {
  gt_tbl <- gt::gt(gt::gtcars[1:2, 1:2])

  # list inputs such as gt tables must be passed within a list to avoid
  # issues
  docx_example <- vec_add_to_body(
    docx_example,
    gt_object = list(gt_tbl, gt_tbl),
    keyword = c("Sample text 1", "Sample text 2")
  )

  officer_summary(docx_example)
}

Description

Write a rdocx, rpptx, or rxlsx object to a file

Usage

write_officer(x, path, overwrite = TRUE, modified_by = Sys.getenv("USER"), ...)

Arguments

Value

Returns the input object (invisibly) and writes the rdocx, rpptx, or rxlsx object to a file with a name and location matching the provided path.