Type:	Package
Title:	Manipulation of Microsoft Word and PowerPoint Documents
Version:	0.6.10
Description:	Access and manipulate 'Microsoft Word', 'RTF' and 'Microsoft PowerPoint' documents from R. The package focuses on tabular and graphical reporting from R; it also provides two functions that let users get document content into data objects. A set of functions lets add and remove images, tables and paragraphs of text in new or existing documents. The package does not require any installation of Microsoft products to be able to write Microsoft files.
License:	MIT + file LICENSE
URL:	https://ardata-fr.github.io/officeverse/, https://davidgohel.github.io/officer/
BugReports:	https://github.com/davidgohel/officer/issues
Imports:	cli, graphics, grDevices, openssl, R6, ragg, stats, utils, uuid, xml2 (≥ 1.1.0), zip (≥ 2.1.0)
Suggests:	devEMF, doconv (≥ 0.3.0), gdtools, ggplot2, knitr, magick, rmarkdown, rsvg, testthat, withr
Encoding:	UTF-8
RoxygenNote:	7.3.2
Collate:	'core_properties.R' 'custom_properties.R' 'defunct.R' 'dev-utils.R' 'docx_add.R' 'docx_comments.R' 'docx_cursor.R' 'docx_part.R' 'docx_replace.R' 'docx_section.R' 'docx_settings.R' 'empty_content.R' 'formatting_properties.R' 'fortify_docx.R' 'fortify_pptx.R' 'knitr_utils.R' 'officer.R' 'ooxml.R' 'ooxml_block_objects.R' 'ooxml_run_objects.R' 'openxml_content_type.R' 'openxml_document.R' 'pack_folder.R' 'ph_location.R' 'post-proc.R' 'ppt_class_dir_collection.R' 'ppt_classes.R' 'ppt_notes.R' 'ppt_ph_dedupe_layout.R' 'ppt_ph_manipulate.R' 'ppt_ph_rename_layout.R' 'ppt_ph_with_methods.R' 'pptx_informations.R' 'pptx_layout_helper.R' 'pptx_matrix.R' 'utils.R' 'pptx_slide_manip.R' 'read_docx.R' 'read_docx_styles.R' 'read_pptx.R' 'read_xlsx.R' 'relationship.R' 'rtf.R' 'shape_properties.R' 'shorcuts.R' 'docx_append_context.R' 'utils-xml.R' 'deprecated.R'
NeedsCompilation:	no
Packaged:	2025-05-30 09:30:12 UTC; davidgohel
Author:	David Gohel [aut, cre], Stefan Moog [aut], Mark Heckmann [aut], ArData [cph], Frank Hangler [ctb] (function body_replace_all_text), Liz Sander [ctb] (several documentation fixes), Anton Victorson [ctb] (fixes xml structures), Jon Calder [ctb] (update vignettes), John Harrold [ctb] (function annotate_base), John Muschelli [ctb] (google doc compatibility), Bill Denney [ctb] (function as.matrix.rpptx), Nikolai Beck [ctb] (set speaker notes for .pptx documents), Greg Leleu [ctb] (fields functionality in ppt), Majid Eismann [ctb], Hongyuan Jia [ctb], Michael Stackhouse [ctb]
Maintainer:	David Gohel <david.gohel@ardata.fr>
Repository:	CRAN
Date/Publication:	2025-05-30 10:30:02 UTC

Manipulate Microsoft Word and PowerPoint Documents with 'officer'

Description

The officer package facilitates access to and manipulation of 'Microsoft Word' and 'Microsoft PowerPoint' documents from R. It also supports the writing of 'RTF' documents.

Examples of usage are:

• Create Word documents with tables, titles, TOC and graphics

• Importation of Word and PowerPoint files into data objects

• Write updated content back to a PowerPoint presentation

• Clinical reporting automation

• Production of reports from a shiny application

To start with officer, read about read_docx(), read_pptx() or rtf_doc().

The package is also providing several objects that can be printed in 'R Markdown' documents for advanced Word or PowerPoint reporting as run_autonum() and block_caption().

Author(s)

Maintainer: David Gohel david.gohel@ardata.fr

Authors:

• Stefan Moog moogs@gmx.de

• Mark Heckmann heckmann.mark@gmail.com (ORCID)

Other contributors:

• ArData [copyright holder]

• Frank Hangler frank@plotandscatter.com (function body_replace_all_text) [contributor]

• Liz Sander lsander@civisanalytics.com (several documentation fixes) [contributor]

• Anton Victorson anton@victorson.se (fixes xml structures) [contributor]

• Jon Calder jonmcalder@gmail.com (update vignettes) [contributor]

• John Harrold john.m.harrold@gmail.com (function annotate_base) [contributor]

• John Muschelli muschellij2@gmail.com (google doc compatibility) [contributor]

• Bill Denney wdenney@humanpredictions.com (ORCID) (function as.matrix.rpptx) [contributor]

• Nikolai Beck beck.nikolai@gmail.com (set speaker notes for .pptx documents) [contributor]

• Greg Leleu gregoire.leleu@gmail.com (fields functionality in ppt) [contributor]

• Majid Eismann [contributor]

• Hongyuan Jia hongyuanjia@cqust.edu.cn (ORCID) [contributor]

• Michael Stackhouse mike.stackhouse@atorusresearch.com [contributor]

See Also

The user documentation: https://ardata-fr.github.io/officeverse/ and manuals https://davidgohel.github.io/officer/

Add a sheet

Description

Add a sheet into an xlsx worksheet.

Usage

add_sheet(x, label)

Arguments

Examples

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

Add a slide

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"
)

Placeholder parameters annotation

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')

PowerPoint table to matrix

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)

Caption block

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_pour_docx(), block_section(), block_table(), block_toc(), fpar(), 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"))

'ggplot' block

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_pour_docx(), block_section(), block_table(), block_toc(), fpar(), 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"))
}

List of blocks

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_pour_docx(), block_section(), block_table(), block_toc(), fpar(), 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"))

External Word document placeholder

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_section(), block_table(), block_toc(), fpar(), 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)

Section for 'Word'

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_pour_docx(), block_table(), block_toc(), fpar(), 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)

Table block

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_pour_docx(), block_section(), block_toc(), fpar(), 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)
  ))

Table of content for 'Word'

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_pour_docx(), block_section(), block_table(), fpar(), plot_instr(), unordered_list()

Examples

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

Add content into a Word document

Description

This function add objects into a Word document. Values are added as new paragraphs or tables.

This function is experimental and will replace the ⁠body_add_*⁠ functions later. For now it is only to be used for successive additions and cannot be used in conjunction with the ⁠body_add_*⁠ functions.

Usage

body_add(x, value, ...)

## S3 method for class 'character'
body_add(x, value, style = NULL, ...)

## S3 method for class 'numeric'
body_add(x, value, style = NULL, format_fun = formatC, ...)

## S3 method for class 'factor'
body_add(x, value, style = NULL, format_fun = as.character, ...)

## S3 method for class 'fpar'
body_add(x, value, style = NULL, ...)

## S3 method for class 'data.frame'
body_add(
  x,
  value,
  style = NULL,
  header = TRUE,
  tcf = table_conditional_formatting(),
  alignment = NULL,
  ...
)

## S3 method for class 'block_caption'
body_add(x, value, ...)

## S3 method for class 'block_list'
body_add(x, value, ...)

## S3 method for class 'block_toc'
body_add(x, value, ...)

## S3 method for class 'external_img'
body_add(x, value, style = "Normal", ...)

## S3 method for class 'run_pagebreak'
body_add(x, value, style = NULL, ...)

## S3 method for class 'run_columnbreak'
body_add(x, value, style = NULL, ...)

## S3 method for class 'gg'
body_add(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  style = "Normal",
  scale = 1,
  unit = "in",
  ...
)

## S3 method for class 'plot_instr'
body_add(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  style = "Normal",
  unit = "in",
  ...
)

## S3 method for class 'block_pour_docx'
body_add(x, value, ...)

## S3 method for class 'block_section'
body_add(x, value, ...)

Arguments

Methods (by class)

• body_add(character): add a character vector.

• body_add(numeric): add a numeric vector.

• body_add(factor): add a factor vector.

• body_add(fpar): add a fpar object. These objects enable the creation of formatted paragraphs made of formatted chunks of text.

• body_add(data.frame): add a data.frame object with block_table().

• body_add(block_caption): add a block_caption object. These objects enable the creation of set of formatted paragraphs made of formatted chunks of text.

• body_add(block_list): add a block_list object. Use this function to add a list of block elements (e.g. paragraphs, images, tables) into a Word document in a more efficient way than with usual ⁠body_add_*⁠ functions. This function will add several elements in a faster way because the cursor is not calculated for each iteraction over the elements, as a consequence the function only append elements at the end of the document and does not allow to insert elements at a specific position.

• body_add(block_toc): add a table of content (a block_toc object).

• body_add(external_img): add an image (a external_img object).

• body_add(run_pagebreak): add a run_pagebreak object.

• body_add(run_columnbreak): add a run_columnbreak object.

• body_add(gg): add a ggplot object.

• body_add(plot_instr): add a base plot with a plot_instr object.

• body_add(block_pour_docx): pour content of an external docx file with with a block_pour_docx object

• body_add(block_section): ends a section with a block_section object

Illustrations

Examples

doc_1 <- read_docx()
doc_1 <- body_add(doc_1, "Table of content", style = "heading 1")
doc_1 <- body_add(doc_1, block_toc())
doc_1 <- body_add(doc_1, run_pagebreak())
doc_1 <- body_add(doc_1, "A title", style = "heading 1")
doc_1 <- body_add(doc_1, head(iris), style = "table_template")
doc_1 <- body_add(doc_1, "Another title", style = "heading 1")
doc_1 <- body_add(doc_1, letters, style = "Normal")
doc_1 <- body_add(
  doc_1,
  block_section(prop_section(type = "continuous"))
)
doc_1 <- body_add(doc_1, plot_instr(code = barplot(1:5, col = 2:6)))
doc_1 <- body_add(
  doc_1,
  block_section(prop_section(page_size = page_size(orient = "landscape")))
)
print(doc_1, target = tempfile(fileext = ".docx"))
# print(doc_1, target = "test.docx")

Add a list of blocks into a 'Word' document

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_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

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"))

Add a page break in a 'Word' document

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_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

Examples

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

Add Word caption in a 'Word' document

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_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

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"))

Add an external docx in a 'Word' document

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.

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_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

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)

Add fpar in a 'Word' document

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_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

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"))

