axlsx 1.1.5 → 1.1.6

data/lib/axlsx/workbook/worksheet/page_setup.rb

@@ -22,10 +22,14 @@ module Axlsx
     # * verticalDpi
     
     # Number of vertical pages to fit on.
-    # @return [Integer]
+    # @note PageSetup#fit_to is the recomended way to manage page fitting as only specifying one of fit_to_width/fit_to_height will result in the counterpart
+    # being set to 1.
+     # @return [Integer]
     attr_reader :fit_to_height
 
     # Number of horizontal pages to fit on.
+    # @note PageSetup#fit_to is the recomended way to manage page fitting as only specifying one of width/height will result in the counterpart
+    # being set to 1. 
     # @return [Integer]
     attr_reader :fit_to_width
 
@@ -45,7 +49,6 @@ module Axlsx
     # @return [Integer]
     attr_reader :scale
 
-
     # Creates a new PageSetup object
     # @option options [Integer] fit_to_height Number of vertical pages to fit on
     # @option options [Integer] fit_to_width Number of horizontal pages to fit on
@@ -77,13 +80,24 @@ module Axlsx
     def paper_width=(v); Axlsx::validate_number_with_unit(v); @paper_width = v; end
     # @see scale
     def scale=(v); Axlsx::validate_page_scale(v); @scale = v; end
+    
+    # convenience method to achieve sanity when setting fit_to_width and fit_to_height 
+    # as they both default to 1 if only their counterpart is specified.
+    # @note This method will overwrite any value you explicitly set via the fit_to_height or fit_to_width methods.
+    # @option options [Integer] width The number of pages to fit this worksheet on horizontally. Default 9999
+    # @option options [Integer] height The number of pages to fit this worksheet on vertically. Default 9999
+    def fit_to(options={})
+      self.fit_to_width = options[:width] || 9999
+      self.fit_to_height = options[:height] || 9999
+      [@fit_to_width, @fit_to_height]
+    end
 
     # Serializes the page settings element.
     # @param [String] str
     # @return [String]
     def to_xml_string(str = '')
       str << '<pageSetup '
-      str << instance_values.map{ |k,v| k.gsub(/_(.)/){ $1.upcase } << %{="#{v}"} }.join(' ')
+      str << instance_values.reject{ |k, v| k == 'worksheet' }.map{ |k,v| k.gsub(/_(.)/){ $1.upcase } << %{="#{v}"} }.join(' ')
       str << '/>'
     end
   end

data/lib/axlsx/workbook/worksheet/row.rb

@@ -5,9 +5,16 @@ module Axlsx
   # @see Worksheet#add_row
   class Row
 
-    # A list of serilizable attributes.
-    SERIALIZABLE_ATTRIBUTES = [:hidden, :outlineLevel, :collapsed, :style]
+    # No support is provided for the following attributes
+    # spans
+    # thickTop
+    # thickBottom
 
+
+    # A list of serilizable attributes.
+    # @note height(ht) and customHeight are manages separately for now. Have a look at Row#height
+    SERIALIZABLE_ATTRIBUTES = [:hidden, :outlineLevel, :collapsed, :s, :customFormat, :ph]
+    
     # The worksheet this row belongs to
     # @return [Worksheet]
     attr_reader :worksheet
@@ -16,36 +23,40 @@ module Axlsx
     # @return [SimpleTypedList]
     attr_reader :cells
 
-    # The height of this row in points, if set explicitly.
+    # Row height measured in point size. There is no margin padding on row height.
     # @return [Float]
     attr_reader :height
 
-    # Flag indicating if the outlining of the affected column(s) is in the collapsed state.
+    # Flag indicating if the outlining of row.
     # @return [Boolean]
     attr_reader :collapsed
 
-    # Flag indicating if the affected column(s) are hidden on this worksheet.
+    # Flag indicating if the the row is hidden.
     # @return [Boolean]
     attr_reader :hidden
 
-    # Outline level of affected column(s). Range is 0 to 7.
+    # Outlining level of the row, when outlining is on
     # @return [Integer]
     attr_reader :outlineLevel
 
-    # Default style for the affected column(s). Affects cells not yet allocated in the column(s). In other words, this style applies to new columns.
+    # The style applied ot the row. This affects the entire row.
     # @return [Integer]
-    attr_reader :style
-
-    # TODO  18.3.1.73
-    # customFormat
-    # # hidden
-    # ph
-    # # s (style)
-    # spans
-    # thickTop
-    # thickBottom
+    attr_reader :s
 
