Podium.Template (Podium v0.3.0)

Copy Markdown View Source

Read-only structural inspection of a template package.

inspect/1 reads a .pptx/.potx package and reports what is actually in it: the slide size, the slide masters, and for every slide layout its name, its type, the master it sits on, and every placeholder it defines with the bounding box that placeholder resolves to.

template = Podium.Template.inspect("priv/brand/skeleton.pptx")

for {index, layout} <- Enum.sort(template.layouts) do
  IO.puts("#{index}: #{layout.name}")

  for ph <- layout.placeholders do
    IO.puts("   {#{ph.type}, #{ph.idx}} #{ph.name}")
  end
end

The {type, idx} pair reported for a placeholder is what Podium.set_placeholder/3, Podium.set_picture_placeholder/3, Podium.set_chart_placeholder/6 and Podium.set_table_placeholder/5 take to address that placeholder on a slide built on the layout.

Placeholder attribute defaults

A <p:ph/> element without a type attribute means "obj", and one without an idx attribute means 0. Inspection fills both in, so a placeholder's type is always a string and its idx always an integer.

Box inheritance

A layout placeholder that carries its own <a:xfrm> uses it. One that does not inherits the box of the master placeholder found by type: ctrTitle and title inherit from the master's title; body, subTitle, obj, chart, tbl, pic, clipArt, dgm and media inherit from the master's body; dt, ftr and sldNum inherit from the master placeholder of the same type. This is how PowerPoint resolves it. box is nil when nothing in the chain has a position.

Summary

Types

A way of naming one placeholder on a layout: the {type, idx} pair inspection reports, a %Podium.Placeholder{}, or any map carrying :type and :idx. A nil type means "obj" and a nil idx means 0.

t()

Functions

The inspection of the template bundled with Podium, cached in :persistent_term because its parts never change.

Inspects a template package and returns a %Podium.Template{}.

The placeholder on layout_index addressed by {type, idx}, or nil when the layout has no placeholder with that idx or its type is a different one.

The placeholder on layout_index with the given idx whatever its type, or nil. Callers that need to tell "no such idx" apart from "wrong type" use this rather than placeholder/3.

The first placeholder of the given type on layout_index, or nil. Used to find the layout's footer, date and slide number chrome.

Types

box()

@type box() :: %{x: integer(), y: integer(), w: integer(), h: integer()}

layout()

@type layout() :: %{
  index: pos_integer(),
  name: String.t() | nil,
  type: String.t() | nil,
  master_index: pos_integer() | nil,
  placeholders: [placeholder()]
}

placeholder()

@type placeholder() :: %{
  type: String.t(),
  idx: non_neg_integer(),
  name: String.t() | nil,
  box: box() | nil
}

ref()

@type ref() ::
  {String.t() | nil, non_neg_integer() | nil}
  | %{
      :type => String.t() | nil,
      :idx => non_neg_integer() | nil,
      optional(atom()) => term()
    }

A way of naming one placeholder on a layout: the {type, idx} pair inspection reports, a %Podium.Placeholder{}, or any map carrying :type and :idx. A nil type means "obj" and a nil idx means 0.

t()

@type t() :: %Podium.Template{
  layouts: %{required(pos_integer()) => layout()},
  masters: %{required(pos_integer()) => %{placeholders: [placeholder()]}},
  slide_size: {non_neg_integer(), non_neg_integer()}
}

Functions

bundled()

@spec bundled() :: t()

The inspection of the template bundled with Podium, cached in :persistent_term because its parts never change.

inspect(parts)

@spec inspect(%{required(String.t()) => binary()} | binary()) :: t()

Inspects a template package and returns a %Podium.Template{}.

source is a parts map (%{partname => binary}), a path to a .pptx/.potx file, or the bytes of one.

placeholder(template, layout_index, ref)

@spec placeholder(t(), pos_integer(), ref()) :: placeholder() | nil

The placeholder on layout_index addressed by {type, idx}, or nil when the layout has no placeholder with that idx or its type is a different one.

A nil type in the reference means "obj" and a nil idx means 0, so a definition taken from Podium.Placeholder.placeholders_for/1 can be passed straight in.

placeholder_by_idx(template, layout_index, idx)

@spec placeholder_by_idx(t(), pos_integer(), non_neg_integer()) :: placeholder() | nil

The placeholder on layout_index with the given idx whatever its type, or nil. Callers that need to tell "no such idx" apart from "wrong type" use this rather than placeholder/3.

placeholder_by_type(template, layout_index, type)

@spec placeholder_by_type(t(), pos_integer(), String.t()) :: placeholder() | nil

The first placeholder of the given type on layout_index, or nil. Used to find the layout's footer, date and slide number chrome.