Add a 'ggplot' in a 'Word' document

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_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

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"))
}

Add an image in a 'Word' document

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_par(), body_add_plot(), body_add_table(), body_add_toc(), body_append_start_context()

Examples

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"))

Add paragraphs of text in a 'Word' document

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_plot(), body_add_table(), body_add_toc(), body_append_start_context()

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"))

Add plot in a 'Word' document

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_par(), body_add_table(), body_add_toc(), body_append_start_context()

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"))

Add table in a 'Word' document

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_par(), body_add_plot(), body_add_toc(), body_append_start_context()

Examples

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

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

Add table of content in a 'Word' document

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_par(), body_add_plot(), body_add_table(), body_append_start_context()

Examples

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

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

Add an xml string as document element

Description

Add an xml string as document element in the document. This function is to be used to add custom openxml code.

Usage

body_add_xml(x, str, pos = c("after", "before", "on"))

Arguments

Fast Append context to a Word document

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)

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_par(), body_add_plot(), body_add_table(), body_add_toc()

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"))

Add bookmark in a 'Word' document

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")

Add comment in a 'Word' document

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))

Add any section

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

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"))

Add multi columns section

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"))

Add a landscape multi columns section

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"))

Add continuous section

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"))

Add landscape section

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"))

Add portrait section

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"))

Remove an element in a 'Word' document

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"))

Replace text anywhere in the document

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, frank@plotandscatter.com

See Also

grepl(), regex(), docx_show_chunk()

Examples

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'

Add plots at bookmark location in a 'Word' document

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

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"))

Replace text at a bookmark location

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

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"))

Define Default Section

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

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)
)

doc_1 <- read_docx()
doc_1 <- body_add_table(doc_1, value = mtcars[1:10, ], style = "table_template")
doc_1 <- body_add_par(doc_1, value = paste(rep(letters, 40), collapse = " "))
doc_1 <- body_set_default_section(doc_1, default_sect_properties)

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

Replace styles in a 'Word' Document

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"))

Color scheme of a PowerPoint file

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 )

Set cursor in a 'Word' document

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(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

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"))

Read document properties

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)

Body xml document

Description

Get the body document as xml. This function is not to be used by end users, it has been implemented to allow other packages to work with officer.

Usage

docx_body_relationship(x)

Arguments

Examples

doc <- read_docx()
docx_body_relationship(doc)

Body xml document

Description

Get the body document as xml. This function is not to be used by end users, it has been implemented to allow other packages to work with officer.

Usage

docx_body_xml(x)

Arguments

Examples

doc <- read_docx()
docx_body_xml(doc)

List Word bookmarks

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())

Get comments in a Word document as a data.frame

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. Elememts 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

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))

xml element on which cursor is

Description

Get the current block element as xml. This function is not to be used by end users, it has been implemented to allow other packages to work with officer. If the document is empty, this block will be set to NULL.

Usage

docx_current_block_xml(x)

Arguments

Examples

doc <- read_docx()
docx_current_block_xml(doc)

'Word' page layout

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())

add images into an rdocx object

Description

reference images into a Word document. This function is now useless as the processing of images is automated when using print.rdocx().

Usage

docx_reference_img(x, src)

Arguments

See Also

Other functions for officer extensions: fortify_location(), get_reference_value(), opts_current_table(), shape_properties_tags(), str_encode_to_rtf(), to_html(), to_pml(), to_rtf(), to_wml(), wml_link_images()

Add character style in a Word document

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

Add or replace paragraph style in a Word document

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

Show underlying text tag structure

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()

Examples

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'

Get Word content in a data.frame

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

Note

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

Examples

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

docx_summary(doc)

docx_summary(doc, preserve = TRUE)[28, ]

Empty block for 'PowerPoint'

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 )

External image

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: 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"))

Eval a location on the current slide

Description

Eval a shape location against the current slide. This function is to be used to add custom openxml code. A list is returned, it contains informations width, height, left and top positions and other informations necessary to add a content on a slide.

Usage

fortify_location(x, doc, ...)

Arguments

See Also

ph_location(), ph_with()

Other functions for officer extensions: docx_reference_img(), get_reference_value(), opts_current_table(), shape_properties_tags(), str_encode_to_rtf(), to_html(), to_pml(), to_rtf(), to_wml(), wml_link_images()

Examples

doc <- read_pptx()
doc <- add_slide(doc,
  layout = "Title and Content",
  master = "Office Theme"
)
fortify_location(ph_location_fullsize(), doc)

Border properties object

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)

Cell formatting properties

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()

Examples

obj <- fp_cell(margin = 1)
update(obj, margin.bottom = 5)

Paragraph formatting properties

Description

Create a fp_par object that describes paragraph formatting properties.

Function fp_par_lite() is generating properties with only entries for the parameters users provided. The undefined properties will inherit from the default settings.

Usage

fp_par(
  text.align = "left",
  padding = 0,
  line_spacing = 1,
  border = fp_border(width = 0),
  padding.bottom,
  padding.top,
  padding.left,
  padding.right,
  border.bottom,
  border.left,
  border.top,
  border.right,
  shading.color = "transparent",
  keep_with_next = FALSE,
  tabs = NULL,
  word_style = "Normal"
)

fp_par_lite(
  text.align = NA,
  padding = NA,
  line_spacing = NA,
  border = FALSE,
  padding.bottom = NA,
  padding.top = NA,
  padding.left = NA,
  padding.right = NA,
  border.bottom = FALSE,
  border.left = FALSE,
  border.top = FALSE,
  border.right = FALSE,
  shading.color = NA,
  keep_with_next = NA,
  tabs = FALSE,
  word_style = NA
)

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

## S3 method for class 'fp_par'
update(
  object,
  text.align,
  padding,
  border,
  padding.bottom,
  padding.top,
  padding.left,
  padding.right,
  border.bottom,
  border.left,
  border.top,
  border.right,
  shading.color,
  keep_with_next,
  word_style,
  ...
)

Arguments

Value

a fp_par object

See Also

fpar

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

Examples

fp_par(text.align = "center", padding = 5)
obj <- fp_par(text.align = "center", padding = 1)
update(obj, padding.bottom = 5)

Tabulation mark properties object

Description

create a tabulation mark properties setting object for Word or RTF. Results can be used as arguments of fp_tabs().

Once tabulation marks settings are defined, tabulation marks can be added with run_tab() inside a call to fpar() or with ⁠\t⁠ within 'flextable' content.

Usage

fp_tab(pos, style = "decimal")

Arguments

See Also

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

Examples

fp_tab(pos = 0.4, style = "decimal")
fp_tab(pos = 1, style = "right")

Tabs properties object

Description

create a set of tabulation mark properties object for Word or RTF. Results can be used as arguments tabs of fp_par() and will only have effects in Word or RTF outputs.

Once a set of tabulation marks settings is defined, tabulation marks can be added with run_tab() inside a call to fpar() or with ⁠\t⁠ within 'flextable' content.

Usage

fp_tabs(...)

Arguments

See Also

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

Examples

z <- fp_tabs(
  fp_tab(pos = 0.4, style = "decimal"),
  fp_tab(pos = 1, style = "decimal")
)
fpar(
  run_tab(), ftext("88."),
  run_tab(), ftext("987.45"),
  fp_p = fp_par(
    tabs = z
  )
)

Text formatting properties

Description

Create an fp_text object that describes text formatting properties.

Function fp_text_lite() is generating properties with only entries for the parameters users provided. The undefined properties will inherit from the default settings.

Usage

fp_text(
  color = "black",
  font.size = 10,
  bold = FALSE,
  italic = FALSE,
  underlined = FALSE,
  font.family = "Arial",
  cs.family = NULL,
  eastasia.family = NULL,
  hansi.family = NULL,
  vertical.align = "baseline",
  shading.color = "transparent"
)

fp_text_lite(
  color = NA,
  font.size = NA,
  font.family = NA,
  cs.family = NA,
  eastasia.family = NA,
  hansi.family = NA,
  bold = NA,
  italic = NA,
  underlined = NA,
  vertical.align = "baseline",
  shading.color = NA
)

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

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

## S3 method for class 'fp_text'
update(
  object,
  color,
  font.size,
  bold,
  italic,
  underlined,
  font.family,
  cs.family,
  eastasia.family,
  hansi.family,
  vertical.align,
  shading.color,
  ...
)

Arguments

Value

a fp_text object

See Also

ftext(), fpar()

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

Examples

fp_text()
fp_text(color = "red")
fp_text(bold = TRUE, shading.color = "yellow")
print(fp_text(color = "red", font.size = 12))

Formatted paragraph

Description

Create a paragraph representation by concatenating formatted text or images. The result can be inserted in a Word document or a PowerPoint presentation and can also be inserted in a block_list() call.

All its arguments will be concatenated to create a paragraph where chunks of text and images are associated with formatting properties.

fpar() supports ftext(), external_img(), ⁠run_*()⁠ functions (i.e. run_autonum(), run_word_field()) when output is Word, and simple strings.

Default text and paragraph formatting properties can also be modified with function update().

Usage

fpar(..., fp_p = fp_par(), fp_t = fp_text_lite(), values = NULL)

## S3 method for class 'fpar'
update(object, fp_p = NULL, fp_t = NULL, ...)

Arguments

See Also

block_list(), body_add_fpar(), ph_with()

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

Examples

fpar(ftext("hello", shortcuts$fp_bold()))

# mix text and image -----
img.file <- file.path( R.home("doc"), "html", "logo.jpg" )

bold_face <- shortcuts$fp_bold(font.size = 12)
bold_redface <- update(bold_face, color = "red")
fpar_1 <- fpar(
  "Hello World, ",
  ftext("how ", prop = bold_redface ),
  external_img(src = img.file, height = 1.06/2, width = 1.39/2),
  ftext(" you?", prop = bold_face ) )
fpar_1

img_in_par <- fpar(
  external_img(src = img.file, height = 1.06/2, width = 1.39/2),
  fp_p = fp_par(text.align = "center") )

Formatted chunk of text

Description

Format a chunk of text with text formatting properties (bold, color, ...). The function allows you to create pieces of text formatted the way you want.

Usage

ftext(text, prop = NULL)

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

fp_text

Other run functions for reporting: external_img(), 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

ftext("hello", fp_text())

properties1 <- fp_text(color = "red")
properties2 <- fp_text(bold = TRUE, shading.color = "yellow")
ftext1 <- ftext("hello", properties1)
ftext2 <- ftext("World", properties2)
paragraph <- fpar(ftext1, " ", ftext2)

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

