rubyXL 2.1.1 → 2.2.0

data/VERSION

@@ -1 +1 @@
-2.1.1
+2.2.0

data/lib/rubyXL.rb

@@ -6,6 +6,7 @@ require 'rubyXL/objects/column_range'
 require 'rubyXL/objects/stylesheet'
 require 'rubyXL/objects/shared_strings'
 require 'rubyXL/objects/worksheet'
+require 'rubyXL/objects/chartsheet'
 require 'rubyXL/objects/calculation_chain'
 require 'rubyXL/objects/workbook'
 require 'rubyXL/objects/document_properties'

data/lib/rubyXL/objects/border.rb

@@ -1,12 +1,11 @@
 require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
 
 module RubyXL
 
   class BorderEdge < OOXMLObject
-    define_attribute(:style,   :string)
-    define_child_node(RubyXL::Color, :default => 'none', :values => 
-                        %w{ none thin medium dashed dotted thick double hair
-                            mediumDashed dashDot mediumDashDot dashDotDot slantDashDot } )
+    define_attribute(:style, RubyXL::ST_BorderStyle, :default => 'none')
+    define_child_node(RubyXL::Color)
 
     def ==(other)
       style == other.style

data/lib/rubyXL/objects/calculation_chain.rb

@@ -14,7 +14,7 @@ module RubyXL
   end
 
   # http://www.schemacentral.com/sc/ooxml/e-ssml_calcChain.html
-  class CalculationChain < OOXMLObject
+  class CalculationChain < OOXMLTopLevelObject
     define_child_node(RubyXL::CalculationChainCell, :collection => true, :accessor => :cells)
     define_child_node(RubyXL::ExtensionStorageArea)
 

data/lib/rubyXL/objects/cell_style.rb

@@ -1,4 +1,5 @@
 require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
 
 module RubyXL
 
@@ -15,10 +16,8 @@ module RubyXL
 
   # http://www.schemacentral.com/sc/ooxml/e-ssml_alignment-1.html
   class Alignment < OOXMLObject
-    define_attribute(:horizontal,      :string,
-                       :values => %w{general left center right fill justify centerContinuous distributed})
-    define_attribute(:vertical,        :string,
-                       :values => %w{top center bottom justify distributed})
+    define_attribute(:horizontal,      RubyXL::ST_HorizontalAlignment)
+    define_attribute(:vertical,        RubyXL::ST_VerticalAlignment)
     define_attribute(:textRotation,    :int)
     define_attribute(:wrapText,        :bool)
     define_attribute(:indent,          :int)

data/lib/rubyXL/objects/chartsheet.rb

