caracal 1.5.0 → 1.6.0

data/lib/caracal/core/models/list_item_model.rb

@@ -17,7 +17,7 @@ module Caracal
         #-------------------------------------------------------------
 
         # accessors
-        attr_accessor :nested_list
+        attr_writer :continuation
 
         # readers (create aliases for superclass methods to conform
         # to expected naming convention.)
@@ -54,6 +54,51 @@ module Caracal
         end
 
 
+        #=============== NESTED LISTS =========================
+
+        # This method returns the nested lists in the order they were
+        # added, each with the number of runs that came before it, so text
+        # after a nested list can be rendered after it.
+        #
+        def nested_lists
+          @nested_lists ||= []
+        end
+
+        def nested_list
+          (pair = nested_lists.last) && pair.last
+        end
+
+        def nested_list=(model)
+          nested_lists << [runs.size, model]
+        end
+
+        # This method returns whether this is the text that follows a
+        # nested list, which renders as an unnumbered paragraph indented
+        # with the item.
+        #
+        def continuation?
+          !!@continuation
+        end
+
+        # This method returns this item and everything nested in it in
+        # document order: the item's text up to its first nested list, the
+        # nested list's items, then any text that follows, and so on.
+        #
+        def recursive_items
+          return [self] if nested_lists.empty?
+
+          items = []
+          start = 0
+          nested_lists.each do |(index, list)|
+            items << segment(start...index, items.any?) if items.empty? || index > start
+            items.concat(list.recursive_items)
+            start = index
+          end
+          items << segment(start...runs.size, true) if runs.size > start
+          items
+        end
+
+
         #=============== SUB-METHODS ===========================
 
         # .ol
@@ -62,7 +107,7 @@ module Caracal
 
           model = Caracal::Core::Models::ListModel.new(options, &block)
           if model.valid?
-            @nested_list = model
+            self.nested_list = model
           else
             raise Caracal::Errors::InvalidModelError, 'Ordered lists require at least one list item.'
           end
@@ -75,7 +120,7 @@ module Caracal
 
           model = Caracal::Core::Models::ListModel.new(options, &block)
           if model.valid?
-            @nested_list = model
+            self.nested_list = model
           else
             raise Caracal::Errors::InvalidModelError, 'Unordered lists require at least one list item.'
           end
@@ -97,6 +142,15 @@ module Caracal
         #-------------------------------------------------------------
         private
 
+        # This method returns a copy of the item holding only the given runs.
+        def segment(range, continuation)
+          copy = dup
+          copy.instance_variable_set(:@runs, runs[range])
+          copy.instance_variable_set(:@nested_lists, [])
+          copy.continuation = continuation
+          copy
+        end
+
         def option_keys
           [:type, :level, :content, :style, :color, :size, :bold, :italic, :underline, :bgcolor]
         end

data/lib/caracal/core/models/list_model.rb

@@ -61,13 +61,7 @@ module Caracal
         # item within this list's tree.
         #
         def recursive_items
-          items.map do |model|
-            if model.nested_list.nil?
-              model
-            else
-              [model, model.nested_list.recursive_items]
-            end
-          end.flatten
+          items.flat_map(&:recursive_items)
         end
         
         

data/lib/caracal/core/models/list_style_model.rb

@@ -108,7 +108,7 @@ module Caracal
         private
         
         def option_keys
-          [:type, :level, :format, :value, :align, :left, :indent, :start]
+          [:type, :level, :format, :value, :align, :left, :indent, :start, :restart]
         end
         
       end

data/lib/caracal/core/models/page_number_model.rb

@@ -24,6 +24,8 @@ module Caracal
         attr_reader :page_number_label_size
         attr_reader :page_number_number_size
         attr_reader :page_number_show
+        attr_reader :page_number_first
+        attr_reader :page_number_start
 
         # initialization
         def initialize(options={}, &block)
@@ -32,6 +34,8 @@ module Caracal
           @page_number_label_size   = nil
           @page_number_number_size  = nil
           @page_number_show         = DEFAULT_PAGE_NUMBER_SHOW
+          @page_number_first        = true
+          @page_number_start        = nil
 
           super options, &block
         end
@@ -65,6 +69,15 @@ module Caracal
           @page_number_show = !!value
         end
 
+        # false leaves the page number off the first page
+        def first_page(value)
+          @page_number_first = !!value
+        end
+
+        def start(value)
+          @page_number_start = value.nil? ? nil : value.to_i
+        end
+
         def size(value)
           v = value.to_i
           @page_number_label_size  = (v == 0) ? nil : v