Layout selection helper

Description

Select a layout by name or index. The master name is inferred and only required for disambiguation in case the layout name is not unique across masters.

Usage

get_layout(
  x,
  layout = NULL,
  master = NULL,
  layout_by_id = TRUE,
  get_first = FALSE
)

Arguments

Value

A ⁠<layout_info>⁠ object, i.e. a list with the entries index, layout_name, layout_file, master_name, master_file, and slide_layout.

Get the document being used as a template

Description

Get filename of the document being used as a template in an R Markdown document rendered as HTML, PowerPoint presentation or Word document. It requires packages rmarkdown >= 1.10.14 and knitr.

Usage

get_reference_value(format = NULL)

Arguments

Value

a name file

See Also

Other functions for officer extensions: docx_reference_img(), fortify_location(), opts_current_table(), shape_properties_tags(), str_encode_to_rtf(), to_html(), to_pml(), to_rtf(), to_wml(), wml_link_images()

Formatted chunk of text with hyperlink

Description

Format a chunk of text with text formatting properties (bold, color, ...), the chunk is associated with an hyperlink.

Usage

hyperlink_ftext(text, prop = NULL, href)

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

Other run functions for reporting: external_img(), 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

ft <- fp_text(font.size = 12, bold = TRUE)
hyperlink_ftext(
  href = "https://cran.r-project.org/index.html",
  text = "some text", prop = ft
)

Images to base64

Description

encodes images into base64 strings.

Usage

image_to_base64(filepaths)

Arguments

Examples

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

Detect and handle duplicate placeholder labels

Description

PowerPoint does not enforce unique placeholder labels in a layout. Selecting a placeholder via its label using ph_location_label will throw an error, if the label is not unique. layout_dedupe_ph_labels helps to detect, rename, or delete duplicate placholder labels.

Usage

layout_dedupe_ph_labels(x, action = "detect", print_info = FALSE)

Arguments

Value

A rpptx object (with modified placeholder labels).

Examples

x <- read_pptx()
layout_dedupe_ph_labels(x)

file <- system.file("doc_examples", "ph_dupes.pptx", package = "officer")
x <- read_pptx(file)
layout_dedupe_ph_labels(x)
layout_dedupe_ph_labels(x, "rename", print_info = TRUE)

Default layout for new slides

Description

Set or remove the default layout used when calling add_slide().

Usage

layout_default(x, layout = NULL, master = NULL, as_list = FALSE)

Arguments

Value

The rpptx object.

See Also

add_slide()

Examples

# set and remove the default layout
x <- read_pptx()
layout_default(x) # no defaults
x <- layout_default(x, "Title and Content") # set default
layout_default(x)
x <- add_slide(x) # new slide with default layout
x <- layout_default(x, NULL) # remove default
layout_default(x) # no defaults

# use when repeatedly adding slides with same layout
x <- read_pptx()
x <- layout_default(x, "Title and Content")
x <- add_slide(x, title = "1. Slide", body = "Some content")
x <- add_slide(x, title = "2. Slide", body = "Some more content")
x <- add_slide(x, title = "3. Slide", body = "Even more content")

Slide layout properties

Description

Detailed information about the placeholders on the slide layouts (label, position, etc.). See Value section below for more info.

Usage

layout_properties(x, layout = NULL, master = NULL)

Arguments

Value

Returns a data frame with one row per placeholder and the following columns:

• master_name: Name of master (a .pptx file may have more than one)

• name: Name of layout

• type: Placeholder type

• type_idx: Running index for phs of the same type. Ordering by ph position (top -> bottom, left -> right)

• id: A unique placeholder id (assigned by PowerPoint automatically, starts at 2, potentially non-consecutive)

• ph_label: Placeholder label (can be set by the user in PowerPoint)

• ph: Placholder XML fragment (usually not needed)

• offx,offy: placeholder's distance from left and top edge (in inch)

• cx,cy: width and height of placeholder (in inch)

• rotation: rotation in degrees

• fld_id is generally stored as a hexadecimal or GUID value

• fld_type: a unique identifier for a particular field

See Also

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

Examples

x <- read_pptx()
layout_properties(x = x, layout = "Title Slide", master = "Office Theme")
layout_properties(x = x, master = "Office Theme")
layout_properties(x = x, layout = "Two Content")
layout_properties(x = x)

Change ph labels in a layout

Description

There are two versions of the function. The first takes a set of key-value pairs to rename the ph labels. The second uses a right hand side (rhs) assignment to specify the new ph labels. See section Details.

NB: You can also rename ph labels directly in PowerPoint. Open the master template view (Alt + F10) and go to Home > Arrange > ⁠Selection Pane⁠.

Usage

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

layout_rename_ph_labels(x, layout, master = NULL, id = NULL) <- value

Arguments

Details

• Note the difference between the terms id and index. Both can be found in the output of layout_properties(). The unique ph id is found in column id. The index refers to the index of the data frame row.

• In a right hand side (rhs) label assignment (⁠<- new_labels⁠), there are two ways to optionally specify a subset of phs to rename. In both cases, the length of the rhs vector (the new labels) must match the length of the id or index:

  1. use the id argument to specify ph ids to rename: layout_rename_ph_labels(..., id = 2:3) <- new_labels

  2. use an index in squared brackets: layout_rename_ph_labels(...)[1:2] <- new_labels

Value

Vector of renamed ph labels.

Examples

x <- read_pptx()

# INFO -------------

# Returns layout's ph_labels by default in same order as layout_properties()
layout_rename_ph_labels(x, "Comparison")
layout_properties(x, "Comparison")$ph_label


# BASICS -----------
#
# HINT: run `plot_layout_properties(x, "Comparison")` to see how labels change

# rename using key-value pairs: 'old label' = 'new label' or 'id' = 'new label'
layout_rename_ph_labels(x, "Comparison", "Title 1" = "LABEL MATCHED") # label matching
layout_rename_ph_labels(x, "Comparison", "3" = "ID MATCHED") # id matching
layout_rename_ph_labels(x, "Comparison", "Date Placeholder 6" = "DATE", "8" = "FOOTER") # label, id

# rename using a named list and the .dots arg
renames <- list("Content Placeholder 3" = "CONTENT_1", "6" = "CONTENT_2")
layout_rename_ph_labels(x, "Comparison", .dots = renames)

# rename via rhs assignment and optional index (not id!)
layout_rename_ph_labels(x, "Comparison") <- LETTERS[1:8]
layout_rename_ph_labels(x, "Comparison")[1:3] <- paste("CHANGED", 1:3)

# rename via rhs assignment and ph id (not index)
layout_rename_ph_labels(x, "Comparison", id = c(2, 4)) <- paste("ID =", c(2, 4))


# MORE ------------

# make all labels lower case
labels <- layout_rename_ph_labels(x, "Comparison")
layout_rename_ph_labels(x, "Comparison") <- tolower(labels)

# rename all labels to type [type_idx]
lp <- layout_properties(x, "Comparison")
layout_rename_ph_labels(x, "Comparison") <- paste0(lp$type, " [", lp$type_idx, "]")

# rename duplicated placeholders (see also `layout_dedupe_ph_labels()`)
file <- system.file("doc_examples", "ph_dupes.pptx", package = "officer")
x <- read_pptx(file)
lp <- layout_properties(x, "2-dupes")
idx <- which(lp$ph_label == "Content 7") # exists twice
layout_rename_ph_labels(x, "2-dupes")[idx] <- paste("DUPLICATE", seq_along(idx))

# warning: in case of duped labels only the first occurrence is renamed
x <- read_pptx(file)
layout_rename_ph_labels(x, "2-dupes", "Content 7" = "new label")

Presentation layouts summary

Description

Get information about slide layouts and master layouts into a data.frame. This function returns a data.frame containing all layout and master names.

Usage

layout_summary(x)

Arguments

See Also

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

Examples

my_pres <- read_pptx()
layout_summary ( x = my_pres )

Number of blocks inside an rdocx object

Description

return the number of blocks inside an rdocx object. This number also include the default section definition of a Word document - default Word section is an uninvisible element.

Usage

## S3 method for class 'rdocx'
length(x)

Arguments

See Also

Other functions for Word document informations: doc_properties(), docx_bookmarks(), docx_dim(), set_doc_properties(), styles_info()

Examples

# how many elements are there in an new document produced
# with the default template.
length( read_docx() )

Number of slides

Description

Function length will return the number of slides.

Usage

## S3 method for class 'rpptx'
length(x)

Arguments

See Also

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

Examples

my_pres <- read_pptx()
my_pres <- add_slide(my_pres, "Title and Content")
my_pres <- add_slide(my_pres, "Title and Content")
length(my_pres)

Extract media from a document object

Description

Extract files from a rpptx object.

Usage

media_extract(x, path, target)

Arguments

Examples

example_pptx <- system.file(package = "officer",
  "doc_examples/example.pptx")
doc <- read_pptx(example_pptx)
content <- pptx_summary(doc)
image_row <- content[content$content_type %in% "image", ]
media_file <- image_row$media_file
png_file <- tempfile(fileext = ".png")
media_extract(doc, path = media_file, target = png_file)

Move a slide

Description

Move a slide in a pptx presentation.

Usage

move_slide(x, index = NULL, to)

Arguments

Note

cursor is set on the last slide.

See Also

read_pptx()

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

Examples

x <- read_pptx()
x <- add_slide(x, "Title and Content")
x <- ph_with(x, "Hello world 1", location = ph_location_type())
x <- add_slide(x, "Title and Content")
x <- ph_with(x, "Hello world 2", location = ph_location_type())
x <- move_slide(x, index = 1, to = 2)

Location of a named placeholder for notes

Description

The function will use the label of a placeholder to find the corresponding location in the slide notes.

Usage

notes_location_label(ph_label, ...)

Arguments

Location of a placeholder for notes

Description

The function will use the type name of the placeholder (e.g. body, hdr), to find the corresponding location.

Usage

notes_location_type(type = "body", ...)

Arguments

Defunct Functions in Package officer

Description

Defunct Functions in Package officer

Usage

slip_in_seqfield(...)

slip_in_column_break(...)

slip_in_xml(...)

slip_in_text(...)

slip_in_footnote(...)

Arguments

Details

slip_in_seqfield() is replaced by run_word_field().

slip_in_column_break() is replaced by run_columnbreak().

slip_in_xml() is replaced by fpar().

slip_in_text() is replaced by fpar().

slip_in_footnote() is replaced by run_footnote().

