axlsx 1.1.1 → 1.1.2

data/lib/axlsx/stylesheet/font.rb

@@ -103,7 +103,8 @@ module Axlsx
     # @option options [Integer] sz
     def initialize(options={})
       options.each do |o|
-        self.send("#{o[0]}=", o[1]) if self.respond_to? o[0]
+        next if o[1].nil?
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
       end
     end
     # @see name

data/lib/axlsx/stylesheet/styles.rb

@@ -14,6 +14,7 @@ module Axlsx
   require 'axlsx/stylesheet/table_style.rb'
   require 'axlsx/stylesheet/table_styles.rb'
   require 'axlsx/stylesheet/table_style_element.rb'
+  require 'axlsx/stylesheet/dxf.rb'
   require 'axlsx/stylesheet/xf.rb'
   require 'axlsx/stylesheet/cell_protection.rb'
 
@@ -137,6 +138,7 @@ module Axlsx
     # @option options [String] bg_color The background color to apply to the cell
     # @option options [Boolean] hidden Indicates if the cell should be hidden
     # @option options [Boolean] locked Indicates if the cell should be locked
+    # @option options [Symbol] type What type of style is this. Options are [:dxf, :xf]. :xf is default
     # @option options [Hash] alignment A hash defining any of the attributes used in CellAlignment
     # @see CellAlignment
     #
@@ -189,67 +191,156 @@ module Axlsx
     #   ws.add_row :values => ["Q4", 2000, 20], :style=>[title, currency, percent]
     #   f = File.open('example_you_got_style.xlsx', 'w')
     #   p.serialize(f)
+    #
+    # @example Differential styling
+    #   # Differential styles apply on top of cell styles. Used in Conditional Formatting. Must specify :type => :dxf, and you can't use :num_fmt.
+    #   require "rubygems" # if that is your preferred way to manage gems!
+    #   require "axlsx"
+    #
+    #   p = Axlsx::Package.new
+    #   wb = p.workbook
+    #   ws = wb.add_worksheet
+    #
+    #   # define your styles
+    #   profitable = wb.styles.add_style(:bg_color => "FFFF0000",
+    #                              :fg_color=>"#FF000000",
+    #                              :type => :dxf)
+    #
+    #   ws.add_row :values => ["Genreated At:", Time.now], :styles=>[nil, date_time]
+    #   ws.add_row :values => ["Previous Year Quarterly Profits (JPY)"], :style=>title
+    #   ws.add_row :values => ["Quarter", "Profit", "% of Total"], :style=>title
+    #   ws.add_row :values => ["Q1", 4000, 40], :style=>[title, currency, percent]
+    #   ws.add_row :values => ["Q2", 3000, 30], :style=>[title, currency, percent]
+    #   ws.add_row :values => ["Q3", 1000, 10], :style=>[title, currency, percent]
+    #   ws.add_row :values => ["Q4", 2000, 20], :style=>[title, currency, percent]
+    #
+    #   ws.add_conditional_formatting("A1:A7", { :type => :cellIs, :operator => :greaterThan, :formula => "2000", :dxfId => profitable, :priority => 1 })
+    #   f = File.open('example_differential_styling', 'w')
+    #   p.serialize(f)
+    #
     def add_style(options={})
