make use of the term id consistent across functions layout_properties(), ph_location_type(), and plot_layout_properties()

[markheckmann]

Hi @davidgohel ,

the different usages of the term/argument id across layout_properties(), ph_location_type(), and plot_layout_properties()got me confused at first (and maybe others too). You also referred to its use in ph_location_type() as a design error here. For this reason, I would like to suggest the changes at the bottom.

Please let me know what you think. I am happy to PR :)

---

SITUATION

NB: The following comprehensive elaborations serve to document the current state and to help my own understanding.

Currently, the notion of id regarding phs is slightly ambiguous. There are several places where id is used with different meanings.

1. layout_properties(): returns an id column, with a unique id for each placeholder. The id is unique across a slide/layout, starts at 2, but is not necessarily consecutive (see technical note below). The value cannot be changed by the user. It is assigned by PowerPoint when a new placeholder is added to a layout.

> layout_properties(x, "Two Content")
    master_name        name   type id                   ph_label   ...
16 Office Theme Two Content  title  2                    Title 1
17 Office Theme Two Content   body  3      Content Placeholder 2
18 Office Theme Two Content   body  4      Content Placeholder 3
19 Office Theme Two Content     dt  5         Date Placeholder 4
20 Office Theme Two Content    ftr  6       Footer Placeholder 5
21 Office Theme Two Content sldNum  7 Slide Number Placeholder 6

2. plot_layout_properties(): with labels = FALSE plots an id for each placeholder. The id in the plot, however, has a different meaning than in the layout_properties() output despite the similar function names. Here, id is a generated sequential index number along phs of the same type (e.g. body).

3. ph_location_type(): the argument id here has the same meaning as in plot_layout_properties(). It is used for disambiguation between placeholders of the same type (e.g. body)

---

Suggestions

To harmonize the use of the term id across functions, I suggest the following changes:

1. layout_properties(): id remains the unique identifier for a placeholder. IMO, this is what a user would probably expect when reading the term "id". The output gains a new type_idx column. type + type_index make it very clear what they refer to.

   • Technical note: The id is extracted from the p:cNvPr node's id attribute. This node and the placeholder are both children of a shape (most common), group shape, graphic frame, etc. According to the specs (ECMA-376, Part 1, p. 2570), the id attribute must be unique on a slide to be OOXML conformant. (NB: id = 1 is reserved for the main slide's background shape, so added objects start at id=2). As not all shapes etc. in a layout necessarily contain a placeholder, the id may be non-consecutive.
   • Personally, I do not mind what the value of an id is, (starting at 2, not subsequent, etc.) as long as it is unique.

2. ph_location_type(): arg name changes from id to idx (or type_idx) to make clear it is an
   index and not the id column from layout_properties(). The id arg will raise a deprecation warning, but will be preserved alongside idx (or similar) for several versions.

3. plot_layout_properties(): the plot contains all relevant ph information, i.e. labels (red), type + type_idx (blue), unique id (green, i.e. column id from layout_properties()). New args type = T/F and id = T/F. The output from plot_layout_properties(x, "Two Content", labels = T, type = T, id = T, title = T) could then look like this.

4. Introduce a new function ph_location_id(): This one takes the "true" ph id as returned by layout_properties() to reference a placeholder. I consider this a nice addition to the ph_location_* family. It would also come in handy for the use case we discussed before (NB: it's of course also solvable via the type + type_idx combination you suggested, but would be a handy alternative.). For quick interactive development, I would also like using an id and not typing out the label or type + id (index) combo.

[davidgohel]

Hi

OK with your propositions 1, 2, 3 and 4.

[markheckmann]

• Suggestions 1 -3 done via PR consistent use of term id across layout_properties(), ph_location_type(), plot_layout_properties() (#606) #608.
• Suggestion 4 TBD

[davidgohel]

FYI, I did ran a revdepcheck ans all IS ok (~65 dep. Packages). So far so good

[markheckmann]

Suggestion 4 commited in PR #609