officer url encoder

Description

encode url so that it can be easily decoded when 'officer' write a file to the disk.

Usage

officer_url_encode(x)

Arguments

Examples

officer_url_encode("https://cran.r-project.org/")

Change current slide

Description

Change current slide index of an rpptx object.

Usage

on_slide(x, index)

Arguments

See Also

read_pptx(), ph_with()

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

Examples

doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- add_slide(doc, "Title and Content")
doc <- add_slide(doc, "Title and Content")
doc <- on_slide(doc, index = 1)
doc <- ph_with(
  x = doc, "First title",
  location = ph_location_type(type = "title")
)
doc <- on_slide(doc, index = 3)
doc <- ph_with(
  x = doc, "Third title",
  location = ph_location_type(type = "title")
)

file <- tempfile(fileext = ".pptx")
print(doc, target = file)

Table options in a 'knitr' context

Description

Get options for table rendering in a 'knitr' context. It should not be used by the end user, but its documentation should be read as a place where table options are documented when 'knitr' is used.

The function is a utility to facilitate the retrieval of table options supported by the 'flextable', 'officedown' and 'officer' packages.

These options should be set with knitr::opts_chunk$set(). The names and expected values are listed in the following sections.

Usage

opts_current_table()

Value

a list

knitr chunk options for table captions

knitr chunk options for Word table captions

knitr chunk options for Word tables

knitr chunk options for data.frame with officedown

returned elements

• cap.style (default: NULL)

• cap.pre (default: "Table ")

• cap.sep (default: ":")

• cap.tnd (default: 0)

• cap.tns (default: "-")

• cap.fp_text (default: fp_text_lite(bold = TRUE))

• id (default: NULL)

• cap (default: NULL)

• alt.title (default: NULL)

• alt.description (default: NULL)

• topcaption (default: TRUE)

• style (default: NULL)

• tab.lp (default: "tab:")

• table_layout (default: "autofit")

• table_width (default: 1)

• first_row (default: TRUE)

• first_column (default: FALSE)

• last_row (default: FALSE)

• last_column (default: FALSE)

• no_hband (default: TRUE)

• no_vband (default: TRUE)

See Also

Other functions for officer extensions: docx_reference_img(), fortify_location(), get_reference_value(), shape_properties_tags(), str_encode_to_rtf(), to_html(), to_pml(), to_rtf(), to_wml(), wml_link_images()

compress a folder

Description

compress a folder to a target file. The function returns the complete path to target file.

Usage

pack_folder(folder, target)

Arguments

Page margins object

Description

Define margins for each page of a section.

The function creates a representation of the dimensions of a page. The dimensions are defined by length, width and orientation. If the orientation is in landscape mode then the length becomes the width and the width becomes the length.

Usage

page_mar(
  bottom = 1417/1440,
  top = 1417/1440,
  right = 1417/1440,
  left = 1417/1440,
  header = 708/1440,
  footer = 708/1440,
  gutter = 0/1440
)

Arguments

See Also

Other functions for section definition: page_size(), prop_section(), section_columns()

Examples

page_mar()

Page size object

Description

The function creates a representation of the dimensions of a page. The dimensions are defined by length, width and orientation. If the orientation is in landscape mode then the length becomes the width and the width becomes the length.

Usage

page_size(
  width = 11906/1440,
  height = 16838/1440,
  orient = "portrait",
  unit = "in"
)

Arguments

See Also

Other functions for section definition: page_mar(), prop_section(), section_columns()

Examples

page_size(orient = "landscape")

Hyperlink a placeholder

Description

Add hyperlink to a placeholder in the current slide.

Usage

ph_hyperlink(x, type = "body", id = 1, id_chr = NULL, ph_label = NULL, href)

Arguments

See Also

ph_with()

Other functions for placeholders manipulation: ph_remove(), ph_slidelink()

Examples

fileout <- tempfile(fileext = ".pptx")
loc_manual <- ph_location(bg = "red", newlabel = "mytitle")
doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(x = doc, "Un titre 1", location = loc_manual)
slide_summary(doc) # read column ph_label here
doc <- ph_hyperlink(
  x = doc, ph_label = "mytitle",
  href = "https://cran.r-project.org"
)

print(doc, target = fileout)

Location for a placeholder from scratch

Description

The function will return a list that complies with expected format for argument location of function ph_with().

Usage

ph_location(
  left = 1,
  top = 1,
  width = 4,
  height = 3,
  newlabel = "",
  bg = NULL,
  rotation = NULL,
  ln = NULL,
  geom = NULL,
  ...
)

Arguments

Details

The location of the bounding box associated to a placeholder within a slide is specified with the left top coordinate, the width and the height. These are defined in inches:

left

left coordinate of the bounding box

top

top coordinate of the bounding box

width

width of the bounding box

height

height of the bounding box

In addition to these attributes, a label can be associated with the shape. Shapes, text boxes, images and other objects will be identified with that label in the Selection Pane of PowerPoint. This label can then be reused by other functions such as ph_location_label(). It can be set with argument newlabel.

See Also

Other functions for placeholder location: ph_location_fullsize(), ph_location_id(), ph_location_label(), ph_location_left(), ph_location_right(), ph_location_template(), ph_location_type()

Examples

doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(doc, "Hello world",
  location = ph_location(width = 4, height = 3, newlabel = "hello")
)
print(doc, target = tempfile(fileext = ".pptx"))

# Set geometry and outline
doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
loc <- ph_location(
  left = 1, top = 1, width = 4, height = 3, bg = "steelblue",
  ln = sp_line(color = "red", lwd = 2.5),
  geom = "trapezoid"
)
doc <- ph_with(doc, "", loc = loc)
print(doc, target = tempfile(fileext = ".pptx"))

Location of a full size element

Description

The function will return the location corresponding to a full size display.

Usage

ph_location_fullsize(newlabel = "", ...)

Arguments

See Also

Other functions for placeholder location: ph_location(), ph_location_id(), ph_location_label(), ph_location_left(), ph_location_right(), ph_location_template(), ph_location_type()

Examples

doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(doc, "Hello world", location = ph_location_fullsize())
print(doc, target = tempfile(fileext = ".pptx"))

Location of a placeholder based on its id

Description

Each placeholder has an id (a low integer value). The ids are unique across a single layout. The function uses the placeholder's id to reference it. Different from a ph label, the id is auto-assigned by PowerPoint and cannot be modified by the user. Use layout_properties() (column id) and plot_layout_properties() (upper right corner, in green) to find a placeholder's id.

Usage

ph_location_id(id, newlabel = NULL, ...)

Arguments

Details

The location of the bounding box associated to a placeholder within a slide is specified with the left top coordinate, the width and the height. These are defined in inches:

left

left coordinate of the bounding box

top

top coordinate of the bounding box

width

width of the bounding box

height

height of the bounding box

In addition to these attributes, a label can be associated with the shape. Shapes, text boxes, images and other objects will be identified with that label in the Selection Pane of PowerPoint. This label can then be reused by other functions such as ph_location_label(). It can be set with argument newlabel.

See Also

Other functions for placeholder location: ph_location(), ph_location_fullsize(), ph_location_label(), ph_location_left(), ph_location_right(), ph_location_template(), ph_location_type()

Examples

doc <- read_pptx()
doc <- add_slide(doc, "Comparison")
plot_layout_properties(doc, "Comparison")

doc <- ph_with(doc, "The Title", location = ph_location_id(id = 2)) # title
doc <- ph_with(doc, "Left Header", location = ph_location_id(id = 3)) # left header
doc <- ph_with(doc, "Left Content", location = ph_location_id(id = 4)) # left content
doc <- ph_with(doc, "The Footer", location = ph_location_id(id = 8)) # footer

file <- tempfile(fileext = ".pptx")
print(doc, file)
## Not run: 
file.show(file) # may not work on your system

## End(Not run)

Location of a named placeholder

Description

The function will use the label of a placeholder to find the corresponding location.

Usage

ph_location_label(ph_label, newlabel = NULL, ...)

Arguments

Details

The location of the bounding box associated to a placeholder within a slide is specified with the left top coordinate, the width and the height. These are defined in inches:

left

left coordinate of the bounding box

top

top coordinate of the bounding box

width

width of the bounding box

height

height of the bounding box

In addition to these attributes, a label can be associated with the shape. Shapes, text boxes, images and other objects will be identified with that label in the Selection Pane of PowerPoint. This label can then be reused by other functions such as ph_location_label(). It can be set with argument newlabel.

See Also

Other functions for placeholder location: ph_location(), ph_location_fullsize(), ph_location_id(), ph_location_left(), ph_location_right(), ph_location_template(), ph_location_type()

Examples

# ph_location_label demo ----

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content")

# all ph_label can be read here
layout_properties(doc, layout = "Title and Content")

doc <- ph_with(doc, head(iris),
  location = ph_location_label(ph_label = "Content Placeholder 2")
)
doc <- ph_with(doc, format(Sys.Date()),
  location = ph_location_label(ph_label = "Date Placeholder 3")
)
doc <- ph_with(doc, "This is a title",
  location = ph_location_label(ph_label = "Title 1")
)

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

Location of a left body element

Description

The function will return the location corresponding to a left bounding box. The function assume the layout 'Two Content' is existing. This is an helper function, if you don't have a layout named 'Two Content', use ph_location_type() and set arguments to your specific needs.

Usage

ph_location_left(newlabel = NULL, ...)

Arguments

See Also

Other functions for placeholder location: ph_location(), ph_location_fullsize(), ph_location_id(), ph_location_label(), ph_location_right(), ph_location_template(), ph_location_type()

Examples

doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(doc, "Hello left", location = ph_location_left())
doc <- ph_with(doc, "Hello right", location = ph_location_right())
print(doc, target = tempfile(fileext = ".pptx"))

Location of a right body element

Description

The function will return the location corresponding to a right bounding box. The function assume the layout 'Two Content' is existing. This is an helper function, if you don't have a layout named 'Two Content', use ph_location_type() and set arguments to your specific needs.

Usage

ph_location_right(newlabel = NULL, ...)

Arguments

See Also

Other functions for placeholder location: ph_location(), ph_location_fullsize(), ph_location_id(), ph_location_label(), ph_location_left(), ph_location_template(), ph_location_type()

Examples

doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(doc, "Hello left", location = ph_location_left())
doc <- ph_with(doc, "Hello right", location = ph_location_right())
print(doc, target = tempfile(fileext = ".pptx"))

Location for a placeholder based on a template

Description

