PowerPoint presentations generation

library(officer)
# Package `magrittr` makes officer usage easier.
library(magrittr)

How to start

Use the function read_pptx() to create an R object representing a PowerPoint document. The initial PowerPoint file can be specified with the path argument. If none is provided, this file will be an empty document located in the package directory. Formats and available slide layouts will be those available in the template file. The content of original document is also preserved (but can be manipulated, i.e. delete a slide).

my_pres <- read_pptx() 

The main functions are presented below:

officer pptx functions

officer pptx functions

Note that ph_with is new and should replace ph_with_* and ph_with_*_at.

Add a slide

To add a new slide, use the function add_slide(). It requires 3 arguments:

Note that the layout and master values must match values from the initial document. Layout names and master layout names are not easily readable within PowerPoint, but these can be read easily with the function layout_summary().

##              layout       master
## 1       Title Slide Office Theme
## 2 Title and Content Office Theme
## 3    Section Header Office Theme
## 4       Two Content Office Theme
## 5        Comparison Office Theme
## 6        Title Only Office Theme
## 7             Blank Office Theme

master layouts and slide layouts

officer uses a PowerPoint file as the initial document. This is the original PowerPoint document where all slide layouts, shapes (placeholders) 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.

Add content in a slide

Use the function ph_with() to add content into a new shape. The location of the shape is defined with argument location with a call to one of the ph_location*functions.

There are several ph_location*functions: ph_location_type(), ph_location_fullsize(), ph_location_label(), ph_location_left(), ph_location_right() and ph_location().

Write the PowerPoint file

The (updated) Powerpoint file can be generated using the print() function along with the target argument:

## [1] "/private/var/folders/08/2qdvv0q95wn52xy6mxgj340r0000gn/T/RtmpxL4xPQ/Rbuilde8c514012a0d/officer/vignettes/assets/pptx/first_example.pptx"

Download file first_example.pptx - view with office web viewer

Slide selection and manipulation

There are functions to let you manipulate slides: add_slide(), remove_slide(), move_slide() and on_slide().

A slide can be added with the add_slide() function.

my_pres <- read_pptx() %>% 
  add_slide(layout = "Two Content", master = "Office Theme") %>% 
  add_slide(layout = "Title and Content", master = "Office Theme") %>% 
  add_slide(layout = "Title Only", master = "Office Theme")
length(my_pres)
## [1] 3

A slide can be removed with the remove_slide() function.

my_pres <- my_pres %>% remove_slide(index = 1)
length(my_pres)
## [1] 2

A slide can be selected with the on_slide() function.

my_pres <- my_pres %>% on_slide(index = 1)

Add content in a placeholder

the location

Use the function ph_with() to add an element into a new shape. The function is expecting an argument location that will be used to specify the location of the new shape. This location can be defined with a call to one of the ph_location*functions.

The following example will add text “Hello world” in a new shape. That shape will inherit its properties from the placeholder that has type body. This is defined in the slide layout used by the slide, i.e. Title and Content in our example.

## [1] "/private/var/folders/08/2qdvv0q95wn52xy6mxgj340r0000gn/T/RtmpxL4xPQ/Rbuilde8c514012a0d/officer/vignettes/assets/pptx/ph_with_location_type.pptx"

Download file ph_with_location_type.pptx - view with office web viewer

The following example will print few rows of iris data.frame in a new shape. That shape will inherit its properties from the placeholder that has label Content Placeholder 2. This is defined in the slide layout used by the slide, i.e. Title and Content in our example. This is the same location that is used in the previous example.

##     master_name              name   type id                   ph_label
## 5  Office Theme Title and Content   body  3      Content Placeholder 2
## 10 Office Theme Title and Content     dt  4         Date Placeholder 3
## 21 Office Theme Title and Content    ftr  5       Footer Placeholder 4
## 25 Office Theme Title and Content sldNum  6 Slide Number Placeholder 5
## 31 Office Theme Title and Content  title  2                    Title 1
##                                             ph     offx      offy       cx
## 5                              <p:ph idx="1"/> 0.500000 1.7500000 9.000000
## 10        <p:ph type="dt" sz="half" idx="10"/> 0.500000 6.9513889 2.333333
## 21    <p:ph type="ftr" sz="quarter" idx="11"/> 3.416667 6.9513889 3.166667
## 25 <p:ph type="sldNum" sz="quarter" idx="12"/> 7.166667 6.9513889 2.333333
## 31                        <p:ph type="title"/> 0.500000 0.3003478 9.000000
##           cy
## 5  4.9496533
## 10 0.3993056
## 21 0.3993056
## 25 0.3993056
## 31 1.2500000
## pptx document with 1 slide(s)
## Available layouts and their associated master(s) are:
##              layout       master
## 1       Title Slide Office Theme
## 2 Title and Content Office Theme
## 3    Section Header Office Theme
## 4       Two Content Office Theme
## 5        Comparison Office Theme
## 6        Title Only Office Theme
## 7             Blank Office Theme
## [1] "/private/var/folders/08/2qdvv0q95wn52xy6mxgj340r0000gn/T/RtmpxL4xPQ/Rbuilde8c514012a0d/officer/vignettes/assets/pptx/ph_with_location_label.pptx"

