sablon 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9aa52423b659a11000ab780b41d5236af1004e39
-  data.tar.gz: aab45da4847e119795627db459141db3d43c870b
+  metadata.gz: ed6349a93ba2cb199faa068f080fac477c2bc8d3
+  data.tar.gz: db1af586f261a43916313337fd504f6a68ddc610
 SHA512:
-  metadata.gz: 8ef1f9feafe3b59eb90860ffef9e3db54b47a030d3195ca3cc27265d0fb92db688ddbeae47a947c939c516e3c175d313d768d100d97791ea958e7beec96c586c
-  data.tar.gz: 5c881774d042b730eabe05a2d294cc667f035cfd28fccef66fc8abcd5f7d7ec463be6a860a8d3b6139138e0e61df1b32efe3754b4d31733687f76bbb46442cc6
+  metadata.gz: 63efa28431abe48b000a1cce4a8e22d065997fa8b010b9161c82fa69c13c972d6dbbbe45a8cb6ca100a884c44e867f2a483af0cfe682cfed0bfc2db66d4fbc50
+  data.tar.gz: 69c728d1c6cb4301e8521a19aabb80d8dfe4f09f8f2fec86a0f8ae6a311e49611a7da9be88e9c27764aaecb96f31fb343eb003283718040f59c8f0feb889232c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sablon (0.1.1)
+    sablon (0.2.0)
       nokogiri (>= 1.6.0)
       rubyzip (>= 1.1.1)
 
@@ -10,7 +10,7 @@ GEM
   specs:
     mini_portile2 (2.3.0)
     minitest (5.10.3)
-    nokogiri (1.8.1)
+    nokogiri (1.8.2)
       mini_portile2 (~> 2.3.0)
     rake (12.3.0)
     rubyzip (1.2.1)

data/README.md

@@ -1,12 +1,12 @@
 # Sablon
 
