RubyGems - janie-htmltoword - Versions diffs - 1.1.2 - Mend

janie-htmltoword 1.1.2

Files changed (28) hide show

checksums.yaml +7 -0
data/README.md +194 -0
data/Rakefile +4 -0
data/bin/htmltoword +36 -0
data/lib/htmltoword.rb +29 -0
data/lib/htmltoword/configuration.rb +12 -0
data/lib/htmltoword/document.rb +155 -0
data/lib/htmltoword/helpers/templates_helper.rb +9 -0
data/lib/htmltoword/helpers/xslt_helper.rb +17 -0
data/lib/htmltoword/railtie.rb +25 -0
data/lib/htmltoword/renderer.rb +43 -0
data/lib/htmltoword/templates/default.docx +0 -0
data/lib/htmltoword/version.rb +3 -0
data/lib/htmltoword/xslt/base.xslt +363 -0
data/lib/htmltoword/xslt/cleanup.xslt +71 -0
data/lib/htmltoword/xslt/extras.xslt +26 -0
data/lib/htmltoword/xslt/functions.xslt +37 -0
data/lib/htmltoword/xslt/header.xslt +34 -0
data/lib/htmltoword/xslt/htmltoword.xslt +22 -0
data/lib/htmltoword/xslt/image_functions.xslt +148 -0
data/lib/htmltoword/xslt/images.xslt +136 -0
data/lib/htmltoword/xslt/inline_elements.xslt +40 -0
data/lib/htmltoword/xslt/links.xslt +34 -0
data/lib/htmltoword/xslt/numbering.xslt +189 -0
data/lib/htmltoword/xslt/relations.xslt +58 -0
data/lib/htmltoword/xslt/style2.xslt +49 -0
data/lib/htmltoword/xslt/tables.xslt +190 -0
metadata +185 -0

checksums.yaml ADDED

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0d05729149187d3e87a12e6c9fd1375a42774fdb
+  data.tar.gz: 14e590f291d423492d0b59f045120c22eade51ce
+SHA512:
+  metadata.gz: 0e209db03dc735e32eec2c55e19243fba57c6d5d565f359119deb351e2f5aaf9152342076dff6a3462858df8e92e7bc62c6be1f01976cc906cd6fb809a15395f
+  data.tar.gz: 1882c1168595571284475ae441cbd7016b94bd91e6105f51a196549b187146756a213d79776e50ee0f29dd257c6ae308fce8bcf21a2b1befab5f411598550978

data/README.md ADDED

