Merge pull request #68 from dmpotter44/numbering

Add support for the "numbering" part

Author: boblail

examples/numbering

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+
+# This example shows how to use the "numbering" system to describe how a list
+# should be numbered within a document.
+
+# require "rails" # workaround: openxml-package uses `extract_options!`
+$:.push Dir.pwd + "/lib"
+require "openxml/docx"
+
+package = OpenXml::Docx::Package.new
+
+include OpenXml::Docx::Elements
+
+# Each list item is a paragraph. A helper function to create paragraphs in the
+# final document:
+def create_paragraph(content)
+  text = Text.new(content)
+  run = Run.new
+  run << text
+  paragraph = Paragraph.new
+  paragraph << run
+  paragraph
+end
+
+# First up, create a style for the list paragraph
+list_style = OpenXml::Docx::Style.new :paragraph
+list_style.id = 'ListParagraph'
+list_style.style_name = 'List Paragraph'
+list_style.paragraph.indentation.left = 720
+list_style.paragraph.contextual_spacing = true
+
+package.styles << list_style
+
+# Each list needs a numbering within the numbering part of the document.
+
+# Create an abstract numbering that describes a bulleted list:
+abstract_numbering = AbstractNumbering.new(0)
+
+# Each numbering can have multiple levels. Define the first level as a bulleted list:
+level_0 = Level.new
+level_0.level = 0
+level_0.start = 1
+level_0.number_format = :bullet
+# This is the default bullet Word uses
+level_0.level_text = "\u00B7".encode("UTF-8")
+level_0.alignment = :left
+level_0.character_style.font.ascii = "Symbol"
+level_0.character_style.font.high_ansi = "Symbol"
+level_0.character_style.font.hint = :default
+level_0.paragraph_style.indentation.left = 720
+level_0.paragraph_style.indentation.hanging = 360
+abstract_numbering << level_0
+
+package.numbering << abstract_numbering
+
+package.document << create_paragraph("Example of adding a list to a document")
+
+list_item = create_paragraph("First list item")
+list_item.paragraph_style = 'ListParagraph'
+# Say that this list item belongs to our first abstract numbering:
+list_item.numbering.level = 0
+list_item.numbering.id = 1
+# This ID is NOT the numbering ID we created above. Instead, it is a concrete
+# numbering that defines an instance of a list in the document. To link it to
+# our existing abstract numbering, we need to create a concrete numbering
+# instance:
+
+numbering = Numbering.new(1)
+# Setting the abstract numbering ID here links it to a given abstract numbering
+numbering.abstract_numbering_id = 0
+
+# And add this number to the numbering
+package.numbering << numbering
+
+# All that allows us to finally add the item to the document.
+
+package.document << list_item
+
+list_item = create_paragraph("Second list item")
+list_item.paragraph_style = 'ListParagraph'
+
+# The second list item is simpler: we can reuse the numbering we used above.
+list_item.numbering.level = 0
+list_item.numbering.id = 1
+
+package.document << list_item
+
+package.document << create_paragraph("Outline Example")
+
+# Lists with numbers are a bit more complicated. The following creates an
+# "outline" list:
+
+abstract_numbering = AbstractNumbering.new(1)
+
+[:upperRoman, :upperLetter, :decimal, :lowerLetter, :lowerRoman, :decimal, :lowerLetter].each.with_index do |number_format, index|
+  level = Level.new
+  level.level = index
+  level.start = 1
+  level.number_format = number_format
+  # Level text replacement tokens are always 1-based, while the levels
+  # themselves are 0-based
+  level.level_text = index < 4 ? "%#{index+1}." : "(%#{index+1})"
+  level.alignment = :left
+  level.paragraph_style.indentation.left = (360 * (index+1))
+  level.paragraph_style.indentation.hanging = 360
+  abstract_numbering << level
+end
+
+package.numbering << abstract_numbering
+
+numbering = Numbering.new(2)
+numbering.abstract_numbering_id = 1
+
+package.numbering << numbering
+
+(0..6).each do |level|
+  list_item = create_paragraph("Level #{level+1}")
+  list_item.paragraph_style = 'ListParagraph'
+  list_item.numbering.level = level
+  list_item.numbering.id = 2
+  package.document << list_item
+end
+
+filename = "numbering_example.docx"
+package.save File.expand_path("#{filename}")

