feat: change defaults of master and layout arg in add_slide(), add `layout_default()`(#635) #644

markheckmann · 2025-03-29T12:30:12Z

Summary

add_slide(): remove default settings for args layout and master
layout_default(): new function to set a default layout for add_slide()

revdeps: Luckily, there are only 2 revdep problems, both easy to fix (however, 11 pkgs failed to check). Please find the complete revdep results at the bottom. Once this PR is accepted, I am happy to submit patch PRs for both packages (flextable & autoslider.core) affected by the {officer} 0.6.9 release, if you like.

Changes

1. `add_slide()`: removing default settings for args `layout` and `master`

add_slide() requires arg layout now
arg master is only required, if the layout is not unique across masters

before

x <- read_pptx() |> add_slide() # uses defaults only matching the pptx template

after

x <- read_pptx() |> add_slide()
> Error in `add_slide()`:
> ! `layout` is `NULL`
> ✖ Either pass a `layout` or set a default layout via `layout_default()`

^{Created on 2025-03-29 with reprex v2.0.2}

2. `layout_default()` to set (and unset) a default layout for `add_slide()`

x <- read_pptx()|> 
  add_slide("Title Slide") |> 
  layout_default("Two Content") |> 
  add_slide() |> 
  add_slide() |> 
  layout_default("Title and Content") |> 
  add_slide() |> 
  add_slide()

print.rpptx now indicates if a default layout is set:

x
#> pptx document with 5 slides
#> Available layouts and their associated master(s):
#> (*) = Default layout
#>              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

^{Created on 2025-03-29 with reprex v2.0.2}

revdep checks

## revdepcheck results

We checked 71 reverse dependencies, comparing R CMD check results across CRAN and dev versions of this package.

 * We saw 2 new problems
 * We failed to check 11 packages

Issues with CRAN packages are summarised below.

### New problems
(This reports the first line of each new failure)

* autoslider.core
  checking examples ... ERROR
  checking tests ...
  checking running R code from vignettes ...

* flextable
  checking examples ... ERROR
  checking tests ...

### Failed to check

* esquisse    (NA) 
* GWSDAT      (NA)
* jsmodule    (NA)
* reappraised (NA)
* reservr     (NA)
* robmedExtra (NA)
* rvg         (NA)
* statgenGWAS (NA)
* TestAnaAPP  (NA)
* ubiquity    (NA)
* visvaR      (NA)

I checked the source code of all packages listed under failed to check manually to see if add_slide() was used without an explicit layout name. This was not the case, so there should be no problems in these packages.

`layout_default()` sets a default layout for `add_slide()`

`print.rpptx` now uses pluralization and marks the default layout (if set by `layout_default()`) with an asterisk (davidgohel#635)

codecov-commenter · 2025-03-29T12:34:58Z

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

Codecov Report

Attention: Patch coverage is 94.93671% with 4 lines in your changes missing coverage. Please review.

Project coverage is 86.47%. Comparing base (a28db25) to head (a6d3d2e).

Files with missing lines	Patch %	Lines
R/pptx_layout_helper.R	91.17%	3 Missing ⚠️
R/read_pptx.R	94.73%	1 Missing ⚠️

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #644      +/-   ##
==========================================
+ Coverage   86.42%   86.47%   +0.04%     
==========================================
  Files          43       43              
  Lines        7235     7275      +40     
==========================================
+ Hits         6253     6291      +38     
- Misses        982      984       +2

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

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

davidgohel · 2025-04-10T07:11:03Z

@markheckmann thanks, I will not be able to work on the PR this week, hopefully next week

I will try to avoid this breaking changes. We can totally afford changing flextable or autoslider.core but there are lot of scripts in companies that will be affected and we must not break their codes.

markheckmann · 2025-04-12T10:30:44Z

okay, then I suggest the following modification to avoid potential breaking changes for user code. @davidgohel Please let me know, in case you have any doubts or further suggestions

New approach

We maintain the current add_slide() behavior - which uses layout = "Title and Content" and master = "Office Theme" as defaults - by setting "Title and Content" as the default layout during read_pptx(), if the layout exists. Then, the behavior of add_slide() would be same as before. The only difference would be, that the layout default is not part of the add_slide() function signature anymore, but is set inside the rpptx object when calling read_pptx().

This approach should not cause any revdep issues and also no problem in user code. I will make the changes and check the former.

To avoid breaking changes in old code, `read_pptx()` automatically sets the default layout `"Slide and Content"`, if it exists. This makes sure, that the behavior of `add_slide()` does not change.

markheckmann · 2025-04-12T15:00:11Z

Updated PR

Hi @davidgohel , I updated the PR as follows:

Summary

add_slide(): default settings for args layout and master removed, while adding default layout "Title And Content" (if it exists) to rpptx object to keep default behavior of add_slide()
layout_default(): new function to set a remove default layout. The default layout is used by add_slide()
No revdep issue any more. Due to the updates, the previous issues (for flextable and autoslider.core) have disappeared. There should be no breaking changes in user code now.

Changes

1. `add_slide()`: removing default settings for args `layout` and `master`. Makes use of default layout.

add_slide() requires arg layout if no default layout is set
arg master is only required, if the layout is not unique across masters
calling read_pptx()will set layout "Title And Content" as default layout, if it exists. This avoids breaking changes in user code.

library(officer)

# read_pptx() sets default layout  to "Title and Content" (if layout exists like in the pptx template)
x <- read_pptx()

# the default layout is marked by an asterisk ...
x
#> pptx document with 0 slides
#> Available layouts and their associated master(s):
#> (*) = Default layout
#>              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

# ... and used by add_slide() so its default behavior remains the same: a slide with layout "Title and Content" is added
x <- x |> add_slide()

# Better error message if layout does not exist
x |> add_slide("xxx")
#> Error:
#> ! Layout "xxx" does not exist
#> ℹ See `layout_summary()` for available layouts.

^{Created on 2025-04-12 with reprex v2.1.1}

2. `layout_default()` to set (and unset) a default layout used by `add_slide()`

library(officer)

x <- read_pptx()|>
  add_slide() |>  # uses default layout "Title and Content" => same behavior as before, avoids breaking changes for user
  add_slide("Title Slide") |> # add slide with layout "Title Slide"
  add_slide() |>  # again add slide with default layout "Title and Content"
  layout_default("Comparison") |>  # change default layout to "Comparison"
  add_slide() # add slide with layout "Comparison"

# note that comparison is marked as default now
x
#> pptx document with 4 slides
#> Available layouts and their associated master(s):
#> (*) = Default layout
#>              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

x <- x |> layout_default()  # remove default

# Without a default layout, the layout arg is required
x |> add_slide() 
#> Error in `add_slide()`:
#> ! `layout` is `NULL`
#> ✖ Either pass a `layout` or set a default layout via `layout_default()`

# passig a layout adds a slide as usual, if no default is iset
x <- x |> add_slide("Comparison")

^{Created on 2025-04-12 with reprex v2.1.1}

3. revdep checks

The behavior of add_slide() has not changed if a layout named "Title and Content" exists (as in the package pptx template). Hence, there should be not backward compatibility issue.

## revdepcheck results

We checked 73 reverse dependencies, comparing R CMD check results across CRAN and dev versions of this package.

 * We saw 0 new problems
 * We failed to check 4 packages

Issues with CRAN packages are summarised below.

### Failed to check

* esquisse    (NA)
* reservr     (NA)
* rvg         (NA)
* statgenGWAS (NA)

I checked the source code of all packages listed under failed to check manually. There should be no problems in these packages.

`add_slide()` now throws a deprecation warning, if no layout is specified (either via the `layout` arg or by setting a default layout). It then uses the `layout` arg's former default value (`"Title and Content"`). This makes sure, that the behavior of `add_slide()` does not change and avoids backward compatibility issues

markheckmann · 2025-04-20T17:53:10Z

PR Update No. 2

@davidgohel I gave it a second thought and what I suggested is no good idea. I think the proper way to do it is as follows.

set the default values for args layout and master in add_slide() to NULL
issue a deprecation warning if add_slide() is called without specifying a layout to inform the user about the changes
for now, still use the old layout arg's default value ("Title and Content") in case layout is NULL, to avoid breaking changes

So these are the complete changes:

Changes

1. add_slide(): removing default settings for args layout and master.

library(officer)

x <- read_pptx()
x <- add_slide(x)  # still works but with deprecation warning
#> Warning in add_slide(x): Calling `add_slide()` without specifying a `layout` is deprecated.
#>  Please pass a `layout` or use `layout_default()` to set a default.
#>  => I will now continue with the former `layout` default "Title and Content" for backwards compatibility...

# new expected way:
x <- add_slide(x, "Title and Content") # pass a layout
x <- x |>
  layout_default("Title and Content") |> # set a default layout
  add_slide()

^{Created on 2025-04-20 with reprex v2.1.1}

2. layout_default() to set (and unset) a default layout used by add_slide()

library(officer)

x <- read_pptx() |>
  layout_default("Title and Content") |> # set default layout to "Title and Content"
  add_slide() |> # add slide with layout "Title and Content"
  layout_default("Comparison") |> # change default layout to "Comparison"
  add_slide()

# note that layout "Comparison" is marked as default now
x
#> pptx document with 2 slides
#> Available layouts and their associated master(s):
#> (*) = Default layout
#>              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

x <- x |> layout_default() # remove default

# Without a default layout, again a deprecation warning is raised.
x |> add_slide()
#> Warning in add_slide(x): Calling `add_slide()` without specifying a `layout` is deprecated.
#>  Please pass a `layout` or use `layout_default()` to set a default.
#>  => I will now continue with the former default layout "Title and Content" for backwards compatibility...

#> pptx document with 3 slides
#> Available layouts and their associated master(s):
#>              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

^{Created on 2025-04-20 with reprex v2.1.1}

3. revdep checks

As the behavior of add_slide() has not changed - except for the deprecation warning - there should be not backward compatibility issue.

We checked 75 reverse dependencies, comparing R CMD check results across CRAN and dev versions of this package.

 * We saw 0 new problems
 * We failed to check 4 packages

Issues with CRAN packages are summarised below.

### Failed to check

* esquisse    (NA)
* reservr     (NA)
* rvg         (NA)
* statgenGWAS (NA)

davidgohel · 2025-05-13T19:36:50Z

Really appreciate the PR, it’s very well done!

Sorry for the delayed response — I finally had time to review it.

markheckmann added 16 commits December 31, 2024 23:56

add manual gha trigger

c15cc89

Merge branch 'davidgohel:master' into master

5acaedd

Merge branch 'davidgohel:master' into master

4cc9cc5

Merge branch 'davidgohel:master' into master

d7399cd

Merge branch 'davidgohel:master' into master

a03904e

get_layout() gains layout_by_id arg

86f1764

use get_layout() in add_slide() to get layout

27cab07

add explicit layout param in add_slide()

b9cb2cb

update NEWS

302a2e4

bump version

f1fc399

new tests for get_layout() and add_slide()

cedbfd8

remove master arg from examples where not necessary

30b72cb

add layout_default() to set a default layout (davidgohel#635)

d212569

`layout_default()` sets a default layout for `add_slide()`

print.rpptx indicates default layout (davidgohel#635)

1d38eb8

`print.rpptx` now uses pluralization and marks the default layout (if set by `layout_default()`) with an asterisk (davidgohel#635)

fix test, add missing pptx

7a01ae6

add test, improve plot_layout_properties() docs

f337ba6

add test for is_layou_info()

7c28118

markheckmann added 2 commits April 12, 2025 15:49

avoid any breaking changes in old code (davidgohel#635 comments)

dc9b5d4

To avoid breaking changes in old code, `read_pptx()` automatically sets the default layout `"Slide and Content"`, if it exists. This makes sure, that the behavior of `add_slide()` does not change.

add test in layout_default (as_list = TRUE)

f7ec7be

markheckmann added 2 commits April 12, 2025 17:12

remove line that cannot be reached

d87fe37

davidgohel merged commit ee4ca76 into davidgohel:master May 13, 2025
4 checks passed

markheckmann deleted the 635_add_slide_default_args branch May 17, 2025 10:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: change defaults of master and layout arg in add_slide(), add `layout_default()`(#635) #644

feat: change defaults of master and layout arg in add_slide(), add `layout_default()`(#635) #644

Uh oh!

markheckmann commented Mar 29, 2025 •

edited

Loading

Uh oh!

codecov-commenter commented Mar 29, 2025 •

edited

Loading

Uh oh!

davidgohel commented Apr 10, 2025

Uh oh!

markheckmann commented Apr 12, 2025 •

edited

Loading

Uh oh!

markheckmann commented Apr 12, 2025 •

edited

Loading

Uh oh!

markheckmann commented Apr 20, 2025 •

edited

Loading

Uh oh!

davidgohel commented May 13, 2025

Uh oh!

Uh oh!

Uh oh!

feat: change defaults of master and layout arg in add_slide(), add layout_default()(#635) #644

feat: change defaults of master and layout arg in add_slide(), add layout_default()(#635) #644

Uh oh!

Conversation

markheckmann commented Mar 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

1. add_slide(): removing default settings for args layout and master

2. layout_default() to set (and unset) a default layout for add_slide()

revdep checks

Uh oh!

codecov-commenter commented Mar 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

davidgohel commented Apr 10, 2025

Uh oh!

markheckmann commented Apr 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markheckmann commented Apr 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Updated PR

Summary

Changes

1. add_slide(): removing default settings for args layout and master. Makes use of default layout.

2. layout_default() to set (and unset) a default layout used by add_slide()

3. revdep checks

Uh oh!

markheckmann commented Apr 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Update No. 2

Changes

1. add_slide(): removing default settings for args layout and master.

2. layout_default() to set (and unset) a default layout used by add_slide()

3. revdep checks

Uh oh!

davidgohel commented May 13, 2025

Uh oh!

Uh oh!

Uh oh!

feat: change defaults of master and layout arg in add_slide(), add `layout_default()`(#635) #644

feat: change defaults of master and layout arg in add_slide(), add `layout_default()`(#635) #644

markheckmann commented Mar 29, 2025 •

edited

Loading

1. `add_slide()`: removing default settings for args `layout` and `master`

2. `layout_default()` to set (and unset) a default layout for `add_slide()`

codecov-commenter commented Mar 29, 2025 •

edited

Loading

markheckmann commented Apr 12, 2025 •

edited

Loading

markheckmann commented Apr 12, 2025 •

edited

Loading

1. `add_slide()`: removing default settings for args `layout` and `master`. Makes use of default layout.

2. `layout_default()` to set (and unset) a default layout used by `add_slide()`

markheckmann commented Apr 20, 2025 •

edited

Loading