sablon 0.0.22 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8dce87aaca368f43d657f2ff7fe7249e6f46ddee
-  data.tar.gz: 8fddd1630ba575d38c6ab790d82ee33e88c33b65
+  metadata.gz: 7bfea533a76e6d1eea7475e9916cce5c9d0b8be1
+  data.tar.gz: 58707c6b8a095d4e1e7d3be17bc39bec340d8ad0
 SHA512:
-  metadata.gz: 8f9b5dfcec4a943d674e4144cfa9d545a99340d14592b4e6aa09e19199ae363f919d182473004787ca43e7153ffa1bd48bdfd828d83bb3474ee811feb301c8ba
-  data.tar.gz: 592faea43070727caf1608ce097aa10fc43f0821c0614a658c7a4af3474a37e501d90115d2d5ad54cdf6303250ed2a7ba2cb21ab6949d79d0cef4fabbe6bf26f
+  metadata.gz: 42659e24a433a882c3d5c10f8dc9204a9e2a701e87d504c6fa3aa1d080c86f3a141de937df4e76db43ae21c527ea1eb2d816f0a766b24754ac6553e19d18ec7d
+  data.tar.gz: 5a4077e98f5214a8ac0603376ca90dbbc90726caa30013b66d480b994dff020541b891da30e3057f48bb077ebd1698f74a809c6c171070f8ce824519bcc74d1e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sablon (0.0.22)
+    sablon (0.1.0)
       nokogiri (>= 1.6.0)
       rubyzip (>= 1.1.1)
 

data/README.md

@@ -114,15 +114,31 @@ word_processing_ml = <<-XML.gsub("\n", "")
 </w:p>
 XML
 
+context = {
+  long_description: Sablon.content(:word_ml, word_processing_ml)
+}
+template.render_to_file File.expand_path("~/Desktop/output.docx"), context
+```
+In the example above the entire paragraph will be replaced because all of the nodes being inserted aren't valid children of a paragraph (w:p) element. The example below shows inline insertion, where only runs are added and instead of replacing the entire paragraph only the merge field gets removed.
+
+**Important:** All text must be wrapped in a run tag for valid inline insertion because WordML is still inserted directly into the document "as is" without any structure transformations other than run properties being merged.
+
+```ruby
+word_processing_ml = <<-XML.gsub("\n", "")
+<w:r w:rsidRPr="00B97C39">
+<w:rPr>
+<w:b />
+</w:rPr>
+<w:t>this is bold text</w:t>
+</w:r>
+XML
+
 context = {
   long_description: Sablon.content(:word_ml, word_processing_ml)
 }
 template.render_to_file File.expand_path("~/Desktop/output.docx"), context
 ```
 
-IMPORTANT: This feature is very much *experimental*. Currently, the insertion
-    will replace the containing paragraph. This means that other content in the same
-    paragraph is discarded.
 
 ##### HTML
 
@@ -136,12 +152,43 @@ is sufficient:
 To use HTML insertion prepare the context like so:
 
 ```ruby
-html_body = <<-HTML
-<div>This text can contain <em>additional formatting</em>
-according to the <strong>HTML</strong> specification.</div>
-<p style="text-align: right; background-color: #FFFF00">Right aligned
-content with a yellow background color</p>
-<div><span style="color: #123456">Inline styles</span> are possible as well</div>
+html_body = <<-HTML.strip
+<div>
+    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.
+</div>
+
+<p style="text-align: right; background-color: #FFFF00">
+    Right aligned content with a yellow background color.
+</p>
+
+<div>
+    <span style="color: #123456">Inline styles</span> are possible as well
+</div>
+
+<table style="border: 1px solid #0000FF;">
+    <caption>Table's can also be created via HTML</caption>
+    <tr>
+        <td>Cell 1 only text</td>
+        <td>
+            <ul>
+                <li>List in Table - 1</li>
+                <li>List in Table - 2</li>
+            </ul>
+        </td>
+    </tr>
+    <tr>
+        <td></td>
+        <td>
+            <table style="border: 1px solid #FF0000;">
+                <tr><th>A</th><th>B</th></tr>
+                <tr><td>C</td><td>D</td></tr>
+            </table>
+        </td>
+    </tr>
+</table>
 HTML
 context = {
   article: Sablon.content(:html, html_body) }
