Office Open XML document templating library for Elixir.

Ootempl enables programmatic manipulation of Microsoft Word documents (.docx) by replacing placeholders with dynamic content to generate customized documents from templates.

Features

• Load and parse .docx templates
• Replace {{variable}} placeholders with dynamic content
• Support nested data access with dot notation ({{customer.name}})
• Conditional sections with {{if condition}}...{{endif}} syntax
• Dynamic table row generation from list data
• Multi-row table templates for complex layouts
• Replace placeholder images with dynamic content (PNG, JPEG, GIF)
• Automatic image dimension scaling with aspect ratio preservation
• Case-insensitive placeholder matching
• Process headers, footers, footnotes, and endnotes
• Replace placeholders in document properties (title, author, company)
• Preserve Word formatting (bold, italic, fonts, table borders, shading)
• Generate valid .docx output files
• Comprehensive validation and error handling

Basic Usage

Simple Variable Replacement

# Render a template with placeholder replacement
data = %{
  "name" => "John Doe",
  "customer" => %{"email" => "john@example.com"},
  "total" => 99.99
}
Ootempl.render("template.docx", data, "output.docx")
#=> :ok

Struct Support

Elixir structs work seamlessly with render/3. You can pass structs directly without converting them to maps first. Struct fields (atoms) are matched case-insensitively to placeholders.

defmodule Customer do
  defstruct [:name, :email, :address]
end

defmodule Address do
  defstruct [:street, :city, :state, :zip]
end

# Use structs directly in your data
customer = %Customer{
  name: "John Doe",
  email: "john@example.com",
  address: %Address{
    city: "Boston",
    state: "MA",
    zip: "02101"
  }
}

data = %{
  "order_id" => "ORD-12345",
  "customer" => customer
}

# Template can reference struct fields:
# - {{customer.name}} → "John Doe"
# - {{customer.email}} → "john@example.com"
# - {{customer.address.city}} → "Boston"

Ootempl.render("invoice_template.docx", data, "invoice.docx")
#=> :ok

Struct features:

• Nested structs: Access fields multiple levels deep
• Case-insensitive: {{customer.Name}} matches :name field
• Mixed data: Combine structs and maps in the same data structure
• Lists of structs: Use structs in table templates

Table Templates

Table templates automatically duplicate rows based on list data. Template rows are identified by placeholders that reference list items.

# Simple table template
data = %{
  "title" => "Claims Report",
  "claims" => [
    %{"id" => 5565, "amount" => 100.50},
    %{"id" => 5566, "amount" => 250.00}
  ],
  "total" => 350.50
}
Ootempl.render("invoice_template.docx", data, "invoice.docx")
#=> :ok

Template structure in Word document:

| Claim ID          | Amount              |  ← Header (no list placeholders)
| {{claims.id}}     | {{claims.amount}}   |  ← Template row (references "claims" list)
| Total             | {{total}}           |  ← Footer (single value)

Generated output:

| Claim ID  | Amount  |
| 5565      | 100.50  |
| 5566      | 250.00  |
| Total     | 350.50  |

Multi-row templates are supported for complex table layouts:

data = %{
  "orders" => [
    %{"id" => 100, "product" => "Widget", "qty" => 5, "price" => 10.00},
    %{"id" => 101, "product" => "Gadget", "qty" => 3, "price" => 25.00}
  ]
}

Template with two rows per order:

| Order {{orders.id}}                                  |  ← Row 1 of template
| {{orders.qty}}x {{orders.product}} @ ${{orders.price}} each |  ← Row 2 of template

Generated output duplicates both rows for each order:

| Order 100           |
| 5x Widget @ $10.00 each |
| Order 101           |
| 3x Gadget @ $25.00 each |

Hierarchical Table Templates

