Authoring from a theme

Build a styled document from a theme’s slide layouts, and style new objects using its presets.

A theme already provides the design. Its slide layouts set type, color, geometry, and spacing, and its presets define styles that new objects can reuse. In Keynote, export a presentation that uses the theme. Every document you build from that file starts with the theme’s slide layouts and presets. The functions in creator_studio_doc_format.authoring fill in the placeholders of those slide layouts.

Explore a theme’s slide layouts

summarize_slide_layouts() reports every slide layout by name, with the placeholders you can set in it:

from creator_studio_doc_format.authoring import summarize_slide_layouts
from creator_studio_doc_format.core import KeyxDocument

doc = KeyxDocument.open("themed.keyx")
theme = doc.presentation.theme

for layout, placeholders in summarize_slide_layouts(theme).items():
    print(layout, [p.name for p in placeholders])

For creator_studio_doc_format/examples/fixtures/Tidal_en.keyx, part of the output is:

Title ['TITLE', 'Subtitle']
Title & Bullets ['TITLE', 'BODY', 'Presentation Name', 'SLIDE_NUMBER']
Title, Bullets & Photo ['TITLE', 'BODY', 'Media']
Quote ['Text', 'Text-1']
Blank []

Each placeholder that summarize_slide_layouts returns is a LayoutPlaceholderSummary. The following example prints the ones from the "Title & Bullets" layout:

>>> from pprint import pprint
>>> for placeholder in summarize_slide_layouts(theme)["Title & Bullets"]:
...     pprint(placeholder)
LayoutPlaceholderSummary(name='TITLE',
                         object_case='shape',
                         prompt='Title Text',
                         tag=None)
LayoutPlaceholderSummary(name='BODY',
                         object_case='shape',
                         prompt='Body Level One',
                         tag=None)
LayoutPlaceholderSummary(name='Presentation Name',
                         object_case='shape',
                         prompt='Example Company',
                         tag='Presentation Name')
LayoutPlaceholderSummary(name='SLIDE_NUMBER',
                         object_case='shape',
                         prompt=None,
                         tag=None)

Each summary tells you how to fill in the placeholder:

name

Identifies the placeholder within its layout. You pass it to the function that fills the placeholder.

object_case

Names the kind of object the placeholder holds. An "image" placeholder takes an image, and a text placeholder takes text. For example, the "Title, Bullets & Photo" layout has an image placeholder named "Media". Keynote exports an object the format has no type for, such as a live video, as an image placeholder holding a picture of it. set_slide_placeholder_image() replaces that picture with yours.

prompt

Holds the placeholder text Keynote shows, such as "Title Text". It’s None when the placeholder has no text, as for "SLIDE_NUMBER".

tag

Holds a label that the theme’s designer gives a custom placeholder, such as "Presentation Name". It’s None for a predefined placeholder such as "TITLE". A tagged placeholder’s name is its tag.

Create a slide from a layout

slide_from_layout() creates a slide the way Keynote does when you choose that layout, and returns it for you to add to the document:

from creator_studio_doc_format.authoring import slide_from_layout

slide = slide_from_layout(theme, "Title & Bullets")

Set the placeholders

Which function you use depends on the placeholder’s object_case:

set_slide_placeholder_text()

Fills a text placeholder, which has an object_case of "shape" or "textbox". It takes a string for one paragraph or a list of strings for several. Each paragraph gets the placeholder’s text style.

set_slide_placeholder_image()

Fills an "image" placeholder by pointing its image at a resource. It doesn’t store the image’s bytes. Add them to the resource store first.

Important

slide_from_layout empties only the "TITLE" and "BODY" placeholders. As in Keynote, a tagged placeholder keeps its sample text and an image placeholder keeps its sample photo until you replace them.

The following example sets a slide’s text:

from creator_studio_doc_format.authoring import set_slide_placeholder_text

set_slide_placeholder_text(slide, "TITLE", "Baking Sourdough")
set_slide_placeholder_text(
    slide,
    "BODY",
    ["Feed the starter", "Twice a day"],
    # Sets each line's list level. Every level keeps the placeholder's
    # paragraph style.
    list_levels=[0, 1],
)
# Passing None clears the tagged placeholder's sample text.
set_slide_placeholder_text(slide, "Presentation Name", None)

The following example adds an image’s bytes, then sets the image:

from pathlib import Path

from creator_studio_doc_format.authoring import set_slide_placeholder_image
from creator_studio_doc_format.core import IndirectResource, Resource, Size

photo = slide_from_layout(theme, "Title, Bullets & Photo")
filename = doc.resources.unique_filename("cover.png")
doc.resources[filename] = Path("cover.png").read_bytes()
set_slide_placeholder_image(
    photo,
    "Media",
    Resource(indirect=IndirectResource(filename=filename)),
    # The width and height of cover.png, so the image fills the
    # placeholder's mask without stretching.
    size=Size(width=1200, height=792),
)

Build a document from the layouts

The following example replaces a themed document’s slides with ones that use its layouts, and saves the result as a new file:

from creator_studio_doc_format.validation import validate_document

sections = [
    ("Baking Sourdough", ["Feed the starter", "Shape the loaf"]),
    ("Baking Day", ["Preheat the oven"]),
]

doc = KeyxDocument.open("themed.keyx")
theme = doc.presentation.theme

slides = []
for title, bullets in sections:
    slide = slide_from_layout(theme, "Title & Bullets")
    set_slide_placeholder_text(slide, "TITLE", title)
    set_slide_placeholder_text(slide, "BODY", bullets)
    set_slide_placeholder_text(slide, "Presentation Name", None)
    slides.append(slide)

# Replacing the slides in place keeps the theme, its presets, and everything
# else in the document.
doc.presentation.slides = slides
doc.save("presentation.keyx", pre_save_hooks=[validate_document])

Style new objects using presets

When no layout fits, style the objects you create using the theme’s presets. A theme stores its style and appearance as presets, such as the paragraph style for body text. You can apply one to a model instance. To see what a preset provides, resolve it with PresetRegistry.

The following example finds the theme’s Body style and prints the font and size it provides:

from creator_studio_doc_format.core import PresetRegistry

styles = {
    style.name: style.properties.preset_identifier
    for style in doc.presentation.stylesheet.paragraph_styles
    if style.properties.preset_identifier
}
registry = PresetRegistry(doc.presets)
font = registry.resolved_properties(styles["Body"])["character_properties"]
print(font["font_name"], font["font_size"])

A style property that a preset can supply is often an Override field. An Override keeps an omitted property apart from an explicit null.

Important

Assigning None to an Override field clears it. For example, shape.shadow = None removes a shadow that the shape’s preset gives it. On a field that isn’t an Override, such as Shape.fill, None omits the property.

The get() method of an Override returns None both for an omitted property and for a null. To tell them apart, read is_not_set or is_cleared.