OxmlMaker

A Ruby gem for generating Microsoft Word DOCX files using OpenXML. Create professional documents with tables, paragraphs, and custom formatting programmatically.

Features

✅ Generate Valid DOCX Files: Creates Microsoft Word-compatible documents
✅ Tables with Dynamic Data: Populate tables from Ruby objects
✅ Advanced Table Features: Vertical cell merging (v_merge) and multi-line content (new_line)
✅ Paragraphs and Text: Simple text content with proper XML structure
✅ Page Configuration: Control page size, margins, headers/footers
✅ Rails Integration: Automatically detects Rails environment for file placement
✅ ZIP-based Structure: Properly formatted DOCX files using rubyzip
✅ XML Safety: Handles special characters and escaping
✅ Public Directory Management: Auto-creates output directories

Installation

Add this line to your application's Gemfile:

gem 'oxml_maker'

And then execute:

bundle install

Or install it yourself as:

gem install oxml_maker

Quick Start

require 'oxml_maker'

# Define document parameters
params = {
  sections: [
    { paragraph: { text: "Welcome to OxmlMaker" } },
    { 
      table: {
        columns: [
          { name: "Product", width: 3000 },
          { name: "Price", width: 2000 }
        ],
        rows: [
          {
            cells: [
              { value: :name, width: 3000 },
              { value: :price, width: 2000 }
            ]
          }
        ],
        data: {
          0 => [
            OpenStruct.new(name: "Widget", price: "$10.99"),
            OpenStruct.new(name: "Gadget", price: "$25.50")
          ]
        },
        font_size: 24
      }
    },
    { paragraph: { text: "End of document" } }
  ],
  page_size: { width: 12240, height: 15840 },
  page_margin: {
    top: 1440, right: 1440, bottom: 1440, left: 1440,
    header: 720, footer: 720, gutter: 0
  }
}

# Create and generate the document
doc = OxmlMaker::Document.new(filename: "example.docx", params: params)
doc.create

# The file will be created in:
# - Rails apps: Rails.root/public/example.docx
# - Non-Rails: ./public/example.docx (auto-created)

Usage Examples

Creating Tables

Tables can be populated with dynamic data from Ruby objects:

# Define table structure
table_config = {
  columns: [
    { name: "Name", width: 2000 },
    { name: "Age", width: 1500 },
    { name: "Email", width: 3000 }
  ],
  rows: [
    {
      cells: [
        { value: :name, width: 2000 },
        { value: :age, width: 1500 },
        { value: :email, width: 3000 }
      ]
    }
  ],
  data: {
    0 => [
      OpenStruct.new(name: "John Doe", age: 30, email: "john@example.com"),
      OpenStruct.new(name: "Jane Smith", age: 25, email: "jane@example.com")
    ]
  },
  font_size: 12
}

params = {
  sections: [
    { table: table_config }
  ],
  page_size: { width: 12240, height: 15840 },
  page_margin: { top: 1440, right: 1440, bottom: 1440, left: 1440, header: 720, footer: 720, gutter: 0 }
}

Advanced Table Features

Vertical Cell Merging and Multi-line Content

# Advanced table with v_merge and new_line features
advanced_table = {
  columns: [
    { name: "Category", width: 1500 },
    { name: "Items", width: 3000 }
  ],
  rows: [
    {
      cells: [
        { value: :category, width: 1500, v_merge: true },
        { value: :items, width: 3000, new_line: true }
      ]
    }
  ],
  data: {
    0 => [
      OpenStruct.new(category: "Electronics", items: "iPhone, Samsung, Google"),
      OpenStruct.new(category: "Electronics", items: "MacBook, ThinkPad, Dell"),
      OpenStruct.new(category: "Books", items: "Fiction, Non-fiction, Science")
    ]
  },
  font_size: 12
}

# v_merge: true - Merges cells with same values vertically
# new_line: true - Splits comma-separated values into separate lines
params = {
  sections: [
    { table: advanced_table }
  ],
  page_size: { width: 12240, height: 15840 },
  page_margin: { top: 1440, right: 1440, bottom: 1440, left: 1440, header: 720, footer: 720, gutter: 0 }
}

Adding Paragraphs

Simple text content with proper XML formatting:

params = {
  sections: [
    { paragraph: { text: "Document Title" } },
    { paragraph: { text: "This is the first paragraph." } },
    { paragraph: { text: "This is the second paragraph with more content." } }
  ],
  page_size: { width: 12240, height: 15840 },
  page_margin: { top: 1440, right: 1440, bottom: 1440, left: 1440, header: 720, footer: 720, gutter: 0 }
}