@@ -0,0 +1,78 @@
+require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
+require 'rubyXL/objects/extensions'
+require 'rubyXL/objects/relationships'
+require 'rubyXL/objects/sheet_common'
+
+module RubyXL
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_sheetProtection-4.html
+  class ChartsheetProtection < OOXMLObject
+    define_attribute(:password, :string)
+    define_attribute(:content,  :bool, :default => false)
+    define_attribute(:objects,  :bool, :default => false)
+    define_element_name 'sheetProtection'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_sheetPr-4.html
+  class ChartsheetProperties < OOXMLObject
+    define_attribute(:published,                         :bool, :default => true)
+    define_attribute(:codeName,                          :string)
+    define_child_node(RubyXL::Color, :node_name => :tabColor)
+    define_element_name 'sheetPr'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_pageSetup-5.html
+  class ChartsheetPageSetup < OOXMLObject
+    define_attribute(:paperSize,          :int,    :default => 1)
+    define_attribute(:firstPageNumber,    :int,    :default => 1)
+    define_attribute(:orientation,        RubyXL::ST_Orientation, :default => 'default')
+    define_attribute(:usePrinterDefaults, :bool,   :default => true)
+    define_attribute(:blackAndWhite,      :bool,   :default => false)
+    define_attribute(:draft,              :bool,   :default => false)
+    define_attribute(:useFirstPageNumber, :bool,   :default => false)
+    define_attribute(:horizontalDpi,      :int,    :default => 600)
+    define_attribute(:verticalDpi,        :int,    :default => 600)
+    define_attribute(:copies,             :int,    :default => 1)
+    define_attribute(:'r:id',             :string)
+    define_element_name 'pageSetup'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_sheetView-2.html
+  class ChartsheetView < OOXMLObject
+    define_attribute(:tabSelected,    :bool,  :default => false)
+    define_attribute(:zoomScale,      :int,   :default => 100)
+    define_attribute(:workbookViewId, :int,   :required => true, :default => 0 )
+    define_attribute(:zoomToFit,      :bool,  :default => false)
+    define_child_node(RubyXL::ExtensionStorageArea)
+    define_element_name 'sheetView'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_sheetViews-4.html
+  class ChartsheetViewContainer < OOXMLObject
+    define_child_node(RubyXL::ChartsheetView, :collection => true, :accessor => :sheet_views)
+    define_child_node(RubyXL::ExtensionStorageArea)
+    define_element_name 'sheetViews'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_chartsheet.html
+  class Chartsheet < OOXMLTopLevelObject
+    define_child_node(RubyXL::ChartsheetProperties)
+    define_child_node(RubyXL::ChartsheetViewContainer, :accessor => :sheet_view_container)
+    define_child_node(RubyXL::ChartsheetProtection)
+    define_child_node(RubyXL::CustomSheetViews,   :accessor => :custom_sheet_view_container)
+    define_child_node(RubyXL::PageMargins)
+    define_child_node(RubyXL::ChartsheetPageSetup)
+    define_child_node(RubyXL::HeaderFooterSettings)
+    define_child_node(RubyXL::RID, :node_name => :drawing)
+    define_child_node(RubyXL::RID, :node_name => :legacyDrawing)
+    define_child_node(RubyXL::RID, :node_name => :legacyDrawingHF)
+    define_child_node(RubyXL::RID, :node_name => :picture)
+    define_child_node(RubyXL::WebPublishingItemContainer, :accessor => :web_items_container)
+    define_child_node(RubyXL::ExtensionStorageArea)
+    define_element_name 'chartsheet'
+    set_namespaces('xmlns'       => 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+                   'xmlns:r'     => 'http://schemas.openxmlformats.org/officeDocument/2006/relationships')
+  end
+
+end

data/lib/rubyXL/objects/container_nodes.rb

@@ -1,4 +1,5 @@
 require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
 
 module RubyXL
 
@@ -78,9 +79,7 @@ module RubyXL
 
   # http://www.schemacentral.com/sc/ooxml/e-docPropsVTypes_vector.html
   class Vector < OOXMLObject
-    define_attribute(:baseType, :string, :required => true, :values => 
-                       %w{ variant i1 i2 i4 i8 ui1 ui2 ui4 ui8 r4 r8
-                           lpstr lpwstr bstr date filetime bool cy error clsid cf })
+    define_attribute(:baseType, RubyXL::ST_VectorBaseType, :required => true)
     define_attribute(:size,     :int, :required => true)
     define_child_node(RubyXL::Variant,     :collection => true, :node_name => 'vt:variant')
     define_child_node(RubyXL::IntegerNode, :collection => true, :node_name => 'vt:i1')

data/lib/rubyXL/objects/data_validation.rb

@@ -1,20 +1,15 @@
 require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
 require 'rubyXL/objects/formula'
 
 module RubyXL
 
   # http://www.schemacentral.com/sc/ooxml/e-ssml_dataValidation-1.html
   class DataValidation < OOXMLObject
-    define_attribute(:type,             :string, :default => 'none',
-                        :values => %w{ none whole decimal list date time textLength custom })
-    define_attribute(:errorStyle,       :string, :default => 'stop',
-                        :values => %w{ stop warning information })
-    define_attribute(:imeMode,          :string, :default => 'noControl',
-                        :values => %w{ noControl off on disabled hiragana fullKatakana halfKatakana
-                            fullAlpha halfAlpha fullHangul halfHangul })
-    define_attribute(:operator,         :string, :default => 'between',
-                        :values => %w{ between notBetween equal notEqual lessThan lessThanOrEqual
-                            greaterThan greaterThanOrEqual })
+    define_attribute(:type,             RubyXL::ST_DataValidationType,       :default => 'none')
+    define_attribute(:errorStyle,       RubyXL::ST_DataValidationErrorStyle, :default => 'stop')
+    define_attribute(:imeMode,          RubyXL::ST_DataValidationImeMode,    :default => 'noControl')
+    define_attribute(:operator,         RubyXL::ST_DataValidationOperator,   :default => 'between')
     define_attribute(:allowBlank,       :bool, :default => false)
     define_attribute(:showDropDown,     :bool, :default => false)
     define_attribute(:showInputMessage, :bool, :default => false)

data/lib/rubyXL/objects/document_properties.rb

@@ -4,7 +4,7 @@ require 'rubyXL/objects/container_nodes'
 module RubyXL
 
   # http://www.schemacentral.com/sc/ooxml/e-extended-properties_Properties.html
-  class DocumentProperties < OOXMLObject
+  class DocumentProperties < OOXMLTopLevelObject
     attr_accessor :workbook
 
     define_child_node(RubyXL::StringNode,  :node_name => :Template)

data/lib/rubyXL/objects/fill.rb

@@ -1,4 +1,5 @@
 require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
 
 module RubyXL
 
@@ -11,11 +12,7 @@ module RubyXL
 
   # http://www.schemacentral.com/sc/ooxml/e-ssml_patternFill-1.html
   class PatternFill < OOXMLObject
-    define_attribute(:patternType, :string, :values =>
-                       %w{ none solid mediumGray darkGray lightGray
-                           darkHorizontal darkVertical darkDown darkUp darkGrid darkTrellis
-                           lightHorizontal lightVertical lightDown lightUp lightGrid lightTrellis
-                           gray125 gray0625 })
+    define_attribute(:patternType, RubyXL::ST_PatternType)
     define_child_node(RubyXL::Color, :node_name => :fgColor )
     define_child_node(RubyXL::Color, :node_name => :bgColor )
     define_element_name 'patternFill'
@@ -23,7 +20,7 @@ module RubyXL
 
   # http://www.schemacentral.com/sc/ooxml/e-ssml_gradientFill-1.html
   class GradientFill < OOXMLObject
-    define_attribute(:type,   :string, :values => %w{ linear path }, :default => 'linear')
+    define_attribute(:type,   RubyXL::ST_GradientType, :default => 'linear')
     define_attribute(:degree, :float,  :default => 0)
     define_attribute(:left,   :float,  :default => 0)
     define_attribute(:right,  :float,  :default => 0)

data/lib/rubyXL/objects/filters.rb