-[![Gem Version](https://badge.fury.io/rb/sablon.svg)](http://badge.fury.io/rb/sablon) [![Build Status](https://travis-ci.org/senny/sablon.svg?branch=master)](https://travis-ci.org/senny/sablon)
+[![Gem Version](https://badge.fury.io/rb/sablon.svg)](http://badge.fury.io/rb/sablon)
+[![Build Status](https://travis-ci.org/senny/sablon.svg?branch=master)](https://travis-ci.org/senny/sablon)
 
 Is a document template processor for Word `docx` files. It leverages Word's
 built-in formatting and layouting capabilities to make template creation easy
 and efficient.
 
-*Note: Sablon is still in early development. Please report if you encounter any issues along the way.*
 
 #### Table of Contents
 * [Installation](#installation)
@@ -15,6 +15,7 @@ and efficient.
       * [Content Insertion](#content-insertion)
          * [WordProcessingML](#wordprocessingml)
          * [HTML](#html)
+         * [Images (Beta)](#images-beta)
       * [Conditionals](#conditionals)
       * [Loops](#loops)
       * [Nesting](#nesting)
@@ -225,14 +226,14 @@ The full Open Office XML specification used to develop the HTML converter
 can be found [here](https://www.ecma-international.org/publications/standards/Ecma-376.htm) (3rd Edition).
 
 
-The example above shows an HTML insertion operation that will replace the entire paragraph. In the same fashion as WordML, inline HTML insertion is possible where only the merge field is replaced as long as only "inline" elements are used. "Inline" in this context does not necessarily mean the same thing as it does in CSS, in this case it means that once the HTML is converted to WordML only valid children of a paragraph (w:p) tag exist. Unlike WordML insertion plain text can be used without being wrapped in tags when working with HTML, see the example below:
+The example above shows an HTML insertion operation that will replace the entire paragraph. In the same fashion as WordML, inline HTML insertion is possible where only the merge field is replaced as long as only "inline" elements are used. "Inline" in this context does not necessarily mean the same thing as it does in CSS, in this case it means that once the HTML is converted to WordML only valid children of a paragraph (w:p) tag exist. As with WordML all plain text needs to be wrapped in a HTML tag. A simple `<span>..</span>` tag enclosing all other elements will suffice. See the example below:
 
 ```ruby
 inline_html = <<-HTML.strip
-    This text can contain <em>additional formatting</em> according to the
+    <span>This text can contain <em>additional formatting</em> according to the
     <strong>HTML</strong> specification. As well as links to external
     <a href="https://github.com/senny/sablon">websites</a>, don't forget
-    the "http/https" bit.
+    the "http/https" bit.</span>
 HTML
 context = {
   article: Sablon.content(:html, inline_html) }
@@ -242,6 +243,35 @@ context = {
 template.render_to_file File.expand_path("~/Desktop/output.docx"), context
 ```
 
+
+##### Images (beta)
+
+Images can be added to the document using a placeholder image wrapped in a
+pair of merge fields set up as `«@figure:start»` and `«@figure:end»`. Where
+in this case "figure" is the key of the context hash storing the image.
+
+Images are wrapped in an instance of a `Sablon::Content` class in the same
+fashion as HTML or WordML strings. An image may be initialized from multiple
+sources such as file paths, URLs, or any object that exposes a `#read`
+method that returns image data. When using a "readable object" if the object
+doesn't have a `#filename` method then a `filename: '...'` option
+needs to be added to the `Sablon.content` method call.
+```ruby
+context = {
+  figure: Sablon.content(:image, 'fixtures/images/c3po.jpg'),
+  figure2: Sablon.content(:image, string_io_obj, filename: 'test.png')
+  # alternative method using special key format for simple paths and URLs
+  # 'image:figure' => 'fixtures/images/c3po.jpg'
+}
+```
+
+Example:
+![image merge fields example](misc/image-example.png)
+
+Additional examples of usage can be found in
+[images_template.docx](test/fixtures/images_template.docx) and
+in [sablon_test.rb](test/sablon_test.rb).
+
 #### Conditionals
 
 Sablon can render parts of the template conditionally based on the value of a
@@ -265,6 +295,7 @@ For more complex conditionals you can use a predicate like so:
 «body:endIf»
 ```
 
+
 #### Loops
 
 Loops repeat parts of the document.

data/lib/sablon.rb

@@ -3,15 +3,12 @@ require 'nokogiri'
 
 require "sablon/version"
 require "sablon/configuration/configuration"
-require "sablon/relationship"
 
-require "sablon/numbering"
 require "sablon/context"
 require "sablon/environment"
 require "sablon/template"
 require "sablon/processor/document"
 require "sablon/processor/section_properties"
-require "sablon/processor/numbering"
 require "sablon/parser/mail_merge"
 require "sablon/operations"
 require "sablon/html/converter"

data/lib/sablon/configuration/html_tag.rb

@@ -49,7 +49,7 @@ module Sablon
         # etc. All the keys need to be symbols to avoid getting reparsed
         # with the element's CSS attributes.
         @properties = options.fetch(:properties, {})
-        @properties = Hash[@properties.map { |k, v| [k.to_sym, v] }]
+        @properties = Hash[@properties.map { |k, v| [k.to_s, v] }]
         # Set permitted child tags or tag groups
         self.allowed_children = options[:allowed_children]
       end

data/lib/sablon/content.rb

@@ -1,3 +1,5 @@
+require 'open-uri'
+
 module Sablon
   module Content
     class << self
@@ -170,8 +172,62 @@ module Sablon
       end
     end
 
+    # Handles reading image data and inserting it into the document
+    class Image < Struct.new(:name, :data, :local_rid)
+      attr_reader :rid_by_file
+
+      def self.id; :image end
+      def self.wraps?(value) false end
+
+      def inspect
+        "#<Image #{name}:#{@rid_by_file}>"
+      end
+
+      def initialize(source, attributes = {})
+        attributes = Hash[attributes.map { |k, v| [k.to_s, v] }]
+        # If the source object is readable, use it as such otherwise open
+        # and read the content
+        if source.respond_to?(:read)
+          name, img_data = process_readable(source, attributes)
+        else
+          name = File.basename(source)
+          img_data = IO.binread(source)
+        end
+        #
+        super name, img_data
+        @attributes = attributes
+        # rId's are separate for each XML file but I want to be able
+        # to reuse the actual image file itself.
+        @rid_by_file = {}
+      end
+
+      def append_to(paragraph, display_node, env) end
+
+      private
+
+      # Reads the data and attempts to find a filename from either the
+      # attributes hash or a #filename method on the source object itself.
+      # A filename is required inorder for MS Word to know the content type.
+      def process_readable(source, attributes)
+        if attributes['filename']
+          name = attributes['filename']
+        elsif source.respond_to?(:filename)
+          name = source.filename
+        else
+          begin
+            name = File.basename(source)
+          rescue TypeError
+            raise ArgumentError, "Error: Could not determine filename from source, try: `Sablon.content(readable_obj, filename: '...')`"
+          end
+        end
+        #
+        [File.basename(name), source.read]
+      end
+    end
+
     register Sablon::Content::String
     register Sablon::Content::WordML
     register Sablon::Content::HTML
+    register Sablon::Content::Image
   end
 end

data/lib/sablon/context.rb

@@ -17,6 +17,8 @@ module Sablon
         case value
         when Hash
           [key, transform_hash(value)]
+        when Array
+          [key, value.map { |v| v.is_a?(Hash) ? transform_hash(v) : v }]
         else
           [key, value]
         end

data/lib/sablon/document_object_model/content_types.rb

@@ -0,0 +1,35 @@
+require 'sablon/document_object_model/file_handler'
+
+module Sablon
+  module DOM
+    # Adds new content types to the document
+    class ContentTypes < FileHandler
+      #
+      # extends the Model class so it now has an "add_content_type" method
+      def self.extend_model(model_klass)
+        super do
+          define_method(:add_content_type) do |extension, type|
+            @dom['[Content_Types].xml'].add_content_type(extension, type)
+          end
+        end
+      end
+
+      # Sets up the class instance to handle new relationships for a document.
+      # I only care about tags that have an integer component
+      def initialize(xml_node)
+        super
+        #
+        @types = xml_node.root
+      end
+
+      # Adds a new content type to the file
+      def add_content_type(extension, type)
+        #
+        # don't add duplicate extensions to the document
+        return unless @types.css(%(Default[Extension="#{extension}"])).empty?
+        #
+        @types << %(<Default Extension="#{extension}" ContentType="#{type}"/>)
+      end
+    end
+  end
+end

data/lib/sablon/document_object_model/file_handler.rb

@@ -0,0 +1,26 @@
+module Sablon
+  module DOM
+    # An abstract class used to setup other file handling classes
+    class FileHandler
+      #
+      # extends the Model class using instance eval with a block argument
+      def self.extend_model(model_klass, &block)
+        model_klass.instance_eval(&block)
+      end
+
+      # All subclasses should be initialized only accepting the content
+      # as a single argument.
+      def initialize(content); end
+
+      # Finds the maximum value of an attribute by converting it to an
+      # integer. Non numeric portions of values are ignored. The method can
+      # be either xpath or css, xpath being the default.
+      def max_attribute_value(xml_node, selector, attr_name, query_method: :xpath)
+        xml_node.send(query_method, selector).map.inject(0) do |max, node|
+          next max unless (match = node.attr(attr_name).match(/(\d+)/))
+          [max, match[1].to_i].max
+        end
+      end
+    end
+  end
+end

data/lib/sablon/document_object_model/model.rb

@@ -0,0 +1,94 @@
+require 'sablon/document_object_model/file_handler'
+require 'sablon/document_object_model/content_types'
+require 'sablon/document_object_model/numbering'
+require 'sablon/document_object_model/relationships'
+
+module Sablon
+  # Stores classes used to build and interact with the template by treating
+  # it as a full document model instead of disparate components that are
+  # packaged together.
+  module DOM
+    class << self
+      # Allows new handlers to be registered for different components of
+      # the MS Word document. The pattern passed in is used to determine
+      # if a file in the entry set should be handled by the class.
+      def register_dom_handler(pattern, klass)
+        handlers[pattern] = klass
+        klass.extend_model(Sablon::DOM::Model)
+      end
+
+      def wrap_with_handler(entry_name, content)
+        key = handlers.keys.detect { |pat| entry_name =~ pat }
+        if key
+          handlers[key].new(content)
+        else
+          Sablon::DOM::FileHandler.new(content)
+        end
+      end
+
+      private
+
+      def handlers
+        @handlers ||= {}
+      end
+    end
+
+    # Object to represent an entire template and it's XML contents
+    class Model
+      attr_accessor :current_entry
+      attr_reader :zip_contents
+
+      # setup the DOM by reading and storing all XML files in the template
+      # in memory
+      def initialize(zip_io_stream)
+        @current_entry = nil
+        @zip_contents = {}
+        zip_io_stream.each do |entry|
+          next unless entry.file?
+          content = entry.get_input_stream.read
+          @zip_contents[entry.name] = wrap_entry(entry.name, content)
+        end
+        #
+        @dom = build_dom(@zip_contents)
+      end
+
+      # Returns the corresponding DOM handled file
+      def [](entry_name)
+        @dom[entry_name]
+      end
+
+      private
+
+      # Determines how the content in the zip file entry should be wrapped
+      def wrap_entry(entry_name, content)
+        if entry_name =~ /\.(?:xml|rels)$/
+          Nokogiri::XML(content)
+        else
+          content
+        end
+      end
+
+      # constructs the dom model using helper clases defined under this
+      # namespace.
+      def build_dom(entries)
+        key_values = entries.map do |entry_name, content|
+          [entry_name, Sablon::DOM.wrap_with_handler(entry_name, content)]
+        end
+        #
+        Hash[key_values]
+      end
+
+      def create_entry_if_not_exist(name, init_content = '')
+        return unless @zip_contents[name].nil?
+        #
+        # create the entry and add it to the dom
+        @zip_contents[name] = wrap_entry(name, init_content)
+        @dom[name] = Sablon::DOM.wrap_with_handler(name, @zip_contents[name])
+      end
+    end
+
+    register_dom_handler(%r{word/numbering.xml}, Sablon::DOM::Numbering)
+    register_dom_handler(/.rels$/, Sablon::DOM::Relationships)
+    register_dom_handler(/Content_Types/, Sablon::DOM::ContentTypes)
+  end
+end

data/lib/sablon/document_object_model/numbering.rb

@@ -0,0 +1,94 @@
+require 'sablon/document_object_model/file_handler'
+
+module Sablon
+  module DOM
+    # Manages the creation of new list definitions
+    class Numbering < FileHandler
+      Definition = Struct.new(:numid, :abstract_id, :style)
+
+      # extends the Model class using instance eval with a block argument
+      def self.extend_model(model_klass, &block)
+        super do
+          #
+          # adds a list definition to the numbering.xml file
+          define_method(:add_list_definition) do |style|
+            @dom['word/numbering.xml'].add_list_definition(style)
+          end
+        end
+      end
+
+      # Sets up the class to add new list definitions to the number.xml
+      # file
+      def initialize(xml_node)
+        super
+        #
+        @numbering = xml_node.root
+        #
+        @max_numid = max_attribute_value('//w:num', 'w:numId')
+        #
+        selector = '//w:abstractNum'
+        @max_abstract_id = max_attribute_value(selector, 'w:abstractNumId')
+      end
+
+      # adds a new relationship and returns the corresponding rId for it
+      def add_list_definition(style)
+        definition = create_definition(style)
+        #
+        # update numbering file with new definitions
+        node = @numbering.xpath('//w:abstractNum').last
+        node.add_next_sibling(abstract_tag(definition))
+        #
+        node = @numbering.xpath('//w:num').last
+        node.add_next_sibling(definition_tag(definition))
+        #
+        definition
+      end
+
+      private
+
+      # Finds the maximum value of an attribute by converting it to an
+      # integer. Non numeric portions of values are ignored.
+      def max_attribute_value(selector, attr_name)
+        super(@numbering, selector, attr_name)
+      end
+
+      # Creates a new list definition tag to define a list
+      def definition_tag(definition)
+        <<-XML.gsub(/^\s+|\n/, '')
+          <w:num w:numId="#{definition.numid}">
+            <w:abstractNumId w:val="#{definition.abstract_id}" />
+          </w:num>
+        XML
+      end
+
+      # Creates a new abstract numbering definition tag to style a list
+      def abstract_tag(definition)
+        abstract_num = find_abstract_definition(definition.style)
+        abstract_num['w:abstractNumId'] = definition.abstract_id
+        abstract_num.xpath('./w:nsid').each(&:remove)
+        #
+        abstract_num
+      end
+
+      # Locates and copies the first abstract numbering definition with
+      # the expected style. If one can not be found an error is raised.
+      def find_abstract_definition(style)
+        path = "//w:abstractNum[descendant-or-self::*[w:pStyle[@w:val='#{style}']]]"
+        unless (abstract_num = @numbering.at_xpath(path))
+          msg = "Could not find w:abstractNum definition for style: '#{style}'"
+          raise ArgumentError, msg
+        end
+        #
+        abstract_num.dup
+      end
+
+      # Creates a new instance of the Definition struct, after incrementing
+      # the max id values
+      def create_definition(style)
+        @max_numid += 1
+        @max_abstract_id += 1
+        Definition.new(@max_numid, @max_abstract_id, style)
+      end
+    end
+  end
+end