-
-      numFmtId = if options[:format_code]
-                   n = @numFmts.map{ |f| f.numFmtId }.max + 1
-                   numFmts << NumFmt.new(:numFmtId => n, :formatCode=> options[:format_code])
-                   n
-                 else
-                   options[:num_fmt] || 0
-                 end
-
-      borderId = options[:border] || 0
-
-      if borderId.is_a?(Hash)
-        raise ArgumentError, "border hash definitions must include both style and color" unless borderId.keys.include?(:style) && borderId.keys.include?(:color)
-
-        s = borderId[:style]
-        c = borderId[:color]
-        edges = borderId[:edges] || [:left, :right, :top, :bottom]
-
-        border = Border.new
-        edges.each {|pr| border.prs << BorderPr.new(:name => pr, :style=>s, :color => Color.new(:rgb => c))}
-        borderId = self.borders << border
+      # Default to :xf
+      options[:type] ||= :xf
+      raise ArgumentError, "Type must be one of [:xf, :dxf]" unless [:xf, :dxf].include?(options[:type] )
+
+      fill = parse_fill_options options
+      font = parse_font_options options
+      numFmt = parse_num_fmt_options options
+      border = parse_border_options options
+      alignment = parse_alignment_options options
+      protection = parse_protection_options options
+
+      case options[:type]
+      when :dxf
+        style = Dxf.new :fill => fill, :font => font, :numFmt => numFmt, :border => border, :alignment => alignment, :protection => protection
+      else
+        style = Xf.new :fillId=>fill || 0, :fontId=>font || 0, :numFmtId=>numFmt || 0, :borderId=>border || 0, :alignment => alignment, :protection => protection, :applyFill=>!fill.nil?, :applyFont=>!font.nil?, :applyNumberFormat =>!numFmt.nil?, :applyBorder=>!border.nil?, :applyAlignment => !alignment.nil?, :applyProtection => !protection.nil?
       end
 
-      raise ArgumentError, "Invalid borderId" unless borderId < borders.size
+      options[:type] == :xf ? cellXfs << style : dxfs << style
+    end
 
-      fill = if options[:bg_color]
-               color = Color.new(:rgb=>options[:bg_color])
-               pattern = PatternFill.new(:patternType =>:solid, :fgColor=>color)
-               fills << Fill.new(pattern)
-             else
-               0
-             end
+    # parses add_style options for protection styles
+    # noop if options hash does not include :hide or :locked key
 
-      fontId = if (options.values_at(:fg_color, :sz, :b, :i, :u, :strike, :outline, :shadow, :charset, :family, :font_name).length)
-                 font = Font.new()
-                 [:b, :i, :u, :strike, :outline, :shadow, :charset, :family, :sz].each { |k| font.send("#{k}=", options[k]) unless options[k].nil? }
-                 font.color = Color.new(:rgb => options[:fg_color]) unless options[:fg_color].nil?
-                 font.name = options[:font_name] unless options[:font_name].nil?
-                 fonts << font
-               else
-                 0
-               end
+    # @option options [Boolean] hide boolean value defining cell protection attribute for hiding.
+    # @option options [Boolean] locked boolean value defining cell protection attribute for locking.
+    # @return [CellProtection]
+    def parse_protection_options(options={})
+      return if (options.keys & [:hidden, :locked]).empty?
+      CellProtection.new(options)
+    end
 
-      applyProtection = (options[:hidden] || options[:locked]) ? 1 : 0
+    # parses add_style options for alignment
+    # noop if options hash does not include :alignment key
+    # @option options [Hash] alignment A hash of options to prive the CellAlignment intializer
+    # @return [CellAlignment]
+    # @see CellAlignment
+    def parse_alignment_options(options={})
+      return unless options[:alignment]
+      CellAlignment.new options[:alignment]
+    end
 
-      xf = Xf.new(:fillId => fill, :fontId=>fontId, :applyFill=>1, :applyFont=>1, :numFmtId=>numFmtId, :borderId=>borderId, :applyProtection=>applyProtection)
+    # parses add_style options for fonts. If the options hash contains :type => :dxf we return a new Font object.
+    # if not, we return the index of the newly created font object in the styles.fonts collection.
+    # @note noop if none of the options described here are set on the options parameter.
+    # @option options [Symbol] type The type of style object we are working with (dxf or xf)
+    # @option options [String] fg_color The text color
+    # @option options [Integer] sz The text size
+    # @option options [Boolean] b Indicates if the text should be bold
+    # @option options [Boolean] i Indicates if the text should be italicised
+    # @option options [Boolean] u Indicates if the text should be underlined
+    # @option options [Boolean] strike Indicates if the text should be rendered with a strikethrough
+    # @option options [Boolean] outline Indicates if the text should be rendered with a shadow
+    # @option options [Integer] charset The character set to use.
+    # @option options [Integer] family The font family to use.
+    # @option options [String] font_name The name of the font to use
+    # @return [Font|Integer]
+    def parse_font_options(options={})
+      return if (options.keys & [:fg_color, :sz, :b, :i, :u, :strike, :outline, :shadow, :charset, :family, :font_name]).empty?
+      font = Font.new(options)
+      font.color = Color.new(:rgb => options[:fg_color]) if options[:fg_color]
+      font.name = options[:font_name] if options[:font_name]
+      options[:type] == :dxf ? font : fonts << font
+    end
 
