Package 'officer'

Description

Add a sheet into an xlsx worksheet.

Usage

add_sheet(x, label)

Arguments

Details

read_xlsx() returns a workbook that already contains one default sheet shipped with the template (named "Sheet1" or "Feuil1" depending on the locale). add_sheet() is purely additive: the default sheet is kept as-is. Remove it explicitly with sheet_remove() if it is not wanted.

Examples

my_ws <- read_xlsx()
my_pres <- add_sheet(my_ws, label = "new sheet")

Description

Add a slide into a pptx presentation.

Usage

add_slide(x, layout = NULL, master = NULL, ..., .dots = NULL)

Arguments

See Also

print.rpptx(), read_pptx(), layout_summary(), plot_layout_properties(), ph_with(), phs_with(), layout_default()

Other functions to manipulate slides: move_slide(), on_slide(), remove_slide(), set_notes()

Examples

x <- read_pptx()

layout_summary(x) # available layouts

x <- add_slide(x, layout = "Two Content")

x <- layout_default(x, "Title Slide") # set default layout for `add_slide()`
x <- add_slide(x) # uses default layout

# use `...` to fill placeholders when adding slide
x <- add_slide(
  x,
  layout = "Two Content",
  `Title 1` = "A title",
  dt = "Jan. 26, 2025",
  `body[2]` = "Body 2",
  left = "Left side",
  `6` = "Footer"
)

Description

generates a slide from each layout in the base document to identify the placeholder indexes, types, names, master names and layout names.

This is to be used when need to know what parameters should be used with ⁠ph_location*⁠ calls. The parameters are printed in their corresponding shapes.

Note that if there are duplicated ph_label, you should not use ph_location_label(). Hint: You can dedupe labels using layout_dedupe_ph_labels().

Usage

annotate_base(path = NULL, output_file = "annotated_layout.pptx")

Arguments

Value

rpptx object of the annotated PowerPoint file

See Also

Other functions for reading presentation information: color_scheme(), doc_properties(), layout_properties(), layout_summary(), length.rpptx(), plot_layout_properties(), slide_size(), slide_summary()

Examples

# To generate an anotation of the default base document with officer:
annotate_base(output_file = tempfile(fileext = ".pptx"))

# To generate an annotation of the base document 'mydoc.pptx' and place the
# annotated output in 'mydoc_annotate.pptx'
# annotate_base(path = 'mydoc.pptx', output_file='mydoc_annotate.pptx')

Description

Convert the data in an a 'PowerPoint' table to a matrix or all data to a list of matrices.

Usage

## S3 method for class 'rpptx'
as.matrix(
  x,
  ...,
  slide_id = NA_integer_,
  id = NA_character_,
  span = c(NA_character_, "fill")
)

Arguments

Value

A matrix with the data, or if slide_id=NULL, a list of matrices

Examples

library(officer)
pptx_file <- system.file(package="officer", "doc_examples", "example.pptx")
z <- read_pptx(pptx_file)
as.matrix(z, slide_id = NULL)

Description

Create a representation of a caption that can be used for cross reference.

Usage

block_caption(label, style = NULL, autonum = NULL)

Arguments

See Also

