docx-builder

Docx::Builder

Gem used to create docx files based on a template. Our idea is quite similar to an erb file (in fact, we use an erb file behind :P) The only difference is:

• When we want to write conditions and loops, we write the code between "{{" and "}}"
• When we want to print a variable, we write it between "{{%" and "%}}"

For example, in our template file example.docx we could have:

{{ items.each do |item| }}
Insert here some text: {{% item.property %}}
{{ end }}

Helpers

Table

In order to render a table on docx template, we wrote:

{{t config t}}

where "config" is a hash that may contain five properties:

• columns: an array of hashes. Each element represents a column and may have the following information:
  • name (required): attribute name;
  • width (required): specifies the value of the preferred width of the column, as a percentual of the table width;
  • description (optional): attribute description used on table's header; if not specified, its name will be used as a description
• rows: an array of hashes. Each element represents a row and all of its properties must appear in the columns' array.
• table_width: preferred width of the table in pixels. Default value: 670 pixels
• font_family (optional): font family of the text displayed on a table. Default: Arial
• font_size (optional): font size of the text displayed on a table. Default: 12

At this moment, table width, font family and font size are the only table customizations available (after version 0.5.0)

Installation

Add this line to your application's Gemfile:

gem 'docx-builder'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install docx-builder

Usage

    builder = Docx::Builder::Template.new('/path/to/input.docx')
    new_xml = builder.render(variables_hash)
    builder.save('/path/to/output.docx', new_xml)
    # or memory_stream = builder.save_as_buffer(new_xml)

An example of table configuration should be:

    {
        columns: [
            {
                name: :name,
                description: 'Name',
                width: 50
            },
            {
                name: :email,
                description: 'Mail address',
                width: 50
            }
        ],
        rows: [
            {
                name: 'João',
                email: '[e-mail]' 
            },
            {
                name: 'José',
                email: '[e-mail]' 
            },
            {
                name: 'Felipe',
                email: '[e-mail]' 
            }
        ],
        table_width: 400,
        font_family: 'Cambria',
        font_size: 14
    }

You can also use a helper to generate the hash presented above. For this example, you may specify the description for each column in an internationalization file (i18n), otherwise its name (symbol) will be used instead.

people = [
    { name: 'João', email: '[e-mail]' },
    { name: 'José', email: '[e-mail]' },
    { name: 'Felipe', email: '[e-mail]' }
]
Docx::Utils.build_table_config_from_array(people, table_width: 400, font_family: 'Cambria', font_size: 14)

docx_builder:
    tables:
        columns:
            name: Name
            email: Mail Address

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/docx-builder. 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 Docx::Builder project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.