docx

A ruby library/gem for interacting with .docx files. currently capabilities include reading paragraphs/bookmarks, inserting text at bookmarks, reading tables/rows/columns/cells and saving the document.

Usage

Prerequisites

• Ruby 2.6 or later

Install

Add the following line to your application's Gemfile:

gem'docx'

And then execute:

bundle install

Or install it yourself as:

gem install docx

Reading

require'docx'# Create a Docx::Document object for our existing docx filedoc=Docx::Document.open('example.docx')# Retrieve and display paragraphsdoc.paragraphs.eachdo |p|
putspend# Retrieve and display bookmarks, returned as hash with bookmark names as keys and objects as valuesdoc.bookmarks.each_pairdo |bookmark_name,bookmark_object|
putsbookmark_nameend

Don't have a local file but a buffer? Docx handles those to:

require'docx'# Create a Docx::Document object from a remote filedoc=Docx::Document.open(buffer)# Everything about reading is the same as shown above

Rendering html

require'docx'# Retrieve and display paragraphs as htmldoc=Docx::Document.open('example.docx')doc.paragraphs.eachdo |p|
putsp.to_htmlend

Reading tables

require'docx'# Create a Docx::Document object for our existing docx filedoc=Docx::Document.open('tables.docx')first_table=doc.tables[0]putsfirst_table.row_countputsfirst_table.column_countputsfirst_table.rows[0].cells[0].textputsfirst_table.columns[0].cells[0].text# Iterate through tablesdoc.tables.eachdo |table|
table.rows.eachdo |row| # Row-based iterationrow.cells.eachdo |cell|
putscell.textendendtable.columns.eachdo |column| # Column-based iterationcolumn.cells.eachdo |cell|
putscell.textendendend

Writing

require'docx'# Create a Docx::Document object for our existing docx filedoc=Docx::Document.open('example.docx')# Insert a single line of text after one of our bookmarksdoc.bookmarks['example_bookmark'].insert_text_after("Hello world.")# Insert multiple lines of text at our bookmarkdoc.bookmarks['example_bookmark_2'].insert_multiple_lines_after(['Hello','World','foo'])# Remove paragraphsdoc.paragraphs.eachdo |p|
p.remove!ifp.to_s =~ /TODO/end# Substitute text, preserving formattingdoc.paragraphs.eachdo |p|
p.each_text_rundo |tr|
tr.substitute('_placeholder_','replacement value')endend# Save document to specified pathdoc.save('example-edited.docx')

Writing to tables

require'docx'# Create a Docx::Document object for our existing docx filedoc=Docx::Document.open('tables.docx')# Iterate over each tabledoc.tables.eachdo |table|
last_row=table.rows.last# Copy last row and insert a new one before last rownew_row=last_row.copynew_row.insert_before(last_row)# Substitute text in each cell of this new rownew_row.cells.eachdo |cell|
cell.paragraphs.eachdo |paragraph|
paragraph.each_text_rundo |text|
text.substitute('_placeholder_','replacement value')endendendenddoc.save('tables-edited.docx')

Advanced

require'docx'd=Docx::Document.open('example.docx')# The Nokogiri::XML::Node on which an element is based can be accessed using #noded.paragraphs.eachdo |p|
putsp.node.inspectend# The #xpath and #at_xpath methods are delegated to the node from the element, saving a stepp_element=d.paragraphs.firstp_children=p_element.xpath("//child::*")# selects all childrenp_child=p_element.at_xpath("//child::*")# selects first child

Development

todo

• Calculate element formatting based on values present in element properties as well as properties inherited from parents
• Default formatting of inserted elements to inherited values
• Implement formattable elements.
• Implement styles.
• Easier multi-line text insertion at a single bookmark (inserting paragraph nodes after the one containing the bookmark)