Sablon (sablon v0.4.3)

Copy Markdown View Source

A document template processor for Word .docx files.

Templates are ordinary Word documents sprinkled with MailMerge fields, so they are written in Word itself and keep the formatting defined there.

template = Sablon.template("template.docx")

Sablon.render_to_file(template, "output.docx", %{
  title: "Fabulous Document",
  technologies: ["Ruby", "Elixir", "HTML"]
})

Fields

  • «=title» inserts a value, «=post.title» looks up a nested one
  • «items:each(item)» … «items:endEach» repeats content
  • «value:if» … «value:elsIf(...)» … «value:else» … «value:endIf»
  • «@figure:start» … «@figure:end» fills a placeholder image
  • «comment» … «endComment» drops content from the output

Content types

Values are inserted as plain text unless wrapped, either with Sablon.content/3 or with a typed context key:

%{
  body: Sablon.content(:html, "<p>Hello</p>"),
  "word_ml:footer" => "<w:p><w:r><w:t>Bye</w:t></w:r></w:p>",
  figure: Sablon.content(:image, "logo.png", properties: [width: "2cm", height: "2cm"])
}

This is an Elixir port of the Ruby gem sablon.

Summary

Functions

configure(fun)

Runs fun so it can customise the global configuration.

content(type, value, options \\ [])

Wraps a value in a content type.

render_to_file(template, output_path, context, properties \\ %{})

Renders template with context and writes the result to output_path.

render_to_string(template, context, properties \\ %{})

Renders template with context and returns the .docx binary.

template(path)

Points at a template on disk.

Functions

configure(fun)

@spec configure((module() -> any()) | (-> any())) :: any()

Runs fun so it can customise the global configuration.

The function is called with the Sablon.Configuration module, which is also usable directly.

Sablon.configure(fn config ->
  config.register_html_tag(:mark, :inline, properties: [highlight: "yellow"])
end)

content(type, value, options \\ [])

@spec content(atom(), term(), keyword() | map()) :: struct()

Wraps a value in a content type.

Sablon.content(:html, "<p>Hi</p>")
Sablon.content(:image, "logo.png", properties: [width: "2cm", height: "2cm"])

render_to_file(template, output_path, context, properties \\ %{})

@spec render_to_file(
  Sablon.Template.t(),
  Path.t(),
  map() | keyword(),
  map() | keyword()
) :: :ok

Renders template with context and writes the result to output_path.

render_to_string(template, context, properties \\ %{})

@spec render_to_string(Sablon.Template.t(), map() | keyword(), map() | keyword()) ::
  binary()

Renders template with context and returns the .docx binary.

template(path)

@spec template(Path.t()) :: Sablon.Template.t()

Points at a template on disk.