-      xf.applyNumberFormat = true if xf.numFmtId > 0
-      xf.applyBorder = true if borderId > 0
+    # parses add_style options for fills. If the options hash contains :type => :dxf we return a Fill object. If not, we return the index of the fill after being added to the fills collection.
+    # @note noop if :bg_color is not specified in options
+    # @option options [String] bg_color The rgb color to apply to the fill
+    # @return [Fill|Integer]
+    def parse_fill_options(options={})
+      return unless options[:bg_color]
+      color = Color.new(:rgb=>options[:bg_color])
+      pattern = PatternFill.new(:patternType =>:solid, :fgColor=>color)
+      fill = Fill.new(pattern)
+      options[:type] == :dxf ? fill : fills << fill
+    end
 
-      if options[:alignment]
-        xf.alignment = CellAlignment.new(options[:alignment])
-        xf.applyAlignment = true
+    # parses Style#add_style options for borders.
+    # @note noop if :border is not specified in options
+    # @option options [Hash|Integer] A border style definition hash or the index of an existing border. Border style definition hashes must include :style and color: key-value entries and may include an :edges entry that references an array of symbols identifying which border edges you wish to apply the style or any other valid Border initializer options. If the :edges entity is not provided the style is applied to all edges of cells that reference this style.
+    # @example
+    #   #apply a thick red border to the top and bottom
+    #   { :border => { :style => :thick, :color => "FFFF0000", :edges => [:top, :bottom] }
+    # @return [Border|Integer]
+    def parse_border_options(options={})
+      return unless options[:border]
+      b_opts = options[:border]
+      if b_opts.is_a?(Hash)
+        raise ArgumentError, (ERR_INVALID_BORDER_OPTIONS % b_opts) unless b_opts.values_at(:style, :color).size == 2
+        border = Border.new b_opts
+        (b_opts[:edges] || [:left, :right, :top, :bottom]).each do |edge|
+          b_options = { :name => edge, :style => b_opts[:style], :color => Color.new(:rgb => b_opts[:color]) }
+          border.prs << BorderPr.new(b_options)
+        end
+        options[:type] == :dxf ? border : borders << border
+      elsif b_opts.is_a? Integer
+        raise ArgumentError, (ERR_INVALID_BORDER_ID % b_opts) unless b_opts < borders.size
+        if options[:type] == :dxf
+          borders[b_opts].clone
+        else
+          border = b_opts
+        end
       end
+    end
 
-      if applyProtection
-        xf.protection = CellProtection.new(options)
+    # Parses Style#add_style options for number formatting.
+    # noop if neither :format_code or :num_format options are set.
+    # @option options [Hash] A hash describing the :format_code and/or :num_fmt integer for the style.
+    # @return [NumFmt|Integer]
+    def parse_num_fmt_options(options={})
+      return if (options.keys & [:format_code, :num_fmt]).empty?
+
+      #When the user provides format_code - we always need to create a new numFmt object
+      #When the type is :dxf we always need to create a new numFmt object
+      if options[:format_code] || options[:type] == :dxf
+        #If this is a standard xf we pull from numFmts the highest current and increment for num_fmt
+        options[:num_fmt] ||= (@numFmts.map{ |num_fmt| num_fmt.numFmtId }.max + 1) if options[:type] != :dxf
+        numFmt = NumFmt.new(:numFmtId => options[:num_fmt] || 0, :formatCode=> options[:format_code].to_s)
+        options[:type] == :dxf ? numFmt : (numFmts << numFmt; numFmt.numFmtId)
+      else
+        options[:num_fmt]
       end