@@ -151,24 +198,49 @@ context = {
 template.render_to_file File.expand_path("~/Desktop/output.docx"), context
 ```
 
-Currently, HTML insertion is somewhat limited. It is recommended that the block level tags such as `p` and `div` are not nested within each other, otherwise the final document may not generate as anticipated. List tags (`ul` and `ol`) and inline tags (`span`, `b`, `em`, etc.) can be nested as deeply as needed.
-
-Not all tags are supported. Currently supported tags are defined in [configuration.rb](lib/sablon/configuration/configuration.rb) for paragraphs in method `prepare_paragraph` and for text runs in `prepare_run`.
-
-Basic conversion of CSS inline styles into matching WordML properties in supported through the `style=" ... "` attribute in the HTML markup. Not all possible styles are supported and only a small subset of CSS styles have a direct WordML equivalent. Styles are passed onto nested elements. The currently supported styles are also defined in [configuration.rb](lib/sablon/configuration/configuration.rb) in method `process_style`. Simple toggle properties that aren't directly supported can be added using the `text-decoration: ` style attribute with the proper WordML tag name as the value. Paragraph and Run property reference can be found at:
+There is no 1:1 conversion between HTML and Open Office XML however, a large
+number of tags are very similar. HTML insertion is relatively complete
+covering several key content structures such as paragraphs, tables and lists.
+The snippet above showcases some of the capabilities present, for a comprehensive
+example please see the html insertion test fixture [here](test/fixtures/html/html_test_content.html).
+All html element conversions are defined in [configuration.rb](lib/sablon/configuration/configuration.rb)
+with their matching AST classes defined in [ast.rb](lib/sablon/html/ast.rb).
+
+Basic conversion of CSS inline styles into matching WordML properties is possible
+using the `style=" ... "` attribute in the HTML markup. Not all CSS properties
+are supported as only a small subset of CSS styles have a direct Open Office XML
+equivalent. Styles are passed onto nested elements if the parent can't use them.
+The currently supported styles are also defined in [configuration.rb](lib/sablon/configuration/configuration.rb). Toggle
+properties that aren't directly supported can be added using the
+`text-decoration: ` style attribute with the proper XML tag name as the
+value (i.e. `text-decoration: dstrike` for `w:dstrike`). Simple single value properties that do not need a conversion can be added using the XML property name directly, omitting the `w:` prefix i.e.
+(`highlight: cyan` for `w:highlight`).
+
+Table, Paragraph and Run property references can be found at:
   * http://officeopenxml.com/WPparagraphProperties.php
   * http://officeopenxml.com/WPtextFormatting.php
+  * http://officeopenxml.com/WPtableProperties.php
+
+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).
 
-If you wish to write out your HTML code in an indented human readable fashion, or you are pulling content from the ERB templating engine in rails the following regular expression can help eliminate extraneous whitespace in the final document.
-```ruby
-# combine all white space
-html_str = html_str.gsub(/\s+/, ' ')
-# clear any white space between block level tags and other content
-html_str.gsub(%r{\s*<(/?(?:h\d|div|p|br|ul|ol|li).*?)>\s*}, '<\1>')
-```
 
-IMPORTANT: Currently, the insertion will replace the containing paragraph. This means that other content in the same paragraph is discarded.
+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:
 
+```ruby
+inline_html = <<-HTML.strip
+    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.
+HTML
+context = {
+  article: Sablon.content(:html, inline_html) }
+  # alternative method using special key format
+  # 'html:article' => html_body
+}
+template.render_to_file File.expand_path("~/Desktop/output.docx"), context
+```
 
 #### Conditionals
 

data/lib/sablon.rb

@@ -3,6 +3,7 @@ require 'nokogiri'
 
 require "sablon/version"
 require "sablon/configuration/configuration"
+require "sablon/relationship"
 
 require "sablon/numbering"
 require "sablon/context"

data/lib/sablon/configuration/configuration.rb

@@ -53,11 +53,16 @@ module Sablon
       @permitted_html_tags = {}
       tags = {
         # special tag used for elements with no parent, i.e. top level
-        '#document-fragment' => { type: :block, ast_class: :root, allowed_children: :_block },
+        '#document-fragment' => { type: :block, ast_class: :root, allowed_children: %i[_block _inline] },
 
         # block level tags
+        table: { type: :block, ast_class: :table, allowed_children: %i[caption thead tbody tfoot tr ]},
+        tr: { type: :block, ast_class: :table_row, allowed_children: %i[th td] },
+        th: { type: :block, ast_class: :table_cell, properties: { b: nil, jc: 'center' }, allowed_children: %i[_block _inline] },
+        td: { type: :block, ast_class: :table_cell, allowed_children: %i[_block _inline] },
         div: { type: :block, ast_class: :paragraph, properties: { pStyle: 'Normal' }, allowed_children: :_inline },
         p: { type: :block, ast_class: :paragraph, properties: { pStyle: 'Paragraph' }, allowed_children: :_inline },
+        caption: { type: :block, ast_class: :paragraph, properties: { pStyle: 'Caption' }, allowed_children: :_inline },
         h1: { type: :block, ast_class: :paragraph, properties: { pStyle: 'Heading1' }, allowed_children: :_inline },
         h2: { type: :block, ast_class: :paragraph, properties: { pStyle: 'Heading2' }, allowed_children: :_inline },
         h3: { type: :block, ast_class: :paragraph, properties: { pStyle: 'Heading3' }, allowed_children: :_inline },
@@ -68,6 +73,11 @@ module Sablon
         ul: { type: :block, ast_class: :list, properties: { pStyle: 'ListBullet' }, allowed_children: %i[ul li] },
         li: { type: :block, ast_class: :list_paragraph },
 
+        # inline style tags for tables
+        thead: { type: :inline, ast_class: nil, properties: { tblHeader: nil }, allowed_children: :tr },
+        tbody: { type: :inline, ast_class: nil, properties: {}, allowed_children: :tr },
+        tfoot: { type: :inline, ast_class: nil, properties: {}, allowed_children: :tr },
+
         # inline style tags
         span: { type: :inline, ast_class: nil, properties: {} },
         strong: { type: :inline, ast_class: nil, properties: { b: nil } },
@@ -80,6 +90,7 @@ module Sablon
         sup: { type: :inline, ast_class: nil, properties: { vertAlign: 'superscript' } },
 
         # inline content tags
+        a: { type: :inline, ast_class: :hyperlink, properties: { rStyle: 'Hyperlink' } },
         text: { type: :inline, ast_class: :run, properties: {}, allowed_children: [] },
         br: { type: :inline, ast_class: :newline, properties: {}, allowed_children: [] }
       }
@@ -122,6 +133,67 @@ module Sablon
           },
           'text-align' => ->(v) { return 'jc', v }
         },
+        # Styles specific to the Table AST class
+        table: {
+          'border' => lambda { |v|
+            props = @defined_style_conversions[:node][:_border].call(v)
+            #
+            return 'tblBorders', [
+              { top: props }, { start: props }, { bottom: props },
+              { end: props }, { insideH: props }, { insideV: props }
+            ]
+          },
+          'margin' => lambda { |v|
+            vals = v.split.map do |s|
+              @defined_style_conversions[:node][:_sz].call(s)
+            end
+            #
+            props = [vals[0], vals[0], vals[0], vals[0]] if vals.length == 1
+            props = [vals[0], vals[1], vals[0], vals[1]] if vals.length == 2
+            props = [vals[0], vals[1], vals[2], vals[1]] if vals.length == 3
+            props = [vals[0], vals[1], vals[2], vals[3]] if vals.length > 3
+            return 'tblCellMar', [
+              { top: { w: props[0], type: 'dxa' } },
+              { end: { w: props[1], type: 'dxa' } },
+              { bottom: { w: props[2], type: 'dxa' } },
+              { start: { w: props[3], type: 'dxa' } }
+            ]
+          },
+          'cellspacing' => lambda { |v|
+            v = @defined_style_conversions[:node][:_sz].call(v)
+            return 'tblCellSpacing', { w: v, type: 'dxa' }
+          },
+          'width' => lambda { |v|
+            v = @defined_style_conversions[:node][:_sz].call(v)
+            return 'tblW', { w: v, type: 'dxa' }
+          }
+        },
+        # Styles specific to the TableCell AST class
+        table_cell: {
+          'border' => lambda { |v|
+            value = @defined_style_conversions[:table]['border'].call(v)[1]
+            return 'tcBorders', value
+          },
+          'colspan' => ->(v) { return 'gridSpan', v },
+          'margin' => lambda { |v|
+            value = @defined_style_conversions[:table]['margin'].call(v)[1]
+            return 'tcMar', value
+          },
+          'rowspan' => lambda { |v|
+            return 'vMerge', 'restart' if v == 'start'
+            return 'vMerge', v if v == 'continue'
+            return 'vMerge', nil if v == 'end'
+          },
+          'vertical-align' => ->(v) { return 'vAlign', v },
+          'white-space' => lambda { |v|
+            return 'noWrap', nil if v == 'nowrap'
+            return 'tcFitText', 'true' if v == 'fit'
+          },
+          'width' => lambda { |v|
+            value = @defined_style_conversions[:table]['width'].call(v)[1]
+            return 'tcW', value
+          }
+        },
         # Styles specific to the Paragraph AST class
         paragraph: {
           'border' => lambda { |v|

data/lib/sablon/content.rb

@@ -71,11 +71,85 @@ module Sablon
       def self.id; :word_ml end
       def self.wraps?(value) false end
 
+      def initialize(value)
+        super Nokogiri::XML.fragment(value)
+      end
+
       def append_to(paragraph, display_node, env)
-        Nokogiri::XML.fragment(xml).children.reverse.each do |child|
-          paragraph.add_next_sibling child
+        # if all nodes are inline then add them to the existing paragraph
+        # otherwise replace the paragraph with the new content.
+        if all_inline?
+          pr_tag = display_node.parent.at_xpath('./w:rPr')
+          add_siblings_to(display_node.parent, pr_tag)
+          display_node.parent.remove
+        else
+          add_siblings_to(paragraph)
+          paragraph.remove
+        end
+      end
+
+      # This allows proper equality checks with other WordML content objects.
+      # Due to the fact the `xml` attribute is a live Nokogiri object
+      # the default `==` comparison returns false unless it is the exact
+      # same object being compared. This method instead checks if the XML
+      # being added to the document is the same when the `other` object is
+      # an instance of the WordML content class.
+      def ==(other)
+        if other.class == self.class
+          xml.to_s == other.xml.to_s
+        else
+          super
+        end
+      end
+
+      private
+
+      # Returns `true` if all of the xml nodes to be inserted are
+      def all_inline?
+        (xml.children.map(&:node_name) - inline_tags).empty?
+      end
+
+      # Array of tags allowed to be a child of the w:p XML tag as defined
+      # by the Open XML specification
+      def inline_tags
+        %w[w:bdo w:bookmarkEnd w:bookmarkStart w:commentRangeEnd
+           w:commentRangeStart w:customXml
+           w:customXmlDelRangeEnd w:customXmlDelRangeStart
+           w:customXmlInsRangeEnd w:customXmlInsRangeStart
+           w:customXmlMoveFromRangeEnd w:customXmlMoveFromRangeStart
+           w:customXmlMoveToRangeEnd w:customXmlMoveToRangeStart
+           w:del w:dir w:fldSimple w:hyperlink w:ins w:moveFrom
+           w:moveFromRangeEnd w:moveFromRangeStart w:moveTo
+           w:moveToRangeEnd w:moveToRangeStart m:oMath m:oMathPara
+           w:pPr w:proofErr w:r w:sdt w:smartTag]
+      end
+
+      # Adds the XML to be inserted in the document as siblings to the
+      # node passed in. Run properties are merged here because of namespace
+      # issues when working with a document fragment
+      def add_siblings_to(node, rpr_tag = nil)
+        xml.children.reverse.each do |child|
+          node.add_next_sibling child
+          # merge properties
+          next unless rpr_tag
+          merge_rpr_tags(child, rpr_tag.children)
+        end
+      end
+
+      # Merges the provided properties into the run proprties of the
+      # node passed in. Properties are only added if they are not already
+      # defined on the node itself.
+      def merge_rpr_tags(node, props)
+        # first assert that all child runs (w:r tags) have a w:rPr tag
+        node.xpath('.//w:r').each do |child|
+          child.prepend_child '<w:rPr></w:rPr>' unless child.at_xpath('./w:rPr')
+        end
+        #
+        # merge run props, only adding them if they aren't already defined
+        node.xpath('.//w:rPr').each do |pr_tag|
+          existing = pr_tag.children.map(&:node_name)
+          props.map { |pr| pr_tag << pr unless existing.include? pr.node_name }
         end
-        paragraph.remove
       end
     end
 

data/lib/sablon/environment.rb

@@ -5,6 +5,7 @@ module Sablon
     attr_reader :template
     attr_reader :numbering
     attr_reader :context
+    attr_reader :relationship
 
     # returns a new environment with merged contexts
     def alter_context(context = {})
@@ -20,9 +21,11 @@ module Sablon
       if parent_env
         @template = parent_env.template
         @numbering = parent_env.numbering
+        @relationship = parent_env.relationship
       else
         @template = template
         @numbering = Numbering.new
+        @relationship = Relationship.new
       end
       #
       @context = Context.transform_hash(context)

data/lib/sablon/html/ast.rb

@@ -1,4 +1,5 @@
 require "sablon/html/ast_builder"
+require "sablon/html/node_properties"
 
 module Sablon
   class HTMLConverter
@@ -90,81 +91,6 @@ module Sablon
       end
     end
 
-    # Manages the properties for an AST node
-    class NodeProperties
-      attr_reader :transferred_properties
-
-      def self.paragraph(properties)
-        new('w:pPr', properties, Paragraph::PROPERTIES)
-      end
-
-      def self.run(properties)
-        new('w:rPr', properties, Run::PROPERTIES)
-      end
-
-      def initialize(tagname, properties, whitelist)
-        @tagname = tagname
-        filter_properties(properties, whitelist)
-      end
-
-      def inspect
-        @properties.map { |k, v| v ? "#{k}=#{v}" : k }.join(';')
-      end
-
-      def [](key)
-        @properties[key]
-      end
-
-      def []=(key, value)
-        @properties[key] = value
-      end
-
-      def to_docx
-        "<#{@tagname}>#{properties_word_ml}</#{@tagname}>" unless @properties.empty?
-      end
-
-      private
-
-      # processes properties adding those on the whitelist to the
-      # properties instance variable and those not to the transferred_properties
-      # isntance variable
-      def filter_properties(properties, whitelist)
-        @transferred_properties = {}
-        @properties = {}
-        #
-        properties.each do |key, value|
-          if whitelist.include? key.to_s
-            @properties[key] = value
-          else
-            @transferred_properties[key] = value
-          end
-        end
-      end
-
-      # processes attributes defined on the node into wordML property syntax
-      def properties_word_ml
-        @properties.map { |k, v| transform_attr(k, v) }.join
-      end
-
-      # properties that have a list as the value get nested in tags and
-      # each entry in the list is transformed. When a value is a hash the
-      # keys in the hash are used to explicitly build the XML tag attributes.
-      def transform_attr(key, value)
-        if value.is_a? Array
-          sub_attrs = value.map do |sub_prop|
-            sub_prop.map { |k, v| transform_attr(k, v) }
-          end
-          "<w:#{key}>#{sub_attrs.join}</w:#{key}>"
-        elsif value.is_a? Hash
-          props = value.map { |k, v| format('w:%s="%s"', k, v) if v }
-          "<w:#{key} #{props.compact.join(' ')} />"
-        else
-          value = format('w:val="%s" ', value) if value
-          "<w:#{key} #{value}/>"
-        end
-      end
-    end
-
     # A container for an array of AST nodes with convenience methods to
     # work with the internal array as if it were a regular node
     class Collection < Node
@@ -189,6 +115,10 @@ module Sablon
       def inspect
         "[#{nodes.map(&:inspect).join(', ')}]"
       end
+
+      def <<(node)
+        @nodes << node
+      end
     end
 
     # Stores all of the AST nodes from the current fragment of HTML being
@@ -217,10 +147,23 @@ module Sablon
     # An AST node representing the top level content container for a word
     # document. These cannot be nested within other paragraph elements
     class Paragraph < Node
+      attr_accessor :runs
+
       PROPERTIES = %w[framePr ind jc keepLines keepNext numPr
                       outlineLvl pBdr pStyle rPr sectPr shd spacing
                       tabs textAlignment].freeze
-      attr_accessor :runs
+
+      # Permitted child tags defined by the OpenXML spec
+      CHILD_TAGS = %w[w:bdo w:bookmarkEnd w:bookmarkStart w:commentRangeEnd
+                      w:commentRangeStart w:customXml
+                      w:customXmlDelRangeEnd w:customXmlDelRangeStart
+                      w:customXmlInsRangeEnd w:customXmlInsRangeStart
+                      w:customXmlMoveFromRangeEnd w:customXmlMoveFromRangeStart
+                      w:customXmlMoveToRangeEnd w:customXmlMoveToRangeStart
+                      w:del w:dir w:fldSimple w:hyperlink w:ins w:moveFrom
+                      w:moveFromRangeEnd w:moveFromRangeStart w:moveTo
+                      w:moveToRangeEnd w:moveToRangeStart m:oMath m:oMathPara
+                      w:pPr w:proofErr w:r w:sdt w:smartTag]
 
       def initialize(env, node, properties)
         super
@@ -340,6 +283,195 @@ module Sablon
       end
     end
 
+    # Builds a table from html table tags
+    class Table < Node
+      PROPERTIES = %w[jc shd tblBorders tblCaption tblCellMar tblCellSpacing
+                      tblInd tblLayout tblLook tblOverlap tblpPr tblStyle
+                      tblStyleColBandSize tblStyleRowBandSize tblW].freeze
+
+      def initialize(env, node, properties)
+        super
+
+        # Process properties
+        properties = self.class.process_properties(properties)
+        @properties = NodeProperties.table(properties)
+        trans_props = transferred_properties
+
+        # Pull out the caption node if it exists and convert it separately.
+        # If multiple caption tags are defined, only the first one is kept.
+        @caption = node.xpath('./caption').remove
+        @caption = nil if @caption.empty?
+        if @caption
+          cap_side_pat = /caption-side: ?(top|bottom)/
+          @cap_side = @caption.attr('style').to_s.match(cap_side_pat).to_a[1]
+          node.add_previous_sibling @caption
+          @caption = ASTBuilder.html_to_ast(env, @caption, trans_props)[0]
+        end
+
+        # convert remaining child nodes and pass on transferrable properties
+        @children = ASTBuilder.html_to_ast(env, node.children, trans_props)
+        @children = Collection.new(@children)
+      end
+
+      def to_docx
+        if @caption && @cap_side == 'bottom'
+          super('w:tbl') + @caption.to_docx
+        elsif @caption
+          # caption always goes above table unless explicitly set to "bottom"
+          @caption.to_docx + super('w:tbl')
+        else
+          super('w:tbl')
+        end
+      end
+
+      def accept(visitor)
+        super
+        @children.accept(visitor)
+      end
+
+      def inspect
+        if @caption && @cap_side == 'bottom'
+          "<Table{#{@properties.inspect}}: #{@children.inspect}, #{@caption.inspect}>"
+        elsif @caption
+          "<Table{#{@properties.inspect}}: #{@caption.inspect}, #{@children.inspect}>"
+        else
+          "<Table{#{@properties.inspect}}: #{@children.inspect}>"
+        end
+      end
+
+      private
+
+      def children_to_docx
+        @children.to_docx
+      end
+    end
+
+    # Converts html table rows into wordML table rows
+    class TableRow < Node
+      PROPERTIES = %w[cantSplit hidden jc tblCellSpacing tblHeader
+                      trHeight tblPrEx].freeze
+
+      def initialize(env, node, properties)
+        super
+        properties = self.class.process_properties(properties)
+        @properties = NodeProperties.table_row(properties)
+        #
+        trans_props = transferred_properties
+        @children = ASTBuilder.html_to_ast(env, node.children, trans_props)
+        @children = Collection.new(@children)
+      end
+
+      def to_docx
+        super('w:tr')
+      end
+
+      def accept(visitor)
+        super
+        @children.accept(visitor)
+      end
+
+      def inspect
+        "<TableRow{#{@properties.inspect}}: #{@children.inspect}>"
+      end
+
+      private
+
+      def children_to_docx
+        @children.to_docx
+      end
+    end
+
+    # Converts html table cells into wordML table cells
+    class TableCell < Node
+      PROPERTIES = %w[gridSpan hideMark noWrap shd tcBorders tcFitText
+                      tcMar tcW vAlign vMerge].freeze
+
+      # Permitted child tags defined by the OpenXML spec
+      CHILD_TAGS = %w[w:altChunk w:bookmarkEnd w:bookmarkStart w:commentRangeEnd
+                      w:commentRangeStart w:customXml w:customXmlDelRangeEnd
+                      w:customXmlDelRangeStart w:customXmlInsRangeEnd
+                      w:customXmlInsRangeStart w:customXmlMoveFromRangeEnd
+                      w:customXmlMoveFromRangeStart w:customXmlMoveToRangeEnd
+                      w:customXmlMoveToRangeStart w:del w:ins w:moveFrom
+                      w:moveFromRangeEnd w:moveFromRangeStart w:moveTo
+                      w:moveToRangeEnd w:moveToRangeStart m:oMath m:oMathPara
+                      w:p w:permEnd w:permStart w:proofErr w:sdt w:tbl w:tcPr]
+
+      def initialize(env, node, properties)
+        super
+        properties = self.class.process_properties(properties)
+        @properties = NodeProperties.table_cell(properties)
+        #
+        # Nodes are processed first "as is" and then based on the XML
+        # generated wrapped by paragraphs.
+        trans_props = transferred_properties
+        @children = ASTBuilder.html_to_ast(env, node.children, trans_props)
+        @children = wrap_with_paragraphs(env, @children)
+      end
+
+      def to_docx
+        super('w:tc')
+      end
+
+      def accept(visitor)
+        super
+        @children.accept(visitor)
+      end
+
+      def inspect
+        "<TableCell{#{@properties.inspect}}: #{@children.inspect}>"
+      end
+
+      private
+
+      # Wraps nodes in Paragraph AST nodes if needed to produced a valid
+      # document
+      def wrap_with_paragraphs(env, nodes)
+        # convert all nodes to live xml, and use first node to determine
+        # if that AST node should be wrapped in a paragraph
+        nodes_xml = nodes.map { |n| Nokogiri::XML.fragment(n.to_docx) }
+        #
+        para = nil
+        new_nodes = []
+        nodes_xml.each_with_index do |n, i|
+          next unless n.children.first
+          # add all nodes that need wrapped to a paragraph sequentially.
+          # New paragraphs are created when something that doesn't need
+          # wrapped is encountered to retain proper content ordering.
+          first_node_name = n.children.first.node_name
+          if wrapped_by_paragraph.include? first_node_name
+            if para.nil?
+              para = new_paragraph(env)
+              new_nodes << para
+            end
+            para.runs << nodes[i]
+          else
+            new_nodes << nodes[i]
+            para = nil
+          end
+        end
+        # Ensure the table cell has an empty paragraph if nothing else
+        new_nodes << new_paragraph(env) if new_nodes.empty?
+        # filter nils and return
+        Collection.new(new_nodes.compact)
+      end
+
+      # Returns a list of child tags that need to be wrapped in a paragraph
+      def wrapped_by_paragraph
+        Paragraph::CHILD_TAGS - self.class::CHILD_TAGS
+      end
+
+      # Creates a new Paragraph AST node, with no children
+      def new_paragraph(env)
+        para = Nokogiri::HTML.fragment('<p></p>').first_element_child
+        ASTBuilder.html_to_ast(env, [para], transferred_properties).first
+      end
+
+      def children_to_docx
+        @children.to_docx
+      end
+    end
+
     # Create a run of text in the document, runs cannot be nested within
     # each other
     class Run < Node
@@ -387,5 +519,46 @@ module Sablon
         "<w:br/>"
       end
     end
+
+    # Creates a clickable URL in the word document, this only supports external
+    # urls only
+    class Hyperlink < Node
+      def initialize(env, node, properties)
+        super
+        # properties are passed directly to runs because hyperlink nodes
+        # don't have a corresponding property tag like runs or paragraphs.
+        @runs = ASTBuilder.html_to_ast(env, node.children, properties)
+        @runs = Collection.new(@runs)
+        @target = node.attributes['href'].value
+        #
+        hyperlink_relation = {
+          Id: 'rId' + SecureRandom.uuid.delete('-'),
+          Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink',
+          Target: @target,
+          TargetMode: 'External'
+        }
+        env.relationship.relationships << hyperlink_relation
+        @attributes = { 'r:id' => hyperlink_relation[:Id] }
+      end
+
+      def to_docx
+        super('w:hyperlink')
+      end
+
+      def inspect
+        "<Hyperlink{target:#{@target}}: #{@runs.inspect}>"
+      end
+
+      def accept(visitor)
+        super
+        @runs.accept(visitor)
+      end
+
+      private
+
+      def children_to_docx
+        @runs.to_docx
+      end
+    end
   end
 end