location short forms for ph_with() location arg

[markheckmann]

This PR implements location short forms as discussed in #623

NB: @davidgohel I use the styler package to format my code. I accidentally also reformatted a few lines of your code in the file ‎R/ph_location.R using styler. See ‎this commit. If you do not like this format or if you do not want this, please let me know and I will recreate your code's format.

---

The location arg in ph_with now understands location short forms (numeric or string). Short forms are an alternative to passing the location object as returned by the ph_location_* functions. The following short forms exist (also listed in the ph_with() help file).

Location function	Short form	Description
ph_location_left()	"left"	Keyword string
ph_location_right()	"right"	Keyword string
ph_location_fullsize()	"fullsize"	Keyword string
ph_location_type("body", 1)	"body [1]"	String: type + index in brackets (1 if omitted)
ph_location_label("my_label")	"my_label"	Any string not matching a keyword or type
ph_location_id(1)	1	Length 1 integer
ph_location(0, 0, 4, 5)	c(0,0,4,5)	Length 4 numeric, optionally named, c(top=0, left=0, ...)

The output of the two examples below are identical. The first uses the ph_location_* functions, the second their location short form equivalents.

Full form

library(officer)
library(ggplot2)

p1 <- ggplot(mtcars) + geom_point(aes(hp, wt), color = "red")
p2 <- ggplot(mtcars) + geom_point(aes(hp, wt), color = "blue")

x <- read_pptx() |>
  add_slide("Two Content") |>
  ph_with("A title", ph_location_label("Title 1")) |>
  ph_with("Jan. 26, 2025", ph_location_type("dt")) |>
  ph_with(p1, ph_location_type("body", 2)) |>
  ph_with(p2, ph_location_left()) |>
  ph_with("Text overlay", ph_location(3, 4.5, 5, 2)) |> 
  ph_with("Footer", ph_location_id(6)) 
  
file <- tempfile(fileext = ".pptx")
print(x, file)
browseURL(file) # opens file on some systems

^{Created on 2025-01-26 with reprex v2.0.2}

Short form

NB: The short forms is often achieved by just removing the ph_location_* wrapper.

x <- read_pptx() |>
  add_slide("Two Content") |>
  ph_with("A title", "Title 1") |>
  ph_with("Jan. 26, 2025", "dt") |>
  ph_with(p1, "body [2]") |>
  ph_with(p2, "left") |>
  ph_with("Text overlay", c(3, 4.5, 5, 2)) |> 
  ph_with("Footer", 6) 

file <- tempfile(fileext = ".pptx")
print(x, file)
browseURL(file) # opens file on some systems

^{Created on 2025-01-26 with reprex v2.0.2}

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 86.35%. Comparing base (1660aec) to head (f95e7a4).
Report is 1 commits behind head on master.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #632      +/-   ##
==========================================
+ Coverage   86.10%   86.35%   +0.25%     
==========================================
  Files          43       43              
  Lines        7032     7161     +129     
==========================================
+ Hits         6055     6184     +129     
  Misses        977      977              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[davidgohel]

thank you @markheckmann !