-
-      cellXfs << xf
     end
 
     # Serializes the object
@@ -306,7 +397,7 @@ module Axlsx
       @cellXfs << Xf.new(:borderId=>0, :xfId=>0, :numFmtId=>14, :fontId=>0, :fillId=>0, :applyNumberFormat=>1)
       @cellXfs.lock
 
-      @dxfs = SimpleTypedList.new(Xf, "dxfs"); @dxfs.lock
+      @dxfs = SimpleTypedList.new(Dxf, "dxfs"); @dxfs.lock
       @tableStyles = TableStyles.new(:defaultTableStyle => "TableStyleMedium9", :defaultPivotStyle => "PivotStyleLight16"); @tableStyles.lock
     end
   end

data/lib/axlsx/stylesheet/xf.rb

@@ -85,6 +85,7 @@ module Axlsx
     # @option options [CellProtection] protection
     def initialize(options={})
       options.each do |o|
+        next if o[1].nil?
         self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
       end
     end
@@ -139,5 +140,6 @@ module Axlsx
       str << '</xf>'
     end
 
+
   end
 end

data/lib/axlsx/util/constants.rb

@@ -232,4 +232,12 @@ module Axlsx
   # error message for duplicate sheet names
   ERR_DUPLICATE_SHEET_NAME = "There is already a worksheet in this workbook named '%s'. Please use a unique name"
 
+  # error message when user does not provide color and or style options for border in Style#add_sytle
+  ERR_INVALID_BORDER_OPTIONS = "border hash must include both style and color. e.g. :border => { :color => 'FF000000', :style => :thin }. You provided: %s"
+
+  # error message for invalid border id reference
+  ERR_INVALID_BORDER_ID = "The border id you specified (%s) does not exist. Please add a border with Style#add_style before referencing its index."
+
+  # error message for invalid angles
+  ERR_ANGLE = "Angles must be a value between -90 and 90. You provided: %s"
 end

data/lib/axlsx/util/validators.rb

@@ -45,6 +45,9 @@ module Axlsx
     true
   end
 
+  def self.validate_angle(v)
+    raise ArgumentError, (ERR_ANGLE % v.inspect) unless (v >= -5400000 && v <= 5400000)
+  end
   # Requires that the value is a Fixnum or Integer and is greater or equal to 0
   # @param [Any] v The value validated
   # @raise [ArgumentError] raised if the value is not a Fixnum or Integer value greater or equal to 0
@@ -96,6 +99,47 @@ module Axlsx
        :darkTrellis, :lightHorizontal, :lightVertical, :lightDown, :lightUp, :lightGrid, :lightTrellis, :gray125, :gray0625], v
   end
 
