htmltoword Ruby Gem

You can control document flow and text emphasis using specific HTML elements and classes:

Page Breaks

Insert a page break by using a div with the -page-break class:

<div class="-page-break"></div>

Text Highlighting

To highlight text, use a span with the class h and provide a color via the data-style attribute.

Valid color values: black, blue, cyan, green, magenta, red, yellow, white, darkBlue, darkCyan, darkGreen, darkMagenta, darkRed, darkYellow, darkGray, lightGray, or none.

<span class="h" data-style="yellow">Highlighted Text Here</span>

To use htmltoword in your Ruby application, add it to your Gemfile:

gem 'htmltoword'

Then run:

$ bundle

Alternatively, you can install it directly via the command line:

$ gem install htmltoword

The Htmltoword::Document class automatically processes images found in the HTML content to embed them into the resulting .docx file.

Image Processing Logic:

1. Detection: The library scans <img> tags in the provided HTML.
2. Source: It uses the src attribute of the image tag. If a data-filename attribute is present, it is used to determine the filename; otherwise, it extracts the filename from the src URL.
3. Embedding: Images are streamed into the word/media/ directory of the .docx zip structure using open-uri.
4. Content Types: The library automatically updates the [Content_Types].xml file within the .docx structure to ensure the new image extensions (e.g., .jpg, .png) are recognized by Word.

If you want to use your own .docx files as templates (to define custom styles for h1, h2, etc.), you must configure the custom_templates_path in the Htmltoword configuration.

require 'htmltoword'

# Configure the location of your custom templates
Htmltoword.config.custom_templates_path = 'some_path'

my_html = '<html><head></head><body><p>Hello</p></body></html>'

# Use the custom template
file = Htmltoword::Document.create_and_save(my_html, 'output.docx', 'my_custom_template.docx')

From version 2.0, you can use a configuration block to set paths for default and custom templates and XSLT files.

• custom_templates_path: Path for your custom .docx templates.
• default_templates_path: Path for default templates (must contain a default.docx file).
• default_xslt_path: Path for the html_to_wordml.xslt file.
• custom_xslt_path: Path for additional custom XSLT files.

Htmltoword.configure do |config|
  config.custom_templates_path = 'path_for_custom_templates'
  config.default_templates_path = 'path_for_default_template'
  config.default_xslt_path = 'some_path'
  config.custom_xslt_path = 'some_path'
end

After integration, you can trigger a Word document download from a controller action in two ways:

1. Using render :docx

You can use the standard render method. By default, it uses the current action name as the filename and the gem's default template.

render docx: 'custom_filename'

2. Using to_docx

If ActionController::Responder is present, you can call to_docx directly on the responder. This is a shorthand for rendering the current action as a docx file.

# Inside a controller action
# This will render the current action name as the filename
to_docx

# Or with custom options
to_docx filename: 'my_report', word_template: 'templates/report.docx.erb'

# Using render
render docx: 'custom_filename'

# Using the to_docx responder
to_docx

# Using to_docx with options
to_docx filename: 'my_report', word_template: 'templates/report.docx.erb'

The htmltoword gem provides a Railtie that automatically registers the :docx MIME type and adds a renderer to ActionController.

Once the gem is included in your Rails application, you can render .docx files directly from your controllers using the render :docx syntax or the to_docx responder method.

The Htmltoword::Document class provides two primary methods for converting HTML to Word documents:

1. create(html_string, [template_name]): Returns the document contents as a string. Use this if you want to handle the raw file data manually.
2. create_and_save(html_string, file_path, [template_name]): Creates the .docx file and saves it directly to the specified file_path.

Note: Since version 0.4.0, create returns a string. If you need to save the file to disk, you must use create_and_save.

require 'htmltoword'

my_html = '<html><head></head><body><p>Hello</p></body></html>'

# Returns a string containing the file contents
document = Htmltoword::Document.create(my_html)

# Saves the file to the specified path
file = Htmltoword::Document.create_and_save(my_html, 'path/to/output.docx')

The Htmltoword::Configuration class allows you to define where the gem looks for default and custom templates and XSLT files. You can set the following attributes using their accessors:

• default_templates_path: The directory containing the gem's built-in templates.
• custom_templates_path: The directory where your application's custom .docx.erb templates are located.
• default_xslt_path: The directory containing the gem's built-in XSLT files.
• custom_xslt_path: The directory where your application's custom XSLT files are located.

By default, both custom and default paths are initialized to the gem's internal templates and xslt directories.

config = Htmltoword::Configuration.new
config.custom_templates_path = '/path/to/your/templates'
config.custom_xslt_path = '/path/to/your/xslt'

The gem supports the following standard HTML tags for document structure:

• div
• p
• ul, ol, li
• b, strong
• i, em
• u
• br
• pre
• h1 through h6

Note: Images and external links are currently not supported.