For nested data structures with parent-child relationships, use block markers ({{#list}}...{{/list}}) in dedicated rows to create multi-level layouts:

data = %{
  "categories" => [
    %{
      "name" => "Electronics",
      "total" => "$300",
      "subtotal" => "$300",
      "items" => [
        %{"desc" => "Phone", "price" => "$200"},
        %{"desc" => "Charger", "price" => "$100"}
      ]
    }
  ]
}

Template structure (marker rows are removed from output):

| {{#categories}} |             |         |  ← Marker row (removed)
| {{name}}        | {{total}}   |         |  ← Header row
| {{#items}}      |             |         |  ← Marker row (removed)
|                 | {{desc}}    | {{price}}|  ← Body row (repeated per child)
| {{/items}}      |             |         |  ← Marker row (removed)
|                 | Subtotal:   | {{subtotal}} | ← Footer row
| {{/categories}} |             |         |  ← Marker row (removed)

Generated output:

| Electronics |       |       |
|             | Phone | $200  |
|             | Charger| $100 |
|             | Subtotal: | $300 |

Block marker features:

• Dedicated rows: Block markers must be in their own rows (removed from output)
• Nested blocks: Support for parent/child iteration with separate data scoping
• Data inheritance: Child rows access both parent and child data fields
• Empty handling: Empty parent list produces no rows; empty children skips body rows

Conditional Sections

Control which sections of your document appear based on data conditions using {{if condition}}...{{endif}} markers. Sections are shown when the condition is truthy and hidden when falsy.

# Template structure:
# Standard content here.
#
# {{if show_disclaimer}}
# DISCLAIMER: This is a legal disclaimer that appears
# only when show_disclaimer is true.
# {{endif}}
#
# {{if include_pricing}}
# Pricing: $100/month
# {{endif}}

data = %{
  "show_disclaimer" => true,
  "include_pricing" => false
}
Ootempl.render("contract_template.docx", data, "contract.docx")
#=> :ok
# Generated document includes disclaimer section, excludes pricing section

If/Else Support:

Use {{else}} markers to show alternative content when a condition is false:

# Template structure:
# Dear Customer,
#
# {{if is_premium}}
# Thank you for being a premium member! You get 20% off.
# {{else}}
# Become a premium member today for 20% off all purchases.
# {{endif}}
#
# Thank you!

data_premium = %{"is_premium" => true}
Ootempl.render("letter.docx", data_premium, "premium_letter.docx")
# Output: "Thank you for being a premium member! You get 20% off."

data_standard = %{"is_premium" => false}
Ootempl.render("letter.docx", data_standard, "standard_letter.docx")
# Output: "Become a premium member today for 20% off all purchases."

Truthiness rules:

• Truthy: non-nil, non-false, non-empty string, non-zero number
• Falsy: nil, false, "" (empty string), 0, 0.0

Conditional features:

• Case-insensitive markers: {{IF name}}, {{if NAME}}, {{ELSE}} all work
• Nested data paths: {{if customer.active}}
• Optional {{else}} for alternative content
• Multi-paragraph sections supported
• Sections can contain tables, images, lists, etc.

Document Properties

Placeholders in document metadata (title, author, company) are automatically replaced. Use this feature to populate document properties from your data.

# Template has placeholders in File > Properties:
# - Title: {{document_title}}
# - Author: {{author}}
# - Company: {{company_name}}

data = %{
  "document_title" => "Q4 Financial Report",
  "author" => "Jane Smith",
  "company_name" => "Acme Corporation"
}
Ootempl.render("report_template.docx", data, "Q4_report.docx")
#=> :ok
# Generated document has Title, Author, and Company fields populated

Supported property fields:

• Core properties: dc:title, dc:subject, dc:description, dc:creator
• App properties: Company, Manager

Headers, Footers, Footnotes, and Endnotes

Placeholders in headers, footers, footnotes, and endnotes are processed just like the main document body:

# Template has:
# - Header with: {{company_name}} - {{document_title}}
# - Footer with: Page {{page}} of {{total_pages}}
# - Footnote with: {{footnote_citation}}

data = %{
  "company_name" => "Acme Corp",
  "document_title" => "Annual Report",
  "footnote_citation" => "Source: Annual Review 2025"
}
Ootempl.render("template.docx", data, "output.docx")

Image Replacement

Replace placeholder images in templates with dynamic images from your data. Use the alt text field in Word to mark placeholder images with {{image:name}} markers.

Preparing templates in Word:

1. Insert a placeholder image (any PNG, JPEG, or GIF)
2. Right-click the image → "View Alt Text" (or "Edit Alt Text")
3. Set the alt text to {{image:placeholder_name}} (e.g., {{image:company_logo}})
4. Save the template

Data structure:

Provide image file paths in your data map using the placeholder name as the key:

data = %{
  "company_logo" => "/path/to/logo.png",
  "employee_photo" => "/path/to/photo.jpg",
  "signature" => "/path/to/signature.gif"
}
Ootempl.render("template.docx", data, "output.docx")
#=> :ok

Image format support:

• PNG - Portable Network Graphics (.png)
• JPEG - Joint Photographic Experts Group (.jpg, .jpeg)
• GIF - Graphics Interchange Format (.gif)

Automatic dimension scaling:

Images are automatically scaled to fit the placeholder dimensions while preserving aspect ratio. The library calculates the minimum scale factor needed to fit the image within the template bounds:

# Template has 200x100 EMU placeholder
# Image is 800x600 pixels → scaled by 0.25x to fit
# Image is 150x75 pixels → scaled by 1.33x to fill space

data = %{"logo" => "large_image.png"}
Ootempl.render("template.docx", data, "output.docx")
# Image automatically scaled to fit placeholder bounds

Multiple images:

Templates can contain multiple placeholder images, each with a unique marker:

# Template contains three images:
# - Header logo with alt text: {{image:company_logo}}
# - Employee photo with alt text: {{image:employee_photo}}
# - Footer signature with alt text: {{image:signature}}

data = %{
  "company_logo" => "assets/logo.png",
  "employee_photo" => "photos/john_doe.jpg",
  "signature" => "signatures/ceo.gif"
}
Ootempl.render("contract_template.docx", data, "contract.docx")
#=> :ok
# All three images replaced with dynamic content

Error handling:

Image replacement returns errors for missing data or invalid files:

# Missing image key in data
data = %{"name" => "John"}
Ootempl.render("template.docx", data, "output.docx")
#=> {:error, %Ootempl.ImageError{
#     message: "Image placeholder '{{image:logo}}' has no corresponding data key 'logo'",
#     placeholder_name: "logo",
#     image_path: nil,
#     reason: :image_not_found_in_data
#   }}

# Image file doesn't exist
data = %{"logo" => "nonexistent.png"}
Ootempl.render("template.docx", data, "output.docx")
#=> {:error, %Ootempl.ImageError{
#     message: "Image file not found for placeholder 'logo': nonexistent.png",
#     placeholder_name: "logo",
#     image_path: "nonexistent.png",
#     reason: :file_not_found
#   }}

# Unsupported format
data = %{"logo" => "document.pdf"}
Ootempl.render("template.docx", data, "output.docx")
#=> {:error, %Ootempl.ImageError{
#     message: "Unsupported image format for placeholder 'logo': document.pdf (format: .pdf, only PNG, JPEG, GIF supported)",
#     placeholder_name: "logo",
#     image_path: "document.pdf",
#     reason: :unsupported_format
#   }}

Architecture

The library is organized into several modules:

• Ootempl.Archive - ZIP archive operations for .docx files
• Ootempl.Xml - XML parsing and serialization using :xmerl
• Ootempl.Xml.Normalizer - XML normalization for fragmented placeholders
• Ootempl.Placeholder - Placeholder detection and parsing
• Ootempl.DataAccess - Nested data access with case-insensitive matching
• Ootempl.Conditional - Conditional marker detection, evaluation, and section processing
• Ootempl.Replacement - Placeholder replacement in XML with formatting preservation
• Ootempl.Table - Table structure detection, template row identification, and duplication
• Ootempl.Validator - Document validation and error handling

Error Handling

The main render/3 function returns:

• :ok on success (document generated successfully)
• {:error, %PlaceholderError{}} when placeholders cannot be resolved
• {:error, exception} on structural failures

Specific error types:

• Ootempl.PlaceholderError - One or more placeholders cannot be resolved
• Ootempl.ValidationError - File validation failures
• Ootempl.InvalidArchiveError - Invalid ZIP structure
• Ootempl.MissingFileError - Required files missing
• Ootempl.MalformedXMLError - XML parsing failures