DocXify

If you've ever wanted to generate a Word Document containing a letter or a contract (not a full page layout advert or advanced formatting like that), DocXify is the gem you need in your life.

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add docxify

If bundler is not being used to manage dependencies, install the gem by executing:

gem install docxify

Usage

@docx = DocXify::Document.new(page_width: DocXify::A4_PORTRAIT_WIDTH, page_height: DocXify::A4_PORTRAIT_HEIGHT)

@docx.default_styling font: "Serif font here", size: 14, color: "#040404"

@docx.add_paragraph "Title", font: "Something", size: 18, color: "#00000", after: 18
@docx.add_paragraph "Body copy"
@docx.add_paragraph "This is <b>bold</b>, <i>Italic</i> and <u>Underlined</u>."
@docx.add_paragraph "Text can also contain <a href='foo'>Links</a>."
@docx.add_paragraph "Centred text", align: :center
@docx.add_paragraph "Highlighted text", background: "#FFFF99"
@docx.add_paragraph "This won't show as <b>bold</b>", inline_styling: false

@docx.add_paragraph "\t1.1.1\tBody copy", tab_stops_cm: [1, 2], hanging_cm: 2
@docx.add_paragraph "{CHECKBOX_EMPTY}\tEmpty checkbox", tab_stops_cm: [2]
@docx.add_paragraph "{CHECKBOX_CHECKED}\tChecked checkbox", tab_stops_cm: [2]

@docx.add_divider

@docx.add_image "file_path or data", align: :right, height_cm: 2, width_cm: 4, after: 18

@docx.add_page_break

@docx.page_layout width: DocXify::A4_PORTRAIT_HEIGHT, height: DocXify::A4_PORTRAIT_WIDTH, orientation: :landscape

rows = []
rows << [
  DocXify::Element::TableCell.new("<b>Header 1</b>"),
  DocXify::Element::TableCell.new("<b>Header 2</b>")
  DocXify::Element::TableCell.new("<b>Header 3</b>")
  DocXify::Element::TableCell.new("<b>Header 4</b>", width_cm: 10)
]
rows << [
  DocXify::Element::TableCell.new("Content 1", valign: :center, align: :left, nowrap: true, colspan: 3),
  DocXify::Element::TableCell.new("Rowspan <b>here</b>", rowspan: true) # merges until a "nil" cell
]
rows << [
  DocXify::Element::TableCell.new("Secondary 1")
  DocXify::Element::TableCell.new("Secondary 2")
  DocXify::Element::TableCell.new("Secondary 3")
  DocXify::Element::TableCell.new(nil) # Word requires that there's an empty cell merged with the previous rowspan
]
container.add_table rows

docx_binary_data = @docx.render
# or
@docx.render "file_path"

# All of the above add_* are also available as objects for more dynamic control

para = DocXify::Element::Paragraph.new()
para.content = "This is <b>bold</b>, <i>Italic</i> and <u>Underlined</u>. It can also contain <a href='foo'>Links</a>."
para.font = "Something"
para.size = 18
para.color = "#040404"
para.background = "#FFFF99"
para.align = :center
@docx.add para

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec 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.

Overall architecture

The main object created by users is a DocXify::Document. This builds up a @content instance variable containing an array of all of the elements. Each element has a to_s method that will convert it's current state to a string, ready for insertion in to a complete document.

The render method on a DocXify::Document will generate a complete document.xml (Word terminology not a Ruby method) by creating a template and iterating each @content item. It will then create a DocXify::Container with that document.xml to generate a complete Zipped DocX file, and call it's render method to generate an in-memory file. This is then either returned to the render caller, or if a file path was passed as the first attribute, then it writes it out.

Known issues

The only known issue is that it doesn't like mixing and matching page orientations. If you start a document as portrait or landscape, it's fine, but it really doesn't like a single page being in a different orientation.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/foundercatalyst/docxify.

docxify