Sablon.DOM.Model (sablon v0.4.3)

An in-memory model of the whole .docx package.

Like Sablon.XML.Document, a model is process local: build it, render with it and serialise it in the same process.

Every part is read once and kept for the duration of a render: XML parts as Sablon.XML.Document trees, everything else as raw binaries. Parts are mutated in place while operations are evaluated - new relationships, media files and list definitions all end up here - and the model is finally serialised back into a ZIP archive.

Summary

Types

content()

t()

Functions

add_content_type(model, extension, type)

Registers a default content type for extension.

add_list_definition(model, style)

Creates a new list definition using the given paragraph style.

add_media(model, name, data, rel_attr)

Adds a file to word/media and creates a relationship pointing at it.

add_relationship(model, rel_attr)

Adds a relationship to the current part's .rels file, returning its rId.

content(model, name)

The content of a part, or nil when it does not exist.

create_entry_if_not_exist(model, name, init_content \\ "")

Creates a part from init_content unless it already exists.

current_entry(model)

The part currently being processed.

drop(model)

Discards the model and every document it holds.

entries(model)

All parts of the package, in archive order.

entry_names(model)

The names of all parts, in archive order.

find_relationship_by(model, attribute, value, entry \\ nil)

Finds a relationship of entry (the current part by default) by attribute value. Returns nil when the part has no relationships file.

from_file(path)

Reads a .docx file into a model.

handler(model, name)

The handler module responsible for a part, or nil.

has_entry?(model, name)

Returns true when the package contains name.

image_rid(model, ref, entry)

The rId an image was given inside entry, or nil.

image_rids(model, ref)

All parts an image has been added to, as a map of entry name to rId.

new(entries)

Builds a model from ordered {entry_name, content} pairs.

put_content(model, name, content)

Stores the content of a part, appending it to the archive when it is new.

put_current_entry(model, name)

Sets the part currently being processed.

put_image_rid(model, ref, entry, rid)

Records the rId an image was given inside entry.

zip_entries(model)

Serialises the model back into ordered {name, binary} ZIP entries.

Types

content()

@type content() :: Sablon.XML.Document.t() | binary()

t()

@type t() :: %Sablon.DOM.Model{store: Sablon.XML.Store.t()}

Functions

add_content_type(model, extension, type)

@spec add_content_type(t(), binary(), binary()) :: :ok

Registers a default content type for extension.

add_list_definition(model, style)

@spec add_list_definition(t(), binary()) :: Sablon.DOM.Numbering.Definition.t()

Creates a new list definition using the given paragraph style.

add_media(model, name, data, rel_attr)

@spec add_media(t(), binary(), binary(), Sablon.Props.t() | map() | keyword()) ::
  binary()

Adds a file to word/media and creates a relationship pointing at it.

Existing media files are never overwritten: a numeric prefix is added to the name instead.

add_relationship(model, rel_attr)

@spec add_relationship(t(), Sablon.Props.t() | map() | keyword()) :: binary()

Adds a relationship to the current part's .rels file, returning its rId.

content(model, name)

@spec content(t(), binary()) :: content() | nil

The content of a part, or nil when it does not exist.

create_entry_if_not_exist(model, name, init_content \\ "")

@spec create_entry_if_not_exist(t(), binary(), binary()) :: :ok

Creates a part from init_content unless it already exists.

current_entry(model)

@spec current_entry(t()) :: binary() | nil

The part currently being processed.

drop(model)

@spec drop(t()) :: :ok

Discards the model and every document it holds.

Optional, but worth calling in a long lived process that renders many documents.

entries(model)

@spec entries(t()) :: [{binary(), content()}]

All parts of the package, in archive order.

entry_names(model)

@spec entry_names(t()) :: [binary()]

The names of all parts, in archive order.

find_relationship_by(model, attribute, value, entry \\ nil)

@spec find_relationship_by(t(), binary(), binary(), binary() | nil) ::
  Sablon.XML.Node.t() | nil

Finds a relationship of entry (the current part by default) by attribute value. Returns nil when the part has no relationships file.

from_file(path)

@spec from_file(Path.t()) :: t()

Reads a .docx file into a model.

handler(model, name)

@spec handler(t(), binary()) :: module() | nil

The handler module responsible for a part, or nil.

has_entry?(model, name)

@spec has_entry?(t(), binary()) :: boolean()

Returns true when the package contains name.

image_rid(model, ref, entry)

@spec image_rid(t(), reference(), binary()) :: binary() | nil

The rId an image was given inside entry, or nil.

image_rids(model, ref)

@spec image_rids(t(), reference()) :: %{required(binary()) => binary()}

All parts an image has been added to, as a map of entry name to rId.

new(entries)

@spec new([{binary(), binary()}]) :: t()

Builds a model from ordered {entry_name, content} pairs.

put_content(model, name, content)

@spec put_content(t(), binary(), content()) :: :ok

Stores the content of a part, appending it to the archive when it is new.

put_current_entry(model, name)

@spec put_current_entry(t(), binary() | nil) :: :ok

Sets the part currently being processed.

put_image_rid(model, ref, entry, rid)

@spec put_image_rid(t(), reference(), binary(), binary()) :: :ok

Records the rId an image was given inside entry.

zip_entries(model)

@spec zip_entries(t()) :: [{binary(), binary()}]

Serialises the model back into ordered {name, binary} ZIP entries.