Download file ph_with_location_label.pptx - view with office web viewer

The following example will print two paragraphs of text in two new shapes, one representing the left side and one representing the right side.

## [1] "/private/var/folders/08/2qdvv0q95wn52xy6mxgj340r0000gn/T/RtmpxL4xPQ/Rbuilde8c514012a0d/officer/vignettes/assets/pptx/ph_with_location_left_right.pptx"

Download file ph_with_location_left_right.pptx - view with office web viewer

Supported contents

The following types of content are supported:

doc <- read_pptx()

# add a "Two Content" slide and then content ----
doc <- add_slide(doc, layout = "Two Content", master = "Office Theme")
doc <- ph_with(x = doc, value = pi, location = ph_location_type(type = "title") )
doc <- ph_with(x = doc, value = as.factor(letters[1:2]), location = ph_location_type(type = "ftr") )
doc <- ph_with(x = doc, value = c("Un titre", "Deux titre"), location = ph_location_left() )
doc <- ph_with(x = doc, value = iris[1:4, 3:5], location = ph_location_right() )

# add a "Title and Content" slide and then a ggplot object ----
if( require("ggplot2") ){
  doc <- add_slide(doc, layout = "Title and Content",
                   master = "Office Theme")
  gg_plot <- ggplot(data = iris ) +
    geom_point(mapping = aes(Sepal.Length, Petal.Length),
               size = 3) + theme_minimal()
  doc <- ph_with(x = doc, value = gg_plot, location = ph_location_fullsize() )
}

# add an image ----
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
img.file <- file.path( R.home("doc"), "html", "logo.jpg" )
doc <- ph_with(x = doc, external_img(img.file, 100/72, 76/72), 
  location = ph_location_type(type = "body") )

# add an unordered_list at a specific location ----
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 <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(x = doc, value = ul, 
               location = ph_location_type(type = "body") )

# add an block_list at a specific location ----
bl <- block_list(
  fpar(ftext("hello world", fp_text(bold = TRUE))),
  fpar(
    ftext("hello", fp_text(bold = TRUE, font.size = 30)),
    ftext(" world", prop = fp_text(color = "red", font.size = 30) )
  )
)

doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(x = doc, value = bl, 
               location = ph_location(label = "my_name",
                 left = 2, top = 3, width = 4, height = 4, 
                 bg = "wheat", rotation = 90) 
       )

print(doc, target = "assets/pptx/ph_with_demo.pptx")
## [1] "/private/var/folders/08/2qdvv0q95wn52xy6mxgj340r0000gn/T/RtmpxL4xPQ/Rbuilde8c514012a0d/officer/vignettes/assets/pptx/ph_with_demo.pptx"

Download file ph_with_demo.pptx - view with office web viewer

Remove content from a slide

Use slide_summary() to easily identify shapes in the slide that can be removed.

slide_summary(doc)
##   type id ph_label offx offy cx cy                   text
## 1 body  2  my_name    2    3  4  4 hello worldhello world

In the following example, the shape corresponding to type "body" will be removed from the current slide:

doc <- ph_remove(x = doc, ph_label = "my_name")

Append text sequentially in a shape

Add to an empty new placeholder

ph_empty() will add a new empty placeholder in the current slide.

##   type id              ph_label     offx offy       cx       cy text
## 1 body  2 Content Placeholder 3 5.083333 1.75 4.416667 4.949653

As there is no paragraph in the new shape yet, the function ph_add_par() will be used to add a new paragraph. Then ph_add_text() will be used to add text into that new paragraph.

## [1] "/private/var/folders/08/2qdvv0q95wn52xy6mxgj340r0000gn/T/RtmpxL4xPQ/Rbuilde8c514012a0d/officer/vignettes/assets/pptx/ph_add_text_1.pptx"

Download file ph_add_text_1.pptx - view with office web viewer

Add to an existing placeholder of text

The following code produces a presentation comprised of one text shape containing the text “A first text”.

##   type id              ph_label offx offy cx       cy         text
## 1 body  2 Content Placeholder 2  0.5 1.75  9 4.949653 A first text

Since there is now a paragraph in the new shape, ph_add_par() will be used to add another paragraph and ph_add_text() then has to be used to add text into the last paragraph of the shape.

## [1] "/private/var/folders/08/2qdvv0q95wn52xy6mxgj340r0000gn/T/RtmpxL4xPQ/Rbuilde8c514012a0d/officer/vignettes/assets/pptx/ph_add_text_2.pptx"

Download file ph_add_text_2.pptx - view with office web viewer

Resources

Len Kiefer wrote two very good blog posts about officer, he is providing nice examples with the corresponding R code:

Eric Nanz gave a short presentation about using officer in the Advanced R Markdown workshop held at the 2019 RStudio conference: