axlsx 1.0.0

data/lib/axlsx/drawing/bar_series.rb

@@ -0,0 +1,91 @@
+module Axlsx
+  # A BarSeries defines the title, data and labels for bar charts
+  # @note The recommended way to manage series is to use Chart#add_series
+  # @see Worksheet#add_chart
+  # @see Chart#add_series
+  class BarSeries < Series
+
+  
+    # The data for this series. 
+    # @return [Array, SimpleTypedList]
+    attr_reader :data
+
+    # The labels for this series.
+    # @return [Array, SimpleTypedList]
+    attr_reader :labels
+
+    # The shabe of the bars or columns
+    # must be one of  [:percentStacked, :clustered, :standard, :stacked]
+    # @return [Symbol]
+    attr_accessor :shape
+
+    # Creates a new series
+    # @option options [Array, SimpleTypedList] data
+    # @option options [Array, SimpleTypedList] labels
+    # @option options [String] title
+    # @option options [String] shape
+    # @param [Chart] chart
+    def initialize(chart, options={})
+      @shape = :box
+      super(chart, options)
+      self.data = options[:data]  || []
+      self.labels = options[:labels] || []
+    end 
+
+    def shape=(v) 
+      RestrictionValidator.validate "BarSeries.shape", [:cone, :coneToMax, :box, :cylinder, :pyramid, :pyramidToMax], v
+      @shape = v
+    end
+
+    # Serializes the series
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      super(xml) do |xml|
+        if !labels.empty?
+          xml.send('c:cat') {
+            xml.send('c:strRef') {
+              xml.send('c:f', Axlsx::cell_range(labels))
+              xml.send('c:strCache') {
+                xml.send('c:ptCount', :val=>labels.size)
+                labels.each_with_index do |cell, index|
+                  v = cell.is_a?(Cell) ? cell.value : cell
+                  xml.send('c:pt', :idx=>index) {
+                    xml.send('c:v', v)
+                  }                          
+                end
+              }
+            }
+          }
+        end
+        xml.send('c:val') {
+          xml.send('c:numRef') {
+            xml.send('c:f', Axlsx::cell_range(data))
+            xml.send('c:numCache') {
+              xml.send('c:formatCode', 'General')
+              xml.send('c:ptCount', :val=>data.size)
+              data.each_with_index do |cell, index|
+                v = cell.is_a?(Cell) ? cell.value : cell
+                xml.send('c:pt', :idx=>index) {
+                  xml.send('c:v', v) 
+                }
+              end
+            }                        
+          }
+        }
+      end      
+    end
+
+    
+    private 
+
+
+    # assigns the data for this series
+    def data=(v) DataTypeValidator.validate "Series.data", [Array, SimpleTypedList], v; @data = v; end
+
+    # assigns the labels for this series
+    def labels=(v) DataTypeValidator.validate "Series.labels", [Array, SimpleTypedList], v; @labels = v; end
+
+  end
+
+end

data/lib/axlsx/drawing/cat_axis.rb

@@ -0,0 +1,58 @@
+module Axlsx
+  #A CatAxis object defines a chart category axis
+  class CatAxis < Axis
+    # From the docs: This element specifies that this axis is a date or text axis based on the data that is used for the axis labels, not a specific choice.
+    # @return [Boolean]
+    attr_accessor :auto
+
+    # specifies how the perpendicular axis is crossed
+    # must be one of [:ctr, :l, :r]
+    # @return [Symbol]
+    attr_accessor :lblAlgn 
+
+    # The offset of the labels
+    # must be between a string between 0 and 1000
+    # @return [Integer]
+    attr_accessor :lblOffset
+
+    # regex for validating label offset
+    LBL_OFFSET_REGEX = /0*(([0-9])|([1-9][0-9])|([1-9][0-9][0-9])|1000)%/
+
+    # Creates a new CatAxis object
+    # @param [Integer] axId the id of this axis
+    # @param [Integer] crossAx the id of the perpendicular axis
+    # @option options [Symbol] axPos
+    # @option options [Symbol] tickLblPos
+    # @option options [Symbol] crosses
+    # @option options [Boolean] auto
+    # @option options [Symbol] lblAlgn
+    # @option options [Integer] lblOffset    
+    def initialize(axId, crossAx, options={})
+      super(axId, crossAx, options)
+      self.auto = true
+      self.lblAlgn = :ctr
+      self.lblOffset = "100%"
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end 
+
+    def auto=(v) Axlsx::validate_boolean(v); @auto = v; end
+    def lblAlgn=(v) RestrictionValidator.validate "#{self.class}.lblAlgn", [:ctr, :l, :r], v; @lblAlgn = v; end
+    def lblOffset=(v) RegexValidator.validate "#{self.class}.lblOffset", LBL_OFFSET_REGEX, v; @lblOffset = v; end
+
+    # Serializes the category axis
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.send('c:catAx') {
+        super(xml)
+        xml.send('c:auto', :val=>@auto)
+        xml.send('c:lblAlgn', :val=>@lblAlgn)
+        xml.send('c:lblOffset', :val=>@lblOffset)                 
+      }
+    end
+  end
+  
+
+end

