Layout API Reference¶

Reference for the layout renderer system and custom layout development.

Layout Renderer Interface¶

All layout renderers implement the LayoutRenderer protocol:

from typing import Protocol
from pptx.slide import Slide
from slidegen.theming import Theme

class LayoutRenderer(Protocol):
    def render(
        self,
        slide: Slide,
        data: dict,
        presentation: Presentation
    ) -> None:
        """Render content to a slide."""
        ...

Built-in Layouts¶

TitleLayoutRenderer¶

Renders title slides with title and optional subtitle.

Registered as: "title"

SectionHeaderLayoutRenderer¶

Renders full-slide section dividers.

Registered as: "section_header"

BulletListLayoutRenderer¶

Renders slides with title and bullet points.

Registered as: "bullet_list"

TwoColumnLayoutRenderer¶

Renders side-by-side content.

Registered as: "two_column"

ComparisonLayoutRenderer¶

Renders before/after comparisons.

Registered as: "comparison"

ImageLayoutRenderer¶

Renders title with image.

Registered as: "image"

ChartLayoutRenderer¶

Renders data visualizations.

Registered as: "chart"

TableLayoutRenderer¶

Renders data tables.

Registered as: "table"

QuoteLayoutRenderer¶

Renders large centered quotes.

Registered as: "quote"

BlankLayoutRenderer¶

Renders empty slides (placeholder).

Registered as: "blank"

Layout Registry¶

The LayoutRegistry manages available layout renderers:

from slidegen.core.registry import LayoutRegistry

registry = LayoutRegistry()

# Get a renderer
renderer = registry.get_renderer("title")

# Check if layout exists
if registry.has_layout("custom_layout"):
    renderer = registry.get_renderer("custom_layout")

Custom Layouts¶

To create a custom layout, implement the LayoutRenderer protocol:

from pptx.slide import Slide
from pptx.presentation import Presentation
from slidegen.layouts.base import LayoutRenderer
from slidegen.theming import Theme

class CustomLayoutRenderer(LayoutRenderer):
    def render(
        self,
        slide: Slide,
        data: dict,
        presentation: Presentation
    ) -> None:
        """Render custom layout."""
        # Access slide data
        title = data.get("title", "")

        # Create shapes on slide
        # ... your rendering logic ...

        # Apply theme
        # ... theme application ...

Register your custom layout:

from slidegen import SlideGenerator
from slidegen.core.registry import LayoutRegistry

gen = SlideGenerator()

# Register custom layout
gen.registry.register("custom_layout", CustomLayoutRenderer())

# Use in schema
schema = {
    "presentation": {
        "slides": [
            {
                "layout": "custom_layout",
                "title": "Custom Slide"
            }
        ]
    }
}

gen.from_dict(schema)
gen.build("output.pptx")

Layout Data Structure¶

Each layout receives a data dictionary with layout-specific properties:

Title Layout¶

data = {
    "layout": "title",
    "title": "Main Title",
    "subtitle": "Subtitle"  # Optional
}

Bullet List Layout¶

data = {
    "layout": "bullet_list",
    "title": "Slide Title",
    "bullets": [
        "Point 1",
        "Point 2",
        {
            "text": "Nested point",
            "level": 1
        }
    ]
}

Chart Layout¶

data = {
    "layout": "chart",
    "title": "Chart Title",
    "chart": {
        "type": "line",
        "data": {
            "labels": ["Q1", "Q2"],
            "values": [100, 120]
        }
    }
}

Positioning Constants¶

Layouts use consistent positioning constants:

from slidegen.layouts.base import (
    TITLE_TOP,
    TITLE_HEIGHT,
    CONTENT_TOP,
    CONTENT_HEIGHT,
    MARGIN_LEFT,
    MARGIN_RIGHT
)