Output Location

The gem intelligently handles output location:

In Rails apps: Files are saved to Rails.root/public/
Outside Rails: Files are saved to ./public/ (created automatically)
Custom location: Pass a custom directory to copy_to_public(custom_dir)

Development

Setup

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

🔧 VS Code Setup for XML Development

Important for Contributors: This project includes XML template files that benefit from proper formatting and validation.

📖 See DEVELOPMENT.md for detailed contributor guidelines and XML formatting standards.

Recommended VS Code Extensions

When you open this project in VS Code, you'll be prompted to install recommended extensions:

XML Language Support (redhat.vscode-xml) - Provides XML formatting, validation, and IntelliSense
JSON Language Features (ms-vscode.vscode-json) - Enhanced JSON editing for configuration files

Automatic Configuration

The project includes .vscode/settings.json with pre-configured XML formatting rules:

✅ Auto-format on save for XML files
✅ 2-space indentation (consistent with Ruby code)
✅ Line width limit of 120 characters
✅ XML validation enabled
✅ Attribute splitting for better readability

XML File Formatting

To format XML files manually:

Open any .xml file in lib/oxml_maker/docx/
Press Shift+Alt+F (or Cmd+Shift+P → "Format Document")
Files will auto-format on save when configured

This ensures consistent XML formatting across all contributors without additional gem dependencies! 🎨

📁 Project Structure

lib/oxml_maker/docx/    # XML template files - keep these formatted!
├── [Content_Types].xml  
├── _rels/
└── word/
    └── document.xml     # Main document template

🧹 Development Cleanup

The project includes automatic cleanup of test artifacts:

# Run tests with automatic cleanup
bundle exec rake test_clean

# Manual cleanup of .docx and .zip files
bundle exec rake clean

# Regular test run (includes automatic cleanup)
bundle exec rake test

Test artifacts are automatically removed from:

lib/oxml_maker/ directory
public/ directory
Root directory

This keeps your workspace clean during development! ✨

Why OxmlMaker is Different: The Ruby Object Revolution

The Problem with Traditional DOCX Gems

Most Ruby DOCX libraries force you into rigid patterns:

# Traditional approach - manual, inflexible
builder.table do |t|
  t.row ["Name", "Age"]        # Static arrays only
  t.row ["John", "30"]         # Manual string building
  t.row ["Jane", "25"]         # Can't use objects directly
end

OxmlMaker's Revolutionary Approach

Direct Ruby Object Mapping - Use ANY Ruby object with methods:

# Revolutionary - works with ANY objects!
data: {
  0 => [
    OpenStruct.new(name: "John", age: 30),     # OpenStruct
    User.find(1),                             # ActiveRecord model  
    JSON.parse('{"name": "Jane"}'),           # JSON object
    api_response.data,                        # API response
    custom_object                             # Any object with methods
  ]
}

# Table automatically calls methods dynamically
{ value: :name }  # Calls object.name on each object
{ value: :email } # Calls object.email on each object

Perfect for Modern Architectures

1. JSON-Native Design

Built for API-first and headless architectures:

# HTML → JSON → DOCX pipeline
html_content = "<div><h1>Title</h1><table>...</table></div>"
json_data = html_to_json_parser(html_content)

# Direct consumption - no transformation needed!
doc = OxmlMaker::Document.new(
  filename: "converted.docx", 
  params: json_data  # Pure JSON input
)

2. Polymorphic Data Handling

Mix any data sources in the same document:

# Different object types in the same table!
data: {
  0 => [
    user_model,                    # ActiveRecord object
    { name: "Jane" },              # Hash
    OpenStruct.new(name: "Bob"),   # OpenStruct
    json_api_response              # JSON object
  ]
}

3. Configuration-Driven Architecture

Documents are pure data structures - serializable and cacheable:

# Store templates as JSON in database
template = DocumentTemplate.find_by(name: "invoice")
live_data = Invoice.includes(:line_items).find(params[:id])

# Merge template with live data
params = template.structure.deep_merge({
  sections: [{
    table: {
      data: { 0 => live_data.line_items.to_a }  # Direct AR relation!
    }
  }]
})

Comparison with Other Ruby DOCX Gems

