axlsx 1.1.7 → 1.1.8

data/README.md

@@ -1,6 +1,7 @@
 Axlsx: Office Open XML Spreadsheet Generation
 ====================================
 [![Build Status](https://secure.travis-ci.org/randym/axlsx.png)](http://travis-ci.org/randym/axlsx/)
+[![Click here to lend your support to: axlsx and make a donation at www.pledgie.com !](http://www.pledgie.com/campaigns/17814.png?skin_name=chrome)](http://www.pledgie.com/campaigns/17814)
 
 **IRC**:[irc.freenode.net / #axlsx](irc://irc.freenode.net/axlsx)
 
@@ -16,7 +17,7 @@ Axlsx: Office Open XML Spreadsheet Generation
 
 **License**: MIT License
 
-**Latest Version**: 1.1.7
+**Latest Version**: 1.1.8
 
 **Ruby Version**: 1.8.7, 1.9.2, 1.9.3
 
@@ -24,7 +25,7 @@ Axlsx: Office Open XML Spreadsheet Generation
 
 **Rubinius Version**: rubinius 2.0.0dev * lower versions may run, this gem always tests against head.
 
-**Release Date**: June 11th 2012
+**Release Date**: July 14th 2012
 
 If you are working in rails, or with active record see:
 http://github.com/randym/acts_as_xlsx
@@ -69,8 +70,6 @@ Feature List
 **10. Support for formulas, merging, row and column outlining as well as
 cell level input data validation.
 
-**11. Support for cell merging as well as column and row outline
-
 **12. Auto filtering tables with worksheet.auto_filter as well as support for Tables
 
 **13. Export using shared strings or inline strings so we can inter-op with iWork Numbers (sans charts for now).
@@ -81,6 +80,9 @@ cell level input data validation.
 
 **16. Support for password and non password based sheet protection.
 
+**17. First stage interoperability support for GoogleDocs, LibraOffice,
+and Numbers
+
 Installing
 ----------
 
@@ -93,7 +95,7 @@ To install Axlsx, use the following command:
 
 The example listing is getting overly large to maintain here.
 If you are using Yard, you will be able to see the examples in line below.
-If not, please refer to the Please see the {file:examples/example.rb} file.
+If not, please refer to the Please see the [examples](https://github.com/randym/axlsx/tree/master/examples/example.rb) here.
 
 {include:file:examples/example.rb}
 
@@ -113,6 +115,15 @@ This gem has 100% test coverage using test/unit. To execute tests for this gem,
 
 #Change log
 ---------
+- **July.14.12**: 1.1.8 release
+   - added html entity encoding for sheet names. This allows you to use
+     characters like '<' and '&' in your sheet names.
+   - new - first round google docs interoperability
+   - added filter to strip out control characters from cell data.
+   - added in interop requirements so that charts are properly exported
+     to PDF from Libra Office
+   - various readability improvements and work standardizing attribute
+     names to snake_case. Aliases are provided for backward compatiblity 
 - **June.11.12**: 1.1.7 release
    - fix chart rendering issue when label offset is specified as a
      percentage in serialization and ensure that formula are not stored
@@ -163,6 +174,29 @@ in value caches
 
 Please see the {file:CHANGELOG.md} document for past release information.
 
+# Known interoperability issues.
+As axslx implements the Office Open XML (ECMA-376 spec) much of the
+functionality is interoperable with other spreadsheet software. Below is
+a listing of some known issues.
+
+1. Libra Office
+   -  You must specify colors for your series. see examples/chart_colors.rb
+for an example.
+   - You must use data in your sheet for charts. You cannot use hard coded
+values.
+   -  Chart axis and gridlines do not render. I have a feeling this is
+related to themes, which axlsx does not implement at this time.
+
+2. Google Docs
+   - Images are known to not work with google docs
+   - border colors do not work
+   - Charts, for the most part, do not work. Google docs has some specific requirements about how the worksheet is set up to create a chart. 
+
+3. Numbers
+   - you must set 'use_shared_strings' to true
+   - charts do not render
+
+
 #Thanks!
 
 Open source software is a community effort. None of this could have been
@@ -191,6 +225,8 @@ done without the help of the people below.
 
 [janhuehne](https://github.com/janhuehne) - for working out the decoder ring and adding in cell level validation, and providing a support for window panes.
 
+[rfc2616](https://github.com/rfc2616) - for FINALLY working out the interop issues with google docs.
+
 #Copyright and License
 ----------
 

data/Rakefile

@@ -9,8 +9,9 @@ task :benchmark do
 end
 
 task :gendoc do
-  system "yardoc"
-  system "yard stats --list-undoc"
+  puts 'yard doc generation disabled until JRuby build native extensions for redcarpet or yard removes the dependency.'
+  #  system "yardoc"
+  #  system "yard stats --list-undoc"
 end
 
 task :test do

data/examples/chart_colors.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby -w -s
 # -*- coding: utf-8 -*-
-# $LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../lib"
+$LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../lib"
 require 'axlsx'
 
 p = Axlsx::Package.new
@@ -36,7 +36,7 @@ end
    sheet.add_row ["First", "Second", "Third", "Fourth"]
    sheet.add_row [1, 2, 3, "=PRODUCT(A2:C2)"]
   sheet.add_chart(Axlsx::Pie3DChart, :start_at => [0,2], :end_at => [5, 15], :title => "example 3: Pie Chart") do |chart|
-     chart.add_series :data => sheet["A2:D2"], :labels => sheet["A1:D1"], :colors => ['FF0000', '00FF00', '0000FF']
+     chart.add_series :data => sheet["A2:D2"], :labels => sheet["A1:D1"], :colors => ['FF0000', '00FF00', '0000FF', '000000']
    end
  end
 
@@ -45,7 +45,7 @@ end
 wb.add_worksheet(:name => "Line Chart") do |sheet|
   sheet.add_row ["First", 1, 5, 7, 9]
   sheet.add_row ["Second", 5, 2, 14, 9]
-  sheet.add_chart(Axlsx::Line3DChart, :title => "example 6: Line Chart", :rotX => 30, :rotY => 20) do |chart|
+  sheet.add_chart(Axlsx::Line3DChart, :title => "example 6: Line Chart", :rotX => 30, :rotY => 30) do |chart|
     chart.start_at 0, 2
     chart.end_at 10, 15
     chart.add_series :data => sheet["B1:E1"], :title => sheet["A1"], :color => "FF0000"
@@ -53,6 +53,21 @@ wb.add_worksheet(:name => "Line Chart") do |sheet|
   end
 end
 
+wb.add_worksheet(:name => 'Line Chart with Axis colors') do |sheet|
+  sheet.add_row ["First", 1, 5, 7, 9]
+  sheet.add_row ["Second", 5, 2, 14, 9]
+  sheet.add_chart(Axlsx::Line3DChart, :title => "example 7: Flat Line Chart", :rot_x => 0, :perspective => 0) do |chart|
+    chart.valAxis.color = "FFFF00"
+    chart.catAxis.color = "00FFFF"
+    chart.serAxis.delete = true
+    chart.start_at 0, 2
+    chart.end_at 10, 15
+    chart.add_series :data => sheet["B1:E1"], :title => sheet["A1"], :color => "FF0000"
+    chart.add_series :data => sheet["B2:E2"], :title => sheet["A2"], :color => "00FF00"
+  end
+
+end
+
 ##Generating A Scatter Chart
 
  wb.add_worksheet(:name => "Scatter Chart") do |sheet|

data/examples/example.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby -w -s
 # -*- coding: utf-8 -*-
-$LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../lib"
+# $LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../lib"
 
 #```ruby
 require 'axlsx'
@@ -210,12 +210,9 @@ end
 #```ruby
 wb.add_worksheet(:name => "Bar Chart") do |sheet|
   sheet.add_row ["A Simple Bar Chart"]
-  sheet.add_row ["First", "Second", "Third"]
-  sheet.add_row [1, 2, 3]
-  sheet.add_chart(Axlsx::Bar3DChart, :start_at => "A4", :end_at => "F17") do |chart|
-    chart.add_series :data => sheet["A3:C3"], :labels => sheet["A2:C2"], :title => sheet["A1"]
-    chart.valAxis.label_rotation = -45
-    chart.catAxis.label_rotation = 45
+  %w(first second third).each { |label| sheet.add_row [label, rand(24)+1] }
+  sheet.add_chart(Axlsx::Bar3DChart, :start_at => "A6", :end_at => "F20") do |chart|
+    chart.add_series :data => sheet["B2:B4"], :labels => sheet["A2:A4"], :title => sheet["A1"]
   end
 end
 #```
@@ -224,11 +221,10 @@ end
 
 #```ruby
 wb.add_worksheet(:name => "Chart With No Gridlines") do |sheet|
-  sheet.add_row ["A Simple Bar Chart"]
-  sheet.add_row ["First", "Second", "Third"]
-  sheet.add_row [1, 2, 3]
-  sheet.add_chart(Axlsx::Bar3DChart, :start_at => "A4", :end_at => "F17") do |chart|
-    chart.add_series :data => sheet["A3:C3"], :labels => sheet["A2:C2"], :title => sheet["A1"]
+  sheet.add_row ["Bar Chart without gridlines"]
+  %w(first second third).each { |label| sheet.add_row [label, rand(24)+1] }
+  sheet.add_chart(Axlsx::Bar3DChart, :start_at => "A6", :end_at => "F20") do |chart|
+    chart.add_series :data => sheet["B2:B4"], :labels => sheet["A2:A4"]
     chart.valAxis.gridlines = false
     chart.catAxis.gridlines = false
   end
@@ -239,28 +235,10 @@ end
 
 #```ruby
 wb.add_worksheet(:name => "Pie Chart") do |sheet|
-  sheet.add_row ["First", "Second", "Third", "Fourth"]
-  sheet.add_row [1, 2, 3, "=PRODUCT(A2:C2)"]
-  sheet.add_chart(Axlsx::Pie3DChart, :start_at => [0,2], :end_at => [5, 15], :title => "example 3: Pie Chart") do |chart|
-    chart.add_series :data => sheet["A2:D2"], :labels => sheet["A1:D1"]
-  end
-end
-#```
-
-##Data over time
-
-#```ruby
-wb.add_worksheet(:name=>'Charting Dates') do |sheet|
-   # cell level style overides when adding cells
-  sheet.add_row ['Date', 'Value'], :sz => 16
-  sheet.add_row [Time.now - (7*60*60*24), 3]
-  sheet.add_row [Time.now - (6*60*60*24), 7]
-  sheet.add_row [Time.now - (5*60*60*24), 18]
-  sheet.add_row [Time.now - (4*60*60*24), 1]
-  sheet.add_chart(Axlsx::Bar3DChart) do |chart|
-    chart.start_at "B7"
-    chart.end_at "H27"
-    chart.add_series(:data => sheet["B2:B5"], :labels => sheet["A2:A5"], :title => sheet["B1"])
+  sheet.add_row ["Simple Pie Chart"]
+  %w(first second third).each { |label| sheet.add_row [label, rand(24)+1] }
+  sheet.add_chart(Axlsx::Pie3DChart, :start_at => [0,5], :end_at => [10, 20], :title => "example 3: Pie Chart") do |chart|
+    chart.add_series :data => sheet["B2:B4"], :labels => sheet["A2:A4"]
   end
 end
 #```
@@ -269,15 +247,18 @@ end
 
 #```ruby
 wb.add_worksheet(:name => "Line Chart") do |sheet|
-  sheet.add_row ["First", 1, 5, 7, 9]
-  sheet.add_row ["Second", 5, 2, 14, 9]
-  sheet.add_chart(Axlsx::Line3DChart, :title => "example 6: Line Chart", :rotX => 30, :rotY => 20) do |chart|
-    chart.start_at 0, 2
-    chart.end_at 10, 15
-    chart.add_series :data => sheet["B1:E1"], :title => sheet["A1"]
-    chart.add_series :data => sheet["B2:E2"], :title => sheet["A2"]
-    chart.catAxis.title = 'Y Axis'
-    chart.valAxis.title = 'X Axis'
+  sheet.add_row ["Simple Line Chart"]
+  sheet.add_row %w(first second)
+  4.times do
+    sheet.add_row [ rand(24)+1, rand(24)+1]
+  end
+  sheet.add_chart(Axlsx::Line3DChart, :title => "Simple Line Chart", :rotX => 30, :rotY => 20) do |chart|
+    chart.start_at 0, 5
+    chart.end_at 10, 20
+    chart.add_series :data => sheet["A3:A6"], :title => sheet["A2"]
+    chart.add_series :data => sheet["B3:B6"], :title => sheet["B2"]
+    chart.catAxis.title = 'X Axis'
+    chart.valAxis.title = 'Y Axis'
   end
 end
 #```
@@ -321,7 +302,7 @@ wb.add_worksheet(:name => "fit to page") do |sheet|
   sheet.add_row ['this all goes on one page']
   sheet.fit_to_page = true
 end
-#```
+##```
 
 
 ##Hide Gridlines in worksheet
@@ -331,7 +312,16 @@ wb.add_worksheet(:name => "No Gridlines") do |sheet|
   sheet.add_row ["This", "Sheet", "Hides", "Gridlines"]
   sheet.show_gridlines = false
 end
-#```
+##```
+
+
+# Sheet Protection and excluding cells from locking.
+unlocked = wb.styles.add_style :locked => false
+wb.add_worksheet(:name => 'Sheet Protection') do |sheet|
+  sheet.sheet_protection.password = 'fish'
+  sheet.add_row [1, 2 ,3] # These cells will be locked
+  sheet.add_row [4, 5, 6], :style => unlocked # these cells will not!
+end
 
 
 ##Specify page margins and other options for printing
@@ -355,7 +345,7 @@ end
 ## Frozen/Split panes
 ## ``` ruby
 wb.add_worksheet(:name => 'fixed headers') do |sheet|
-  sheet.add_row(['',  (0..99).map { |i| "column header #{i}" }].flatten )
+ sheet.add_row(['',  (0..99).map { |i| "column header #{i}" }].flatten )
   100.times.with_index { |index| sheet << ["row header", (0..index).to_a].flatten }
   sheet.sheet_view.pane do |pane|
     pane.top_left_cell = "B2"
@@ -366,6 +356,70 @@ wb.add_worksheet(:name => 'fixed headers') do |sheet|
   end
 end
 
+# conditional formatting
+#
+percent = wb.styles.add_style(:format_code => "0.00%", :border => Axlsx::STYLE_THIN_BORDER)
+money = wb.styles.add_style(:format_code => '0,000', :border => Axlsx::STYLE_THIN_BORDER)
+
+# define the style for conditional formatting
+profitable = wb.styles.add_style( :fg_color=>"FF428751",
+                                    :type => :dxf)
+
+wb.add_worksheet(:name => "Conditional Cell Is") do |ws|
+
+  # Generate 20 rows of data
+  ws.add_row ["Previous Year Quarterly Profits (JPY)"]
+  ws.add_row ["Quarter", "Profit", "% of Total"]
+  offset = 3
+  rows = 20
+  offset.upto(rows + offset) do |i|
+    ws.add_row ["Q#{i}", 10000*((rows/2-i) * (rows/2-i)), "=100*B#{i}/SUM(B3:B#{rows+offset})"], :style=>[nil, money, percent]
+  end
+
+# Apply conditional formatting to range B3:B100 in the worksheet
+  ws.add_conditional_formatting("B3:B100", { :type => :cellIs, :operator => :greaterThan, :formula => "100000", :dxfId => profitable, :priority => 1 })
+end
+
+wb.add_worksheet(:name => "Conditional Color Scale") do |ws|
+  ws.add_row ["Previous Year Quarterly Profits (JPY)"]
+  ws.add_row ["Quarter", "Profit", "% of Total"]
+  offset = 3
+  rows = 20
+  offset.upto(rows + offset) do |i|
+    ws.add_row ["Q#{i}", 10000*((rows/2-i) * (rows/2-i)), "=100*B#{i}/SUM(B3:B#{rows+offset})"], :style=>[nil, money, percent]
+  end
+# Apply conditional formatting to range B3:B100 in the worksheet
+  color_scale = Axlsx::ColorScale.new
+  ws.add_conditional_formatting("B3:B100", { :type => :colorScale, :operator => :greaterThan, :formula => "100000", :dxfId => profitable, :priority => 1, :color_scale => color_scale })
+end
+
+
+wb.add_worksheet(:name => "Conditional Data Bar") do |ws|
+  ws.add_row ["Previous Year Quarterly Profits (JPY)"]
+  ws.add_row ["Quarter", "Profit", "% of Total"]
+  offset = 3
+  rows = 20
+  offset.upto(rows + offset) do |i|
+    ws.add_row ["Q#{i}", 10000*((rows/2-i) * (rows/2-i)), "=100*B#{i}/SUM(B3:B#{rows+offset})"], :style=>[nil, money, percent]
+  end
+# Apply conditional formatting to range B3:B100 in the worksheet
+  data_bar = Axlsx::DataBar.new
+  ws.add_conditional_formatting("B3:B100", { :type => :dataBar, :dxfId => profitable, :priority => 1, :data_bar => data_bar })
+end
+
+wb.add_worksheet(:name => "Conditional Format Icon Set") do |ws|
+  ws.add_row ["Previous Year Quarterly Profits (JPY)"]
+  ws.add_row ["Quarter", "Profit", "% of Total"]
+  offset = 3
+  rows = 20
+  offset.upto(rows + offset) do |i|
+    ws.add_row ["Q#{i}", 10000*((rows/2-i) * (rows/2-i)), "=100*B#{i}/SUM(B3:B#{rows+offset})"], :style=>[nil, money, percent]
+  end
+# Apply conditional formatting to range B3:B100 in the worksheet
+  icon_set = Axlsx::IconSet.new
+  ws.add_conditional_formatting("B3:B100", { :type => :iconSet, :dxfId => profitable, :priority => 1, :icon_set => icon_set })
+end
+
 ##Validate and Serialize
 
 #```ruby

data/lib/axlsx.rb

@@ -1,16 +1,11 @@
 # encoding: UTF-8
+require 'htmlentities'
 require 'axlsx/version.rb'
 
 require 'axlsx/util/simple_typed_list.rb'
 require 'axlsx/util/constants.rb'
 require 'axlsx/util/validators.rb'
 
-#not even close to being ready but it does not break anything so it stays for now.
-# needs a full re-write to use agile-encryption properly
-# require 'axlsx/util/storage.rb'
-# require 'axlsx/util/cbf.rb'
-# require 'axlsx/util/ms_off_crypto.rb'
-
 # to be included with parsable intitites.
 #require 'axlsx/util/parser.rb'
 
@@ -53,6 +48,12 @@ module Axlsx
     ref
   end
 
+  #global reference html entity encoding
+  # @return [HtmlEntities]
+  def self.coder
+    @@coder ||= ::HTMLEntities.new
+  end
+  
   # returns the x, y position of a cell
   def self.name_to_indices(name)
     raise ArgumentError, 'invalid cell name' unless name.size > 1

data/lib/axlsx/content_type/content_type.rb

@@ -1,5 +1,6 @@
 # encoding: UTF-8
 module Axlsx
+
   require 'axlsx/content_type/default.rb'
   require 'axlsx/content_type/override.rb'
 
@@ -21,4 +22,5 @@ module Axlsx
     end
 
   end
+
 end

data/lib/axlsx/content_type/default.rb

@@ -1,8 +1,23 @@
 # encoding: UTF-8
 module Axlsx
+
   # An default content part. These parts are automatically created by for you based on the content of your package.
   class Default
 
+    #Creates a new Default object
+    # @option options [String] extension
+    # @option options [String] content_type
+    # @raise [ArgumentError] An argument error is raised if both extension and content_type are not specified.
+    def initialize(options={})
+      raise ArgumentError, INVALID_ARGUMENTS unless validate_options(options)
+      options.each do |name, value|
+        self.send("#{name}=", value) if self.respond_to? "#{name}="
+      end
+    end
+
+    # Error string for option validation
+    INVALID_ARGUMENTS = "extension and content_type are required"
+
     # The extension of the content type.
     # @return [String]
     attr_reader :extension
@@ -13,18 +28,6 @@ module Axlsx
     attr_reader :content_type
     alias :ContentType :content_type
 
-    #Creates a new Default object
-    # @option options [String] extension
-    # @option options [String] content_type
-    # @raise [ArgumentError] An argument error is raised if both extension and content_type are not specified.
-    def initialize(options={})
-      raise ArgumentError, "extension and content_type are required" unless (options[:Extension] || options[:extension]) && (options[:content_type] || options[:ContentType])
-      options.each do |o|
-        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
-      end
-    end
-
-
     # Sets the file extension for this content type.
     def extension=(v) Axlsx::validate_string v; @extension = v end
     alias :Extension= :extension=
@@ -43,5 +46,11 @@ module Axlsx
       str << '/>'
     end
 
+    private
+    def validate_options(options)
+      (options[:Extension] || options[:extension]) && (options[:content_type] || options[:ContentType])
+    end
+
   end
+
 end