@@ -0,0 +1,194 @@
+# Ruby Html to word Gem
+This simple gem allows you to create MS Word docx documents from simple html documents. This makes it easy to create dynamic reports and forms that can be downloaded by your users as simple MS Word docx files.
+Add this line to your application's Gemfile:
+    gem 'htmltoword'
+And then execute:
+    $ bundle
+Or install it yourself as:
+    $ gem install htmltoword
+** Note: ** Since version 0.4.0 the ```create``` method will return a string with the contents of the file. If you want to save the file please use ```create_and_save```. See the usage for more
+## Usage
+### Standalone
+By default, the file will be saved at the specified location. In case you want to handle the contents of the file
+as a string and do what suits you best, you can specify that when calling the create function.
+Using the default word file as template
+```ruby
+require 'htmltoword'
+my_html = '<html><head></head><body><p>Hello</p></body></html>'
+document = Htmltoword::Document.create(my_html)
+file = Htmltoword::Document.create_and_save(my_html, file_path)
+```
+Using your custom word file as a template, where you can setup your own style for normal text, h1,h2, etc.
+```ruby
+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>'
+document = Htmltoword::Document.create(my_html, word_template_file_name)
+file = Htmltoword::Document.create_and_save(my_html, file_path, word_template_file_name)
+```
+The ```create``` function will return a string with the file, so you can do with it what you consider best.
+The ```create_and_save``` function will create the file in the specified file_path.
+### With Rails
+**For htmltoword version >= 0.2**
+An action controller renderer has been defined, so there's no need to declare the mime-type and you can just respond to .docx format. It will look then for views with the extension ```.docx.erb``` which will provide the HTML that will be rendered in the Word file.
+```ruby
+# On your controller.
+respond_to :docx
+# filename and word_template are optional. By default it will name the file as your action and use the default template provided by the gem. The use of the .docx in the filename and word_template is optional.
+def my_action
+  # ...
+  respond_with(@object, filename: 'my_file.docx', word_template: 'my_template.docx')
+  # Alternatively, if you don't want to create the .docx.erb template you could
+  respond_with(@object, content: '<html><head></head><body><p>Hello</p></body></html>', filename: 'my_file.docx')
+end
+def my_action2
+  # ...
+  respond_to do |format|
+    format.docx do
+      render docx: 'my_view', filename: 'my_file.docx'
+      # Alternatively, if you don't want to create the .docx.erb template you could
+      render docx: 'my_file.docx', content: '<html><head></head><body><p>Hello</p></body></html>'
+    end
+  end
+end
+```
+Example of my_view.docx.erb
+```
+<h1> My custom template </h1>
+<%= render partial: 'my_partial', collection: @objects, as: :item %>
+```
+Example of _my_partial.docx.erb
+```
+<h3><%= item.title %></h3>
+<p> My html for item <%= item.id %> goes here </p>
+```
+**For htmltoword version <= 0.1.8**
+```ruby
+# Add mime-type in /config/initializers/mime_types.rb:
+Mime::Type.register "application/vnd.openxmlformats-officedocument.wordprocessingml.document", :docx
+# Add docx responder in your controller
+def show
+  respond_to do |format|
+    format.docx do
+      file = Htmltoword::Document.create params[:docx_html_source], "file_name.docx"
+      send_file file.path, :disposition => "attachment"
+    end
+  end
+end
+```
+```javascript
+  // OPTIONAL: Use a jquery click handler to store the markup in a hidden form field before the form is submitted.
+  // Using this strategy makes it easy to allow users to dynamically edit the document that will be turned
+  // into a docx file, for example by toggling sections of a document.
+  $('#download-as-docx').on('click', function () {
+    $('input[name="docx_html_source"]').val('<!DOCTYPE html>\n' + $('.delivery').html());
+  });
+```
+### Configure templates and xslt paths
+From version 2.0 you can configure the location of default and custom templates and xslt files. By default templates are defined under ```lib/htmltoword/templates``` and xslt under ```lib/htmltoword/xslt```
+```ruby
+Htmltoword.configure do |config|
+  config.custom_templates_path = 'path_for_custom_templates'
+  # If you modify this path, there should be a 'default.docx' file in there
+  config.default_templates_path = 'path_for_default_template'
+  # If you modify this path, there should be a 'html_to_wordml.xslt' file in there
+  config.default_xslt_path = 'some_path'
+  # The use of additional custom xslt will come soon
+  config.custom_xslt_path = 'some_path'
+end
+```
+## Features
+All standard html elements are supported and will create the closest equivalent in wordml. For example spans will create inline elements and divs will create block like elements.
+### Highlighting text
+You can add highlighting to text by wrapping it in a span with class h and adding a data style with a color that wordml supports (http://www.schemacentral.com/sc/ooxml/t-w_ST_HighlightColor.html) ie:
+```html
+<span class="h" data-style="green">This text will have a green highlight</span>
+```
+### Page breaks
+To create page breaks simply add a div with class -page-break ie:
+```html
+<div class="-page-break"></div>
+````
+### Images
+Support for images is very basic and is only possible for external images(i.e accessed via URL). If the image doesn't
+have correctly defined it's width and height it won't be included in the document
+**Limitations:**
+- Images are external i.e. pictures accessed via URL, not stored within document
+- only sizing is customisable
+Examples:
+```html
+<img src="http://placehold.it/250x100.png" style="width: 250px; height: 100px">
+<img src="http://placehold.it/250x100.png" data-width="250px" data-height="100px">
+<img src="http://placehold.it/250x100.png" data-height="150px" style="width:250px; height:100px">
+```
+## Contributing / Extending
+Word docx files are essentially just a zipped collection of xml files and resources.
+This gem contains a standard empty MS Word docx file and a stylesheet to transform arbitrary html into wordml.
+The basic functioning of this gem can be summarised as:
+1. Transform inputed html to wordml.
+2. Unzip empty word docx file bundled with gem and replace its document.xml content with the new transformed result of step 1.
+3. Zip up contents again into a resulting .docx file.
+For more info about WordML: http://rep.oio.dk/microsoft.com/officeschemas/wordprocessingml_article.htm
+Contributions would be very much appreciated.
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+## License
+(The MIT License)
+Copyright © 2013:
+* Cristina Matonte
+* Nicholas Frandsen

data/Rakefile ADDED

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+task :default => :spec
+RSpec::Core::RakeTask.new

data/bin/htmltoword ADDED

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+require 'methadone'
+require 'rmultimarkdown'
+require_relative '../lib/htmltoword'
+include Methadone::Main
+include Methadone::CLILogging
+main do |input, output|
+  puts "Converting #{input} to #{output}" if options[:verbose]
+  markup = File.read input
+  if options[:format] == 'markdown'
+    markup = markdown2html(markup)
+  end
+  Htmltoword::Document.create_and_save(markup, output, options[:template_name], options[:extras])
+  puts "Done" if options[:verbose]
+end
+def markdown2html(text)
+  MultiMarkdown.new(text.to_s).to_html
+end
+version Htmltoword::VERSION
+description 'Convert simple html input (or markdown) to MS Word (docx)'
+arg :input, :required
+arg :output, :required
+on('--verbose', '-v', 'Be verbose')
+on('--extras', '-e', 'Use extra formatting features')
+on('--template', '-t', 'Use custom word base template (.docx file)')
+on('-f FORMAT', '--format', 'Format', /markdown|html/)
+# options['ip-address'] = '127.0.0.1'
+# on('-i IP_ADDRESS', '--ip-address', 'IP Address', /^\d+\.\d+\.\d+\.\d+$/)
+go!

data/lib/htmltoword.rb ADDED

@@ -0,0 +1,29 @@
+# encoding: UTF-8
+require 'nokogiri'
+require 'zip'
+require 'open-uri'
+require_relative 'htmltoword/configuration'
+module Htmltoword
+  class << self
+    def configure
+      yield configuration
+    end
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias_method :config, :configuration
+  end
+end
+require_relative 'htmltoword/version'
+require_relative 'htmltoword/helpers/templates_helper'
+require_relative 'htmltoword/helpers/xslt_helper'
+require_relative 'htmltoword/document'
+if defined?(Rails)
+  require_relative 'htmltoword/renderer'
+  require_relative 'htmltoword/railtie'
+end

data/lib/htmltoword/configuration.rb ADDED

@@ -0,0 +1,12 @@
+module Htmltoword
+  class Configuration
+    attr_accessor :default_templates_path, :custom_templates_path, :default_xslt_path, :custom_xslt_path
+    def initialize
+      @default_templates_path = File.join(File.expand_path('../', __FILE__), 'templates')
+      @custom_templates_path = File.join(File.expand_path('../', __FILE__), 'templates')
+      @default_xslt_path = File.join(File.expand_path('../', __FILE__), 'xslt')
+      @custom_xslt_path = File.join(File.expand_path('../', __FILE__), 'xslt')
+    end
+  end
+end

data/lib/htmltoword/document.rb ADDED

@@ -0,0 +1,155 @@
+module Htmltoword
+  class Document
+    include XSLTHelper
+    class << self
+      include TemplatesHelper
+      def create(content, template_name = nil, extras = false)
+        template_name += extension if template_name && !template_name.end_with?(extension)
+        document = new(template_file(template_name))
+        document.replace_files(content, extras)
+        document.generate
+      end
+      def create_and_save(content, file_path, template_name = nil, extras = false)
+        File.open(file_path, 'wb') do |out|
+          out << create(content, template_name, extras)
+        end
+      end
+      def create_with_content(template, content, extras = false)
+        template += extension unless template.end_with?(extension)
+        document = new(template_file(template))
+        document.replace_files(content, extras)
+        document.generate
+      end
+      def extension
+        '.docx'
+      end
+      def doc_xml_file
+        'word/document.xml'
+      end
+      def numbering_xml_file
+        'word/numbering.xml'
+      end
+      def relations_xml_file
+        'word/_rels/document.xml.rels'
+      end
+      def content_types_xml_file
+        '[Content_Types].xml'
+      end
+    end
+    def initialize(template_path)
+      @replaceable_files = {}
+      @template_path = template_path
+      @image_files = []
+    end
+    #
+    # Generate a string representing the contents of a docx file.
+    #
+    def generate
+      Zip::File.open(@template_path) do |template_zip|
+        buffer = Zip::OutputStream.write_buffer do |out|
+          template_zip.each do |entry|
+            out.put_next_entry entry.name
+            if @replaceable_files[entry.name] && entry.name == Document.doc_xml_file
+              source = entry.get_input_stream.read
+              # Change only the body of document. TODO: Improve this...
+              source = source.sub(/(<w:body>)((.|\n)*?)(<w:sectPr)/, "\\1#{@replaceable_files[entry.name]}\\4")
+              out.write(source)
+            elsif @replaceable_files[entry.name]
+              out.write(@replaceable_files[entry.name])
+            elsif entry.name == Document.content_types_xml_file
+              raw_file = entry.get_input_stream.read
+              content_types = @image_files.empty? ? raw_file : inject_image_content_types(raw_file)
+              out.write(content_types)
+            else
+              out.write(template_zip.read(entry.name))
+            end
+          end
+          unless @image_files.empty?
+          #stream the image files into the media folder using open-uri
+            @image_files.each do |hash|
+              out.put_next_entry("word/media/#{hash[:filename]}")
+              open(hash[:url], 'rb') do |f|
+                out.write(f.read)
+              end
+            end
+          end
+        end
+        buffer.string
+      end
+    end
+    def replace_files(html, extras = false)
+      html = '<body></body>' if html.nil? || html.empty?
+      original_source = Nokogiri::HTML(html.gsub(/>\s+</, '><'))
+      source = xslt(stylesheet_name: 'cleanup').transform(original_source)
+      transform_and_replace(source, xslt_path('numbering'), Document.numbering_xml_file)
+      transform_and_replace(source, xslt_path('relations'), Document.relations_xml_file)
+      transform_doc_xml(source, extras)
+      local_images(source)
+    end
+    def transform_doc_xml(source, extras = false)
+      transformed_source = xslt(stylesheet_name: 'cleanup').transform(source)
+      transformed_source = xslt(stylesheet_name: 'inline_elements').transform(transformed_source)
+      transform_and_replace(transformed_source, document_xslt(extras), Document.doc_xml_file, extras)
+    end
+    private
+    def transform_and_replace(source, stylesheet_path, file, remove_ns = false)
+      stylesheet = xslt(stylesheet_path: stylesheet_path)
+      content = stylesheet.apply_to(source)
+      content.gsub!(/\s*xmlns:(\w+)="(.*?)\s*"/, '') if remove_ns
+      @replaceable_files[file] = content
+    end
+    #generates an array of hashes with filename and full url
+    #for all images to be embeded in the word document
+    def local_images(source)
+      source.css('img').each_with_index do |image,i|
+        filename = image['data-filename'] ? image['data-filename'] : image['src'].split("/").last
+        ext = File.extname(filename).delete(".").downcase
+        @image_files << { filename: "image#{i+1}.#{ext}", url: image['src'], ext: ext }
+      end
+    end
+    #get extension from filename and clean to match content_types
+    def content_type_from_extension(ext)
+      ext == "jpg" ? "jpeg" : ext
+    end
+    #inject the required content_types into the [content_types].xml file...
+    def inject_image_content_types(source)
+      doc = Nokogiri::XML(source)
+      #get a list of all extensions currently in content_types file
+      existing_exts = doc.css("Default").map { |node| node.attribute("Extension").value }.compact
+      #get a list of extensions we need for our images
+      required_exts = @image_files.map{ |i| i[:ext] }
+      #workout which required extensions are missing from the content_types file
+      missing_exts = (required_exts - existing_exts).uniq
+      #inject missing extensions into document
+      missing_exts.each do |ext|
+        doc.at_css("Types").add_child( "<Default Extension='#{ext}' ContentType='image/#{content_type_from_extension(ext)}'/>")
+      end
+      #return the amended source to be saved into the zip
+      doc.to_s
+    end
+  end
+end

data/lib/htmltoword/helpers/templates_helper.rb ADDED

@@ -0,0 +1,9 @@
+module Htmltoword
+  module TemplatesHelper
+    def template_file(template_file_name = nil)
+      default_path = File.join(::Htmltoword.config.default_templates_path, 'default.docx')
+      template_path = template_file_name.nil? ? '' : File.join(::Htmltoword.config.custom_templates_path, template_file_name)
+      File.exist?(template_path) ? template_path : default_path
+    end
+  end
+end