@@ -75,7 +88,9 @@ module Caracal
         #=============== VALIDATION ===========================
 
         def valid?
-          (!page_number_show || [:left, :center, :right].include?(page_number_align))
+          valid_align = (!page_number_show || [:left, :center, :right].include?(page_number_align))
+          valid_start = (page_number_start.nil? || page_number_start >= 0)
+          valid_align && valid_start
         end
 
 
@@ -85,7 +100,7 @@ module Caracal
         private
 
         def option_keys
-          [:align, :label, :label_size, :number_size, :show]
+          [:align, :label, :label_size, :number_size, :show, :size, :start, :first_page]
         end
 
       end

data/lib/caracal/core/models/paragraph_model.rb

@@ -2,6 +2,7 @@ require 'caracal/core/models/base_model'
 require 'caracal/core/models/bookmark_model'
 require 'caracal/core/models/link_model'
 require 'caracal/core/models/text_model'
+require 'caracal/core/models/field_model'
 require 'caracal/errors'
 
 
@@ -127,6 +128,20 @@ module Caracal
           model
         end
 
+        # .field
+        def field(*args, &block)
+          options = Caracal::Utilities.extract_options!(args)
+          options = options.merge({ type: args[0] })
+
+          model = Caracal::Core::Models::FieldModel.new(options, &block)
+          if model.valid?
+            runs << model
+          else
+            raise Caracal::Errors::InvalidModelError, ':field method must receive :page or :numpages.'
+          end
+          model
+        end
+
         # .link
         def link(*args, &block)
           options = Caracal::Utilities.extract_options!(args)
@@ -177,7 +192,7 @@ module Caracal
         private
 
         def option_keys
-          [:content, :style, :align, :color, :size, :bold, :italic, :underline, :bgcolor]
+          [:content, :style, :align, :color, :size, :bold, :italic, :underline, :bgcolor, :keep_next]
         end
 
       end

data/lib/caracal/core/models/relationship_model.rb