lib/openxml/docx.rb

@@ -7,13 +7,15 @@ module Docx
     REL_FOOTER = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer".freeze
     REL_FONT_TABLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable".freeze
     REL_FONT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font".freeze
+    REL_NUMBERING = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering".freeze
     REL_IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image".freeze
 
     TYPE_STYLES = "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml".freeze
     TYPE_SETTINGS = "application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml".freeze
     TYPE_HEADER = "application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml".freeze
     TYPE_FOOTER = "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml".freeze
     TYPE_FONT_TABLE = "application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml".freeze
+    TYPE_NUMBERING = "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml".freeze
     TYPE_XML = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml".freeze
     TYPE_OBSCURED_FONT = "application/vnd.openxmlformats-officedocument.obfuscatedFont".freeze
     TYPE_IMAGE = {

lib/openxml/docx/elements/abstract_numbering.rb

@@ -0,0 +1,34 @@
+module OpenXml
+  module Docx
+    module Elements
+      class AbstractNumbering < OpenXml::Docx::Element
+        include HasChildren, HasProperties
+        tag :abstractNum
+
+        def initialize(id)
+          super()
+          self.id = id
+        end
+        # TODO: child levels is limited to a max of 9
+
+        with_namespace :w do
+          attribute :id, expects: :integer, displays_as: :abstractNumId#, required: true
+        end
+
+        # value_property :nsid - this is a UI property and likely not worth implementing
+        value_property :multi_level_type
+        # value_property :tmpl - this is a UI property and likely not worth implementing
+        # value_property :name
+        # value_property :style_link
+        # value_property :num_style_link
+
+        def property_xml(xml)
+          props = properties.keys.map(&method(:send)).compact
+          return if props.none?(&:render?)
+
+          props.each { |prop| prop.to_xml(xml) }
+        end
+      end
+    end
+  end
+end

lib/openxml/docx/elements/level.rb

@@ -0,0 +1,53 @@
+module OpenXml
+  module Docx
+    module Elements
+      class Level < OpenXml::Docx::Element
+        include HasChildren, HasProperties
+        tag :lvl
+
+        with_namespace :w do
+          attribute :level, expects: :integer, displays_as: :ilvl # required
+          # tplc is an entirely opaque "Word template code" and is
+          # "application-specific" according to the spec
+          attribute :template_code, expects: :long_hex_number, displays_as: :tplc
+          attribute :tentative, expects: :boolean
+        end
+
+        value_property :start
+        value_property :number_format
+        value_property :level_restart
+        value_property :associated_paragraph_style, as: :paragraph_style
+        value_property :legal_numbering
+        value_property :suffix
+        value_property :level_text
+        # TODO: Add pic_bullet support (this refers to an element that isn't
+        # implemented in the Numbering part)
+        # value_property :lvl_pic_bullet_id
+        value_property :alignment, as: :level_alignment
+
+        def paragraph_style
+          @paragraph_style ||= Paragraph.new
+        end
+
+        def character_style
+          @character_style ||= Run.new
+        end
+
+        def property_xml(xml)
+          props = properties.keys.map(&method(:send)).compact
+          return if props.none?(&:render?)
+
+          props.each { |prop| prop.to_xml(xml) }
+        end
+
+        def to_xml(xml)
+          xml["w"].public_send(tag, xml_attributes) {
+            property_xml(xml)
+            @paragraph_style.property_xml(xml) unless @paragraph_style.nil?
+            @character_style.property_xml(xml) unless @character_style.nil?
+          }
+        end
+      end
+    end
+  end
+end

lib/openxml/docx/elements/level_override.rb

@@ -0,0 +1,27 @@
+module OpenXml
+  module Docx
+    module Elements
+      class LevelOverride < OpenXml::Docx::Element
+        include HasChildren, HasProperties
+        tag :lvlOverride
+
+        with_namespace :w do
+          attribute :level, expects: :integer, displays_as: :ilvl # required
+        end
+
+        value_property :start_override
+
+        def override
+          @override ||= Level.new
+        end
+
+        def to_xml(xml)
+          xml["w"].public_send(tag, xml_attributes) {
+            start_override.to_xml(xml)
+            @override.to_xml(xml) unless @override.nil?
+          }
+        end
+      end
+    end
+  end
+end

lib/openxml/docx/elements/numbering.rb

@@ -0,0 +1,29 @@
+module OpenXml
+  module Docx
+    module Elements
+      class Numbering < OpenXml::Docx::Element
+        include HasChildren, HasProperties
+        tag :num
+
+        def initialize(id)
+          super()
+          self.id = id
+        end
+        # TODO: child lvlOverride is limited to 9
+
+        with_namespace :w do
+          attribute :id, expects: :integer, displays_as: :numId#, required: true
+        end
+
+        value_property :abstract_numbering_id
+
+        def property_xml(xml)
+          props = properties.keys.map(&method(:send)).compact
+          return if props.none?(&:render?)
+
+          props.each { |prop| prop.to_xml(xml) }
+        end
+      end
+    end
+  end
+end

lib/openxml/docx/package.rb

@@ -10,6 +10,7 @@ class Package < OpenXml::Package
                   :footers,
                   :styles,
                   :fonts,
+                  :numbering,
                   :image_names
 
       content_types do
@@ -23,6 +24,7 @@ class Package < OpenXml::Package
         override "/word/styles.xml", TYPE_STYLES
         override "/word/settings.xml", TYPE_SETTINGS
         override "/word/fontTable.xml", TYPE_FONT_TABLE
+        override "/word/numbering.xml", TYPE_NUMBERING
       end
 
       def initialize
@@ -32,6 +34,7 @@ def initialize
         @settings = OpenXml::Docx::Parts::Settings.new
         @styles = OpenXml::Docx::Parts::Styles.new
         @fonts = OpenXml::Docx::Parts::Fonts.new
+        @numbering = OpenXml::Docx::Parts::Numbering.new
         @document = OpenXml::Docx::Parts::Document.new
         @headers = []
         @footers = []
@@ -40,13 +43,15 @@ def initialize
         document.relationships.add_relationship REL_STYLES, "styles.xml"
         document.relationships.add_relationship REL_SETTINGS, "settings.xml"
         document.relationships.add_relationship REL_FONT_TABLE, "fontTable.xml"
+        document.relationships.add_relationship REL_NUMBERING, "numbering.xml"
 
         add_part "word/_rels/document.xml.rels", document.relationships
         add_part "word/_rels/fontTable.xml.rels", fonts.relationships
         add_part "word/document.xml", document
         add_part "word/settings.xml", settings
         add_part "word/styles.xml", styles
         add_part "word/fontTable.xml", fonts
+        add_part "word/numbering.xml", numbering
       end
 
       def embed_truetype_font(path: nil, name: nil)

lib/openxml/docx/parts/numbering.rb

@@ -0,0 +1,42 @@
+module OpenXml
+  module Docx
+    module Parts
+      class Numbering < OpenXml::Part
+        include RootNamespaces
+
+        attr_reader :abstractNumbers, :numbers
+
+        use_namespaces :w
+
+        def initialize
+          @abstractNumbers = []
+          @numbers = []
+          @relationships = OpenXml::Parts::Rels.new
+        end
+
+        def <<(child)
+          if child.is_a?(OpenXml::Docx::Elements::AbstractNumbering)
+            abstractNumbers << child
+          elsif child.is_a?(OpenXml::Docx::Elements::Numbering)
+            numbers << child
+          end
+        end
+
+        def count
+          abstractNums.count
+        end
+
+        def to_xml
+          build_standalone_xml do |xml|
+            xml.numbering(root_namespaces) {
+              xml.parent.namespace = :w
+              abstractNumbers.each { |num| num.to_xml(xml) }
+              numbers.each { |number| number.to_xml(xml) }
+            }
+          end
+        end
+
+      end
+    end
+  end
+end

lib/openxml/docx/properties/abstract_number_id.rb

@@ -0,0 +1,10 @@
+module OpenXml
+  module Docx
+    module Properties
+      class AbstractNumberingId < IntegerProperty
+        tag :abstractNumId
+
+      end
+    end
+  end
+end

lib/openxml/docx/properties/legal_numbering.rb

@@ -0,0 +1,10 @@
+module OpenXml
+  module Docx
+    module Properties
+      class LegalNumbering < OnOffProperty
+        tag :isLgl
+
+      end
+    end
+  end
+end