+  # Requires that the value is one of the ST_TimePeriod types
+  # valid time period types are today, yesterday, tomorrow, last7Days,
+  # thisMonth, lastMonth, nextMonth, thisWeek, lastWeek, nextWeek
+  def self.validate_time_period_type(v)
+    RestrictionValidator.validate :time_period_type, [:today, :yesterday, :tomorrow, :last7Days, :thisMonth, :lastMonth, :nextMonth, :thisWeek, :lastWeek, :nextWeek], v
+
+
+  end
+
+  # Requires that the value is one of the valid ST_IconSet types
+  # Allowed values are: 3Arrows, 3ArrowsGray, 3Flags, 3TrafficLights1, 3TrafficLights2, 3Signs, 3Symbols, 3Symbols2, 4Arrows, 4ArrowsGray, 4RedToBlack, 4Rating, 4TrafficLights, 5Arrows, 5ArrowsGray, 5Rating, 5Quarters
+  def self.validate_icon_set(v)
+    RestrictionValidator.validate :iconSet, ["3Arrows", "3ArrowsGray", "3Flags", "3TrafficLights1", "3TrafficLights2", "3Signs", "3Symbols", "3Symbols2", "4Arrows", "4ArrowsGray", "4RedToBlack", "4Rating", "4TrafficLights", "5Arrows", "5ArrowsGray", "5Rating", "5Quarters"], v
+  end
+
+  # Requires that the value is valid conditional formatting type.
+  # valid types must be one of expression, cellIs, colorScale,
+  # dataBar, iconSet, top10, uniqueValues, duplicateValues,
+  # containsText, notContainsText, beginsWith, endsWith,
+  # containsBlanks, notContainsBlanks, containsErrors,
+  # notContainsErrors, timePeriod, aboveAverage
+  # @param [Any] v The value validated
+  def self.validate_conditional_formatting_type(v)
+    RestrictionValidator.validate :conditional_formatting_type, [:expression, :cellIs, :colorScale, :dataBar, :iconSet, :top10, :uniqueValues, :duplicateValues, :containsText, :notContainsText, :beginsWith, :endsWith, :containsBlanks, :notContainsBlanks, :containsErrors, :notContainsErrors, :timePeriod, :aboveAverage], v
+  end
+
+  # Requires thatt he value is a valid conditional formatting value object type.
+  # valid types must be one of num, percent, max, min, formula and percentile
+  def self.validate_conditional_formatting_value_object_type(v)
+    RestrictionValidator.validate :conditional_formatting_value_object_type, [:num, :percent, :max, :min, :formula, :percentile], v
+  end
+
+  # Requires that the value is valid conditional formatting operator.
+  # valid operators must be one of lessThan, lessThanOrEqual, equal,
+  # notEqual, greaterThanOrEqual, greaterThan, between, notBetween,
+  # containsText, notContains, beginsWith, endsWith
+  # @param [Any] v The value validated
+  def self.validate_conditional_formatting_operator(v)
+    RestrictionValidator.validate :conditional_formatting_type, [:lessThan, :lessThanOrEqual, :equal, :notEqual, :greaterThanOrEqual, :greaterThan, :between, :notBetween, :containsText, :notContains, :beginsWith, :endsWith], v
+  end
+
   # Requires that the value is a gradient_type.
   # valid types are :linear and :path
   # @param [Any] v The value validated

data/lib/axlsx/version.rb

@@ -5,6 +5,6 @@ module Axlsx
   # When using bunle exec rake and referencing the gem on github or locally
   # it will use the gemspec, which preloads this constant for the gem's version.
   # We check to make sure that it has not already been loaded
-  VERSION="1.1.1" unless defined? Axlsx::VERSION
+  VERSION="1.1.2" unless defined? Axlsx::VERSION
 
 end

data/lib/axlsx/workbook/workbook.rb

@@ -4,6 +4,12 @@ module Axlsx
 require 'axlsx/workbook/worksheet/date_time_converter.rb'
 require 'axlsx/workbook/worksheet/cell.rb'
 require 'axlsx/workbook/worksheet/page_margins.rb'
+require 'axlsx/workbook/worksheet/cfvo.rb'
+require 'axlsx/workbook/worksheet/color_scale.rb'
+require 'axlsx/workbook/worksheet/data_bar.rb'
+require 'axlsx/workbook/worksheet/icon_set.rb'
+require 'axlsx/workbook/worksheet/conditional_formatting.rb'
+require 'axlsx/workbook/worksheet/conditional_formatting_rule.rb'
 require 'axlsx/workbook/worksheet/row.rb'
 require 'axlsx/workbook/worksheet/col.rb'
 require 'axlsx/workbook/worksheet/worksheet.rb'

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