@@ -18,6 +18,7 @@ module Caracal
         TYPE_MAP = {
           font:       'http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable', 
           footer:     'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer',
+          header:     'http://schemas.openxmlformats.org/officeDocument/2006/relationships/header',
           image:      'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image',
           link:       'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink',
           numbering:  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering',

data/lib/caracal/core/models/table_model.rb

@@ -232,7 +232,7 @@ module Caracal
           k << [:data, :align, :width]
           k << [:border_color, :border_line, :border_size, :border_spacing]
           k << [:border_bottom, :border_left, :border_right, :border_top, :border_horizontal, :border_vertical]
-          k << [:column_widths]
+          k << [:column_widths, :header_rows]
           k.flatten
         end
         

data/lib/caracal/core/page_numbers.rb

@@ -25,6 +25,8 @@ module Caracal
           attr_reader :page_number_label_size
           attr_reader :page_number_number_size
           attr_reader :page_number_show
+          attr_reader :page_number_first
+          attr_reader :page_number_start
 
 
           #-------------------------------------------------------------
@@ -45,8 +47,10 @@ module Caracal
               @page_number_label_size   = model.page_number_label_size
               @page_number_number_size  = model.page_number_number_size
               @page_number_show         = model.page_number_show
+              @page_number_first        = model.page_number_first
+              @page_number_start        = model.page_number_start
             else
-              raise Caracal::Errors::InvalidModelError, 'page_numbers :align parameter must be :left, :center, or :right'
+              raise Caracal::Errors::InvalidModelError, 'page_numbers :align must be :left, :center, or :right, and :start must not be negative.'
             end
           end
 

data/lib/caracal/document.rb

@@ -4,6 +4,8 @@ require 'caracal/core/bookmarks'
 require 'caracal/core/custom_properties'
 require 'caracal/core/file_name'
 require 'caracal/core/fonts'
+require 'caracal/core/footer'
+require 'caracal/core/header'
 require 'caracal/core/iframes'
 require 'caracal/core/ignorables'
 require 'caracal/core/images'
@@ -26,6 +28,7 @@ require 'caracal/renderers/custom_renderer'
 require 'caracal/renderers/document_renderer'
 require 'caracal/renderers/fonts_renderer'
 require 'caracal/renderers/footer_renderer'
+require 'caracal/renderers/header_renderer'
 require 'caracal/renderers/numbering_renderer'
 require 'caracal/renderers/package_relationships_renderer'
 require 'caracal/renderers/relationships_renderer'
@@ -62,6 +65,9 @@ module Caracal
     include Caracal::Core::Tables
     include Caracal::Core::Text
 
+    include Caracal::Core::Footer
+    include Caracal::Core::Header
+
 
     #------------------------------------------------------
     # Public Class Methods
@@ -128,6 +134,49 @@ module Caracal
       @contents ||= []
     end
 
+    # A header or footer part to write: which kind it is, which pages it
+    # covers ('default' or 'first'), the content to render, whether to
+    # add the page number, and whether the section refers to it.
+    #
+    HeaderFooterPart = Struct.new(:kind, :type, :target, :model, :page_number, :referenced)
+
+    # This method returns the header and footer parts the document needs.
+    # footer1.xml is always written, as it always has been, but is only
+    # referenced when it has something to show.
+    #
+    def header_footer_parts
+      parts = []
+      if header_content
+        parts << HeaderFooterPart.new(:header, 'default', 'header1.xml', header_content, false, true)
+      end
+      shown = page_number_show || !footer_content.nil?
+      parts << HeaderFooterPart.new(:footer, 'default', 'footer1.xml', footer_content, page_number_show || footer_content.nil?, shown)
+
+      if title_page?
+        # The first page uses only first-page parts, so fall back to the
+        # default content for whichever one wasn't customized.
+        first_header = first_header_content || header_content
+        if first_header && first_header.valid?
+          parts << HeaderFooterPart.new(:header, 'first', 'header2.xml', first_header, false, true)
+        end
+
+        first_footer = first_footer_content || footer_content
+        first_footer = nil unless first_footer && first_footer.valid?
+        first_number = page_number_show && page_number_first
+        if first_footer || first_number
+          parts << HeaderFooterPart.new(:footer, 'first', 'footer2.xml', first_footer, first_number, true)
+        end
+      end
+      parts
+    end
+
+    # This method returns whether the first page has its own header and
+    # footer (Word's "Different First Page").
+    #
+    def title_page?
+      !first_header_content.nil? || !first_footer_content.nil? || (page_number_show && !page_number_first)
+    end
+
 
     #============ RENDERING ===============================
 
@@ -136,6 +185,9 @@ module Caracal
     #
     def render
       register_nested_iframes(contents)
+      header_footer_parts.each do |part|
+        relationship({ target: part.target, type: part.kind })
+      end
 
       buffer = ::Zip::OutputStream.write_buffer do |zip|
         render_package_relationships(zip)
@@ -144,7 +196,7 @@ module Caracal
         render_core(zip)
         render_custom(zip)
         render_fonts(zip)
-        render_footer(zip)
+        render_headers_and_footers(zip)
         render_settings(zip)
         render_styles(zip)
         render_document(zip)
@@ -193,53 +245,65 @@ module Caracal
 
     #============ RENDERERS ===============================
 
+    # This method adds a part to the package. Giving rubyzip the size up
+    # front stops rubyzip 3 from adding a zip64 extra field "just in case"
+    # to every entry, which LibreOffice 7.4 and older can't read.
+    #
+    def write_entry(zip, name, content)
+      content = content.to_s
+      entry   = ::Zip::Entry.new('', name)
+      entry.size = content.bytesize
+
+      zip.put_next_entry(entry)
+      zip.write(content)
+    end
+
     def render_app(zip)
       content = ::Caracal::Renderers::AppRenderer.render(self)
 
-      zip.put_next_entry('docProps/app.xml')
-      zip.write(content)
+      write_entry(zip, 'docProps/app.xml', content)
     end
 
     def render_content_types(zip)
       content = ::Caracal::Renderers::ContentTypesRenderer.render(self)
 
-      zip.put_next_entry('[Content_Types].xml')
-      zip.write(content)
+      write_entry(zip, '[Content_Types].xml', content)
     end
 
     def render_core(zip)
       content = ::Caracal::Renderers::CoreRenderer.render(self)
 
-      zip.put_next_entry('docProps/core.xml')
-      zip.write(content)
+      write_entry(zip, 'docProps/core.xml', content)
     end
 
     def render_custom(zip)
       content = ::Caracal::Renderers::CustomRenderer.render(self)
 
-      zip.put_next_entry('docProps/custom.xml')
-      zip.write(content)
+      write_entry(zip, 'docProps/custom.xml', content)
     end
 
     def render_document(zip)
       content = ::Caracal::Renderers::DocumentRenderer.render(self)
 
-      zip.put_next_entry('word/document.xml')
-      zip.write(content)
+      write_entry(zip, 'word/document.xml', content)
     end
 
     def render_fonts(zip)
       content = ::Caracal::Renderers::FontsRenderer.render(self)
 
-      zip.put_next_entry('word/fontTable.xml')
-      zip.write(content)
+      write_entry(zip, 'word/fontTable.xml', content)
     end
 
-    def render_footer(zip)
-      content = ::Caracal::Renderers::FooterRenderer.render(self)
+    def render_headers_and_footers(zip)
+      header_footer_parts.each do |part|
+        renderer = (part.kind == :header) ? ::Caracal::Renderers::HeaderRenderer : ::Caracal::Renderers::FooterRenderer
+        content  = renderer.render(self, part.model, part.page_number)
 
-      zip.put_next_entry('word/footer1.xml')
-      zip.write(content)
+        write_entry(zip, "word/#{ part.target }", content)
+
+        # rendering collects the relationships, so write them straight away
+        render_part_relationships(zip, part.target, part.model)
+      end
     end
 
     def render_media(zip)
@@ -251,44 +315,49 @@ module Caracal
           content = ::Caracal::Utilities.read_resource(rel.relationship_target)
         end
 
-        zip.put_next_entry("word/#{ rel.formatted_target }")
-        zip.write(content)
+        write_entry(zip, "word/#{ rel.formatted_target }", content)
       end
     end
 
     def render_numbering(zip)
       content = ::Caracal::Renderers::NumberingRenderer.render(self)
 
-      zip.put_next_entry('word/numbering.xml')
-      zip.write(content)
+      write_entry(zip, 'word/numbering.xml', content)
     end
 
     def render_package_relationships(zip)
       content = ::Caracal::Renderers::PackageRelationshipsRenderer.render(self)
 
-      zip.put_next_entry('_rels/.rels')
-      zip.write(content)
+      write_entry(zip, '_rels/.rels', content)
     end
 
     def render_relationships(zip)
       content = ::Caracal::Renderers::RelationshipsRenderer.render(self)
 
-      zip.put_next_entry('word/_rels/document.xml.rels')
-      zip.write(content)
+      write_entry(zip, 'word/_rels/document.xml.rels', content)
+    end
+
+    # Headers and footers resolve their images and links against their
+    # own relationships part, not the document's.
+    #
+    def render_part_relationships(zip, part, model)
+      return if model.nil? || model.relationships.empty?
+
+      content = ::Caracal::Renderers::RelationshipsRenderer.render(self, model.relationships)
+
+      write_entry(zip, "word/_rels/#{ part }.rels", content)
     end
 
     def render_settings(zip)
       content = ::Caracal::Renderers::SettingsRenderer.render(self)
 
-      zip.put_next_entry('word/settings.xml')
-      zip.write(content)
+      write_entry(zip, 'word/settings.xml', content)
     end
 
     def render_styles(zip)
       content = ::Caracal::Renderers::StylesRenderer.render(self)
 
-      zip.put_next_entry('word/styles.xml')
-      zip.write(content)
+      write_entry(zip, 'word/styles.xml', content)
     end
 
   end

data/lib/caracal/renderers/content_types_renderer.rb

@@ -31,7 +31,9 @@ module Caracal
             xml.send 'Override', { 'PartName' => '/docProps/core.xml',   'ContentType' => 'application/vnd.openxmlformats-package.core-properties+xml' }
             xml.send 'Override', { 'PartName' => '/docProps/custom.xml', 'ContentType' => 'application/vnd.openxmlformats-officedocument.custom-properties+xml' }
             xml.send 'Override', { 'PartName' => '/word/document.xml',   'ContentType' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml' }
-            xml.send 'Override', { 'PartName' => '/word/footer1.xml',    'ContentType' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml' }
+            document.header_footer_parts.each do |part|
+              xml.send 'Override', { 'PartName' => "/word/#{ part.target }", 'ContentType' => "application/vnd.openxmlformats-officedocument.wordprocessingml.#{ part.kind }+xml" }
+            end
             xml.send 'Override', { 'PartName' => '/word/fontTable.xml',  'ContentType' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml' }
             xml.send 'Override', { 'PartName' => '/word/numbering.xml',  'ContentType' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml' }
             xml.send 'Override', { 'PartName' => '/word/settings.xml',   'ContentType' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml' }

data/lib/caracal/renderers/document_renderer.rb

@@ -31,13 +31,17 @@ module Caracal
               #============= PAGE SETTINGS ==============================
 
               xml['w'].sectPr do
-                if document.page_number_show
-                  if rel = document.find_relationship('footer1.xml')
-                    xml['w'].footerReference({ 'r:id' => rel.formatted_id, 'w:type' => 'default' })
+                document.header_footer_parts.select(&:referenced).each do |part|
+                  if rel = document.find_relationship(part.target)
+                    xml['w'].send("#{ part.kind }Reference", { 'r:id' => rel.formatted_id, 'w:type' => part.type })
                   end
                 end
                 xml['w'].pgSz page_size_options
                 xml['w'].pgMar page_margin_options
+                unless document.page_number_start.nil?
+                  xml['w'].pgNumType({ 'w:start' => document.page_number_start })
+                end
+                xml['w'].titlePg if document.title_page?
               end
 
             end
@@ -63,6 +67,13 @@ module Caracal
         "render_#{ type }"
       end
 
+      # This method registers a relationship needed by the part being
+      # rendered. Images and links in the body belong to the document.
+      #
+      def relationship(options)
+        document.relationship(options)
+      end
+
       # This method renders a standard node of run properties based on the
       # model's attributes.
       #
@@ -113,7 +124,7 @@ module Caracal
           r_href     = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
 
           entry      = zip.glob('word/document.xml').first
-          content    = entry.get_input_stream.read
+          content    = Caracal::Core::Models::IFrameModel.read_entry(entry)
           doc_xml    = Nokogiri::XML(content)
 
           fragment = doc_xml.xpath('//w:body').first.children
@@ -145,7 +156,7 @@ module Caracal
           raise Caracal::Errors::NoDefaultStyleError 'Document must declare a default paragraph style.'
         end
 
-        rel      = document.relationship({ type: :image, target: model.image_url, data: model.image_data })
+        rel      = relationship({ type: :image, target: model.image_url, data: model.image_data })
         rel_id   = rel.relationship_id
         rel_name = rel.formatted_target
 
@@ -205,7 +216,7 @@ module Caracal
 
       def render_link(xml, model)
         if model.external?
-          rel = document.relationship({ target: model.link_href, type: :link })
+          rel = relationship({ target: model.link_href, type: :link })
           hyperlink_options = { 'r:id' => rel.formatted_id }
         else
           hyperlink_options = { 'w:anchor' => model.link_href }
@@ -219,6 +230,27 @@ module Caracal
         end
       end
 
+      # A complex field is a sequence of runs: begin, instruction, separate
+      # and end. Viewers that don't evaluate fields show the instruction
+      # text when the field characters aren't in runs of their own.
+      #
+      def render_field(xml, model)
+        xml['w'].r run_options do
+          render_run_attributes(xml, model, false)
+          xml['w'].fldChar({ 'w:fldCharType' => 'begin' })
+        end
+        xml['w'].r run_options do
+          render_run_attributes(xml, model, false)
+          xml['w'].instrText({ 'xml:space' => 'preserve' }, " #{ model.formatted_type } ")
+        end
+        %w(separate end).each do |type|
+          xml['w'].r run_options do
+            render_run_attributes(xml, model, false)
+            xml['w'].fldChar({ 'w:fldCharType' => type })
+          end
+        end
+      end
+
       def render_list(xml, model)
         if model.list_level == 0
           document.toplevel_lists << model
@@ -236,11 +268,16 @@ module Caracal
 
         xml['w'].p paragraph_options do
           xml['w'].pPr do
-            xml['w'].numPr do
-              xml['w'].ilvl({ 'w:val' => model.list_item_level })
-              xml['w'].numId({ 'w:val' => list_num })
+            if model.continuation?
+              # text after a nested list: no number, aligned with the item's text
+              xml['w'].ind({ 'w:left' => ls.style_left })
+            else
+              xml['w'].numPr do
+                xml['w'].ilvl({ 'w:val' => model.list_item_level })
+                xml['w'].numId({ 'w:val' => list_num })
+              end
+              xml['w'].ind({ 'w:left' => ls.style_left, 'w:hanging' => hanging })
             end
-            xml['w'].ind({ 'w:left' => ls.style_left, 'w:hanging' => hanging })
             xml['w'].contextualSpacing({ 'w:val' => '1' })
             xml['w'].rPr do
               xml['w'].u({ 'w:val' => 'none' })