axlsx 1.1.1 → 1.1.2

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

@@ -0,0 +1,46 @@
+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 :cfvos
+
+    # A simple types list of colors
+    # @return [SimpleTypedList]
+    # @see Color
+    attr_reader :colors
+
+    def initializer
+      initialize_cfvos
+      initialize_colors
+      yield self if block_given?
+    end
+
+    def add
+      @cfvos << Cfvo.new(:type => :min, :val => 0)
+      @colors << Color.new :rgb => "FF000000"
+      {:cfvo => @cfvos.last, :color => @colors.last}
+    end
+
+    protected
+
+    def initialize_cfvos
+      @cfvos = SimpleTypedList.new Cfvo
+      @cfvos.concat [Cfvo.new(:type => :min, :val => 0), Cfvo.new(:type => :max, :val => 0)]
+      @cfvos.lock
+    end
+
+    def initialize_colors
+      @colors = SimpleTypedList.new Color
+      @colors.concat [Color.new(:rgb => "FFFF0000", Color.new(:rgb => "FF0000FF")]
+      @colors.lock
+    end
+
+  end

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

@@ -0,0 +1,82 @@
+module Axlsx
+  # Conditional formatting allows styling of ranges based on functions
+  #
+  # @note The recommended way to manage conditional formatting is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule
+  class ConditionalFormatting
+
+    # Range over which the formatting is applied, in "A1:B2" format
+    # @return [String]
+    attr_reader :sqref
+
+    # Rules to apply the formatting to. Can be either a hash of
+    # options to create a {ConditionalFormattingRule}, an array of hashes
+    # for multiple ConditionalFormattingRules, or an array of already
+    # created ConditionalFormattingRules.
+    # @see ConditionalFormattingRule#initialize
+    # @return [Array]
+    attr_reader :rules
+
+    # Creates a new {ConditionalFormatting} object
+    # @option options [Array] rules The rules to apply
+    # @option options [String] sqref The range to apply the rules to
+    def initialize(options={})
+      @rules = []
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # Add Conditional Formatting Rules to this object. Rules can either
+    # be already created {ConditionalFormattingRule} elements or
+    # hashes of options for automatic creation.  If rules is a hash
+    # instead of an array, assume only one rule being added.
+    #
+    # @example This would apply formatting "1" to cells > 20, and formatting "2" to cells < 1
+    #        conditional_formatting.add_rules [
+    #            { :type => :cellIs, :operator => :greaterThan, :formula => "20", :dxfId => 1, :priority=> 1 },
+    #            { :type => :cellIs, :operator => :lessThan, :formula => "10", :dxfId => 2, :priority=> 2 } ]
+    #
+    # @param [Array|Hash] rules the rules to apply, can be just one in hash form
+    # @see ConditionalFormattingRule#initialize
+    def add_rules(rules)
+      rules = [rules] if rules.is_a? Hash
+      rules.each do |rule|
+        add_rule rule
+      end
+    end
+
+    # Add a ConditionalFormattingRule. If a hash of options is passed
+    # in create a rule on the fly.
+    # @param [ConditionalFormattingRule|Hash] rule A rule to use, or the options necessary to create one.
+    # @see ConditionalFormattingRule#initialize
+    def add_rule(rule)
+      if rule.is_a? Axlsx::ConditionalFormattingRule
+        @rules << rule
+      elsif rule.is_a? Hash
+        @rules << ConditionalFormattingRule.new(rule)
+      end
+    end
+
+    # @see rules
+    def rules=(v); @rules = v end
+    # @see sqref
+    def sqref=(v); Axlsx::validate_string(v); @sqref = v end
+
+    # Serializes the conditional formatting element
+    # @example Conditional Formatting XML looks like:
+    #    <conditionalFormatting sqref="E3:E9">
+    #        <cfRule type="cellIs" dxfId="0" priority="1" operator="greaterThan">
+    #             <formula>0.5</formula>
+    #        </cfRule>
+    #    </conditionalFormatting>
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<conditionalFormatting sqref="' << sqref << '">'
+      str << rules.collect{ |rule| rule.to_xml_string }.join(' ')
+      str << '</conditionalFormatting>'
+    end
+  end
+end

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

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+  # Conditional formatting rules specify formulas whose evaluations
+  # format cells
+  #
+  # @note The recommended way to manage these rules is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule#initialize
+  class ConditionalFormattingRule
+
+    # instance values that must be serialized as their own elements - e.g. not attributes.
+    CHILD_ELEMENTS = [:formula, :color_scale, :data_bar, :icon_set]
+
+    # Formula
+    # @return [String]
+    attr_reader :formula
+
+    # Type (ST_CfType)
+    # options are expression, cellIs, colorScale, dataBar, iconSet,
+    # top10, uniqueValues, duplicateValues, containsText,
+    # notContainsText, beginsWith, endsWith, containsBlanks,
+    # notContainsBlanks, containsErrors, notContainsErrors,
+    # timePeriod, aboveAverage
+    # @return [Symbol]
+    attr_reader :type
+
+    # Above average rule
+    # Indicates whether the rule is an "above average" rule. True
+    # indicates 'above average'. This attribute is ignored if type is
+    # not equal to aboveAverage.
+    # @return [Boolean]
+    attr_reader :aboveAverage
+
+    # Bottom N rule
+    # @return [Boolean]
+    attr_reader :bottom
+
+    # Differential Formatting Id
+    # @return [Integer]
+    attr_reader :dxfId
+
+    # Equal Average
+    # Flag indicating whether the 'aboveAverage' and 'belowAverage'
+    # criteria is inclusive of the average itself, or exclusive of
+    # that value.
+    # @return [Boolean]
+    attr_reader :equalAverage
+
+    # Operator
+    # The operator in a "cell value is" conditional formatting
+    # rule. This attribute is ignored if type is not equal to cellIs
+    #
+    # Operator must be one of lessThan, lessThanOrEqual, equal,
+    # notEqual, greaterThanOrEqual, greaterThan, between, notBetween,
+    # containsText, notContains, beginsWith, endsWith
+    # @return [Symbol]
+    attr_reader :operator
+
+    # Priority
+    # The priority of this conditional formatting rule. This value is
+    # used to determine which format should be evaluated and
+    # rendered. Lower numeric values are higher priority than higher
+    # numeric values, where '1' is the highest priority.
+    # @return [Integer]
+    attr_reader :priority
+
+    # Text
+    # used in a "text contains" conditional formatting
+    # rule.
+    # @return [String]
+    attr_reader :text
+
+    # percent (Top 10 Percent)
+    # indicates whether a "top/bottom n" rule is a "top/bottom n
+    # percent" rule. This attribute is ignored if type is not equal to
+    # top10.
+    # @return [Boolean]
+    attr_reader :percent
+
+    # rank (Rank)
+    # The value of "n" in a "top/bottom n" conditional formatting
+    # rule. This attribute is ignored if type is not equal to top10.
+    # @return [Integer]
+    attr_reader :rank
+
+    # stdDev (StdDev)
+    # The number of standard deviations to include above or below the
+    # average in the conditional formatting rule. This attribute is
+    # ignored if type is not equal to aboveAverage. If a value is
+    # present for stdDev and the rule type = aboveAverage, then this
+    # rule is automatically an "above or below N standard deviations"
+    # rule.
+    # @return [Integer]
+    attr_reader :stdDev
+
+    # stopIfTrue (Stop If True)
+    # If this flag is '1', no rules with lower priority shall be
+    # applied over this rule, when this rule evaluates to true.
+    # @return [Boolean]
+    attr_reader :stopIfTrue
+
+    # timePeriod (Time Period)
+    # The applicable time period in a "date occurring…" conditional
+    # formatting rule. This attribute is ignored if type is not equal
+    # to timePeriod.
+    # Valid types are today, yesterday, tomorrow, last7Days,
+    # thisMonth, lastMonth, nextMonth, thisWeek, lastWeek, nextWeek
+    attr_reader :timePeriod
+
+
+    # colorScale (Color Scale)
+    # The color scale to apply to this conditional formatting
+    # @return [ColorScale]
+    def color_scale
+      @color_scale ||= ColorScale.new
+    end
+
+    # dataBar (Data Bar)
+    # The data bar to apply to this conditional formatting
+    # @return [DataBar]
+    def data_bar
+      @data_bar ||= DataBar.new
+    end
+
+    # iconSet (Icon Set)
+    # The icon set to apply to this conditional formatting
+    # @return [IconSet]
+    def icon_set
+      @icon_set ||= IconSet.new
+    end
+
+    # Creates a new Conditional Formatting Rule object
+    # @option options [Symbol] type The type of this formatting rule
+    # @option options [Boolean] aboveAverage This is an aboveAverage rule
+    # @option options [Boolean] bottom This is a bottom N rule.
+    # @option options [Integer] dxfId The formatting id to apply to matches
+    # @option options [Boolean] equalAverage Is the aboveAverage or belowAverage rule inclusive
+    # @option options [Integer] priority The priority of the rule, 1 is highest
+    # @option options [Symbol] operator Which operator to apply
+    # @option options [String] text The value to apply a text operator against
+    # @option options [Boolean] percent If a top/bottom N rule, evaluate as N% rather than N
+    # @option options [Integer] rank If a top/bottom N rule, the value of N
+    # @option options [Integer] stdDev The number of standard deviations above or below the average to match
+    # @option options [Boolean] stopIfTrue Stop evaluating rules after this rule matches
+    # @option options [Symbol]  timePeriod The time period in a date occuring... rule
+    # @option options [String] formula The formula to match against in i.e. an equal rule
+    def initialize(options={})
+      @color_scale = @data_bar = @icon_set = @formula = nil
+      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_type(v); @type = v end
+    # @see aboveAverage
+    def aboveAverage=(v); Axlsx::validate_boolean(v); @aboveAverage = v end
+    # @see bottom
+    def bottom=(v); Axlsx::validate_boolean(v); @bottom = v end
+    # @see dxfId
+    def dxfId=(v); Axlsx::validate_unsigned_numeric(v); @dxfId = v end
+    # @see equalAverage
+    def equalAverage=(v); Axlsx::validate_boolean(v); @equalAverage = v end
+    # @see priority
+    def priority=(v); Axlsx::validate_unsigned_numeric(v); @priority = v end
+    # @see operator
+    def operator=(v); Axlsx::validate_conditional_formatting_operator(v); @operator = v end
+    # @see text
+    def text=(v); Axlsx::validate_string(v); @text = v end
+    # @see percent
+    def percent=(v); Axlsx::validate_boolean(v); @percent = v end
+    # @see rank
+    def rank=(v); Axlsx::validate_unsigned_numeric(v); @rank = v end
+    # @see stdDev
+    def stdDev=(v); Axlsx::validate_unsigned_numeric(v); @stdDev = v end
+    # @see stopIfTrue
+    def stopIfTrue=(v); Axlsx::validate_boolean(v); @stopIfTrue = v end
+    # @see timePeriod
+    def timePeriod=(v); Axlsx::validate_time_period_type(v); @timePeriod = v end
+    # @see formula
+    def formula=(v); Axlsx::validate_string(v); @formula = v end
+
+    # @see color_scale
+    def color_scale=(v)
+      Axlsx::DataTypeValidator.validate 'conditional_formatting_rule.color_scale', ColorScale, v
+      @color_scale = v
+    end
+
+    # @see data_bar
+    def data_bar=(v)
+      Axlsx::DataTypeValidator.validate 'conditional_formatting_rule.data_bar', DataBar, v
+      @data_bar = v
+    end
+
+    # @see icon_set
+    def icon_set=(v)
+      Axlsx::DataTypeValidator.validate 'conditional_formatting_rule.icon_set', IconSet, v
+      @icon_set = v
+    end
+
+
+    # Serializes the conditional formatting rule
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<cfRule '
+      str << instance_values.map { |key, value| '' << key << '="' << value.to_s << '"' unless CHILD_ELEMENTS.include?(key.to_sym) }.join(' ')
+      str << '>'
+      str << '<formula>' << self.formula << '</formula>' if @formula
+      @color_scale.to_xml_string(str) if @color_scale && @type == :colorScale
+      @data_bar.to_xml_string(str) if @data_bar && @type == :dataBar
+      @icon_set.to_xml_string(str) if @icon_set && @type == :iconSet
+      str << '</cfRule>'
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+module Axlsx
+  # Conditional Format Rule data bar object
+  # Describes a data bar 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 DataBar
+
+    # instance values that must be serialized as their own elements - e.g. not attributes.
+    CHILD_ELEMENTS = [:value_objects, :color]
+
+    # minLength attribute
+    # The minimum length of the data bar, as a percentage of the cell width.
+    # The default value is 10
+    # @return [Integer]
+    attr_reader :minLength
+
+    # maxLength attribute
+    # The maximum length of the data bar, as a percentage of the cell width.
+    # The default value is 90
+    # @return [Integer]
+    attr_reader :maxLength
+
+    # maxLength attribute
+    # Indicates whether to show the values of the cells on which this data bar is applied.
+    # The default value is true
+    # @return [Boolean]
+    attr_reader :showValue
+
+    # A simple typed list of cfvos
+    # @return [SimpleTypedList]
+    # @see Cfvo
+    attr_reader :value_objects
+
+    # color
+    # the color object used in the data bar formatting
+    # @return [Color]
+    def color
+      @color ||= Color.new :rgb => "FF0000FF"
+    end
+
+    # Creates a new data bar conditional formatting object
+    # @option options [Integer] minLength
+    # @option options [Integer] maxLength
+    # @option options [Boolean] showValue
+    # @option options [String] color - the rbg value used to color the bars
+    def initialize(options = {})
+      @minLength = 10
+      @maxLength = 90
+      @showValue = true
+      initialize_value_objects
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+
+    # @see minLength
+    def minLength=(v); Axlsx.validate_unsigned_int(v); @minLength = v end
+    # @see maxLength
+    def maxLength=(v); Axlsx.validate_unsigned_int(v); @maxLength = v end
+
+    # @see showValue
+    def showValue=(v); Axlsx.validate_boolean(v); @showValue = v end
+
+    # Sets the color for the data bars.
+    # @param [Color|String] The color object, or rgb string value to apply
+    def color=(v)
+      @color = v if v.is_a? Color
+      self.color.rgb = v if v.is_a? String
+      @color
+    end
+
+    # Serialize this object to an xml string
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str="")
+      str << '<dataBar '
+      str << instance_values.map { |key, value| '' << key << '="' << value.to_s << '"' unless CHILD_ELEMENTS.include?(key.to_sym) }.join(' ')
+      str << '>'
+      @value_objects.each { |cfvo| cfvo.to_xml_string(str) }
+      self.color.to_xml_string(str)
+      str << '</dataBar>'
+    end
+
+    private
+
+    # Initalize the simple typed list of value objects
+    # I am keeping this private for now as I am not sure what impact changes to the required two cfvo objects will do.
+    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
+  end
+end

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

