# Basic Usage

library(ggplot2)
library(r2pptx)

Let’s go through how to make a basic presentation using r2pptx!

r2pptx leverages the power of the officer package and the ease of use of PowerPoint templates to form a simple and easy to use API to create PowerPoint slide decks straight from R. Therefore, the first thing we need to do is to choose a PowerPoint template. This is a normal .pptx file that has the template we want in Slide Master. By default, r2pptx uses the default template in officer, which seems like a slight variation on the default Microsoft PowerPoint template.

Let’s start by creating a presentation.

presentation <- new_presentation()
print(presentation)
#> Presentation with 0 slides.
print(template_path(presentation))
#> [1] "/Library/Frameworks/R.framework/Versions/4.1-arm64/Resources/library/officer/template/template.pptx"

We can see this is an empty presentation with the template path set to the default officer template. What’s in this template? We can check easily using some utility functions.

get_layouts(presentation)
#>              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

This template has seven different layouts. That’s good to know, but it doesn’t help us entirely figure out which layout to use for which purpose. Let’s keep going!

layouts <- get_layouts(presentation)\$layout
for (layout in layouts) {
plot_layout(presentation, layout)
title(main = layout)
}

Now we can see for each slide layout what options we have to use as placeholders! Knowing this, we can move forward and start constructing our presentation!

In r2pptx syntax, presentations are made up of slides which are made up of elements. elements represent anything we want to add to the deck – text, plots, images, tables, etc. Anything compatible with the officer package works here!

We start out making a title slide with a title and subtitle. We give elements for the title and subtitle as arguments to the new_slide() function. And we give “Title Slide” as the layout name, per the information from above.

title_slide <- new_slide(
layout = "Title Slide",
elements = list(
new_element(key = "Title 1", value = "The title"),
new_element(key = "Subtitle 2", value = "The subtitle")
)
)
print(title_slide)
#> Slide with layout Title Slide and 2 elements:
#> -  character
#> -  character

elements have two arguments. The key tells R where to place the element. Currently, this only supports a placeholder label. Placeholder lables are the name of placeholders, which are the objects in a PowerPoint slide layout (as seen above). Future development may allow other location specifications, such as giving x and y positions.

Now we add the title slide to our presentation.

presentation <- presentation + title_slide
print(presentation)
#> Presentation with 1 slides.

Easy!

Let’s add another slide with a ggplot. This time, we’ll add the elements to the slide rather than initializing the slide with elements.

# create the slide object
plot_slide <- new_slide(layout = "Title and Content")
print(plot_slide)
#> Slide with layout Title and Content and 0 elements:
#> -

# create an element for the title element
title_element <- new_element(key = "Title 1", value = "A plot")

# create a ggplot
cars_plot <- ggplot(mtcars, aes(x = mpg, y = cyl)) +
geom_point()
# create an element for the plot
plot_element <- new_element(key = "Content Placeholder 2", value = cars_plot)

plot_slide <- plot_slide +
title_element +
plot_element
print(plot_slide)
#> Slide with layout Title and Content and 2 elements:
#> -  character
#> -  gg

presentation <- presentation +
plot_slide
print(presentation)
#> Presentation with 2 slides.

And then we can write the presentation to PowerPoint.

ppt_path <- tempfile(fileext = ".pptx")
write_pptx(presentation, ppt_path)
if (interactive()) system(paste("open", ppt_path))

And you have a slide deck! Congrats!