The function will return a list that complies with expected format for argument location of function ph_with(). A placeholder will be used as template and its positions will be updated with values left, top, width, height.

Usage

ph_location_template(
  left = 1,
  top = 1,
  width = 4,
  height = 3,
  newlabel = "",
  type = NULL,
  id = 1,
  ...
)

Arguments

Details

The location of the bounding box associated to a placeholder within a slide is specified with the left top coordinate, the width and the height. These are defined in inches:

left

left coordinate of the bounding box

top

top coordinate of the bounding box

width

width of the bounding box

height

height of the bounding box

In addition to these attributes, a label can be associated with the shape. Shapes, text boxes, images and other objects will be identified with that label in the Selection Pane of PowerPoint. This label can then be reused by other functions such as ph_location_label(). It can be set with argument newlabel.

See Also

Other functions for placeholder location: ph_location(), ph_location_fullsize(), ph_location_id(), ph_location_label(), ph_location_left(), ph_location_right(), ph_location_type()

Examples

doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(doc, "Title",
  location = ph_location_type(type = "title")
)
doc <- ph_with(doc, "Hello world",
  location = ph_location_template(top = 4, type = "title")
)
print(doc, target = tempfile(fileext = ".pptx"))

Location of a placeholder based on a type

Description

The function will use the type name of the placeholder (e.g. body, title), the layout name and few other criterias to find the corresponding location.

Usage

ph_location_type(
  type = "body",
  type_idx = NULL,
  position_right = TRUE,
  position_top = TRUE,
  newlabel = NULL,
  id = NULL,
  ...
)

Arguments

Details

The location of the bounding box associated to a placeholder within a slide is specified with the left top coordinate, the width and the height. These are defined in inches:

left

left coordinate of the bounding box

top

top coordinate of the bounding box

width

width of the bounding box

height

height of the bounding box

In addition to these attributes, a label can be associated with the shape. Shapes, text boxes, images and other objects will be identified with that label in the Selection Pane of PowerPoint. This label can then be reused by other functions such as ph_location_label(). It can be set with argument newlabel.

See Also

Other functions for placeholder location: ph_location(), ph_location_fullsize(), ph_location_id(), ph_location_label(), ph_location_left(), ph_location_right(), ph_location_template()

Examples

# ph_location_type demo ----

loc_title <- ph_location_type(type = "title")
loc_footer <- ph_location_type(type = "ftr")
loc_dt <- ph_location_type(type = "dt")
loc_slidenum <- ph_location_type(type = "sldNum")
loc_body <- ph_location_type(type = "body")


doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(x = doc, "Un titre", location = loc_title)
doc <- ph_with(x = doc, "pied de page", location = loc_footer)
doc <- ph_with(x = doc, format(Sys.Date()), location = loc_dt)
doc <- ph_with(x = doc, "slide 1", location = loc_slidenum)
doc <- ph_with(x = doc, letters[1:10], location = loc_body)

loc_subtitle <- ph_location_type(type = "subTitle")
loc_ctrtitle <- ph_location_type(type = "ctrTitle")
doc <- add_slide(doc, layout = "Title Slide")
doc <- ph_with(x = doc, "Un sous titre", location = loc_subtitle)
doc <- ph_with(x = doc, "Un titre", location = loc_ctrtitle)

fileout <- tempfile(fileext = ".pptx")
print(doc, target = fileout)

Remove a shape

Description

Remove a shape in a slide.

Usage

ph_remove(x, type = "body", id = 1, ph_label = NULL, id_chr = NULL)

Arguments

See Also

ph_with()

Other functions for placeholders manipulation: ph_hyperlink(), ph_slidelink()

Examples

fileout <- tempfile(fileext = ".pptx")
dummy_fun <- function(doc) {
  doc <- add_slide(doc,
    layout = "Two Content",
    master = "Office Theme"
  )
  doc <- ph_with(
    x = doc, value = "Un titre",
    location = ph_location_type(type = "title")
  )
  doc <- ph_with(
    x = doc, value = "Un corps 1",
    location = ph_location_type(type = "body", id = 1)
  )
  doc <- ph_with(
    x = doc, value = "Un corps 2",
    location = ph_location_type(type = "body", id = 2)
  )
  doc
}
doc <- read_pptx()
for (i in 1:3) {
  doc <- dummy_fun(doc)
}

doc <- on_slide(doc, index = 1)
doc <- ph_remove(x = doc, type = "title")

doc <- on_slide(doc, index = 2)
doc <- ph_remove(x = doc, type = "body", id = 2)

doc <- on_slide(doc, index = 3)
doc <- ph_remove(x = doc, type = "body", id = 1)

print(doc, target = fileout)

Slide link to a placeholder

Description

Add slide link to a placeholder in the current slide.

Usage

ph_slidelink(
  x,
  type = "body",
  id = 1,
  id_chr = NULL,
  ph_label = NULL,
  slide_index
)

Arguments

See Also

ph_with()

Other functions for placeholders manipulation: ph_hyperlink(), ph_remove()

Examples

fileout <- tempfile(fileext = ".pptx")
loc_title <- ph_location_type(type = "title")
doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(x = doc, "Un titre 1", location = loc_title)
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(x = doc, "Un titre 2", location = loc_title)
doc <- on_slide(doc, 1)
slide_summary(doc) # read column ph_label here
doc <- ph_slidelink(x = doc, ph_label = "Title 1", slide_index = 2)

print(doc, target = fileout)

Add objects on the current slide

Description

add object into a new shape in the current slide. This function is able to add all supported outputs to a presentation. See section Methods (by class) to see supported outputs.

Usage

ph_with(x, value, location, ...)

ph_with.character(x, value, location, ...)

ph_with.numeric(x, value, location, format_fun = format, ...)

ph_with.factor(x, value, location, ...)

ph_with.logical(x, value, location, format_fun = format, ...)

ph_with.block_list(x, value, location, level_list = integer(0), ...)

ph_with.unordered_list(x, value, location, ...)

ph_with.data.frame(
  x,
  value,
  location,
  header = TRUE,
  tcf = table_conditional_formatting(),
  alignment = NULL,
  ...
)

ph_with.gg(x, value, location, res = 300, alt_text = "", scale = 1, ...)

ph_with.plot_instr(x, value, location, res = 300, ...)

ph_with.external_img(x, value, location, use_loc_size = TRUE, ...)

ph_with.fpar(x, value, location, ...)

ph_with.empty_content(x, value, location, ...)

ph_with.xml_document(x, value, location, ...)

Arguments

Functions

• ph_with.character(): add a character vector to a new shape on the current slide, values will be added as paragraphs.

• ph_with.numeric(): add a numeric vector to a new shape on the current slide, values will be be first formatted then added as paragraphs.

• ph_with.factor(): add a factor vector to a new shape on the current slide, values will be be converted as character and then added as paragraphs.

• ph_with.block_list(): add a block_list() made of fpar() to a new shape on the current slide.

• ph_with.unordered_list(): add a unordered_list() made of fpar() to a new shape on the current slide.

• ph_with.data.frame(): add a data.frame to a new shape on the current slide with function block_table(). Use package 'flextable' instead for more advanced formattings.

• ph_with.gg(): add a ggplot object to a new shape on the current slide. Use package 'rvg' for more advanced graphical features.

• ph_with.plot_instr(): add an R plot to a new shape on the current slide. Use package 'rvg' for more advanced graphical features.

• ph_with.external_img(): add a external_img() to a new shape on the current slide.

  When value is a external_img object, image will be copied into the PowerPoint presentation. The width and height specified in call to external_img() will be ignored, their values will be those of the location, unless use_loc_size is set to FALSE.

• ph_with.fpar(): add an fpar() to a new shape on the current slide as a single paragraph in a block_list().

• ph_with.empty_content(): add an empty_content() to a new shape on the current slide.

• ph_with.xml_document(): add an xml_document object to a new shape on the current slide. This function is to be used to add custom openxml code.

Short forms

The location argument of ph_with() either expects a location object as returned by the ⁠ph_location_*⁠ functions or a corresponding location short form (string or numeric):

Illustrations

See Also

Specify placeholder locations with ph_location_type, ph_location, ph_location_label, ph_location_left, ph_location_right, ph_location_fullsize, ph_location_template. phs_with is a sibling of ph_with that fills mutiple placeholders at once.

Examples

# this name will be used to print the file
# change it to "youfile.pptx" to write the pptx
# file in your working directory.
fileout <- tempfile(fileext = ".pptx")

doc_1 <- read_pptx()
sz <- slide_size(doc_1)
# add text and a table ----
doc_1 <- add_slide(doc_1, layout = "Two Content", master = "Office Theme")
doc_1 <- ph_with(
  x = doc_1, value = c("Table cars"),
  location = ph_location_type(type = "title")
)
doc_1 <- ph_with(
  x = doc_1, value = names(cars),
  location = ph_location_left()
)
doc_1 <- ph_with(
  x = doc_1, value = cars,
  location = ph_location_right()
)

# add a base plot ----
anyplot <- plot_instr(code = {
  col <- c(
    "#440154FF", "#443A83FF", "#31688EFF",
    "#21908CFF", "#35B779FF", "#8FD744FF", "#FDE725FF"
  )
  barplot(1:7, col = col, yaxt = "n")
})

doc_1 <- add_slide(doc_1, "Title and Content")
doc_1 <- ph_with(doc_1, anyplot,
  location = ph_location_fullsize(),
  bg = "#006699"
)

# add a ggplot2 plot ----
if (require("ggplot2")) {
  doc_1 <- add_slide(doc_1, "Title and Content")
  gg_plot <- ggplot(data = iris) +
    geom_point(
      mapping = aes(Sepal.Length, Petal.Length),
      size = 3
    ) +
    theme_minimal()
  doc_1 <- ph_with(
    x = doc_1, value = gg_plot,
    location = ph_location_type(type = "body"),
    bg = "transparent"
  )
  doc_1 <- ph_with(
    x = doc_1, value = "graphic title",
    location = ph_location_type(type = "title")
  )
}

# add a external images ----
doc_1 <- add_slide(doc_1,
  layout = "Title and Content",
  master = "Office Theme"
)
doc_1 <- ph_with(
  x = doc_1, value = empty_content(),
  location = ph_location(
    left = 0, top = 0,
    width = sz$width, height = sz$height, bg = "black"
  )
)

svg_file <- file.path(R.home(component = "doc"), "html/Rlogo.svg")
if (require("rsvg")) {
  doc_1 <- ph_with(
    x = doc_1, value = "External images",
    location = ph_location_type(type = "title")
  )
  doc_1 <- ph_with(
    x = doc_1, external_img(svg_file, 100 / 72, 76 / 72),
    location = ph_location_right(), use_loc_size = FALSE
  )
  doc_1 <- ph_with(
    x = doc_1, external_img(svg_file),
    location = ph_location_left(),
    use_loc_size = TRUE
  )
}

# add a block_list ----
dummy_text <- readLines(system.file(
  package = "officer",
  "doc_examples/text.txt"
))
fp_1 <- fp_text(bold = TRUE, color = "pink", font.size = 0)
fp_2 <- fp_text(bold = TRUE, font.size = 0)
fp_3 <- fp_text(italic = TRUE, color = "red", font.size = 0)
bl <- block_list(
  fpar(ftext("hello world", fp_1)),
  fpar(
    ftext("hello", fp_2),
    ftext("hello", fp_3)
  ),
  dummy_text
)
doc_1 <- add_slide(doc_1, "Title and Content")
doc_1 <- ph_with(
  x = doc_1, value = bl,
  location = ph_location_type(type = "body")
)


# fpar ------
fpt <- fp_text(
  bold = TRUE, font.family = "Bradley Hand",
  font.size = 150, color = "#F5595B"
)
hw <- fpar(
  ftext("hello ", fpt),
  hyperlink_ftext(
    href = "https://cran.r-project.org/index.html",
    text = "cran", prop = fpt
  )
)
doc_1 <- add_slide(doc_1, "Title and Content")
doc_1 <- ph_with(
  x = doc_1, value = hw,
  location = ph_location_type(type = "body")
)
# unordered_list ----
ul <- unordered_list(
  level_list = c(1, 2, 2, 3, 3, 1),
  str_list = c("Level1", "Level2", "Level2", "Level3", "Level3", "Level1"),
  style = fp_text(color = "red", font.size = 0)
)
doc_1 <- add_slide(doc_1, "Title and Content")
doc_1 <- ph_with(
  x = doc_1, value = ul,
  location = ph_location_type()
)

print(doc_1, target = fileout)


# Example using short form locations ----
x <- read_pptx()
x <- add_slide(x, "Title Slide")
x <- ph_with(x, "A title", "Title 1")        # label
x <- ph_with(x, "A subtitle", 3)             # id
x <- ph_with(x, "A left text", "left")       # keyword
x <- ph_with(x, "A date", "dt[1]")           # type + index
x <- ph_with(x, "More content", c(5,.5,9,2)) # numeric vector
file <- tempfile(fileext = ".pptx")
print(x, file)
# browseURL(file)  # opens file on some systems

Fill multiple placeholders using key value syntax

Description

A sibling of ph_with that fills mutiple placeholders at once. Placeholder locations are specfied using the short form syntax. The location and corresponding object are passed as key value pairs (phs_with("short form location" = object)). Under the hood, ph_with is called for each pair. Note that phs_with does not cover all options from the ⁠ph_location_*⁠ family and is also less customization. It is a covenience wrapper for the most common use cases. The implemented short forms are listed in section "Short forms".

Usage

phs_with(x, ..., .dots = NULL, .slide_idx = NULL)

Arguments

Short forms

The following short forms are implemented and can be used as the parameter in the function call. The corresponding function from the ⁠ph_location_*⁠ family (called under the hood) is displayed on the right.

See Also

ph_with(), add_slide()

Examples

library(officer)

# use key-value format to fill phs
x <- read_pptx()
x <- add_slide(x, "Two Content")
x <- phs_with(x,
  `Title 1` = "A title", # ph label
  dt = "Jan. 26, 2025", # ph type
  `body[2]` = "Body 2", # ph type + type index
  left = "Left side", # ph keyword
  `6` = "Footer" # ph index
)

# reuse ph content via the .dots arg
x <- read_pptx()
my_ph_list <- list(`6` = "Footer", dt = "Jan. 26, 2025")
x <- add_slide(x, "Two Content")
x <- phs_with(x, `Title 1` = "Title A", `body[2]` = "Body A", .dots = my_ph_list)
x <- add_slide(x, "Two Content")
x <- phs_with(x, `Title 1` = "Title B", `body[2]` = "Body B", .dots = my_ph_list)

# use the .slide_idx arg to select which slide(s) to process
x <- read_pptx()
x <- add_slide(x, "Two Content")
x <- add_slide(x, "Two Content")
x <- phs_with(x, `6` = "Footer", dt = "Jan. 26, 2025", .slide_idx = 1:2)

# run to see results
## Not run: 
file <- tempfile(fileext = ".pptx")
print(x, file)
browseURL(file) # may not work on all systems

## End(Not run)

Wrap plot instructions for png plotting in Powerpoint or Word

Description

A simple wrapper to capture plot instructions that will be executed and copied in a document. It produces an object of class 'plot_instr' with a corresponding method ph_with() and body_add_plot().

The function enable usage of any R plot with argument code. Wrap your code between curly bracket if more than a single expression.

Usage

plot_instr(code)

Arguments

See Also

ph_with(), body_add_plot()

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

Examples

# plot_instr demo ----

anyplot <- plot_instr(code = {
  barplot(1:5, col = 2:6)
  })

doc <- read_docx()
doc <- body_add(doc, anyplot, width = 5, height = 4)
print(doc, target = tempfile(fileext = ".docx"))


doc <- read_pptx()
doc <- add_slide(doc, "Title and Content")
doc <- ph_with(
  doc, anyplot,
  location = ph_location_fullsize(),
  bg = "#00000066", pointsize = 12)
print(doc, target = tempfile(fileext = ".pptx"))

Slide layout properties plot

Description

Plot slide layout properties into corresponding placeholders. This can be useful to help visualize placeholders locations and identifiers. All information in the plot stems from the layout_properties() output. See Details section for more info.

Usage

plot_layout_properties(
  x,
  layout = NULL,
  master = NULL,
  labels = TRUE,
  title = TRUE,
  type = TRUE,
  id = TRUE,
  cex = c(labels = 0.5, type = 0.5, id = 0.5),
  legend = FALSE
)

Arguments

Details

The plot contains all relevant information to reference a placeholder via the ⁠ph_location_*⁠ function family:

• label: ph label (red, center) to be used in ph_location_label(). NB: The label can be assigned by the user in PowerPoint.

• type[idx]: ph type + type index in brackets (blue, upper left) to be used in ph_location_type(). NB: The index is consecutive and is sorted by ph position (top -> bottom, left -> right).

• id: ph id (green, upper right) to be used in ph_location_id() (forthcoming). NB: The id is set by PowerPoint automatically and lack a meaningful order.

See Also

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

Examples

x <- read_pptx()

# select layout explicitly
plot_layout_properties(x = x, layout = "Title Slide", master = "Office Theme")
plot_layout_properties(x = x, layout = "Title Slide") # no master needed if layout name unique
plot_layout_properties(x = x, layout = 1) # use layout index instead of name

# plot current slide's layout (default if no layout is passed)
x <- read_pptx()
x <- add_slide(x, "Title Slide")
plot_layout_properties(x)

# change appearance: what to show, font size, legend etc.
plot_layout_properties(x, layout = "Two Content", title = FALSE, type = FALSE, id = FALSE)
plot_layout_properties(x, layout = 4, cex = c(labels = .8, id = .7, type = .7))
plot_layout_properties(x, 1, legend = TRUE)

PowerPoint content in a data.frame

Description

Read content of a PowerPoint document and return a dataset representing the document.

Usage

pptx_summary(x, preserve = FALSE)

Arguments

Examples

example_pptx <- system.file(package = "officer",
  "doc_examples/example.pptx")
doc <- read_pptx(example_pptx)
pptx_summary(doc)
pptx_summary(example_pptx)

Write a 'PowerPoint' file.

Description

Create a 'PowerPoint' file from an rpptx object (created by read_pptx()).

Usage

## S3 method for class 'rpptx'
print(x, target = NULL, ...)

Arguments

See Also

read_pptx()

Examples

# write an rpptx object to a .pptx file ----
file <- tempfile(fileext = ".pptx")
x <- read_pptx()
print(x, target = file)

Write an 'RTF' document to a file

Description

Write the RTF object and its content to a file.

Usage

## S3 method for class 'rtf'
print(x, target = NULL, ...)

Arguments

See Also

rtf_doc()

Examples

# write a rdocx object in a rtf file ----
doc <- rtf_doc()
print(doc, target = tempfile(fileext = ".rtf"))

Section properties

Description

A section is a grouping of blocks (ie. paragraphs and tables) that have a set of properties that define pages on which the text will appear.

A Section properties object stores information about page composition, such as page size, page orientation, borders and margins.

Usage

prop_section(
  page_size = NULL,
  page_margins = NULL,
  type = "continuous",
  section_columns = NULL,
  header_default = NULL,
  header_even = NULL,
  header_first = NULL,
  footer_default = NULL,
  footer_even = NULL,
  footer_first = NULL
)

Arguments

Illustrations

See Also

block_section

Other functions for section definition: page_mar(), page_size(), section_columns()

Examples

library(officer)

landscape_one_column <- block_section(
  prop_section(
    page_size = page_size(orient = "landscape"), type = "continuous"
  )
)
landscape_two_columns <- block_section(
  prop_section(
    page_size = page_size(orient = "landscape"), type = "continuous",
    section_columns = section_columns(widths = c(4.75, 4.75))
  )
)

doc_1 <- read_docx()
# there starts section with landscape_one_column
doc_1 <- body_add_table(doc_1, value = mtcars[1:10, ], style = "table_template")
doc_1 <- body_end_block_section(doc_1, value = landscape_one_column)
# there stops section with landscape_one_column


# there starts section with landscape_two_columns
doc_1 <- body_add_par(doc_1, value = paste(rep(letters, 50), collapse = " "))
doc_1 <- body_end_block_section(doc_1, value = landscape_two_columns)
# there stops section with landscape_two_columns

doc_1 <- body_add_table(doc_1, value = mtcars[1:25, ], style = "table_template")

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


# an example with headers and footers -----
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()
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"))

Table properties

Description

Define table properties such as fixed or autofit layout, table width in the document, eventually column widths.

Usage

prop_table(
  style = NA_character_,
  layout = table_layout(),
  width = table_width(),
  stylenames = table_stylenames(),
  colwidths = table_colwidths(),
  tcf = table_conditional_formatting(),
  align = "center",
  word_title = NULL,
  word_description = NULL
)

Arguments

See Also

Other functions for table definition: table_colwidths(), table_conditional_formatting(), table_layout(), table_stylenames(), table_width()

Examples

prop_table()
to_wml(prop_table())

Create a 'Word' document object

Description

read and import a docx file as an R object representing the document. When no file is specified, it uses a default empty file.

Use then this object to add content to it and create Word files from R.

Usage

read_docx(path = NULL)

## S3 method for class 'rdocx'
print(
  x,
  target = NULL,
  copy_header_refs = FALSE,
  copy_footer_refs = FALSE,
  ...
)

Arguments

Value

an object of class rdocx.

Functions

• print(rdocx): write docx to a file. It returns the path of the result file.

styles

read_docx() uses a Word file as the initial document. This is the original Word document from which the document layout, paragraph styles, or table styles come.

You will be able to add formatted text, change the paragraph style with the R api but also use the styles from the original document.

See ⁠body_add_*⁠ functions to add content.

Illustrations

See Also

body_add_par, body_add_plot, body_add_table

Examples

library(officer)

pinst <- plot_instr({
  z <- c(rnorm(100), rnorm(50, mean = 5))
  plot(density(z))
})

doc_1 <- read_docx()
doc_1 <- body_add_par(doc_1, "This is a table", style = "heading 2")
doc_1 <- body_add_table(doc_1, value = mtcars, style = "table_template")
doc_1 <- body_add_par(doc_1, "This is a plot", style = "heading 2")
doc_1 <- body_add_plot(doc_1, pinst)
docx_file_1 <- print(doc_1, target = tempfile(fileext = ".docx"))

template <- system.file(package = "officer",
  "doc_examples", "landscape.docx")
doc_2 <- read_docx(path = template)
doc_2 <- body_add_par(doc_2, "This is a table", style = "heading 2")
doc_2 <- body_add_table(doc_2, value = mtcars)
doc_2 <- body_add_par(doc_2, "This is a plot", style = "heading 2")
doc_2 <- body_add_plot(doc_2, pinst)
docx_file_2 <- print(doc_2, target = tempfile(fileext = ".docx"))

Create a 'PowerPoint' document object

Description

Read and import a pptx file as an R object representing the document.

The function is called read_pptx because it allows you to initialize an object of class rpptx from an existing PowerPoint file. Content will be added to the existing presentation. By default, an empty document is used.

Usage

read_pptx(path = NULL)

Arguments

master layouts and slide layouts

read_pptx() uses a PowerPoint file as the initial document. This is the original PowerPoint document where all slide layouts, placeholders for shapes and styles come from. Major points to be aware of are:

• Slide layouts are relative to a master layout. A document can contain one or more master layouts; a master layout can contain one or more slide layouts.

• A slide layout inherits design properties from its master layout but some properties can be overwritten.

• Designs and formatting properties of layouts and shapes (placeholders in a layout) are defined within the initial document. There is no R function to modify these values - they must be defined in the initial document.

See Also

print.rpptx(), add_slide(), plot_layout_properties(), ph_with()

Examples

read_pptx()

Create an 'Excel' document object

Description

Read and import an xlsx file as an R object representing the document. This function is experimental.

Usage

read_xlsx(path = NULL)

## S3 method for class 'rxlsx'
length(x)

## S3 method for class 'rxlsx'
print(x, target = NULL, ...)

Arguments

Examples

read_xlsx()
x <- read_xlsx()
print(x, target = tempfile(fileext = ".xlsx"))

Remove a slide

Description

Remove a slide from a pptx presentation.

Usage

remove_slide(x, index = NULL, rm_images = FALSE)

Arguments

Note

cursor is set on the last slide.

See Also

read_pptx(), ph_with(), ph_remove()

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

Examples

my_pres <- read_pptx()
my_pres <- add_slide(my_pres, "Title and Content")
my_pres <- remove_slide(my_pres)

Resolve short form location

Description

Convert short form location format, a numeric or a string (e.g. "body [1]"), into its corresponding location object. Under the hood, we parse the short form location and call the corresponding function from the ⁠ph_location_*⁠ family. Note that short forms may not cover all function from the ⁠ph_location_*⁠ and offer less customization.

Usage

resolve_location(x)

Short forms

The following location short forms are implemented. The corresponding call of the function from the ⁠ph_location_*⁠ family is displayed on the right.

Examples

resolve_location("left")
resolve_location("right")
resolve_location("fullsize")
resolve_location("body")
resolve_location("body [1]")
resolve_location("<some label>")
resolve_location(2)
resolve_location(c(0, 0, 4, 5))

Add content into an RTF document

Description

This function add 'officer' objects into an RTF document. Values are added as new paragraphs. See section 'Methods (by class)' that list supported objects.

Usage

rtf_add(x, value, ...)

## S3 method for class 'block_section'
rtf_add(x, value, ...)

## S3 method for class 'character'
rtf_add(x, value, ...)

## S3 method for class 'factor'
rtf_add(x, value, ...)

## S3 method for class 'double'
rtf_add(x, value, formatter = formatC, ...)

## S3 method for class 'fpar'
rtf_add(x, value, ...)

## S3 method for class 'block_list'
rtf_add(x, value, ...)

## S3 method for class 'gg'
rtf_add(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  scale = 1,
  ppr = fp_par(text.align = "center"),
  ...
)

## S3 method for class 'plot_instr'
rtf_add(
  x,
  value,
  width = 6,
  height = 5,
  res = 300,
  scale = 1,
  ppr = fp_par(text.align = "center"),
  ...
)

Arguments

Methods (by class)

• rtf_add(block_section): add a new section definition

• rtf_add(character): add characters as new paragraphs

• rtf_add(factor): add a factor vector as new paragraphs

• rtf_add(double): add a double vector as new paragraphs

• rtf_add(fpar): add an fpar()

• rtf_add(block_list): add an block_list()

• rtf_add(gg): add a ggplot2

• rtf_add(plot_instr): add a plot_instr() object

Examples

library(officer)

def_text <- fp_text_lite(color = "#006699", bold = TRUE)
center_par <- fp_par(text.align = "center", padding = 3)

doc <- rtf_doc(
  normal_par = fp_par(line_spacing = 1.4, padding = 3)
)

doc <- rtf_add(
  x = doc,
  value = fpar(
    ftext("how are you?", prop = def_text),
    fp_p = fp_par(text.align = "center")
  )
)

a_paragraph <- fpar(
  ftext("Here is a date: ", prop = def_text),
  run_word_field(field = "Date \\@ \"MMMM d yyyy\""),
  fp_p = center_par
)
doc <- rtf_add(
  x = doc,
  value = block_list(
    a_paragraph,
    a_paragraph,
    a_paragraph
  )
)

if (require("ggplot2")) {
  gg <- gg_plot <- ggplot(data = iris) +
    geom_point(mapping = aes(Sepal.Length, Petal.Length))
  doc <- rtf_add(doc, gg,
    width = 3, height = 4,
    ppr = center_par
  )
}
anyplot <- plot_instr(code = {
  barplot(1:5, col = 2:6)
})
doc <- rtf_add(doc, anyplot,
  width = 5, height = 4,
  ppr = center_par
)

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

Create an RTF document object

Description

Creation of the object representing an RTF document which can then receive contents with the rtf_add() function and be written to a file with the print(x, target="doc.rtf") function.

Usage

rtf_doc(
  def_sec = prop_section(),
  normal_par = fp_par(),
  normal_chunk = fp_text(font.family = "Arial", font.size = 11)
)

Arguments

Value

an object of class rtf representing an empty RTF document.

See Also

read_docx(), print.rtf(), rtf_add()

Examples

rtf_doc(normal_par = fp_par(padding = 3))

Auto number

Description

Create an autonumbered chunk, i.e. a string representation of a sequence, each item will be numbered. These runs can also be bookmarked and be used later for cross references.

Usage

run_autonum(
  seq_id = "table",
  pre_label = "Table ",
  post_label = ": ",
  bkm = NULL,
  bkm_all = FALSE,
  prop = NULL,
  start_at = NULL,
  tnd = 0,
  tns = "-"
)

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

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

Other Word computed fields: run_reference(), run_word_field()

Examples

run_autonum()
run_autonum(seq_id = "fig", pre_label = "fig. ")
run_autonum(seq_id = "tab", pre_label = "Table ", bkm = "anytable")
run_autonum(
  seq_id = "tab", pre_label = "Table ", bkm = "anytable",
  tnd = 2, tns = " "
)

Bookmark for 'Word'

Description

Add a bookmark on a run object.

Usage

run_bookmark(bkm, run)

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

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

Examples

ft <- fp_text(font.size = 12, bold = TRUE)
run_bookmark("par1", ftext("some text", ft))

Column break for 'Word'

Description

Create a representation of a column break.

Usage

run_columnbreak()

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

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

Examples

run_columnbreak()

Comment for 'Word'

Description

Add a comment on a run object.

Usage

run_comment(
  cmt,
  run = ftext(""),
  author = "",
  date = "",
  initials = "",
  prop = NULL
)

Arguments

See Also

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

Examples

fp_bold <- fp_text_lite(bold = TRUE)
fp_red <- fp_text_lite(color = "red")

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

comment1 <- run_comment(
  cmt = bl,
  run = ftext("with a comment"),
  author = "Author Me",
  date = Sys.Date(),
  initials = "AM"
)
par1 <- fpar("A paragraph ", comment1)

bl <- block_list(
  fpar(ftext("Comment a paragraph."))
)

comment2 <- run_comment(
  cmt = bl, run = ftext("A commented paragraph"),
  author = "Author You",
  date = Sys.Date(),
  initials = "AY"
)
par2 <- fpar(comment2)

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

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

Footnote for 'Word'

Description

Wraps a footnote in an object that can then be inserted as a run/chunk with fpar() or within an R Markdown document.

Usage

run_footnote(x, prop = NULL)

Arguments

See Also

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

Examples

library(officer)

fp_bold <- fp_text_lite(bold = TRUE)
fp_refnote <- fp_text_lite(vertical.align = "superscript")

img.file <- file.path(R.home("doc"), "html", "logo.jpg")
bl <- block_list(
  fpar(ftext("hello", fp_bold)),
  fpar(
    ftext("hello world", fp_bold),
    external_img(src = img.file, height = 1.06, width = 1.39)
  )
)

a_par <- fpar(
  "this paragraph contains a note ",
  run_footnote(x = bl, prop = fp_refnote),
  "."
)

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

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

Word footnote reference

Description