+    # indicates that a style has been applied directly to the row via Row#s
+    # @return [Boolean]
+    attr_reader :customFormat
 
+    # indicates if the row should show phonetic
+    # @return [Boolean]
+    attr_reader :ph
+
+    # NOTE removing this from the api as it is actually incorrect. 
+    # having a method to style a row's cells is fine, but it is not an attribute on the row. 
+    # The proper attribute is ':s'
+    # attr_reader style
+    #
+    
     # Creates a new row. New Cell objects are created based on the values, types and style options.
     # A new cell is created for each item in the values array. style and types options are applied as follows:
     #   If the types option is defined and is a symbol it is applied to all the cells created.
@@ -81,6 +92,12 @@ module Axlsx
       Axlsx.validate_boolean(v)
       @hidden = v
     end
+   
+    # @see Row#ph
+    def ph=(v) Axlsx.validate_boolean(v); @ph = v end
+
+    # @see Row#s
+    def s=(v) Axlsx.validate_unsigned_numeric(v); @s = v; @customFormat = true end
 
     # @see Row#outline
     def outlineLevel=(v)
@@ -88,7 +105,6 @@ module Axlsx
       @outlineLevel = v
     end
 
-
     # The index of this row in the worksheet
     # @return [Integer]
     def index

data/lib/axlsx/workbook/worksheet/sheet_protection.rb

@@ -0,0 +1,224 @@
+# encoding: UTF-8
+module Axlsx
+
+  # The SheetProtection object manages worksheet protection options per sheet.
+  class SheetProtection
+
+    # If 1 or true then AutoFilters should not be allowed to operate when the sheet is protected.
+    # If 0 or false then AutoFilters should be allowed to operate when the sheet is protected.
+    # @return [Boolean]
+    # default true 
+    attr_reader :auto_filter
+
+    # If 1 or true then deleting columns should not be allowed when the sheet is protected. 
+    # If 0 or false then deleting columns should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :delete_columns
+
+    # If 1 or true then deleting rows should not be allowed when the sheet is protected.
+    # If 0 or false then deleting rows should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :delete_rows
+
+    # If 1 or true then formatting cells should not be allowed when the sheet is protected.
+    # If 0 or false then formatting cells should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :format_cells
+
+    # If 1 or true then formatting columns should not be allowed when the sheet is protected.
+    # If 0 or false then formatting columns should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :format_columns
+
+    # If 1 or true then formatting rows should not be allowed when the sheet is protected. 
+    # If 0 or false then formatting rows should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :format_rows
+
+    # If 1 or true then inserting columns should not be allowed when the sheet is protected. 
+    # If 0 or false then inserting columns should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :insert_columns
+
+    # If 1 or true then inserting hyperlinks should not be allowed when the sheet is protected. 
+    # If 0 or false then inserting hyperlinks should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :insert_hyperlinks
+
+    # If 1 or true then inserting rows should not be allowed when the sheet is protected. 
+    # If 0 or false then inserting rows should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :insert_rows
+
+    # If 1 or true then editing of objects should not be allowed when the sheet is protected. 
+    # If 0 or false then objects are allowed to be edited when the sheet is protected.
+    # @return [Boolean]
+    # default false
+    attr_reader :objects
+
+    # If 1 or true then PivotTables should not be allowed to operate when the sheet is protected.
+    # If 0 or false then PivotTables should be allowed to operate when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :pivot_tables
+
+    # Specifies the salt which was prepended to the user-supplied password before it was hashed using the hashing algorithm
+    # @return [String]
+    attr_reader :salt_value
+
+    # If 1 or true then Scenarios should not be edited when the sheet is protected.
+    # If 0 or false then Scenarios are allowed to be edited when the sheet is protected.
+    # @return [Boolean]
+    # default false
+    attr_reader :scenarios
+
+    # If 1 or true then selection of locked cells should not be allowed when the sheet is protected.
+    # If 0 or false then selection of locked cells should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default false
+    attr_reader :select_locked_cells
+
+    # If 1 or true then selection of unlocked cells should not be allowed when the sheet is protected.
+    # If 0 or false then selection of unlocked cells should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default false
+    attr_reader :select_unlocked_cells
+
+    # If 1 or true then the sheet is protected. 
+    # If 0 or false then the sheet is not protected. 
+    # @return [Boolean]
+    # default true
+    attr_reader :sheet
+
+    # If 1 or true then sorting should not be allowed when the sheet is protected.
+    # If 0 or false then sorting should be allowed when the sheet is protected.
+    # @return [Boolean]
+    # default true
+    attr_reader :sort
+
+    # Password hash
+    # @return [String]
+    # default nil
+    attr_reader :password
+
+    # Creates a new SheetProtection instance
+    # @option options [Boolean] sheet @see SheetProtection#sheet
+    # @option options [Boolean] objects @see SheetProtection#objects
+    # @option options [Boolean] scenarios @see SheetProtection#scenarios
+    # @option options [Boolean] format_cells @see SheetProtection#objects
+    # @option options [Boolean] format_columns @see SheetProtection#format_columns
+    # @option options [Boolean] format_rows @see SheetProtection#format_rows
+    # @option options [Boolean] insert_columns @see SheetProtection#insert_columns
+    # @option options [Boolean] insert_rows @see SheetProtection#insert_rows
+    # @option options [Boolean] insert_hyperlinks @see SheetProtection#insert_hyperlinks
+    # @option options [Boolean] delete_columns @see SheetProtection#delete_columns
+    # @option options [Boolean] delete_rows @see SheetProtection#delete_rows
+    # @option options [Boolean] select_locked_cells @see SheetProtection#select_locked_cells
+    # @option options [Boolean] sort @see SheetProtection#sort
+    # @option options [Boolean] auto_filter @see SheetProtection#auto_filter
+    # @option options [Boolean] pivot_tables @see SheetProtection#pivot_tables
+    # @option options [Boolean] select_unlocked_cells @see SheetProtection#select_unlocked_cells
+    # @option options [String] password. The password required for unlocking. @see SheetProtection#password=
+    # @option options [Boolean] objects @see SheetProtection#objects
+    def initialize(options={})
+      @objects = @scenarios = @select_locked_cells = @select_unlocked_cells = false
+      @sheet = @format_cells = @format_rows = @format_columns = @insert_columns = @insert_rows = @insert_hyperlinks = @delete_columns = @delete_rows = @sort = @auto_filter = @pivot_tables = true
+      @password = nil
+
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+
+     # create validating setters for boolean values
+     # @return [Boolean] 
+     [:sheet, :objects, :scenarios, :select_locked_cells, :sort,
+     :select_unlocked_cells, :format_cells, :format_rows, :format_columns,
+     :insert_columns, :insert_rows, :insert_hyperlinks, :delete_columns,
+     :delete_rows, :auto_filter, :pivot_tables].each do |f_name|
+       define_method "#{f_name.to_s}=".to_sym do |v|
+         Axlsx::validate_boolean(v)
+         instance_variable_set "@#{f_name.to_s}".to_sym, v
+       end
+     end
+
+     # This block is intended to implement the salt_value, hash_value and spin count as per the ECMA-376 standard. 
+     # However, it does not seem to actually work in EXCEL - instead they are using their old retro algorithm shown below 
+     # defined in the transitional portion of the speck. I am leaving this code in in the hope that someday Ill be able to 
+     # figure out why it does not work, and if Excel even supports it.
+#     def propper_password=(v)
+#       @algorithm_name = v == nil ? nil : 'SHA-1'
+#       @salt_value = @spin_count = @hash_value = v if v == nil
+#       return if v == nil
+#       require 'digest/sha1'
+#       @spin_count = 10000
+#       @salt_value = Digest::SHA1.hexdigest(rand(36**8).to_s(36))
+#       @spin_count.times do |count|
+#         @hash_value = Digest::SHA1.hexdigest((@hash_value ||= (@salt_value + v.to_s)) + Array(count).pack('V'))
+#       end
+#     end
+
+
+
+     # encodes password for protection locking
+     def password=(v)
+       return if v == nil
+        @password = create_password_hash(v)
+     end
+
+     # Serialize the object
+     # @param [String] str
+     # @return [String]
+     def to_xml_string(str = '')
+       str << '<sheetProtection '
+       str << instance_values.map{ |k,v| k.gsub(/_(.)/){ $1.upcase } << %{="#{v.to_s}"} }.join(' ')
+       str << '/>'
+     end
+
+  private
+    # Creates a password hash for a given password
+    # @return [String]
+    def create_password_hash(password)
+      encoded_password = encode_password(password)
+
+      password_as_hex = [encoded_password].pack("v")
+      password_as_string = password_as_hex.unpack("H*").first.upcase
+
+      password_as_string[2..3] + password_as_string[0..1]
+    end
+
+
+    # Encodes a given password
+    # Based on the algorithm provided by Daniel Rentz of OpenOffice.
+    # http://www.openoffice.org/sc/excelfileformat.pdf, Revision 1.42, page 115 (21.05.2012)
+    # @return [String]
+    def encode_password(password)
+      i = 0
+      chars = password.split(//)
+      count = chars.size
+
+      chars.collect! do |char|
+        i += 1
+        char     = char.unpack('c')[0] << i #ord << i
+        low_15   = char & 0x7fff
+        high_15  = char & 0x7fff << 15
+        high_15  = high_15 >> 15
+        char     = low_15 | high_15
+      end
+
+      encoded_password  = 0x0000
+      chars.each { |c| encoded_password ^= c }
+      encoded_password ^= count
+      encoded_password ^= 0xCE4B
+    end
+  end
+end

data/lib/axlsx/workbook/worksheet/table.rb

@@ -19,8 +19,8 @@ module Axlsx
     attr_reader :style
 
     # Creates a new Table object
-    # @param [String] ref The reference to the table data.
-    # @param [Sheet] ref The sheet containing the table data.
+    # @param [String] ref The reference to the table data like 'A1:G24'.
+    # @param [Worksheet] sheet The sheet containing the table data.
     # @option options [Cell, String] name
     # @option options [TableStyle] style
     def initialize(ref, sheet, options={})

data/lib/axlsx/workbook/worksheet/worksheet.rb

@@ -8,6 +8,15 @@ module Axlsx
     # @return [String]
     attr_reader :name
 
+    # The sheet protection object for this workbook
+    # @return [SheetProtection]
+    # @see SheetProtection
+    def sheet_protection
+      @sheet_protection ||= SheetProtection.new
+      yield @sheet_protection if block_given?
+      @sheet_protection
+    end
+
     # The workbook that owns this worksheet
     # @return [Workbook]
     attr_reader :workbook
@@ -51,9 +60,14 @@ module Axlsx
     # @return Boolean
     attr_reader :selected
 
-    # Indicates if the worksheet should print in a single page
+    # Indicates if the worksheet will be fit by witdh or height to a specific number of pages.
+    # To alter the width or height for page fitting, please use page_setup.fit_to_widht or page_setup.fit_to_height.
+    # If you want the worksheet to fit on more pages (e.g. 2x2), set {PageSetup#fit_to_width} and {PageSetup#fit_to_height} accordingly.
     # @return Boolean
-    attr_reader :fit_to_page
+    # @see #page_setup
+    def fit_to_page
+      (@page_setup != nil && (@page_setup.fit_to_width != nil || @page_setup.fit_to_height != nil))
+    end
 
 
     # Column info for the sheet
@@ -88,7 +102,7 @@ module Axlsx
     #      wb = Axlsx::Package.new.workbook
     #
     #      # using options when creating the worksheet.
-    #      ws = wb.add_worksheet :page_setup => {:fit_to_width => 1, :orientation => :landscape}
+    #      ws = wb.add_worksheet :page_setup => {:fit_to_width => 2, :orientation => :landscape}
     #
     #      # use the set method of the page_setup object
     #      ws.page_setup.set(:paper_width => "297mm", :paper_height => "210mm")
@@ -110,15 +124,15 @@ module Axlsx
     # @example
     #      wb = Axlsx::Package.new.workbook
     #      # using options when creating the worksheet.
-    #      ws = wb.add_worksheet :print_options => {:gridLines => true, :horizontalCentered => true}
+    #      ws = wb.add_worksheet :print_options => {:grid_lines => true, :horizontal_centered => true}
     #
     #      # use the set method of the page_margins object
     #      ws.print_options.set(:headings => true)
     #
     #      # set page margins in a block
     #      ws.print_options do |options|
-    #        options.horizontalCentered = true
-    #        options.verticalCentered = true
+    #        options.horizontal_centered = true
+    #        options.vertical_centered = true
     #      end
     # @see PrintOptions#initialize
     # @return [PrintOptions]
@@ -146,16 +160,17 @@ module Axlsx
       self.workbook = wb
       @workbook.worksheets << self
       @page_marging = @page_setup = @print_options = nil
-      @drawing = @page_margins = @auto_filter = nil
+      @drawing = @page_margins = @auto_filter = @sheet_protection = nil
       @merged_cells = []
       @auto_fit_data = []
       @conditional_formattings = []
+      @data_validations = []
       @comments = Comments.new(self)
       @selected = false
       @show_gridlines = true
       self.name = "Sheet" + (index+1).to_s
       @page_margins = PageMargins.new options[:page_margins] if options[:page_margins]
-      @page_setup = PageSetup.new options[:page_setup] if options[:page_setup]
+      @page_setup = PageSetup.new options[:page_setup]  if options[:page_setup]
       @print_options = PrintOptions.new options[:print_options] if options[:print_options]
       @rows = SimpleTypedList.new Row
       @column_info = SimpleTypedList.new Col
@@ -188,6 +203,17 @@ module Axlsx
       cf.add_rules rules
       @conditional_formattings << cf
     end
+    
+    # Add data validation to this worksheet.
+    #
+    # @param [String] cells The cells the validation will apply to.
+    # @param [hash] data_validation options defining the validation to apply.
+    # @see  examples/data_validation.rb for an example
+    def add_data_validation(cells, data_validation)
+      dv = DataValidation.new(data_validation)
+      dv.sqref = cells
+      @data_validations << dv
+    end
 
     # Creates merge information for this worksheet.
     # Cells can be merged by calling the merge_cells method on a worksheet.
@@ -202,7 +228,7 @@ module Axlsx
       @merged_cells << if cells.is_a?(String)
                          cells
                        elsif cells.is_a?(Array)
-                         cells = cells.sort { |x, y| x.r <=> y.r }
+                         cells = cells.sort { |x, y| [x.index, x.row.index] <=> [y.index, y.row.index] }
                          "#{cells.first.r}:#{cells.last.r}"
                        end
     end
@@ -233,12 +259,11 @@ module Axlsx
     end
 
 
-    # Indicates if the worksheet should print in a single page.
-    # This is true by default.
+    # (see #fit_to_page)
     # @return [Boolean]
     def fit_to_page=(v)
-      Axlsx::validate_boolean v
-      @fit_to_page = v
+      warn('axlsx::DEPRECIATED: Worksheet#fit_to_page has been depreciated. This value will automatically be set for you when you use PageSetup#fit_to.')
+      fit_to_page
     end
 
 
@@ -462,6 +487,7 @@ module Axlsx
     # @param [String] str
     # @return [String]
     def to_xml_string
+      rels = relationships
       str = '<?xml version="1.0" encoding="UTF-8"?>'
       str.concat "<worksheet xmlns=\"%s\" xmlns:r=\"%s\">" % [XML_NS, XML_NS_R]
       str.concat "<sheetPr><pageSetUpPr fitToPage=\"%s\"></pageSetUpPr></sheetPr>" % fit_to_page if fit_to_page
@@ -477,19 +503,28 @@ module Axlsx
       @rows.each_with_index { |row, index| row.to_xml_string(index, str) }
       str.concat '</sheetData>'
       str.concat "<autoFilter ref='%s'></autoFilter>" % @auto_filter if @auto_filter
+      @sheet_protection.to_xml_string(str) if @sheet_protection
       str.concat "<mergeCells count='%s'>%s</mergeCells>" % [@merged_cells.size, @merged_cells.reduce('') { |memo, obj| memo += "<mergeCell ref='%s'></mergeCell>" % obj } ] unless @merged_cells.empty?
       print_options.to_xml_string(str) if @print_options
       page_margins.to_xml_string(str) if @page_margins
       page_setup.to_xml_string(str) if @page_setup
-      str.concat "<drawing r:id='rId1'></drawing>" if @drawing
-      unless @tables.empty?
-        str.concat "<tableParts count='%s'>%s</tableParts>" % [@tables.size, @tables.reduce('') { |memo, obj| memo += "<tablePart r:id='%s'/>" % obj.rId }]
-      end
-      @conditional_formattings.each do |cf|
-        str.concat cf.to_xml_string
-      end
-      str << '<legacyDrawing r:id="rId1"/>' if @comments.size > 0
-      str + '</worksheet>'
+      str << "<drawing r:id='rId" << (rels.index{ |r| r.Type == DRAWING_R } + 1).to_s << "'/>" if @drawing
+      str << "<legacyDrawing r:id='rId" << (rels.index{ |r| r.Type == VML_DRAWING_R } + 1).to_s << "'/>" if @comments.size > 0
+     unless @tables.empty?
+       str.concat "<tableParts count='%s'>%s</tableParts>" % [@tables.size, @tables.reduce('') { |memo, obj| memo += "<tablePart r:id='%s'/>" % obj.rId }]
+     end
+     @conditional_formattings.each do |cf|
+       str.concat cf.to_xml_string
+     end
+     
+     unless @data_validations.empty?
+       str.concat "<dataValidations count=\"#{@data_validations.size}\">"
+       @data_validations.each do |df|
+         str.concat df.to_xml_string
+       end
+       str.concat '</dataValidations>'
+     end
+     str + '</worksheet>'
     end
 
     # The worksheet relationships. This is managed automatically by the worksheet