@@ -0,0 +1,62 @@
+module Axlsx
+  # Conditional Format Value Object
+  # Describes the values of the interpolation points in a gradient scale. This object is used by ColorScale, DataBar and IconSet classes
+  #
+  # @note The recommended way to manage these rules is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule#initialize
+  #
+  class Cfvo
+
+    # Type (ST_CfvoType)
+    # The type of this conditional formatting value object. options are num, percent, max, min, formula and percentile
+    # @return [Symbol]
+    attr_reader :type
+
+
+    # Type (xsd:boolean)
+    # For icon sets, determines whether this threshold value uses the greater than or equal to operator. 0 indicates 'greater than' is used instead of 'greater than or equal to'.
+    # The default value is true
+    # @return [Boolean]
+    attr_reader :gte
+
+
+    # Type (ST_Xstring)
+    # The value of the conditional formatting object
+    # This library will accept any value so long as it supports to_s
+    attr_reader :val
+
+    # Creates a new Cfvo object
+    # @option options [Symbol] type The type of conditional formatting value object
+    # @option options [Boolean]  gte threshold value usage indicator
+    # @option options [String] val The value of the conditional formatting object
+    def initialize(options={})
+      @gte = true
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # @see type
+    def type=(v); Axlsx::validate_conditional_formatting_value_object_type(v); @type = v end
+
+    # @see gte
+    def gte=(v); Axlsx::validate_boolean(v); @gte = v end
+
+    # @see val
+    def val=(v)
+      raise ArgumentError, "#{v.inspect} must respond to to_s" unless v.respond_to?(:to_s)
+      @val = v.to_s
+    end
+
+    # serialize the Csvo object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<cfvo '
+      str << instance_values.map { |key, value| '' << key << '="' << value.to_s << '"' }.join(' ')
+      str << ' />'
+    end
+
+  end
+end

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

@@ -0,0 +1,76 @@
+module Axlsx
+  # Conditional Format Rule color scale object
+  # Describes a gradated color scale in this conditional formatting rule.
+
+  # @note The recommended way to manage these rules is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule#initialize
+  class ColorScale
+
+    # A simple typed list of cfvos
+    # @return [SimpleTypedList]
+    # @see Cfvo
+    attr_reader :value_objects
+
+    # A simple types list of colors
+    # @return [SimpleTypedList]
+    # @see Color
+    attr_reader :colors
+
+    # creates a new ColorScale object.
+    # This method will yield it self so you can alter the properites of the defauls conditional formating value object (cfvo and colors
+    # Two value objects and two colors are created on initialization and cannot be deleted.
+    # @see Cfvo
+    # @see Color
+    def initialize
+      initialize_value_objects
+      initialize_colors
+      yield self if block_given?
+    end
+
+    # adds a new cfvo / color pair to the color scale and returns a hash containing
+    # a reference to the newly created cfvo and color objects so you can alter the default properties.
+    # @return [Hash] a hash with :cfvo and :color keys referencing the newly added objects.
+    def add(options={})
+      @value_objects << Cfvo.new(:type => options[:type] || :min, :val => options[:val] || 0)
+      @colors << Color.new(:rgb => options[:color] || "FF000000")
+      {:cfvo => @value_objects.last, :color => @colors.last}
+    end
+
+
+    # removes the cfvo and color pair at the index specified.
+    # @param [Integer] index The index of the cfvo and color object to delete
+    # @note you cannot remove the first two cfvo and color pairs
+    def delete_at(index=2)
+      @value_objects.delete_at index
+      @colors.delete_at index
+    end
+
+    # Serialize this color_scale object data to an xml string
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<colorScale>'
+      @value_objects.each { |cfvo| cfvo.to_xml_string(str) }
+      @colors.each { |color| color.to_xml_string(str) }
+      str << '</colorScale>'
+    end
+
+    private
+
+    # creates the initial cfvo objects
+    def initialize_value_objects
+      @value_objects = SimpleTypedList.new Cfvo
+      @value_objects.concat [Cfvo.new(:type => :min, :val => 0), Cfvo.new(:type => :max, :val => 0)]
+      @value_objects.lock
+    end
+
+    # creates the initial color objects
+    def initialize_colors
+      @colors = SimpleTypedList.new Color
+      @colors.concat [Color.new(:rgb => "FFFF0000"), Color.new(:rgb => "FF0000FF")]
+      @colors.lock
+    end
+
+  end
+end