@@ -0,0 +1,83 @@
+module Axlsx
+  # Conditional Format Rule icon sets
+  # Describes an icon set 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 IconSet
+
+    # instance values that must be serialized as their own elements - e.g. not attributes.
+    CHILD_ELEMENTS = [:value_objects]
+
+    # The icon set to display.
+    # Allowed values are: 3Arrows, 3ArrowsGray, 3Flags, 3TrafficLights1, 3TrafficLights2, 3Signs, 3Symbols, 3Symbols2, 4Arrows, 4ArrowsGray, 4RedToBlack, 4Rating, 4TrafficLights, 5Arrows, 5ArrowsGray, 5Rating, 5Quarters
+    # The default value is 3TrafficLights1
+    # @return [String]
+    attr_reader :iconSet
+
+    # Indicates whether the thresholds indicate percentile values, instead of number values.
+    # The default falue is true
+    # @return [Boolean]
+    attr_reader :percent
+
+    # If true, reverses the default order of the icons in this icon set.maxLength attribute
+    # The default value is false
+    # @return [Boolean]
+    attr_reader :reverse
+
+    # Indicates whether to show the values of the cells on which this data bar is applied.
+    # The default value is true
+    # @return [Boolean]
+    attr_reader :showValue
+
+    # Creates a new icon set object
+    # @option options [String] iconSet
+    # @option options [Boolean] reverse
+    # @option options [Boolean] percent
+    # @option options [Boolean] showValue
+    def initialize(options = {})
+      @percent = @showValue = true
+      @reverse = false
+      @iconSet = "3TrafficLights1"
+      initialize_value_objects
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+
+    # @see iconSet
+    def iconSet=(v); Axlsx::validate_icon_set(v); @iconSet = v end
+
+    # @see showValue
+    def showValue=(v); Axlsx.validate_boolean(v); @showValue = v end
+
+    # @see percent
+    def percent=(v); Axlsx.validate_boolean(v); @percent = v end
+
+    # @see reverse
+    def reverse=(v); Axlsx.validate_boolean(v); @reverse = v end
+
+    # Serialize this object to an xml string
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str="")
+      str << '<iconSet '
+      str << instance_values.map { |key, value| '' << key << '="' << value.to_s << '"' unless CHILD_ELEMENTS.include?(key.to_sym) }.join(' ')
+      str << '>'
+      @value_objects.each { |cfvo| cfvo.to_xml_string(str) }
+      str << '</iconSet>'
+    end
+
+    private
+
+    # Initalize the simple typed list of value objects
+    # I am keeping this private for now as I am not sure what impact changes to the required two cfvo objects will do.
+    def initialize_value_objects
+      @value_objects = SimpleTypedList.new Cfvo
+      @value_objects.concat [Cfvo.new(:type => :percent, :val => 0), Cfvo.new(:type => :percent, :val => 33), Cfvo.new(:type => :percent, :val => 67)]
+      @value_objects.lock
+    end
+  end
+end