@@ -0,0 +1,120 @@
+require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
+require 'rubyXL/objects/extensions'
+
+module RubyXL
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_dateGroupItem-1.html
+  class DateGroupItem < OOXMLObject
+    define_attribute(:year,   :int, :required => true)
+    define_attribute(:month,  :int)
+    define_attribute(:day,    :int)
+    define_attribute(:hour,   :int)
+    define_attribute(:minute, :int)
+    define_attribute(:second, :int)
+    define_attribute(:dateTimeGrouping, RubyXL::ST_DateTimeGrouping)
+    define_element_name 'dateGroupItem'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_filters-1.html
+  class FilterContainer < OOXMLObject
+    define_attribute(:blank,        :bool,  :default  => false)
+    define_attribute(:calendarType, RubyXL::ST_CalendarType, :default => 'none')
+    define_child_node(RubyXL::StringValue,    :node_name => :filter, :collection => true, :accessor => :filters)
+    define_child_node(RubyXL::DateGroupItem, :collection => true, :accessor => :date_group_items)
+    define_element_name 'filters'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_top10-1.html
+  class Top10 < OOXMLObject
+    define_attribute(:top,       :bool,  :default  => true)	
+    define_attribute(:percent,   :bool,  :default  => false)
+    define_attribute(:val,       :float, :required => true)
+    define_attribute(:filterVal, :float)
+    define_element_name 'top10'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_customFilter-1.html
+  class CustomFilter < OOXMLObject
+    define_attribute(:operator, RubyXL::ST_FilterOperator, :default => 'equal')
+    define_attribute(:val, :string)
+    define_element_name 'customFilter'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_customFilters-1.html
+  class CustomFilterContainer < OOXMLObject
+    define_attribute(:and, :bool,  :default  => false)
+    define_child_node(RubyXL::CustomFilter, :collection => true, :accessor => :custom_filters)
+    define_element_name 'customFilters'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_dynamicFilter-1.html
+  class DynamicFilter < OOXMLObject
+    define_attribute(:type,   RubyXL::ST_DynamicFilterType, :required => true)
+    define_attribute(:val,    :float)
+    define_attribute(:maxVal, :float)
+    define_element_name 'dynamicFilter'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_colorFilter-1.html
+  class ColorFilter < OOXMLObject
+    define_attribute(:dxfId,     :string)
+    define_attribute(:cellColor, :bool)
+    define_element_name 'colorFilter'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_iconFilter-1.html
+  class IconFilter < OOXMLObject
+    define_attribute(:iconSet, RubyXL::ST_IconSetType)
+    define_attribute(:iconId,  :int)
+    define_element_name 'iconFilter'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_filterColumn-1.html
+  class AutoFilterColumn < OOXMLObject
+    define_attribute(:colId,        :int,  :required => true)
+    define_attribute(:hiddenButton, :bool, :default  => false)
+    define_attribute(:showButton,   :bool, :default  => true)	
+    define_child_node(RubyXL::FilterContainer)
+    define_child_node(RubyXL::Top10)
+    define_child_node(RubyXL::CustomFilterContainer, :accessor => :custom_filter_container)
+    define_child_node(RubyXL::DynamicFilter)
+    define_child_node(RubyXL::ColorFilter)
+    define_child_node(RubyXL::IconFilter)
+    define_child_node(RubyXL::ExtensionStorageArea)
+    define_element_name 'filterColumn'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_sortCondition-1.html
+  class SortCondition < OOXMLObject
+    define_attribute(:descending, :bool,   :default  => false)
+    define_attribute(:sortBy,     RubyXL::ST_SortBy, :default => 'value')
+    define_attribute(:ref,        :ref,    :required => true)
+    define_attribute(:customList, :string)
+    define_attribute(:dxfId,      :int)
+    define_attribute(:iconSet,    RubyXL::ST_IconSetType, :required => true, :default => '3Arrows')
+    define_attribute(:iconId,     :int)
+    define_element_name 'sortCondition'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_sortState-2.html
+  class SortState < OOXMLObject
+    define_attribute(:columnSort,    :bool,   :default  => false)
+    define_attribute(:caseSensitive, :bool,   :default  => false)
+    define_attribute(:sortMethod,    RubyXL::ST_SortMethod, :default => 'none')
+    define_attribute(:ref,           :ref,    :required => true)
+    define_child_node(RubyXL::SortCondition,  :colection => true)
+    define_child_node(RubyXL::ExtensionStorageArea)
+    define_element_name 'sortState'
+  end
+
+  # http://www.schemacentral.com/sc/ooxml/e-ssml_autoFilter-2.html
+  class AutoFilter < OOXMLObject
+    define_attribute(:ref, :ref)
+    define_child_node(RubyXL::AutoFilterColumn)
+    define_child_node(RubyXL::SortState)
+    define_child_node(RubyXL::ExtensionStorageArea)
+    define_element_name 'autoFilter'
+  end
+
+end

data/lib/rubyXL/objects/formula.rb

@@ -1,12 +1,12 @@
 require 'rubyXL/objects/ooxml_object'
+require 'rubyXL/objects/simple_types'
 
 module RubyXL
 
   # http://www.schemacentral.com/sc/ooxml/e-ssml_f-1.html
   class Formula < OOXMLObject
     define_attribute(:_,    :string, :accessor => :expression)
-    define_attribute(:t,    :string, :default => 'normal', :values =>
-                       %w{ normal array dataTable shared })
+    define_attribute(:t,    RubyXL::ST_CellFormulaType, :default => 'normal')
     define_attribute(:aca,  :bool,   :default => false)
     define_attribute(:ref,  :ref)
     define_attribute(:dt2D, :bool,   :default => false)

data/lib/rubyXL/objects/ooxml_object.rb

@@ -1,12 +1,9 @@
-require 'pp'
-
 module RubyXL
 
   # Parent class for defining OOXML based objects (not unlike Rails' +ActiveRecord+!)
   # Most importantly, provides functionality of parsing such objects from XML,
   # and marshalling them to XML.
   class OOXMLObject
-
     # Get the value of a [sub]class variable if it exists, or create the respective variable
     # with the passed-in +default+ (or +{}+, if not specified)
     # 
@@ -30,46 +27,73 @@ module RubyXL
 
     # Defines an attribute of OOXML object.
     # === Parameters