Feature	OxmlMaker	Caracal	ruby-docx	docx	sablon
Ruby Object Mapping	✅ Dynamic	❌ Manual	❌ Manual	❌ Template	❌ Template
JSON Serializable	✅ 100%	❌ Code-based	❌ Code-based	❌ Template	❌ Template
Any Ruby Object	✅ Polymorphic	❌ Arrays only	❌ Limited	❌ Static	❌ Mail merge
HTML→JSON→DOCX	✅ Native	❌ Complex	❌ N/A	❌ N/A	❌ Template only
API-Friendly	✅ Pure data	❌ Code required	❌ Code required	❌ Files	❌ Templates
Microservices Ready	✅ Stateless	❌ Complex	❌ Complex	❌ File-based	❌ Template-based

Perfect Use Cases

CMS/Blog Export

# Blog post with mixed content types
post_json = {
  sections: [
    { paragraph: { text: post.title } },
    { table: { 
        data: { 0 => post.comments.approved }  # Direct relation!
      }
    }
  ]
}

API Report Generation

# Consume external APIs directly
api_response = HTTParty.get("https://api.example.com/reports/#{id}")
json_data = JSON.parse(api_response.body, object_class: OpenStruct)

# No transformation needed!
doc = OxmlMaker::Document.new(params: { sections: json_data.sections })

Dynamic Form Processing

# Form submission → DOCX
form_data = params[:form_responses]  # Frontend JSON

document_params = {
  sections: [{
    table: {
      data: { 0 => form_data.map { |item| OpenStruct.new(item) } }
    }
  }]
}

The Architectural Advantage

Zero Impedance Mismatch - Your data flows directly into documents without transformation layers, making OxmlMaker perfect for:

Headless CMS systems
API-first applications
Microservice architectures
HTML→DOCX conversion pipelines
Real-time report generation
JSON-driven document templates

This isn't just a different API - it's a fundamentally superior architecture for modern Ruby applications.

Testing

Test Framework

The gem uses Minitest as its testing framework, which is included in Ruby's standard library. The test structure follows Ruby conventions:

test/test_helper.rb - Common setup and helper methods
test/test_*.rb - Individual test files for each class
Tests run with bundle exec rake test

Current Test Coverage

67 tests, 344 assertions, 0 failures, 0 errors
Unit tests for all classes (Document, Paragraph, Table)
Integration tests for complete workflows
Advanced table feature tests (v_merge, new_line)
ZIP functionality tests with rubyzip
Rails environment detection tests
Error handling and edge case tests

Test Files

test_oxml_maker.rb - Tests for the main module
test_paragraph.rb - Tests for the Paragraph class
test_table.rb - Tests for the Table class
test_document.rb - Tests for the Document class
test_integration.rb - Integration tests combining multiple classes
test_zip_functionality.rb - ZIP creation and DOCX structure tests
test_full_workflow_integration.rb - Complete end-to-end workflow tests

Running Tests

# Run all tests
bundle exec rake test

# Run a specific test file
bundle exec ruby -Itest test/test_paragraph.rb

# Run a specific test method
bundle exec ruby -Itest test/test_paragraph.rb -n test_initialize_with_valid_hash

Types of Tests

1. Unit Tests

Test individual methods and classes in isolation:

def test_initialize_with_valid_hash
  data = { text: "Hello, World!" }
  paragraph = OxmlMaker::Paragraph.new(data)
  
  assert_equal data, paragraph.data
end

2. Template/Output Tests

Verify that XML output contains expected elements:

def test_template_includes_xml_declaration
  doc = OxmlMaker::Document.new(params: @sample_params)
  template = doc.template

  assert_includes template, '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
end

3. Integration Tests

Test multiple classes working together:

def test_document_with_mixed_content
  params = {
    sections: [
      { paragraph: { text: "Document Title" } },
      { table: table_data }
    ],
    page_size: { width: 12240, height: 15840 }
  }

  document = OxmlMaker::Document.new(params: params)
  xml = document.template

  assert_includes xml, "<w:t>Document Title</w:t>"
end

4. ZIP Functionality Tests

Verify DOCX file creation and structure:

def test_created_zip_is_valid_docx
  doc = OxmlMaker::Document.new(filename: "test.docx", params: @params)
  doc.create

  # Verify ZIP structure matches DOCX requirements
  Zip::File.open(@docx_path) do |zip|
    assert zip.find_entry("[Content_Types].xml"), "Should contain Content Types"
    assert zip.find_entry("_rels/.rels"), "Should contain relationships"
    assert zip.find_entry("word/document.xml"), "Should contain main document"
  end
end

Dependencies

rubyzip (~> 3.2) - For ZIP file creation and DOCX generation
Standard Ruby libraries (FileUtils, etc.)
Optional: Rails - For automatic public directory detection

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/airbearr/oxml_maker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the OxmlMaker project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

oxml_maker

Runtime