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:
nameIdentifies the placeholder within its layout. You pass it to the function that fills the placeholder.
object_caseNames 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.promptHolds the placeholder text Keynote shows, such as
"Title Text". It’sNonewhen the placeholder has no text, as for"SLIDE_NUMBER".tagHolds a label that the theme’s designer gives a custom placeholder, such as
"Presentation Name". It’sNonefor a predefined placeholder such as"TITLE". A tagged placeholder’snameis 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_caseof"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.