-    # * +attribute_name+ - Name of the element attribute as seen in the source XML. Can be either "String" or :Symbol
-    #   * Special attibute name '_' (underscore) denotes the value of the element rather than attribute.
+    # * +attribute_name+ - Name of the element attribute as seen in the source XML. Can be either <tt>"String"</tt> or <tt>:Symbol</tt>
+    #   * Special attibute name <tt>'_'</tt> (underscore) denotes the value of the element rather than attribute.
     # * +attribute_type+ - Specifies the conversion type for the attribute when parsing. Available options are:
-    #   * :int - Integer
-    #   * :float - Float
-    #   * :string - String (no conversion)
-    #   * :sqref - RubyXL::Sqref
-    #   * :ref - RubyXL::Reference
-    #   * :bool - Boolean ("1" and "true" convert to +true+, others to +false+)
+    #   * +:int+ - <tt>Integer</tt>
+    #   * +:float+ - <tt>Float</tt>
+    #   * +:string+ - <tt>String</tt> (no conversion)
+    #   * +:sqref+ - RubyXL::Sqref
+    #   * +:ref+ - RubyXL::Reference
+    #   * +:bool+ - <tt>Boolean</tt> ("1" and "true" convert to +true+, others to +false+)
+    #   * one of +simple_types+ - <tt>String</tt>, plus the list of acceptable values is saved for future validation (not used yet).
     # * +extra_parameters+ - Hash of optional parameters as follows:
-    #   * :accessor - Name of the accessor for this attribute to be defined on the object. If not provided, defaults to classidied +attribute_name+.
-    #   * :default - Value this attribute defaults to if not explicitly provided.
-    #   * :required - Whether this attribute is required when writing XML. If the value of the attrinute is not explicitly provided, +:default+ is written instead.
-    #   * :values - List of acceptable values for this attribute (curently not used).
+    #   * +:accessor+ - Name of the accessor for this attribute to be defined on the object. If not provided, defaults to classidied +attribute_name+.
+    #   * +:default+ - Value this attribute defaults to if not explicitly provided.
+    #   * +:required+ - Whether this attribute is required when writing XML. If the value of the attrinute is not explicitly provided, +:default+ is written instead.
     # ==== Examples
     #   define_attribute(:outline, :bool, :default => true)
-    # A Boolean attribute 'outline' with default value +true+ will be accessible by calling +obj.outline+
+    # A <tt>Boolean</tt> attribute 'outline' with default value +true+ will be accessible by calling +obj.outline+
     #   define_attribute(:uniqueCount,  :int)
-    # An Integer attribute 'uniqueCount' accessible as +obj.unique_count+
+    # An <tt>Integer</tt> attribute 'uniqueCount' accessible as +obj.unique_count+
     #   define_attribute(:_,  :string, :accessor => :expression)
-    # The value of the element will be accessible as a String by calling +obj.expression+
+    # The value of the element will be accessible as a <tt>String</tt> by calling +obj.expression+
     #   define_attribute(:errorStyle, :string, :default => 'stop', :values => %w{ stop warning information })
-    # A String attribute named 'errorStyle' will be accessible as +obj.error_style+, valid values are "stop", "warning", "information"
+    # A <tt>String</tt> attribute named 'errorStyle' will be accessible as +obj.error_style+, valid values are <tt>"stop"</tt>, <tt>"warning"</tt>, <tt>"information"</tt>
     def self.define_attribute(attr_name, attr_type, extra_params = {})
       attrs = obtain_class_variable(:@@ooxml_attributes)
 
       accessor = extra_params[:accessor] || accessorize(attr_name)
       attr_name = attr_name.to_s
 