data/lib/axlsx/drawing/chart.rb

@@ -0,0 +1,120 @@
+module Axlsx
+  # A Chart is the superclass for specific charts
+  # @note Worksheet#add_chart is the recommended way to create charts for your worksheets.
+  class Chart
+
+    # The title object for the chart.
+    # @return [Title]
+    attr_accessor :title
+
+    # The 3D view properties for the chart
+    attr_accessor :view3D
+
+    # A reference to the graphic frame that owns this chart
+    # @return [GraphicFrame]
+    attr_reader :graphic_frame
+
+    # A collection of series objects that are applied to the chart
+    # @return [SimpleTypedList]
+    attr_reader :series
+
+    # The type of series to use for this chart
+    # @return [Series]
+    attr_reader :series_type
+
+    # The index of this chart in the workbooks charts collection
+    # @return [Integer]
+    attr_reader :index
+
+    # The part name for this chart
+    # @return [String]
+    attr_reader :pn
+
+    #TODO data labels!
+    #attr_accessor :dLabls
+
+    # The starting marker for this chart
+    # @return [Marker]
+    attr_reader :start_at
+
+    # The ending marker for this chart
+    # @return [Marker]
+    attr_reader :end_at
+
+    # Show the legend in the chart
+    # @return [Boolean]
+    attr_accessor :show_legend
+   
+    # Creates a new chart object
+    # @param [GraphicalFrame] frame The frame that holds this chart.
+    # @option options [Cell, String] title
+    # @option options [Boolean] show_legend
+    def initialize(frame, options={})
+      @graphic_frame=frame
+      @graphic_frame.anchor.drawing.worksheet.workbook.charts << self
+      @series = SimpleTypedList.new Series
+      @show_legend = true
+      @series_type = Series
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+
+    def index
+      @graphic_frame.anchor.drawing.worksheet.workbook.charts.index(self)
+    end
+
+    def pn
+      "#{CHART_PN % (index+1)}"
+    end
+
+    def view3D=(v) DataTypeValidator.validate "#{self.class}.view3D", View3D, v; @view3D = v; end
+
+    def title=(v) 
+      v = Title.new(v) if v.is_a?(String) || v.is_a?(Cell)
+      DataTypeValidator.validate "#{self.class}.title", Title, v
+      @title = v
+    end
+
+    def show_legend=(v) Axlsx::validate_boolean(v); @show_legend = v; end
+
+    # Adds a new series to the chart's series collection.
+    # @return [Series]
+    # @see Series
+    def add_series(options={})
+      @series_type.new(self, options)
+      @series.last
+    end
+
+    # Chart Serialization
+    # serializes the chart
+    def to_xml
+      builder = Nokogiri::XML::Builder.new(:encoding => ENCODING) do |xml|
+        xml.send('c:chartSpace',:'xmlns:c' => XML_NS_C, :'xmlns:a' => XML_NS_A) {
+          xml.send('c:chart') {
+            @title.to_xml(xml) unless @title.nil?
+            @view3D.to_xml(xml) unless @view3D.nil?
+            xml.send('c:plotArea') {
+              xml.send('c:layout')
+              yield xml if block_given?
+            }
+            if @show_legend
+              xml.send('c:legend') {
+                xml.send('c:legendPos', :val => "r")
+                xml.send('c:layout')
+              }
+            end
+          }
+        }
+      end
+      builder.to_xml
+    end
+
+    private
+    
+    def start_at=(v) DataTypeValidator.validate "#{self.class}.start_at", Marker, v; @start_at = v; end
+    def end_at=(v) DataTypeValidator.validate "#{self.class}.end_at", Marker, v; @end_at = v; end
+
+  end
+end

data/lib/axlsx/drawing/drawing.rb

