Open Source Ruby Library to Generate Word DOCX Files
A Powerful Free Ruby API That Enables Software Developers to Create Word DOCX Documents with ease. It allow to Design Document's Layout, Apply Styles, and Use Mail Merge Fields as Placeholders for Dynamic Content.
What is Sablon Library?
In the world of software development, generating dynamic documents like reports, invoices, or letters is a common requirement. While many libraries can create documents from scratch, they often involve a steep learning curve and tedious coding to get the formatting just right. This is where Sablon, a powerful open-source Ruby library, comes to the rescue. Sablon revolutionizes document generation by leveraging the familiarity of Microsoft Word and the power of Ruby, allowing you to create complex and beautifully formatted documents with minimal effort. It supports features like Word Docx creation, content Insertion via MailMerge fields, advanced formatting support, adding annotations in templates, configurable HTML & CSS conversion and many more.
At its core, Sablon is a document template processor for .docx files. It utilizes Word's built-in Mail Merge functionality, enabling you to create templates in a familiar environment. You can design your document's layout, apply styles, and use Mail Merge fields as placeholders for dynamic content. Sablon then takes this template and a data context (a Ruby hash) to produce a final, data-populated Word document. This approach separates the presentation layer (the Word template) from the data layer (your Ruby code), making the document generation process clean and maintainable. Its syntax is intuitive for anyone familiar with Ruby and templating languages. It is designer-friendly, the content and design are completely separated. Designers can work directly in Word without touching code.
Getting Started with Sablon
The recommend way to install Sablon is using RubyGems. Please use the following command for a smooth installation.
Content Insertion with Word Fields via Ruby
The most basic function is inserting dynamic content. The open source Ruby library Sablon uses Word's built-in field syntax to define placeholders. In your Word template, you insert a field code, where you want dynamic content. Sablon will replace this field with your value. The following example demonstrates, how software developers can dynamically insert a piece of content to greet a user.
How to Dynamically Insert Text Contents into Word Docs File via Ruby?
require 'sablon'
template = Sablon.template(File.expand_path('~/template.docx'))
context = {
name: "Sarah Connor"
}
template.render_to_file(File.expand_path('~/output.docx'), context)
Template:
Hello, «name»! Welcome to our platform.
Output:
Hello, Sarah Connor! Welcome to our platform.
HTML to WordML Conversion
One of Sablon's standout features is its ability to convert HTML into WordProcessingML (the XML format used by .docx files). This is incredibly useful when you need to insert rich text content, such as formatted paragraphs, lists, or tables, from a database or a rich text editor. Sablon will convert the HTML string into a properly formatted section in the Word document, preserving headings, bold and italic text, and list formatting. Here is a simple example that demonstrate, how to load an existing template and convert the HTML content to Word Docx file inside Ruby applications.
How to Convert HTML Contents into Word Docx File via Ruby Library?
require "sablon"
template = Sablon.template(File.expand_path("template.docx"))
html_content = "This is a Subheading
This is a paragraph with bold and italic text.
- First item
- Second item
"
context = {
article_content: Sablon.content(:html, html_content)
}
template.render_to_file(File.expand_path("output.docx"), context)
Conditional Rendering
Dynamic Image Insertion via Ruby
The open source Sablon library has included a useful feature for dynamically inserting image inside Word Docx documents using Ruby library. With just a couple of lines of code developers can dynamically insert images into your documents. You can specify an image file, and Sablon will embed it in the document. The following example demonstrates how to achieve dynamic image insertion into Word documents.
How to Dynamically Insert Image into Word Docx via Ruby Library?
// You would have a placeholder image in your template with a special filename like «=company_logo».
context = {
company_logo: Sablon.content(:image, "path/to/your/logo.png")
}
Conditional Rendering via Ruby
The Sablon library supports conditional blocks, allowing users to show or hide parts of their Word document based on the presence or value of a variable. This is perfect for customizing documents based on specific conditions. For instance the following example shows how users can set commands to hide or show specific information inside a word document. If show_extra_info is true, the content between the if and endIf tags will be included in the final document. If it's false or nil, the content will be removed.
How to Display or Hide Parts of Word Docx Documents using Ruby?
context = {
show_extra_info: true # or false
}