Wraps a footnote reference in an object that can then be inserted as a run/chunk with fpar() or within an R Markdown document.

Usage

run_footnoteref(prop = NULL)

Arguments

See Also

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

Examples

run_footnoteref()
to_wml(run_footnoteref())

Page break for 'Word'

Description

Object representing a line break for a Word document. The result must be used within a call to fpar.

Usage

run_linebreak()

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

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

Examples

fp_t <- fp_text(font.size = 12, bold = TRUE)
an_fpar <- fpar("let's add a line break", run_linebreak(), ftext("and blah blah!", fp_t))

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

Page break for 'Word'

Description

Object representing a page break for a Word document.

Usage

run_pagebreak()

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

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_reference(), run_tab(), run_word_field(), run_wordtext()

Examples

fp_t <- fp_text(font.size = 12, bold = TRUE)
an_fpar <- fpar("let's add a break page", run_pagebreak(), ftext("and blah blah!", fp_t))

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

Cross reference

Description

Create a representation of a reference

Usage

run_reference(id, prop = NULL)

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

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_tab(), run_word_field(), run_wordtext()

Other Word computed fields: run_autonum(), run_word_field()

Examples

run_reference("a_ref")

Tab for 'Word'

Description

Object representing a tab in a Word document. The result must be used within a call to fpar. It will only have effects in Word output.

Tabulation marks settings can be defined with fp_tabs() in paragraph settings defined with fp_par().

Usage

run_tab()

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

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_word_field(), run_wordtext()

Examples

z <- fp_tabs(
  fp_tab(pos = 0.5, style = "decimal"),
  fp_tab(pos = 1.5, style = "decimal")
)
par1 <- fpar(
  run_tab(), ftext("88."),
  run_tab(), ftext("987.45"),
  fp_p = fp_par(
    tabs = z
  )
)
par2 <- fpar(
  run_tab(), ftext("8."),
  run_tab(), ftext("670987.45"),
  fp_p = fp_par(
    tabs = z
  )
)
x <- read_docx()
x <- body_add(x, par1)
x <- body_add(x, par2)
print(x, target = tempfile(fileext = ".docx"))

'Word' computed field

Description

Create a 'Word' computed field.

Usage

run_word_field(field, prop = NULL, seqfield = NULL)

run_seqfield(field, prop = NULL, seqfield = NULL)

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.

Note

In the previous version, this function was called run_seqfield but the name was wrong and should have been run_word_field.

See Also

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_wordtext()

Other Word computed fields: run_autonum(), run_reference()

Examples

run_word_field(field = "PAGE  \\* MERGEFORMAT")
run_word_field(field = "Date \\@ \"MMMM d yyyy\"")

Word chunk of text with a style

Description

Format a chunk of text associated with a 'Word' character style. The style is defined with its unique identifer.

Usage

run_wordtext(text, style_id = NULL)

Arguments

See Also

ftext()

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()

Examples

run1 <- run_wordtext("hello", "DefaultParagraphFont")
paragraph <- fpar(run1)

x <- read_docx()
x <- body_add_fpar(x, paragraph)
print(x, target = tempfile(fileext = ".docx"))

Remove unused media from a document

Description

The function will scan the media directory and delete images that are not used anymore. This function is to be used when images have been replaced many times.

Usage

sanitize_images(x)

Arguments

Section columns

Description

The function creates a representation of the columns of a section.

Usage

section_columns(widths = c(2.5, 2.5), space = 0.25, sep = FALSE)

Arguments

See Also

Other functions for section definition: page_mar(), page_size(), prop_section()

Examples

section_columns()

Update bookmark of an autonumber run

Description

This function lets recycling a object made by run_autonum() by changing the bookmark value. This is useful to avoid calling run_autonum() several times because of many tables.

Usage

set_autonum_bookmark(x, bkm = NULL)

Arguments

See Also

run_autonum()

Examples

z <- run_autonum(
  seq_id = "tab", pre_label = "Table ",
  bkm = "anytable"
)
set_autonum_bookmark(z, bkm = "anothertable")

Set document properties

Description

set Word or PowerPoint document properties. These are not visible in the document but are available as metadata of the document.

Any character property can be added as a document property. It provides an easy way to insert arbitrary fields. Given the challenges that can be encountered with find-and-replace in word with officer, the use of document fields and quick text fields provides a much more robust approach to automatic document generation from R.

Usage

set_doc_properties(
  x,
  title = NULL,
  subject = NULL,
  creator = NULL,
  description = NULL,
  created = NULL,
  ...,
  values = NULL
)

Arguments

Note

The "last modified" and "last modified by" fields will be automatically be updated when the file is written.

See Also

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

Examples

x <- read_docx()
x <- set_doc_properties(x, title = "title",
  subject = "document subject", creator = "Me me me",
  description = "this document is empty",
  created = Sys.time(),
  yoyo = "yok yok",
  glop = "pas glop")
x <- doc_properties(x)

Set notes for current slide

Description

Set speaker notes for the current slide in a pptx presentation.

Usage

set_notes(x, value, location, ...)

## S3 method for class 'character'
set_notes(x, value, location, ...)

## S3 method for class 'block_list'
set_notes(x, value, location, ...)

Arguments

Methods (by class)

• set_notes(character): add a character vector to a place holder in the notes on the current slide, values will be added as paragraphs.

• set_notes(block_list): add a block_list() to a place holder in the notes on the current slide.

See Also

print.rpptx(), read_pptx(), add_slide(), notes_location_label(), notes_location_type()

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

Examples

# this name will be used to print the file
# change it to "youfile.pptx" to write the pptx
# file in your working directory.
fileout <- tempfile(fileext = ".pptx")
fpt_blue_bold <- fp_text_lite(color = "#006699", bold = TRUE)
doc <- read_pptx()
# add a slide with some text ----
doc <- add_slide(doc, layout = "Title and Content")
doc <- ph_with(x = doc, value = "Slide Title 1",
   location = ph_location_type(type = "title") )
# set speaker notes for the slide ----
doc <- set_notes(doc, value = "This text will only be visible for the speaker.",
   location = notes_location_type("body"))

# add a slide with some text ----
doc <- add_slide(doc, layout = "Title and Content")
doc <- ph_with(x = doc, value = "Slide Title 2",
   location = ph_location_type(type = "title") )
bl <- block_list(
  fpar(ftext("hello world", fpt_blue_bold)),
  fpar(ftext("Turlututu chapeau pointu", fpt_blue_bold))
)
doc <- set_notes(doc, value = bl,
   location = notes_location_type("body"))

print(doc, target = fileout)

pptx tags for visual and non visual properties

Description

Visual and non visual properties of a shape can be returned by this function.

Usage

shape_properties_tags(
  left = 0,
  top = 0,
  width = 3,
  height = 3,
  bg = "transparent",
  rot = 0,
  label = "",
  ph = "<p:ph/>",
  ln = sp_line(lwd = 0, linecmpd = "solid", lineend = "rnd"),
  geom = NULL
)

Arguments

Value

a character value

See Also

Other functions for officer extensions: docx_reference_img(), fortify_location(), get_reference_value(), opts_current_table(), str_encode_to_rtf(), to_html(), to_pml(), to_rtf(), to_wml(), wml_link_images()

Select sheet

Description

Set a particular sheet selected when workbook will be edited.

Usage

sheet_select(x, sheet)

Arguments

Examples

my_ws <- read_xlsx()
my_pres <- add_sheet(my_ws, label = "new sheet")
my_pres <- sheet_select(my_ws, sheet = "new sheet")
print(my_ws, target = tempfile(fileext = ".xlsx") )

shortcuts for formatting properties

Description

Shortcuts for fp_text(), fp_par(), fp_cell() and fp_border().

Usage

shortcuts

Examples

shortcuts$fp_bold()
shortcuts$fp_italic()
shortcuts$b_null()

Slides width and height

Description

Get the width and height of slides in inches as a named vector.

Usage

slide_size(x)

Arguments

See Also

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

Examples

my_pres <- read_pptx()
my_pres <- add_slide(my_pres,
  layout = "Two Content", master = "Office Theme")
slide_size(my_pres)

Slide content in a data.frame

Description

Get content and positions of current slide into a data.frame. Data for any tables, images, or paragraphs are imported into the resulting data.frame.

Usage

slide_summary(x, index = NULL)

Arguments

Note

The column id of the result is not to be used by users. This is a technical string id whose value will be used by office when the document will be rendered. This is not related to argument index required by functions ph_with().

See Also

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

Examples

my_pres <- read_pptx()
my_pres <- add_slide(my_pres, "Title and Content")
my_pres <- ph_with(my_pres, format(Sys.Date()),
  location = ph_location_type(type="dt"))
my_pres <- add_slide(my_pres, "Title and Content")
my_pres <- ph_with(my_pres, iris[1:2,],
  location = ph_location_type(type="body"))
slide_summary(my_pres)
slide_summary(my_pres, index = 1)

Get or set slide visibility

Description

PPTX slides can be visible or hidden. This function gets or sets the visibility of slides.

Usage

slide_visible(x) <- value

slide_visible(x, hide = NULL, show = NULL)

Arguments

Value

Boolean vector with slide visibilities or rpptx object if changes are made to the object.

Examples

path <- system.file("doc_examples/example.pptx", package = "officer")
x <- read_pptx(path)

slide_visible(x) # get slide visibilities

x <- slide_visible(x, hide = 1:2) # hide slides 1 and 2
x <- slide_visible(x, show = 1:2) # make slides 1 and 2 visible
x <- slide_visible(x, show = 1:2, hide = 3)

slide_visible(x) <- FALSE # hide all slides
slide_visible(x) <- c(TRUE, FALSE, TRUE) # set each slide separately
slide_visible(x) <- c(TRUE, FALSE) # warns that rhs values are recycled

slide_visible(x)[2] <- TRUE # set 2nd slide to visible
slide_visible(x)[c(1, 3)] <- FALSE # 1st and 3rd slide
slide_visible(x)[c(1, 3)] <- c(FALSE, FALSE) # identical

Line properties

Description

Create a sp_line object that describes line properties.

Usage

sp_line(
  color = "transparent",
  lwd = 1,
  lty = "solid",
  linecmpd = "sng",
  lineend = "rnd",
  linejoin = "round",
  headend = sp_lineend(type = "none"),
  tailend = sp_lineend(type = "none")
)

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

## S3 method for class 'sp_line'
update(
  object,
  color,
  lwd,
  lty,
  linecmpd,
  lineend,
  linejoin,
  headend,
  tailend,
  ...
)

Arguments