-      attrs[attr_name] = {
+      attr_hash = {
         :accessor   => accessor,
         :attr_type  => attr_type,
         :optional   => !extra_params[:required], 
         :default    => extra_params[:default],
-        :valies     => extra_params[:values]
       }
 
+      if attr_type.is_a?(Array) then
+        attr_hash[:values] = attr_type
+        attr_hash[:attr_type] = :string
+      end
+
+
+      attrs[attr_name] = attr_hash
+
       self.send(:attr_accessor, accessor)
     end
     
+    # Defines a child node of OOXML object.
+    # === Parameters
+    # * +klass+ - Class (descendant of RubyXL::OOXMLObject) of the child nodes. Child node objects will be produced by calling +parse+ method of that class.
+    # * +extra_parameters+ - Hash of optional parameters as follows:
+    #   * +:accessor+ - Name of the accessor for this attribute to be defined on the object. If not provided, defaults to classidied +attribute_name+.
+    #   * +:node_name+ - Node name for the child node, in case it does not match the one defined by the +klass+.
+    #   * +:collection+ - Whether the child node should be treated as a single node or a collection of nodes:
+    #     * +false+ (default) - child node is directly accessible through the respective accessor;
+    #     * +true+ - a collection of child nodes is accessed as +Array+ through the respective accessor;
+    #     * +:with_count+ - same as +true+, but in addition, the attribute +count+ is defined on the current object, that will be automatically set to the number of elements in the collection at the start of +write_xml+ call.
+    # ==== Examples
+    #   define_child_node(RubyXL::Alignment)
+    # Define a singular child node parsed by the RubyXL::BorderEdge.parse() and accessed by the default <tt>obj.alignment</tt> accessor
+    #   define_child_node(RubyXL::Hyperlink, :colection => true, :accessor => :hyperlinks)
+    # Define an array of nodes accessed by <tt>obj.hyperlinks</tt> accessor, each of which will be parsed by the RubyXL::Hyperlink.parse()
+    #   define_child_node(RubyXL::BorderEdge, :node_name => :left)
+    #   define_child_node(RubyXL::BorderEdge, :node_name => :right)
+    # Use class RubyXL::BorderEdge when parsing both the elements <tt><left ...></tt> and <tt><right ...></tt> elements.
+    #   define_child_node(RubyXL::Font, :collection => :with_count, :accessor => :fonts)
+    # Upon writing of the object this was defined on, its <tt>count</tt> attribute will be set to the count of nodes in <tt>fonts</tt> array
     def self.define_child_node(klass, extra_params = {})
       child_nodes = obtain_class_variable(:@@ooxml_child_nodes)
       child_node_name = (extra_params[:node_name] || klass.class_variable_get(:@@ooxml_tag_name)).to_s
@@ -88,25 +112,33 @@ module RubyXL
       self.send(:attr_accessor, accessor)
     end
 
-    def self.define_element_name(v)
-      self.class_variable_set(:@@ooxml_tag_name, v)
+    # Defines the name of the element that represents the current OOXML object. Should only be used once per object.
+    # In case of different objects represented by the same class in different parts of OOXML tree, +:node_name+ 
+    # extra parameter can be used to override the default element name.
+    # === Parameters
+    # * +element_name+
+    # ==== Examples
+    #   define_element_name 'externalReference'
+    def self.define_element_name(element_name)
+      self.class_variable_set(:@@ooxml_tag_name, element_name)
     end
 
+    # #TODO# This method will eventually be obsoleted.
     def self.set_countable
       self.class_variable_set(:@@ooxml_countable, true)
       self.send(:attr_accessor, :count)
     end
 
-    # Sets the list of namespaces on this object to be added when writing out XML. Valid only on top-level objects.
+    # Recursively write the OOXML object and all its children out as Nokogiri::XML. Immediately before the actual 
+    # generation, +before_write_xml()+ is called to perform last-minute cleanup and validation operations; if it
+    # returns +false+, an empty string is returned (rather than +nil+, so Nokogiri::XML's <tt>&lt;&lt;</tt> operator
+    # can be used without additional +nil+ checking)
     # === Parameters
-    # * +namespace_hash+ - Hash of namespaces in the form of <tt>"prefix" => "url"</tt>
+    # * +xml+ - Base Nokogiri::XML object used for building. If omitted, a blank document will be generated.
+    # * +node_name_override+ - if present, is used instead of the default element name for this object provided by +define_element_name+
     # ==== Examples
-    #   set_namespaces('xmlns'   => 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
-    #                  'xmlns:r' => 'http://schemas.openxmlformats.org/officeDocument/2006/relationships')
-    def self.set_namespaces(namespace_hash)
-      self.class_variable_set(:@@ooxml_namespaces, namespace_hash)
-    end
-
+    #   obj.write_xml
+    # Creates a new Nokogiti::XML and 
     def write_xml(xml = nil, node_name_override = nil)
       if xml.nil? then
         seed_xml = Nokogiri::XML('<?xml version = "1.0" standalone ="yes"?>')
@@ -172,20 +204,6 @@ module RubyXL
       instance_variable_set("@count", 0) if obtain_class_variable(:@@ooxml_countable, false)
     end
 
-    def self.process_attribute(obj, raw_value, params)
-      val = raw_value &&
-              case params[:attr_type]
-              when :int    then Integer(raw_value)
-              when :float  then Float(raw_value)
-              when :string then raw_value
-              when :sqref  then RubyXL::Sqref.new(raw_value)
-              when :ref    then RubyXL::Reference.new(raw_value)
-              when :bool   then ['1', 'true'].include?(raw_value)
-              end              
-      obj.send("#{params[:accessor]}=", val)
-    end
-    private_class_method :process_attribute
-
     def self.parse(node)
       node = Nokogiri::XML.parse(node) if node.is_a?(IO) || node.is_a?(String)
 
@@ -251,6 +269,9 @@ module RubyXL
       new_copy
     end
 
+    # Prototype method. For sparse collections (+Rows+, +Cells+, etc.) must return index at which this object
+    # is expected to reside in the collection. If +nil+ is returned, then object is simply added 
+    # to the end of the collection.
     def index_in_collection
       nil
     end
@@ -266,30 +287,69 @@ module RubyXL
       true 
     end
 
-    def add_to_zip(zipfile)
-      xml_string = write_xml
-      return if xml_string.empty?
-      zipfile.get_output_stream(self.class.filepath) { |f| f << xml_string }
+    private
+    def self.accessorize(str)
+      acc = str.to_s.dup
+      acc.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+      acc.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      acc.gsub!(':','_')
+      acc.downcase.to_sym
     end
 
+    def self.process_attribute(obj, raw_value, params)
+      val = raw_value &&
+              case params[:attr_type]
+              when :int    then Integer(raw_value)
+              when :float  then Float(raw_value)
+              when :string then raw_value
+              when :sqref  then RubyXL::Sqref.new(raw_value)
+              when :ref    then RubyXL::Reference.new(raw_value)
+              when :bool   then ['1', 'true'].include?(raw_value)
+              end              
+      obj.send("#{params[:accessor]}=", val)
+    end
+
+  end
+
+  # Extension class providing functionality for top-level OOXML objects that are represented by
+  # their own <tt>.xml</tt> files in <tt>.xslx</tt> zip container.
+
+  class OOXMLTopLevelObject < OOXMLObject
+    # Prototype method. For top-level OOXML object, returns the path at which the current object's XML file
+    # is located within the <tt>.xslx</tt> zip container.
     def self.filepath
       raise 'Subclass responsebility'
     end
 
+    # Sets the list of namespaces on this object to be added when writing out XML. Valid only on top-level objects.
+    # === Parameters
+    # * +namespace_hash+ - Hash of namespaces in the form of <tt>"prefix" => "url"</tt>
+    # ==== Examples
+    #   set_namespaces('xmlns'   => 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+    #                  'xmlns:r' => 'http://schemas.openxmlformats.org/officeDocument/2006/relationships')
+    def self.set_namespaces(namespace_hash)
+      self.class_variable_set(:@@ooxml_namespaces, namespace_hash)
+    end
+
+    # Generates the top-level OOXML object by parsing its XML file from the temporary
+    # directory containing the unzipped contents of <tt>.xslx</tt>
+    # === Parameters
+    # * +dirpath+ - path to the directory with the unzipped <tt>.xslx</tt> contents.
     def self.parse_file(dirpath)
       full_path = File.join(dirpath, filepath)
       return nil unless File.exist?(full_path)
       parse(File.open(full_path, 'r'))
     end
 
-    private
-    def self.accessorize(str)
-      acc = str.to_s.dup
-      acc.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
-      acc.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
-      acc.gsub!(':','_')
-      acc.downcase.to_sym
+    # Saves the contents of the object as XML to respective location in <tt>.xslx</tt> zip container.
+    # === Parameters
+    # * +zipfile+ - ::Zip::File to which the resulting XNMML should be added.
+    def add_to_zip(zipfile)
+      xml_string = write_xml
+      return if xml_string.empty?
+      zipfile.get_output_stream(self.class.filepath) { |f| f << xml_string }
     end
 
   end
+
 end