@@ -0,0 +1,121 @@
+module Axlsx
+  require 'axlsx/drawing/series.rb'
+  require 'axlsx/drawing/pie_series.rb'
+  require 'axlsx/drawing/bar_series.rb'  
+
+  require 'axlsx/drawing/axis.rb'
+  require 'axlsx/drawing/cat_axis.rb'
+  require 'axlsx/drawing/val_axis.rb'
+  require 'axlsx/drawing/view_3D.rb'
+  require 'axlsx/drawing/scaling.rb'
+  require 'axlsx/drawing/title.rb'
+
+  require 'axlsx/drawing/graphic_frame.rb'
+  require 'axlsx/drawing/marker.rb'
+  require 'axlsx/drawing/two_cell_anchor.rb'
+
+  require 'axlsx/drawing/chart.rb'
+  require 'axlsx/drawing/pie_3D_chart.rb'
+  require 'axlsx/drawing/bar_3D_chart.rb'
+
+  # A Drawing is a canvas for charts. Each worksheet has a single drawing that can specify multiple anchors which reference charts.
+  # @note The recommended way to manage drawings is to use the Worksheet.add_chart method, specifying the chart class, start and end marker locations. 
+  # @see Worksheet#add_chart
+  # @see TwoCellAnchor
+  # @see Chart
+  class Drawing
+
+    # The worksheet that owns the drawing
+    # @return [Worksheet]
+    attr_reader :worksheet
+
+   
+    # A collection of anchors for this drawing
+    # @return [SimpleTypedList]
+    attr_reader :anchors
+
+    # An array of charts that are associated with this drawing's anchors
+    # @return [Array]
+    attr_reader :charts
+
+    # The index of this drawing in the owning workbooks's drawings collection.
+    # @return [Integer]
+    attr_reader :index
+
+    # The relation reference id for this drawing
+    # @return [String]
+    attr_reader :rId
+
+    # The part name for this drawing
+    # @return [String]
+    attr_reader :pn
+
+    # The relational part name for this drawing
+    # @return [String]
+    attr_reader :rels_pn
+
+    # The drawing's relationships.
+    # @return [Relationships]
+    attr_reader :relationships
+
+    # Creates a new Drawing object
+    # @param [Worksheet] worksheet The worksheet that owns this drawing
+    def initialize(worksheet)
+      DataTypeValidator.validate "Drawing.worksheet", Worksheet, worksheet
+      @worksheet = worksheet
+      @worksheet.workbook.drawings << self
+      @anchors = SimpleTypedList.new TwoCellAnchor
+    end
+    
+
+    # Adds a chart to the drawing. 
+    # @note The recommended way to manage charts is to use Worksheet.add_chart.
+    # @param [Chart] chart_type The class of the chart to be added to the drawing
+    # @param [Hash] options
+    def add_chart(chart_type, options={})
+      DataTypeValidator.validate "Drawing.chart_type", Chart, chart_type 
+      TwoCellAnchor.new(self, chart_type, options)
+      @anchors.last.graphic_frame.chart
+    end
+    
+    def charts
+      @anchors.map { |a| a.graphic_frame.chart }
+    end
+
+    def index
+      @worksheet.workbook.drawings.index(self)
+    end
+
+    def rId
+      "rId#{index+1}"
+    end
+
+    def pn
+      "#{DRAWING_PN % (index+1)}"
+    end
+    
+    def rels_pn
+      "#{DRAWING_RELS_PN % (index+1)}"
+    end
+
+    def relationships
+      r = Relationships.new
+      @anchors.each do |anchor|
+        chart = anchor.graphic_frame.chart
+        r << Relationship.new(CHART_R, "../#{chart.pn}")
+      end
+      r
+    end
+
+    # Serializes the drawing
+    # @return [String]
+    def to_xml
+      builder = Nokogiri::XML::Builder.new(:encoding => ENCODING) do |xml|
+        xml.send('xdr:wsDr', :'xmlns:xdr'=>XML_NS_XDR, :'xmlns:a'=>XML_NS_A) {
+          anchors.each {|anchor| anchor.to_xml(xml) }
+        }        
+      end
+      builder.to_xml
+    end
+  end
+end

data/lib/axlsx/drawing/graphic_frame.rb

@@ -0,0 +1,55 @@
+module Axlsx
+  # A graphic frame defines a container for a chart object
+  # @note The recommended way to manage charts is Worksheet#add_chart
+  # @see Worksheet#add_chart
+  class GraphicFrame
+
+    #TODO add in support for other graphical objects, primarily images.
+    
+    # A reference to the chart object associated with this frame
+    # @return [Chart]
+    attr_reader :chart
+
+    # A anchor that holds this frame
+    # @return [TwoCellAnchor]
+    attr_reader :anchor
+
+    # The relationship id for this graphic
+    # @return [String]
+    attr_reader :rId
+
+    # Creates a new GraphicFrame object
+    # @param [TwoCellAnchor] anchor
+    # @param [Class] chart_type
+    def initialize(anchor, chart_type, options)
+      @anchor = anchor
+      @chart = chart_type.new(self, options)
+    end
+
+    def rId 
+      "rId#{@anchor.index+1}"
+    end
+
+    # Serializes the graphic frame
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.send('xdr:graphicFrame') {        
+        xml.send('xdr:nvGraphicFramePr') {
+          xml.send('xdr:cNvPr', :id=>2, :name=>chart.title)
+          xml.send('xdr:cNvGraphicFramePr')                
+        }
+        xml.send('xdr:xfrm') {
+          xml.send('a:off', :x=>0, :y=>0)
+          xml.send('a:ext', :cx=>0, :cy=>0)
+        }
+        xml.send('a:graphic') {
+          xml.send('a:graphicData', :uri=>XML_NS_C) {
+            xml.send('c:chart', :'xmlns:c'=>XML_NS_C, :'xmlns:r'=>XML_NS_R, :'r:id'=>rId)
+          }
+        }
+      }
+      
+    end
+  end
+end