Create Dynamic Word Files from Template via Free Ruby API

Getting Started with Ruby-Docx-Templater

The recommend way to install Ruby-Docx-Templater is using RubyGems. Please use the following command for a smooth installation.

 gem install ruby-docx-templater 

 git clone https://github.com/jawspeak/ruby-docx-templater.git 

Create Word Docx File from Template via Ruby

The most basic feature of Ruby-Docx-Templater is simple text replacement. You can place placeholders anywhere in your Word document, and the library will replace them with actual values. The beauty of this approach is that formatting is preserved. If you make $COMPANY_NAME$ bold and red in your template, it will remain bold and red in the output. This gives designers complete control over document appearance. In your Word template, you define keys using the $KEY$ syntax. The dollar signs act as delimiters, making it clear where substitutions should occur.

require 'docx_templater'

# Load your template file
doc = DocxTemplater::TemplateProcessor.new('invoice_template.docx')

# Define your data as a hash
data = {
  'COMPANY_NAME' => 'Acme Corporation',
  'INVOICE_NUMBER' => 'INV-2024-001',
  'INVOICE_DATE' => '2024-11-04',
  'CLIENT_NAME' => 'John Smith',
  'TOTAL_AMOUNT' => '$1,250.00'
}

# Render the document with your data
doc.render(data)

# Save the output
doc.save('output_invoice.docx')

Multi-Row Table Loops Support

One of the most powerful features is the ability to generate dynamic tables with multiple rows. This is essential for creating itemized lists in invoices, product catalogs, or any report with repeating data. You define a loop region in your table and the library will duplicate everything between these markers for each item in your data array. You can format each cell individually in Word. For instance, you might right-align numbers, make headers bold, or apply specific fonts. All formatting will be preserved in the generated rows.

require 'docx_templater'

doc = DocxTemplater::TemplateProcessor.new('product_report.docx')

# Define items as an array of hashes
data = {
  'REPORT_TITLE' => 'Monthly Sales Report',
  'REPORT_DATE' => 'November 2024',
  'ITEMS_LIST' => [
    {
      'PRODUCT_NAME' => 'Laptop Pro 15"',
      'QUANTITY' => '5',
      'UNIT_PRICE' => '$1,200.00',
      'TOTAL' => '$6,000.00'
    },
    {
      'PRODUCT_NAME' => 'Wireless Mouse',
      'QUANTITY' => '12',
      'UNIT_PRICE' => '$25.00',
      'TOTAL' => '$300.00'
    },
    {
      'PRODUCT_NAME' => 'USB-C Cable',
      'QUANTITY' => '20',
      'UNIT_PRICE' => '$15.00',
      'TOTAL' => '$300.00'
    }
  ]
}

doc.render(data)
doc.save('output_sales_report.docx')

Memory-Based Processing

The open source Ruby-Docx-Templater library is very easy to handle and support memory-based processing inside Ruby applications. All document manipulation happens in memory, which means your sensitive data never touches the file system during the templating process. This is crucial for applications dealing with confidential information like medical records, financial documents, or personal data.

Working with Word XML

One unique aspect of Ruby-Docx-Templater is that you sometimes need to manually edit the underlying XML of your Word document. Word often inserts formatting markup that can split your template keys, breaking the substitution process. When you type $CUSTOMER_NAME$ in Word, it might appear correct on screen, but the underlying XML could look like this.