Other block functions for reporting: block_gg(), block_list(), block_list_items(), block_pour_docx(), block_section(), block_table(), block_toc(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

library(officer)

run_num <- run_autonum(seq_id = "tab", pre_label = "tab. ",
  bkm = "mtcars_table")
caption <- block_caption("mtcars table",
  style = "Normal",
  autonum = run_num
)

doc_1 <- read_docx()
doc_1 <- body_add(doc_1, "A title", style = "heading 1")
doc_1 <- body_add(doc_1, "Hello world!", style = "Normal")
doc_1 <- body_add(doc_1, caption)
doc_1 <- body_add(doc_1, mtcars, style = "table_template")

print(doc_1, target = tempfile(fileext = ".docx"))

Description

A simple wrapper to add a 'ggplot' object as a png in a document. It produces an object of class 'block_gg' with a corresponding method to_wml() that can be used to convert the object to a WordML string.

Usage

block_gg(
  value,
  fp_p = fp_par(),
  width = 6,
  height = 5,
  res = 300,
  scale = 1,
  unit = "in"
)

Arguments

See Also

Other block functions for reporting: block_caption(), block_list(), block_list_items(), block_pour_docx(), block_section(), block_table(), block_toc(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

library(officer)
if (require("ggplot2")) {
  set.seed(2)
  doc <- read_docx()

  z <- body_append_start_context(doc)

  for (i in seq_len(3)) {
    df <- data.frame(x = runif(10), y = runif(10))
    gg <- ggplot(df, aes(x = x, y = y)) + geom_point()

    write_elements_to_context(
      context = z,
      block_gg(
        value = gg
      )
    )
  }

  doc <- body_append_stop_context(z)

  print(doc, target = tempfile(fileext = ".docx"))
}

Description

A list of blocks can be used to gather several blocks (paragraphs, tables, ...) into a single object. The result can be added into a Word document or a PowerPoint presentation.

Usage

block_list(...)

Arguments

See Also

ph_with(), body_add_blocks(), fpar()

Other block functions for reporting: block_caption(), block_gg(), block_list_items(), block_pour_docx(), block_section(), block_table(), block_toc(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

# block list ------

img.file <- file.path( R.home("doc"), "html", "logo.jpg" )
fpt_blue_bold <- fp_text(color = "#006699", bold = TRUE)
fpt_red_italic <- fp_text(color = "#C32900", italic = TRUE)


## This can be only be used in a MS word output as pptx does
## not support paragraphs made of text and images.
## (actually it can be used but image will not appear in the
## pptx output)
value <- block_list(
  fpar(ftext("hello world", fpt_blue_bold)),
  fpar(ftext("hello", fpt_blue_bold), " ",
       ftext("world", fpt_red_italic)),
  fpar(
    ftext("hello world", fpt_red_italic),
          external_img(
            src = img.file, height = 1.06, width = 1.39)))
value

doc <- read_docx()
doc <- body_add(doc, value)
print(doc, target = tempfile(fileext = ".docx"))


value <- block_list(
  fpar(ftext("hello world", fpt_blue_bold)),
  fpar(ftext("hello", fpt_blue_bold), " ",
       ftext("world", fpt_red_italic)),
  fpar(
    ftext("blah blah blah", fpt_red_italic)))
value

doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(doc, value, location = ph_location_type(type = "body"))
print(doc, target = tempfile(fileext = ".pptx"))

Description

Create a bullet or numbered list from list_item() elements. Supports rich text via fpar() and multi-level nesting. Works in both Word and PowerPoint documents.

Usage

block_list_items(..., list_type = "bullet")

Arguments

See Also

list_item(), body_add(), ph_with()

Other block functions for reporting: block_caption(), block_gg(), block_list(), block_pour_docx(), block_section(), block_table(), block_toc(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

items <- block_list_items(
  list_item(fpar(
    ftext("Item 1", fp_text(color = "red"))
  ), level = 1),
  list_item(fpar("Sub-item"), level = 2),
  list_item(fpar("Item 2"), level = 1),
  list_type = "bullet"
)
items

Description

Pour the content of a docx file in the resulting docx from an 'R Markdown' document.

Usage

block_pour_docx(file)

Arguments

See Also

Other block functions for reporting: block_caption(), block_gg(), block_list(), block_list_items(), block_section(), block_table(), block_toc(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

library(officer)
docx <- tempfile(fileext = ".docx")
doc <- read_docx()
doc <- body_add(doc, iris[1:20,], style = "table_template")
print(doc, target = docx)

target <- tempfile(fileext = ".docx")
doc_1 <- read_docx()
doc_1 <- body_add(doc_1, block_pour_docx(docx))
print(doc_1, target = target)

Description

Create a representation of a section.

A section affects preceding paragraphs or tables; i.e. a section starts at the end of the previous section (or the beginning of the document if no preceding section exists), and stops where the section is declared.

When a new landscape section is needed, it is recommended to add a block_section with type = "continuous", to add the content to be appened in the new section and finally to add a block_section with page_size = page_size(orient = "landscape").

Usage

block_section(property)

Arguments

See Also

Other block functions for reporting: block_caption(), block_gg(), block_list(), block_list_items(), block_pour_docx(), block_table(), block_toc(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

ps <- prop_section(
  page_size = page_size(orient = "landscape"),
  page_margins = page_mar(top = 2),
  type = "continuous"
)
block_section(ps)

Description

Create a representation of a table

Usage

block_table(x, header = TRUE, properties = prop_table(), alignment = NULL)

Arguments

See Also

prop_table()

Other block functions for reporting: block_caption(), block_gg(), block_list(), block_list_items(), block_pour_docx(), block_section(), block_toc(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

block_table(x = head(iris))

block_table(x = mtcars, header = TRUE,
  properties = prop_table(
    tcf = table_conditional_formatting(
      first_row = TRUE, first_column = TRUE)
  ))

Description

Create a representation of a table of content for Word documents.

Usage

block_toc(level = 3, style = NULL, seq_id = NULL, separator = ";")

Arguments

See Also

Other block functions for reporting: block_caption(), block_gg(), block_list(), block_list_items(), block_pour_docx(), block_section(), block_table(), fpar(), list_item(), plot_instr(), unordered_list()

Examples

block_toc(level = 2)
block_toc(style = "Table Caption")

Description

Add a list of blocks produced by block_list() into into an rdocx object.

Usage

body_add_blocks(x, blocks, pos = "after")

Arguments

See Also

Other functions for adding content: body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

library(officer)

img.file <- file.path(R.home("doc"), "html", "logo.jpg")

bl <- block_list(
  fpar(ftext("hello", shortcuts$fp_bold(color = "red"))),
  fpar(
    ftext("hello world", shortcuts$fp_bold()),
    external_img(src = img.file, height = 1.06, width = 1.39),
    fp_p = fp_par(text.align = "center")
  )
)

doc_1 <- read_docx()
doc_1 <- body_add_blocks(doc_1, blocks = bl)
print(doc_1, target = tempfile(fileext = ".docx"))

Description

Add a page break into an rdocx object

Usage

body_add_break(x, pos = "after")

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

doc <- read_docx()
doc <- body_add_break(doc)
print(doc, target = tempfile(fileext = ".docx"))

Description

Add a Word caption into an rdocx object.

Usage

body_add_caption(x, value, pos = "after")

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

doc <- read_docx()

if (capabilities(what = "png")) {
  doc <- body_add_plot(doc,
    value = plot_instr(
      code = {
        barplot(1:5, col = 2:6)
      }
    ),
    style = "centered"
  )
}
run_num <- run_autonum(
  seq_id = "fig", pre_label = "Figure ",
  bkm = "barplot"
)
caption <- block_caption("a barplot",
  style = "Normal",
  autonum = run_num
)
doc <- body_add_caption(doc, caption)
print(doc, target = tempfile(fileext = ".docx"))

Description

Add content of a docx into an rdocx object.

The function is using a 'Microsoft Word' feature: when the document will be edited, the content of the file will be inserted in the main document.

This feature is unlikely to work as expected if the resulting document is edited by another software. You can use function body_import_docx() to import the content as an alternative.

The file is added when the method print() that produces the final Word file is called, so don't remove file defined with src before.

Usage

body_add_docx(x, src, pos = "after")

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

file1 <- tempfile(fileext = ".docx")
file2 <- tempfile(fileext = ".docx")
file3 <- tempfile(fileext = ".docx")
x <- read_docx()
x <- body_add_par(x, "hello world 1", style = "Normal")
print(x, target = file1)

x <- read_docx()
x <- body_add_par(x, "hello world 2", style = "Normal")
print(x, target = file2)

x <- read_docx(path = file1)
x <- body_add_break(x)
x <- body_add_docx(x, src = file2)
print(x, target = file3)

Description

Add an fpar() (a formatted paragraph) into an rdocx object.

Usage

body_add_fpar(x, value, style = NULL, pos = "after")

Arguments

See Also

fpar()

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

bold_face <- shortcuts$fp_bold(font.size = 30)
bold_redface <- update(bold_face, color = "red")
fpar_ <- fpar(
  ftext("Hello ", prop = bold_face),
  ftext("World", prop = bold_redface),
  ftext(", how are you?", prop = bold_face)
)
doc <- read_docx()
doc <- body_add_fpar(doc, fpar_)

print(doc, target = tempfile(fileext = ".docx"))

# a way of using fpar to center an image in a Word doc ----
rlogo <- file.path(R.home("doc"), "html", "logo.jpg")
img_in_par <- fpar(
  external_img(src = rlogo, height = 1.06 / 2, width = 1.39 / 2),
  hyperlink_ftext(
    href = "https://cran.r-project.org/index.html",
    text = "cran", prop = bold_redface
  ),
  fp_p = fp_par(text.align = "center")
)

doc <- read_docx()
doc <- body_add_fpar(doc, img_in_par)
print(doc, target = tempfile(fileext = ".docx"))

Description

Add a ggplot as a png image into an rdocx object.

Usage

body_add_gg(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  style = "Normal",
  scale = 1,
  pos = "after",
  unit = "in",
  ...
)

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

if (require("ggplot2")) {
  doc <- read_docx()

  gg_plot <- ggplot(data = iris) +
    geom_point(mapping = aes(Sepal.Length, Petal.Length))

  if (capabilities(what = "png")) {
    doc <- body_add_gg(doc, value = gg_plot, style = "centered")

    # Set the unit in which the width and height arguments are expressed
    doc <- body_add_gg(doc, value = gg_plot, style = "centered", unit = "cm")
  }

  print(doc, target = tempfile(fileext = ".docx"))
}

Description

Add an image into an rdocx object.

Usage

body_add_img(x, src, style = NULL, width, height, pos = "after", unit = "in")

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

library(officer)

doc <- read_docx()

img.file <- file.path(R.home("doc"), "html", "logo.jpg")
if (file.exists(img.file)) {
  doc <- body_add_img(x = doc, src = img.file, height = 1.06, width = 1.39)

  # Set the unit in which the width and height arguments are expressed
  doc <- body_add_img(
    x = doc,
    src = img.file,
    height = 2.69,
    width = 3.53,
    unit = "cm"
  )
}

print(doc, target = tempfile(fileext = ".docx"))

Description

Add a bullet or numbered list produced by block_list_items() into an rdocx object.

Usage

body_add_list(x, items, pos = "after")

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

library(officer)

items <- block_list_items(
  list_item(fpar(ftext("Item 1", fp_text(color = "red"))), level = 1),
  list_item(fpar("Sub-item"), level = 2),
  list_item(fpar("Item 2"), level = 1),
  list_type = "bullet"
)

doc <- read_docx()
doc <- body_add_list(doc, items = items)
print(doc, target = tempfile(fileext = ".docx"))

Description

Add a paragraph of text into an rdocx object

Usage

body_add_par(x, value, style = NULL, pos = "after")

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

doc <- read_docx()
doc <- body_add_par(doc, "A title", style = "heading 1")
doc <- body_add_par(doc, "Hello world!", style = "Normal")
doc <- body_add_par(doc, "centered text", style = "centered")

print(doc, target = tempfile(fileext = ".docx"))

Description

Add a plot as a png image into an rdocx object.

Usage

body_add_plot(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  style = "Normal",
  pos = "after",
  unit = "in",
  ...
)

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_table(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

doc <- read_docx()

if (capabilities(what = "png")) {
  p <- plot_instr(
      code = {
        barplot(1:5, col = 2:6)
      }
    )

  doc <- body_add_plot(doc, value = p, style = "centered")

  # Set the unit in which the width and height arguments are expressed
  doc <- body_add_plot(doc, value = p, style = "centered", unit = "cm")
}

print(doc, target = tempfile(fileext = ".docx"))

Description

Add a table into an rdocx object.

Usage

body_add_table(
  x,
  value,
  style = NULL,
  pos = "after",
  header = TRUE,
  alignment = NULL,
  align_table = "center",
  stylenames = table_stylenames(),
  first_row = TRUE,
  first_column = FALSE,
  last_row = FALSE,
  last_column = FALSE,
  no_hband = FALSE,
  no_vband = TRUE
)

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_toc(), body_append_start_context(), body_import_docx()

Examples

doc <- read_docx()
doc <- body_add_table(doc, iris, style = "table_template")

print(doc, target = tempfile(fileext = ".docx"))

Description

Add a table of content into an rdocx object. The TOC will be generated by Word, if the document is not edited with Word (i.e. Libre Office) the TOC will not be generated.

Usage

body_add_toc(x, level = 3, pos = "after", style = NULL, separator = ";")

Arguments

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_append_start_context(), body_import_docx()

Examples

doc <- read_docx()
doc <- body_add_toc(doc)

print(doc, target = tempfile(fileext = ".docx"))

Description

This function is used to append content to a Word document in a fast way.

It does not use the XML tree of the document neither the cursor that is responsible for increasing the performance of Word document generation when looping over a large number of elements.

This function must be used with the write_elements_to_context() and body_append_stop_context() functions:

1. body_append_start_context() creates a context and returns a list with the context and the file connection.

2. write_elements_to_context() writes the elements to the context file connection.

3. body_append_stop_context() closes the file connection and replaces the XML in the document with the new XML.

Usage

body_append_start_context(x, additional_ns = character())

write_elements_to_context(context, ...)

body_append_stop_context(context)

Arguments

Value

body_append_start_context() returns a list representing the context that contains:

• doc: the original document object

• file_con: the file connection to the context

• file_path: the path to the context file

• final_str: the final XML string to be appended to the document later when calling body_append_stop_context().

This object should not be modified by the user but instead passed to write_elements_to_context() and body_append_stop_context().

write_elements_to_context() returns the context object.

body_append_stop_context() returns the rdocx object with the cursor position set to the end of the document.

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_import_docx()

Examples

library(officer)

doc <- read_docx()
doc <- body_add_par(doc, value = "blah blah blah", style = "Normal")

z <- body_append_start_context(doc)

for (i in seq_len(50)) {
  write_elements_to_context(
    context = z,
    fpar(
      "Hello World, ",
      i,
      fp_p = fp_par(word_style = "heading 1")
    ),
    fpar(run_pagebreak())
  )
}
doc <- body_append_stop_context(z)


print(doc, target = tempfile(fileext = ".docx"))

Description

Add a bookmark at the cursor location. The bookmark is added on the first run of text in the current paragraph.

Usage

body_bookmark(x, id)

Arguments

Examples

# cursor_bookmark ----

doc <- read_docx()
doc <- body_add_par(doc, "centered text", style = "centered")
doc <- body_bookmark(doc, "text_to_replace")

Description

Add a comment at the cursor location. The comment is added on the first run of text in the current paragraph.

Usage

body_comment(x, cmt = ftext(""), author = "", date = "", initials = "")

Arguments

Examples

doc <- read_docx()
doc <- body_add_par(doc, "Paragraph")
doc <- body_comment(doc, block_list("This is a comment."))
docx_file <- print(doc, target = tempfile(fileext = ".docx"))
docx_comments(read_docx(docx_file))

Description

Add a section to the document. You can define any section with a block_section object. All other ⁠body_end_section_*⁠ are specialized, this one is highly flexible but it's up to the user to define the section properties.

Usage

body_end_block_section(x, value)

Arguments

Section model in Word

A block_section added with body_end_block_section() applies to the content that precedes the call: it closes the section that holds the previous paragraphs / tables and inherits any layout (orientation, columns, margins, headers / footers) defined by the block_section. The function name reflects this: it marks the end of a section.

Typical pattern: add the content, then close it with the section that should layout it.

doc <- read_docx() |>
  body_add_par("This paragraph is in landscape orientation.") |>
  body_end_block_section(block_section(prop_section(
    page_size = page_size(orient = "landscape")
  )))

The default section of the document (defined by the template or by body_set_default_section()) closes any content added after the last body_end_block_section() call.

The RTF output uses the opposite model: rtf_add(block_section(...)) applies to the content that follows the call. See rtf_add().

Illustrations

See Also

Other functions for Word sections: body_end_section_columns(), body_end_section_columns_landscape(), body_end_section_continuous(), body_end_section_landscape(), body_end_section_portrait(), body_set_default_section()

Examples

library(officer)
str1 <- "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
str1 <- rep(str1, 20)
str1 <- paste(str1, collapse = " ")

ps <- prop_section(
  page_size = page_size(orient = "landscape"),
  page_margins = page_mar(top = 2),
  type = "continuous"
)

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")

doc_1 <- body_end_block_section(doc_1, block_section(ps))

doc_1 <- body_add_par(doc_1, value = str1, style = "centered")

print(doc_1, target = tempfile(fileext = ".docx"))

Description

A section with multiple columns is added to the document.

You may prefer to use body_end_block_section() that is more flexible.

Usage

body_end_section_columns(x, widths = c(2.5, 2.5), space = 0.25, sep = FALSE)

Arguments

See Also

Other functions for Word sections: body_end_block_section(), body_end_section_columns_landscape(), body_end_section_continuous(), body_end_section_landscape(), body_end_section_portrait(), body_set_default_section()

Examples

str1 <- "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
str1 <- rep(str1, 5)
str1 <- paste(str1, collapse = " ")

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_end_section_columns(doc_1)
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
print(doc_1, target = tempfile(fileext = ".docx"))

Description

A landscape section with multiple columns is added to the document.

Usage

body_end_section_columns_landscape(
  x,
  widths = c(2.5, 2.5),
  space = 0.25,
  sep = FALSE,
  w = 16838/1440,
  h = 11906/1440
)

Arguments

See Also

Other functions for Word sections: body_end_block_section(), body_end_section_columns(), body_end_section_continuous(), body_end_section_landscape(), body_end_section_portrait(), body_set_default_section()

Examples

str1 <- "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
str1 <- rep(str1, 5)
str1 <- paste(str1, collapse = " ")

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_end_section_columns_landscape(doc_1, widths = c(6, 2))
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
print(doc_1, target = tempfile(fileext = ".docx"))

Description

Section break starts the new section on the same page. This type of section break is often used to change the number of columns without starting a new page.

Usage

body_end_section_continuous(x)

Arguments

See Also

Other functions for Word sections: body_end_block_section(), body_end_section_columns(), body_end_section_columns_landscape(), body_end_section_landscape(), body_end_section_portrait(), body_set_default_section()

Examples

str1 <- "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
str1 <- rep(str1, 5)
str1 <- paste(str1, collapse = " ")
str2 <- "Aenean venenatis varius elit et fermentum vivamus vehicula."
str2 <- rep(str2, 5)
str2 <- paste(str2, collapse = " ")

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, value = "Default section", style = "heading 1")
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_add_par(doc_1, value = str2, style = "Normal")
doc_1 <- body_end_section_continuous(doc_1)

print(doc_1, target = tempfile(fileext = ".docx"))

Description

A section with landscape orientation is added to the document.

Usage

body_end_section_landscape(x, w = 16838/1440, h = 11906/1440)

Arguments

See Also

Other functions for Word sections: body_end_block_section(), body_end_section_columns(), body_end_section_columns_landscape(), body_end_section_continuous(), body_end_section_portrait(), body_set_default_section()

Examples

str1 <- "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
str1 <- rep(str1, 5)
str1 <- paste(str1, collapse = " ")

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_end_section_landscape(doc_1)

print(doc_1, target = tempfile(fileext = ".docx"))

Description

A section with portrait orientation is added to the document.

Usage

body_end_section_portrait(x, w = 16838/1440, h = 11906/1440)

Arguments

See Also

Other functions for Word sections: body_end_block_section(), body_end_section_columns(), body_end_section_columns_landscape(), body_end_section_continuous(), body_end_section_landscape(), body_set_default_section()

Examples

str1 <- "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
str1 <- rep(str1, 5)
str1 <- paste(str1, collapse = " ")

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
doc_1 <- body_end_section_portrait(doc_1)
doc_1 <- body_add_par(doc_1, value = str1, style = "Normal")
print(doc_1, target = tempfile(fileext = ".docx"))

Description

Import body content and footnotes of a Word document into an rdocx object.

The function is similar to body_add_docx() but instead of adding the content as an external object, the document is read and all its content is appended to the target document.

Usage

body_import_docx(
  x,
  src,
  par_style_mapping = list(),
  run_style_mapping = list(),
  tbl_style_mapping = list(),
  prepend_chunks_on_styles = list()
)

Arguments

par_style_mapping = list(
  "Normal"    = c("List Paragraph", "Body Text"),
  "heading 1" = "Heading 1"
)
run_style_mapping = list(
  "Emphasis"  = c("Emphasis", "Italic")
)
tbl_style_mapping = list(
  "Normal Table" = c("Light Shading")
)

Details

The following operations are performed when importing a document:

• Numberings are copied from the source document to the target document.

• Styles are not copied. If styles in the source document do not exist in the target document, the style specified in the par_style_mapping, run_style_mapping and tbl_style_mapping arguments will be used instead. If no mapping is provided, the default style will be used and a warning is emitted.

See Also

Other functions for adding content: body_add_blocks(), body_add_break(), body_add_caption(), body_add_docx(), body_add_fpar(), body_add_gg(), body_add_img(), body_add_list(), body_add_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

Examples

library(officer)

# example file from the package
file_input <- system.file(
  package = "officer",
  "doc_examples/example.docx"
)

# create a new rdocx document
x <- read_docx()

# import content from file_input
x <- body_import_docx(
  x = x,
  src = file_input,
  # style mapping for paragraphs and tables
  par_style_mapping = list(
    "Normal" = c("List Paragraph")
  ),
  tbl_style_mapping = list(
    "Normal Table" = "Light Shading"
  )
)

# Create temporary file
tf <- tempfile(fileext = ".docx")
# write to file
print(x, target = tf)

Description

Remove element pointed by cursor from a 'Word' document.

Usage

body_remove(x)

Arguments

Examples

library(officer)

str1 <- rep("Lorem ipsum dolor sit amet, consectetur adipiscing elit. ", 20)
str1 <- paste(str1, collapse = "")

str2 <- "Drop that text"

str3 <- rep("Aenean venenatis varius elit et fermentum vivamus vehicula. ", 20)
str3 <- paste(str3, collapse = "")

my_doc <- read_docx()
my_doc <- body_add_par(my_doc, value = str1, style = "Normal")
my_doc <- body_add_par(my_doc, value = str2, style = "centered")
my_doc <- body_add_par(my_doc, value = str3, style = "Normal")

new_doc_file <- print(my_doc,
  target = tempfile(fileext = ".docx")
)

my_doc <- read_docx(path = new_doc_file)
my_doc <- cursor_reach(my_doc, keyword = "that text")
my_doc <- body_remove(my_doc)

print(my_doc, target = tempfile(fileext = ".docx"))

Description

Replace text anywhere in the document, or at a cursor.

Replace all occurrences of old_value with new_value. This method uses grepl()/gsub() for pattern matching; you may supply arguments as required (and therefore use regex() features) using the optional ... argument.

Note that by default, grepl/gsub will use fixed=FALSE, which means that old_value and new_value will be interepreted as regular expressions.

Chunking of text

Note that the behind-the-scenes representation of text in a Word document is frequently not what you might expect! Sometimes a paragraph of text is broken up (or "chunked") into several "runs," as a result of style changes, pauses in text entry, later revisions and edits, etc. If you have not styled the text, and have entered it in an "all-at-once" fashion, e.g. by pasting it or by outputing it programmatically into your Word document, then this will likely not be a problem. If you are working with a manually-edited document, however, this can lead to unexpected failures to find text.

You can use the officer function docx_show_chunk() to show how the paragraph of text at the current cursor has been chunked into runs, and what text is in each chunk. This can help troubleshoot unexpected failures to find text.

Usage

body_replace_all_text(
  x,
  old_value,
  new_value,
  only_at_cursor = FALSE,
  warn = TRUE,
  ...
)

headers_replace_all_text(
  x,
  old_value,
  new_value,
  only_at_cursor = FALSE,
  warn = TRUE,
  ...
)

footers_replace_all_text(
  x,
  old_value,
  new_value,
  only_at_cursor = FALSE,
  warn = TRUE,
  ...
)

Arguments

header_replace_all_text

Replacements will be performed in each header of all sections.

Replacements will be performed in each footer of all sections.

Author(s)

Frank Hangler, [email protected]

See Also

grepl(), regex(), docx_show_chunk()

Examples

library(officer)

doc <- read_docx()
doc <- body_add_par(doc, "Placeholder one")
doc <- body_add_par(doc, "Placeholder two")

# Show text chunk at cursor
docx_show_chunk(doc) # Output is 'Placeholder two'

# Simple search-and-replace at current cursor, with regex turned off
doc <- body_replace_all_text(
  doc,
  old_value = "Placeholder",
  new_value = "new",
  only_at_cursor = TRUE,
  fixed = TRUE
)
docx_show_chunk(doc) # Output is 'new two'

# Do the same, but in the entire document and ignoring case
doc <- body_replace_all_text(
  doc,
  old_value = "placeholder",
  new_value = "new",
  only_at_cursor = FALSE,
  ignore.case = TRUE
)
doc <- cursor_backward(doc)
docx_show_chunk(doc) # Output is 'new one'

# Use regex : replace all words starting with "n" with the word "example"
doc <- body_replace_all_text(doc, "\\bn.*?\\b", "example")
docx_show_chunk(doc) # Output is 'example one'

Description

Use these functions if you want to replace a paragraph containing a bookmark with a 'ggplot' or a base plot.

Usage

body_replace_gg_at_bkm(
  x,
  bookmark,
  value,
  width = 6,
  height = 5,
  res = 300,
  style = "Normal",
  scale = 1,
  keep = FALSE,
  ...
)

body_replace_plot_at_bkm(
  x,
  bookmark,
  value,
  width = 6,
  height = 5,
  res = 300,
  style = "Normal",
  keep = FALSE,
  ...
)

Arguments

Examples

library(officer)

if (require("ggplot2")) {
  gg_plot <- ggplot(data = iris) +
    geom_point(mapping = aes(Sepal.Length, Petal.Length))

  doc <- read_docx()
  doc <- body_add_par(doc, "insert_plot_here")
  doc <- body_bookmark(doc, "plot")
  doc <- body_replace_gg_at_bkm(doc, bookmark = "plot", value = gg_plot)
  print(doc, target = tempfile(fileext = ".docx"))
}
doc <- read_docx()
doc <- body_add_par(doc, "insert_plot_here")
doc <- body_bookmark(doc, "plot")
if (capabilities(what = "png")) {
  doc <- body_replace_plot_at_bkm(
    doc,
    bookmark = "plot",
    value = plot_instr(
      code = {
        barplot(1:5, col = 2:6)
      }
    )
  )
}
print(doc, target = tempfile(fileext = ".docx"))

Description

Replace text content enclosed in a bookmark with different text. A bookmark will be considered as valid if enclosing words within a paragraph; i.e., a bookmark along two or more paragraphs is invalid, a bookmark set on a whole paragraph is also invalid, but bookmarking few words inside a paragraph is valid.

Usage

body_replace_text_at_bkm(x, bookmark, value)

body_replace_img_at_bkm(x, bookmark, value)

headers_replace_text_at_bkm(x, bookmark, value)

headers_replace_img_at_bkm(x, bookmark, value)

footers_replace_text_at_bkm(x, bookmark, value)

footers_replace_img_at_bkm(x, bookmark, value)

Arguments

Examples

library(officer)

doc <- read_docx()
doc <- body_add_par(doc, "a paragraph to replace", style = "centered")
doc <- body_bookmark(doc, "text_to_replace")
doc <- body_replace_text_at_bkm(doc, "text_to_replace", "new text")


# demo usage of bookmark and images ----
template <- system.file(package = "officer", "doc_examples/example.docx")

img.file <- file.path(R.home("doc"), "html", "logo.jpg")

doc <- read_docx(path = template)
doc <- headers_replace_img_at_bkm(
  x = doc,
  bookmark = "bmk_header",
  value = external_img(src = img.file, width = .53, height = .7)
)
doc <- footers_replace_img_at_bkm(
  x = doc,
  bookmark = "bmk_footer",
  value = external_img(src = img.file, width = .53, height = .7)
)
print(doc, target = tempfile(fileext = ".docx"))

Description

Define default section of the document. You can define section propeerties (page size, orientation, ...) with a prop_section object.

Usage

body_set_default_section(x, value)

Arguments

Illustrations

See Also

Other functions for Word sections: body_end_block_section(), body_end_section_columns(), body_end_section_columns_landscape(), body_end_section_continuous(), body_end_section_landscape(), body_end_section_portrait()

Examples

# Example 1: Setting page layout properties ----
# This example demonstrates how to configure the default section
# properties for page orientation, type, and margins

# Define custom section properties
# - Landscape orientation for wide tables
# - Continuous section (no page break)
# - Custom margins: top=1.5", bottom=0.75", left/right=2"
default_sect_properties <- prop_section(
  page_size = page_size(orient = "landscape"),
  type = "continuous",
  page_margins = page_mar(bottom = .75, top = 1.5, right = 2, left = 2)
)

# Create a new document
doc_1 <- read_docx()

# Add a wide table that benefits from landscape orientation
doc_1 <- body_add_par(doc_1, "Motor Trend Car Road Tests", style = "heading 1")
doc_1 <- body_add_table(doc_1, value = mtcars[1:10, ], style = "table_template")

# Add some text content
doc_1 <- body_add_par(doc_1, "Sample Text Content", style = "heading 2")
doc_1 <- body_add_par(doc_1, value = paste(rep(letters, 40), collapse = " "))

# Apply the section properties to the entire document
# This must be called at the end, after all content is added
doc_1 <- body_set_default_section(doc_1, default_sect_properties)

# Save the document
print(doc_1, target = tempfile(fileext = ".docx"))


# Example 2: Adding headers and footers ----
# This example shows how to create a document with:
# - A header containing the R logo
# - A footer with the current date and page numbers

# Get the path to R logo
img_path <- file.path(R.home("doc"), "html", "logo.jpg")

# Create header content with the R logo
# The logo is positioned on the right side with specific dimensions
header_content <- block_list(
  fpar(
    external_img(src = img_path, height = 0.5, width = 0.5),
    fp_p = fp_par(text.align = "right")
  )
)

# Create footer content with date and page numbers
# Format: "Document generated on: [Date] | Page [X]"
footer_content <- block_list(
  fpar(
    "Document generated on: ",
    run_word_field(field = "Date \\@ \"MMMM d, yyyy\""),
    " | Page ",
    run_word_field(field = "PAGE"),
    fp_p = fp_par(text.align = "center")
  )
)

# Define section properties that include header and footer
# The header and footer will appear on all pages
sect_with_hf <- prop_section(
  page_size = page_size(orient = "portrait", width = 8.3, height = 11.7),
  page_margins = page_mar(
    bottom = 1,
    top = 1,
    right = 1,
    left = 1,
    header = 0.5,
    footer = 0.5
  ),
  type = "continuous",
  header_default = header_content,
  footer_default = footer_content
)

# Create a new document with content
doc_2 <- read_docx()

# Add a title page
doc_2 <- body_add_par(doc_2, "Annual Report 2024", style = "heading 1")
doc_2 <- body_add_par(
  doc_2,
  "Company Performance Analysis",
  style = "heading 2"
)

# Add some sections with content
doc_2 <- body_add_par(doc_2, "Executive Summary", style = "heading 2")
doc_2 <- body_add_par(
  doc_2,
  "This report provides a comprehensive analysis of company performance metrics."
)

# Add a table
doc_2 <- body_add_par(doc_2, "Key Metrics", style = "heading 2")
summary_data <- data.frame(
  Metric = c("Revenue", "Profit", "Growth"),
  Q1 = c(1.2, 0.3, 12),
  Q2 = c(1.5, 0.4, 15),
  Q3 = c(1.8, 0.5, 18),
  Q4 = c(2.1, 0.6, 20)
)
doc_2 <- body_add_table(doc_2, value = summary_data, style = "table_template")

# Add a plot
doc_2 <- body_add_par(doc_2, "Revenue Trend", style = "heading 2")
revenue_plot <- plot_instr({
  quarters <- paste0("Q", 1:4)
  revenue <- c(1.2, 1.5, 1.8, 2.1)
  barplot(
    revenue,
    names.arg = quarters,
    col = "#4472C4",
    border = NA,
    main = "Quarterly Revenue (Millions)",
    ylab = "Revenue ($M)",
    xlab = "Quarter"
  )
})
doc_2 <- body_add_plot(doc_2, revenue_plot, width = 5, height = 4)

# Apply section properties with header and footer
# The header (with R logo) and footer (with date and page number)
# will appear on all pages
doc_2 <- body_set_default_section(doc_2, sect_with_hf)

# Save the document
output_file <- tempfile(fileext = ".docx")
print(doc_2, target = output_file)

Description

Replace styles with others in a 'Word' document. This function can be used for paragraph, run/character and table styles.

Usage

change_styles(x, mapstyles)

Arguments

Examples

# creating a sample docx so that we can illustrate how
# to change styles
doc_1 <- read_docx()

doc_1 <- body_add_par(doc_1, "A title", style = "heading 1")
doc_1 <- body_add_par(doc_1, "Another title", style = "heading 2")
doc_1 <- body_add_par(doc_1, "Hello world!", style = "Normal")
file <- print(doc_1, target = tempfile(fileext = ".docx"))

# now we can illustrate how
# to change styles with `change_styles`
doc_2 <- read_docx(path = file)
mapstyles <- list(
  "centered" = c("Normal", "heading 2"),
  "strong" = "Default Paragraph Font"
)
doc_2 <- change_styles(doc_2, mapstyles = mapstyles)
print(doc_2, target = tempfile(fileext = ".docx"))

Description

Get the color scheme of a 'PowerPoint' master layout into a data.frame.

Usage

color_scheme(x)

Arguments

See Also

Other functions for reading presentation information: annotate_base(), doc_properties(), layout_properties(), layout_summary(), length.rpptx(), plot_layout_properties(), slide_size(), slide_summary()

Examples

x <- read_pptx()
color_scheme ( x = x )

Description

A set of functions is available to manipulate the position of a virtual cursor. This cursor will be used when inserting, deleting or updating elements in the document.

Usage

cursor_begin(x)

cursor_bookmark(x, id)

cursor_end(x)

cursor_reach_index(x, index)

cursor_reach(x, keyword, fixed = FALSE)

cursor_reach_test(x, keyword)

cursor_forward(x)

cursor_backward(x)

Arguments

cursor_begin

Set the cursor at the beginning of the document, on the first element of the document (usually a paragraph or a table).

cursor_bookmark

Set the cursor at a bookmark that has previously been set.

cursor_end

Set the cursor at the end of the document, on the last element of the document.

cursor_reach_index

Set the cursor at a specific index position in the document.

cursor_reach

Set the cursor on the first element of the document that contains text specified in argument keyword. The argument keyword is a regexpr pattern.

cursor_reach_test

Test if an expression has a match in the document that contains text specified in argument keyword. The argument keyword is a regexpr pattern.

cursor_forward

Move the cursor forward, it increments the cursor in the document.

cursor_backward

Move the cursor backward, it decrements the cursor in the document.

Examples

library(officer)

# create a template ----
doc <- read_docx()
doc <- body_add_par(doc, "blah blah blah")
doc <- body_add_par(doc, "blah blah blah")
doc <- body_add_par(doc, "blah blah blah")
doc <- body_add_par(doc, "Hello text to replace")
doc <- body_add_par(doc, "blah blah blah")
doc <- body_add_par(doc, "blah blah blah")
doc <- body_add_par(doc, "blah blah blah")
doc <- body_add_par(doc, "Hello text to replace")
doc <- body_add_par(doc, "blah blah blah")
template_file <- print(
  x = doc,
  target = tempfile(fileext = ".docx")
)

# replace all pars containing "to replace" ----
doc <- read_docx(path = template_file)
while (cursor_reach_test(doc, "to replace")) {
  doc <- cursor_reach(doc, "to replace")

  doc <- body_add_fpar(
    x = doc,
    pos = "on",
    value = fpar(
      "Here is a link: ",
      hyperlink_ftext(
        text = "yopyop",
        href = "https://cran.r-project.org/"
      )
    )
  )
}

doc <- cursor_end(doc)
doc <- body_add_par(doc, "Yap yap yap yap...")

result_file <- print(
  x = doc,
  target = tempfile(fileext = ".docx")
)

# cursor_bookmark ----

doc <- read_docx()
doc <- body_add_par(doc, "centered text", style = "centered")
doc <- body_bookmark(doc, "text_to_replace")
doc <- body_add_par(doc, "A title", style = "heading 1")
doc <- body_add_par(doc, "Hello world!", style = "Normal")
doc <- cursor_bookmark(doc, "text_to_replace")
doc <- body_add_table(doc, value = iris, style = "table_template")

print(doc, target = tempfile(fileext = ".docx"))

Description

Read Word or PowerPoint document properties and get results in a data.frame.

Usage

doc_properties(x)

Arguments

Value

a data.frame

See Also

Other functions for Word document informations: docx_bookmarks(), docx_dim(), length.rdocx(), set_doc_properties(), styles_info()

Other functions for reading presentation information: annotate_base(), color_scheme(), layout_properties(), layout_summary(), length.rpptx(), plot_layout_properties(), slide_size(), slide_summary()

Examples

x <- read_docx()
doc_properties(x)

Description

List bookmarks id that can be found in a 'Word' document.

Usage

docx_bookmarks(x)

Arguments

See Also

Other functions for Word document informations: doc_properties(), docx_dim(), length.rdocx(), set_doc_properties(), styles_info()

Examples

library(officer)

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, "centered text", style = "centered")
doc_1 <- body_bookmark(doc_1, "text_to_replace_1")
doc_1 <- body_add_par(doc_1, "centered text", style = "centered")
doc_1 <- body_bookmark(doc_1, "text_to_replace_2")

docx_bookmarks(doc_1)

docx_bookmarks(read_docx())

Description

return a data.frame representing the comments in a Word document.

Usage

docx_comments(x)

Arguments

Details

Each row of the returned data frame contains data for one comment. The columns contain the following information:

• "comment_id" - unique comment id

• "author" - name of the comment author

• "initials" - initials of the comment author

• "date" - timestamp of the comment

• "text" - a list column of characters containing the comment text. Elements can be vectors of length > 1 if a comment contains multiple paragraphs, blocks or runs or of length 0 if the comment is empty.

• "para_id" - a list column of characters containing the parent paragraph IDs. Elememts can be vectors of length > 1 if a comment spans multiple paragraphs or of length 0 if the comment has no parent paragraph.

• "commented_text" - a list column of characters containing the commented text. Elements can be vectors of length > 1 if a comment spans multiple paragraphs or runs or of length 0 if the commented text is empty.

Examples

library(officer)

bl <- block_list(
  fpar("Comment multiple words."),
  fpar("Second line")
)

a_par <- fpar(
  "This paragraph contains",
  run_comment(
    cmt = bl,
    run = ftext("a comment."),
    author = "Author Me",
    date = "2023-06-01"
  )
)

doc <- read_docx()
doc <- body_add_fpar(doc, value = a_par, style = "Normal")

docx_file <- print(doc, target = tempfile(fileext = ".docx"))

docx_comments(read_docx(docx_file))

Description

Get page width, page height and margins (in inches). The return values are those corresponding to the section where the cursor is.

Usage

docx_dim(x)

Arguments

See Also

Other functions for Word document informations: doc_properties(), docx_bookmarks(), length.rdocx(), set_doc_properties(), styles_info()

Examples

docx_dim(read_docx())

Description

Copy TrueType or OpenType font files from the local system into a Word document. The font data is stored inside the .docx archive so that the document renders correctly when opened on a system where the font is not installed.

When only font_family is provided (without regular), the function looks up font file paths on the local system via gdtools::sys_fonts() and copies them into the document. A message shows the equivalent explicit call for reproducibility.

Usage

docx_embed_font(
  x,
  font_family,
  regular = NULL,
  bold = NULL,
  italic = NULL,
  bold_italic = NULL
)

Arguments

Value

the rdocx object with embedded fonts

Font licensing

Embedding a font in a document redistributes it. You must ensure that the font license permits embedding. Fonts under the SIL Open Font License (e.g. Liberation, Google Fonts) generally allow it. Many commercial fonts restrict or prohibit embedding. Check the license of the font before using this function.

See Also

gdtools::sys_fonts(), gdtools::register_gfont(), docx_set_settings()

Examples

# automatic detection (requires gdtools)
gdtools::register_liberationsans()
doc <- read_docx()
doc <- docx_embed_font(doc, font_family = "Liberation Sans")

# # explicit paths (no gdtools needed)
# doc <- docx_embed_font(
#   doc,
#   font_family = "My Font",
#   regular = "path/to/font-regular.ttf",
#   bold = "path/to/font-bold.ttf"
# )

Description

The function lets you add or modify Word character styles.

Usage

docx_set_character_style(
  x,
  style_id,
  style_name,
  base_on,
  fp_t = fp_text_lite()
)

Arguments

Examples

library(officer)
doc <- read_docx()

doc <- docx_set_character_style(
  doc,
  style_id = "newcharstyle",
  style_name = "label for char style",
  base_on = "Default Paragraph Font",
  fp_text_lite(
    shading.color = "red",
    color = "white")
)
paragraph <- fpar(
  run_wordtext("hello",
    style_id = "newcharstyle"))

doc <- body_add_fpar(doc, value = paragraph)
docx_file <- print(doc, target = tempfile(fileext = ".docx"))
docx_file

Description

The function lets you add or replace a Word paragraph style.

Usage

docx_set_paragraph_style(
  x,
  style_id,
  style_name,
  base_on = "Normal",
  fp_p = fp_par(),
  fp_t = NULL
)

Arguments

Examples

library(officer)

doc <- read_docx()

doc <- docx_set_paragraph_style(
  doc,
  style_id = "rightaligned",
  style_name = "Explicit label",
  fp_p = fp_par(text.align = "right", padding = 20),
  fp_t = fp_text_lite(
    bold = TRUE,
    shading.color = "#FD34F0",
    color = "white")
)

doc <- body_add_par(doc,
  value = "This is a test",
  style = "Explicit label")

docx_file <- print(doc, target = tempfile(fileext = ".docx"))
docx_file

Description

Set various settings of a 'Microsoft Word' document generated with 'officer'. Options include:

• zoom factor (default view in Word),

• default tab stop,

• hyphenation zone,

• decimal symbol,

• list separator (see details below),

• compatibility mode,

• even and odd headers management (see details below),

• and auto hyphenation activation.

Usage

docx_set_settings(
  x,
  zoom = 1,
  default_tab_stop = 0.5,
  hyphenation_zone = 0.25,
  decimal_symbol = ".",
  list_separator = ";",
  compatibility_mode = "15",
  even_and_odd_headers = FALSE,
  auto_hyphenation = FALSE,
  unit = "in"
)

Arguments

Details

• even_and_odd_headers: If TRUE, 'Microsoft Word' will use different headers for odd and even pages ("Different Odd & Even Pages" feature in Word). This is useful for professional documents or reports that require alternating page layouts.

• list_separator: Sets the character used by 'Microsoft Word' to separate items in lists (for example, when inserting tables or lists in Word). This parameter affects how 'Microsoft Word' handles data import/export (CSV, etc.) and can be adapted to language or local conventions (e.g., ";" for French, "," for English).

See Also

read_docx()

Examples

library(officer)

txt_lorem <- rep(
  "Purus lectus eros metus turpis mattis platea praesent sed. ",
  50
)
txt_lorem <- paste0(txt_lorem, collapse = "")

header_first <- block_list(fpar(ftext("text for first page header")))
header_even <- block_list(fpar(ftext("text for even page header")))
header_default <- block_list(fpar(ftext("text for default page header")))
footer_first <- block_list(fpar(ftext("text for first page footer")))
footer_even <- block_list(fpar(ftext("text for even page footer")))
footer_default <- block_list(fpar(ftext("text for default page footer")))

ps <- prop_section(
  header_default = header_default,
  footer_default = footer_default,
  header_first = header_first,
  footer_first = footer_first,
  header_even = header_even,
  footer_even = footer_even
)

x <- read_docx()

x <- docx_set_settings(
  x = x,
  zoom = 2,
  list_separator = ",",
  even_and_odd_headers = TRUE
)

for (i in 1:20) {
  x <- body_add_par(x, value = txt_lorem)
}
x <- body_set_default_section(
  x,
  value = ps
)
print(x, target = tempfile(fileext = ".docx"))

Description

Show the structure of text tags at the current cursor. This is most useful when trying to troubleshoot search-and-replace functionality using body_replace_all_text().

Usage

docx_show_chunk(x)

Arguments

See Also

body_replace_all_text()

Description

read content of a Word document and return a data.frame representing the document.

Usage

docx_summary(x, preserve = FALSE, remove_fields = FALSE, detailed = FALSE)

Arguments

Value

A data.frame with the following columns depending on the value of detailed:

When detailed = FALSE (default), the data.frame contains:

• doc_index: Document element index (integer).

• content_type: Type of content: "paragraph" or "table cell" (character).

• style_name: Name of the paragraph style (character).

• text: Collapsed text content of the paragraph or cell (character).

• table_index: Index of the table (integer). NA for non-table content.

• row_id: Row position in table (integer). NA for non-table content.

• cell_id: Cell position in table row (integer). NA for non-table content.

• is_header: Whether the row is a table header (logical). NA for non-table content.

• row_span: Number of rows spanned by the cell (integer). 0 for merged cells. NA for non-table content.

• col_span: Number of columns spanned by the cell (character). NA for non-table content.

• table_stylename: Name of the table style (character). NA for non-table content.

When detailed = TRUE, the data.frame contains additional run-level information:

• run_index: Index of the run within the paragraph (integer).

• run_content_index: Index of content element within the run (integer).

• run_content_text: Text content of the run element (character).

• image_path: Path to embedded image stored in the temporary directory associated with the rdocx object (character). Images should be copied to a permanent location before closing the R session if needed.

• field_code: Field code content (character).

• footnote_text: Footnote text content (character).

• link: Hyperlink URL (character).

• link_to_bookmark: Internal bookmark anchor name for hyperlinks (character).

• bookmark_start: Names of the bookmarks starting on this paragraph (values are concatenated with '|').

• character_stylename: Name of the character/run style (character).

• sz: Font size in half-points (integer).

• sz_cs: Complex script font size in half-points (integer).

• font_family_ascii: Font family for ASCII characters (character).

• font_family_eastasia: Font family for East Asian characters (character).

• font_family_hansi: Font family for high ANSI characters (character).

• font_family_cs: Font family for complex script characters (character).

• bold: Whether the run is bold (logical).

• italic: Whether the run is italic (logical).

• underline: Whether the run is underlined (logical).

• color: Text color in hexadecimal format (character).

• shading: Shading pattern (character).

• shading_color: Shading foreground color (character).

• shading_fill: Shading background fill color (character).

• keep_with_next: Whether paragraph should stay with next (logical).

• align: Paragraph alignment (character).

• level: Numbering level (integer). NA if not a numbered list.

• num_id: Numbering definition ID (integer). NA if not a numbered list.

Note

Documents included with body_add_docx() will not be accessible in the results.

Examples

library(officer)

example_docx <- system.file(
  package = "officer",
  "doc_examples/example.docx"
)
doc <- read_docx(example_docx)

docx_summary(doc)

docx_summary(doc, detailed = TRUE)

Description

Create an empty object to include as an empty placeholder shape in a presentation. This comes in handy when presentation are updated through R, but a user still wants to add some comments in this new content.

Empty content also works with layout fields (slide number and date) to preserve them: they are included on the slide and keep being updated by PowerPoint, i.e. update to the when the slide number when the slide moves in the deck, update to the date.

Usage

empty_content()

See Also

ph_with(), body_add_blocks()

Examples

fileout <- tempfile(fileext = ".pptx")
doc <- read_pptx()
doc <- add_slide(doc, layout = "Two Content",
  master = "Office Theme")
doc <- ph_with(x = doc, value = empty_content(),
 location = ph_location_type(type = "title") )

doc <- add_slide(doc, "Title and Content")
# add slide number as a computer field
doc <- ph_with(
  x = doc, value = empty_content(),
  location = ph_location_type(type = "sldNum"))

print(doc, target = fileout )

Description

Wraps an image in an object that can then be embedded in a PowerPoint slide or within a Word paragraph.

The image is added as a shape in PowerPoint (it is not possible to mix text and images in a PowerPoint form). With a Word document, the image will be added inside a paragraph.

Usage

external_img(
  src,
  width = 0.5,
  height = 0.2,
  unit = "in",
  guess_size = FALSE,
  alt = ""
)

Arguments

usage

You can use this function in conjunction with fpar to create paragraphs consisting of differently formatted text parts. You can also use this function as an r chunk in an R Markdown document made with package officedown.

See Also

ph_with, body_add, fpar

Other run functions for reporting: floating_external_img(), ftext(), hyperlink_ftext(), run_autonum(), run_bookmark(), run_columnbreak(), run_comment(), run_footnote(), run_footnoteref(), run_linebreak(), run_pagebreak(), run_reference(), run_tab(), run_word_field(), run_wordtext()

Examples

# wrap r logo with external_img ----
srcfile <- file.path(R.home("doc"), "html", "logo.jpg")
extimg <- external_img(
  src = srcfile, height = 1.06 / 2,
  width = 1.39 / 2
)

# pptx example ----
doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(
  x = doc, value = extimg,
  location = ph_location_type(type = "body"),
  use_loc_size = FALSE
)
print(doc, target = tempfile(fileext = ".pptx"))

fp_t <- fp_text(font.size = 20, color = "red")
an_fpar <- fpar(extimg, ftext(" is cool!", fp_t))

# docx example ----
x <- read_docx()
x <- body_add(x, an_fpar)
print(x, target = tempfile(fileext = ".docx"))

Description

Wraps an image in an object that can be embedded as a floating image in a 'Word' document. Unlike external_img(), which creates inline images, this function creates floating images that can be positioned anywhere on the page and allow text wrapping around them.

Usage

floating_external_img(
  src,
  width = 0.5,
  height = 0.2,
  pos_x = 0,
  pos_y = 0,
  pos_h_from = "margin",
  pos_v_from = "margin",
  wrap_type = "square",
  wrap_side = "bothSides",
  wrap_dist_top = 0,
  wrap_dist_bottom = 0,
  wrap_dist_left = 0.125,
  wrap_dist_right = 0.125,
  unit = "in",
  guess_size = FALSE,
  alt = ""
)

Arguments

usage

You can use this function in conjunction with fpar to create paragraphs consisting of differently formatted text parts. You can also use this function as an r chunk in an R Markdown document made with package officedown.

See Also

external_img, body_add, fpar, rtf_doc, rtf_add

Other run functions for reporting: external_img(), ftext(), hyperlink_ftext(), run_autonum(), run_bookmark(), run_columnbreak(), run_comment(), run_footnote(), run_footnoteref(), run_linebreak(), run_pagebreak(), run_reference(), run_tab(), run_word_field(), run_wordtext()

Examples

library(officer)
srcfile <- file.path(R.home("doc"), "html", "logo.jpg")
floatimg <- floating_external_img(
  src = srcfile, height = 1.06 / 2, width = 1.39 / 2,
  pos_x = 0, pos_y = 0,
  pos_h_from = "margin", pos_v_from = "margin"
)

text <- paste0(
  " is a floating image in a ",
  paste0(rep("very ", 30), collapse = ""),
  " long text!"
)

# docx example ----
x <- read_docx()
fp_t <- fp_text(font.size = 20, color = "red")
an_fpar <- fpar(floatimg, ftext(text, fp_t))
x <- body_add_fpar(x, an_fpar)
print(x, target = tempfile(fileext = ".docx"))

# rtf example ----
rtf_doc <- rtf_doc()
rtf_doc <- rtf_add(rtf_doc, an_fpar)
print(rtf_doc, target = tempfile(fileext = ".rtf"))

Description

create a border properties object.

Usage

fp_border(color = "black", style = "solid", width = 1)

## S3 method for class 'fp_border'
update(object, color, style, width, ...)

Arguments

Details

For Word output the following border styles are supported:

• "none" or "nil" - No Border

• "solid" or "single" - Single Line Border

• "thick" - Single Line Border

• "double" - Double Line Border

• "dotted" - Dotted Line Border

• "dashed" - Dashed Line Border

• "dotDash" - Dot Dash Line Border

• "dotDotDash" - Dot Dot Dash Line Border

• "triple" - Triple Line Border

• "thinThickSmallGap" - Thin, Thick Line Border

• "thickThinSmallGap" - Thick, Thin Line Border

• "thinThickThinSmallGap" - Thin, Thick, Thin Line Border

• "thinThickMediumGap" - Thin, Thick Line Border

• "thickThinMediumGap" - Thick, Thin Line Border

• "thinThickThinMediumGap" - Thin, Thick, Thin Line Border

• "thinThickLargeGap" - Thin, Thick Line Border

• "thickThinLargeGap" - Thick, Thin Line Border

• "thinThickThinLargeGap" - Thin, Thick, Thin Line Border

• "wave" - Wavy Line Border

• "doubleWave" - Double Wave Line Border

• "dashSmallGap" - Dashed Line Border

• "dashDotStroked" - Dash Dot Strokes Line Border

• "threeDEmboss" or "ridge" - 3D Embossed Line Border

• "threeDEngrave" or "groove" - 3D Engraved Line Border

• "outset" - Outset Line Border

• "inset" - Inset Line Border

For HTML output only a limited amount of border styles are supported:

• "none" or "nil" - No Border

• "solid" or "single" - Single Line Border

• "double" - Double Line Border

• "dotted" - Dotted Line Border

• "dashed" - Dashed Line Border

• "threeDEmboss" or "ridge" - 3D Embossed Line Border

• "threeDEngrave" or "groove" - 3D Engraved Line Border

• "outset" - Outset Line Border

• "inset" - Inset Line Border

Non-supported Word border styles will default to "solid".

See Also

Other functions for defining formatting properties: fp_cell(), fp_par(), fp_tab(), fp_tabs(), fp_text()

Examples

fp_border()
fp_border(color = "orange", style = "solid", width = 1)
fp_border(color = "gray", style = "dotted", width = 1)

# modify object ------
border <- fp_border()
update(border, style = "dotted", width = 3)

Description

Create a fp_cell object that describes cell formatting properties.

Usage

fp_cell(
  border = fp_border(width = 0),
  border.bottom,
  border.left,
  border.top,
  border.right,
  vertical.align = "center",
  margin = 0,
  margin.bottom,
  margin.top,
  margin.left,
  margin.right,
  background.color = "transparent",
  text.direction = "lrtb",
  rowspan = 1,
  colspan = 1
)

## S3 method for class 'fp_cell'
format(x, type = "wml", ...)

## S3 method for class 'fp_cell'
print(x, ...)

## S3 method for class 'fp_cell'
update(
  object,
  border,
  border.bottom,
  border.left,
  border.top,
  border.right,
  vertical.align,
  margin = 0,
  margin.bottom,
  margin.top,
  margin.left,
  margin.right,
  background.color,
  text.direction,
  rowspan = 1,
  colspan = 1,
  ...
)

Arguments

See Also

Other functions for defining formatting properties: fp_border(), fp_par(), fp_tab(), fp_tabs(), fp_text()