axlsx 1.0.15 → 1.0.16

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 CHANGELOG
 ---------
+- **December.14.11**: 1.0.14 release
+   - Added support for merging cells
+   - Added support for auto filters
+   - Improved auto width calculations
+   - Improved charts
+   - Updated examples to output to a single workbook with multiple sheets
+   - Added access to app and core package objects so you can set the creator and other properties of the package
+   - The beginning of password protected xlsx files - roadmapped for January release.
+	
+- **December.8.11**: 1.0.13 release
+   -  Fixing .gemspec errors that caused gem to miss the lib directory. Sorry about that.
+
+- **December.7.11**: 1.0.12 release
+    DO NOT USE THIS VERSION = THE GEM IS BROKEN
+  - changed dependency from 'zip' gem to 'rubyzip' and added conditional code to force binary encoding to resolve issue with excel 2011
+  - Patched bug in app.xml that would ignore user specified properties.
+- **December.5.11**: 1.0.11 release
+  - Added [] methods to worksheet and workbook to provide name based access to cells.
+  - Added support for functions as cell values
+  - Updated color creation so that two character shorthand values can be used like 'FF' for 'FFFFFFFF' or 'D8' for 'FFD8D8D8'
+  - Examples for all this fun stuff added to the readme
+  - Clean up and support for 1.9.2 and travis integration
+  - Added support for string based cell referencing to chart start_at and end_at. That means you can now use :start_at=>"A1" when using worksheet.add_chart, or chart.start_at ="A1" in addition to passing a cell or the x, y coordinates.
 
 - **October.30.11**: 1.0.10 release
   - Updating gemspec to lower gem version requirements.

data/README.md

@@ -7,10 +7,10 @@ Axlsx: Office Open XML Spreadsheet Generation
 **Author**:       Randy Morgan   
 **Copyright**:    2011      
 **License**:      MIT License      
-**Latest Version**: 1.0.15   
+**Latest Version**: 1.0.16   
 **Ruby Version**: 1.8.7, 1.9.2, 1.9.3 
 
-**Release Date**: January 6th 2012     
+**Release Date**: February 2nd 2012     
 
 Synopsis
 --------
@@ -44,7 +44,7 @@ Feature List
 
 **6. Support for automatically formatted 1904 and 1900 epocs configurable in the workbook.
 
-**7. Add jpg, gif and png images to worksheets
+**7. Add jpg, gif and png images to worksheets with hyperlinks
 
 **8. Refernce cells in your worksheet with "A1" and "A1:D4" style references or from the workbook using "Sheett1!A3:B4" style references
 
@@ -89,18 +89,50 @@ To install Axlsx, use the following command:
        end
      end
 
-##Using Custom Formatting
-
+##Using Custom Formatting and date1904
+     require 'date'
      wb.styles do |s|
        date = s.add_style(:format_code => "yyyy-mm-dd", :border => Axlsx::STYLE_THIN_BORDER)
        padded = s.add_style(:format_code => "00#", :border => Axlsx::STYLE_THIN_BORDER)
        percent = s.add_style(:format_code => "0000%", :border => Axlsx::STYLE_THIN_BORDER)
+       wb.date1904 = true # required for generation on mac
        wb.add_worksheet(:name => "Formatting Data") do |sheet|
          sheet.add_row ["Custom Formatted Date", "Percent Formatted Float", "Padded Numbers"], :style => Axlsx::STYLE_THIN_BORDER
-         sheet.add_row [Time.now, 0.2, 32], :style => [date, percent, padded]
+         sheet.add_row [Date::strptime('2012-01-19','%Y-%m-%d'), 0.2, 32], :style => [date, percent, padded]
        end
      end
 
+##Add an Image
+
+     wb.add_worksheet(:name => "Images") do |sheet|
+       img = File.expand_path('examples/image1.jpeg') 
+       sheet.add_image(:image_src => img, :noSelect => true, :noMove => true) do |image|
+         image.width=720
+         image.height=666
+         image.start_at 2, 2
+       end
+     end  
+
+##Add an Image with a hyperlink
+
+     wb.add_worksheet(:name => "Image with Hyperlink") do |sheet|
+       img = File.expand_path('examples/image1.jpeg') 
+       sheet.add_image(:image_src => img, :noSelect => true, :noMove => true, :hyperlink=>"http://axlsx.blogspot.com") do |image|
+         image.width=720
+         image.height=666
+         image.hyperlink.tooltip = "Labeled Link"
+         image.start_at 2, 2
+       end
+     end  
+
+##Asian Language Support
+
+     wb.add_worksheet(:name => "Unicode Support") do |sheet|
+       sheet.add_row ["日本語"]
+       sheet.add_row ["华语/華語"]
+       sheet.add_row ["한국어/조선말"]
+     end  
+
 ##Styling Columns
 
      wb.styles do |s|
@@ -140,26 +172,6 @@ To install Axlsx, use the following command:
          sheet['A1:D2'].each { |c| c.style = Axlsx::STYLE_THIN_BORDER }
      end     
 
-##Add an Image
-
-     wb.add_worksheet(:name => "Images") do |sheet|
-       img = File.expand_path('examples/image1.jpeg') 
-       sheet.add_image(:image_src => img, :noSelect => true, :noMove => true) do |image|
-         image.width=720
-         image.height=666
-         image.start_at 2, 2
-       end
-     end  
-
-##Asian Language Support
-
-     wb.add_worksheet(:name => "Unicode Support") do |sheet|
-       sheet.add_row ["日本語"]
-       sheet.add_row ["华语/華語"]
-       sheet.add_row ["한국어/조선말"]
-     end  
-
-
 ##Using formula
 
      wb.add_worksheet(:name => "Using Formulas") do |sheet|
@@ -167,8 +179,7 @@ To install Axlsx, use the following command:
        sheet.add_row [1, 2, 3, "=SUM(A2:C2)"]
      end
 
-
-##Merging Cells
+##Merging Cells.
 
      wb.add_worksheet(:name => 'Merging Cells') do |sheet|
          # cell level style overides when adding cells
@@ -255,48 +266,34 @@ This gem is 100% documented with YARD, an exceptional documentation library. To
       gem install yard
       yard server -g
 
-
 #Specs
 ------
 This gem has 100% test coverage using test/unit. To execute tests for this gem, simply run rake in the gem directory.
  
 #Changelog
 ---------
+- ** February.2.12**: 1.0.16 release
+   - Bug fix for schema file locations when validating in rails
+   - Added hyperlink to images
+   - date1904 now automatically set in bsd and mac environments
+   - removed whitespace/indentation from xml outputs
+   - col_style now skips rows that do not contain cells at the column index
+ 
 - **January.6.12**: 1.0.15 release
    - Bug fix add_style specified number formats must be explicity applied for libraOffice
    - performance improvements from ochko when creating cells with options.
    - Bug fix setting types=>[:n] when adding a row incorrectly determines the cell type to be string as the value is null during creation.
    - Release in preparation for password protection merge
 
-- **December.14.11**: 1.0.14 release
-   - Added support for merging cells
-   - Added support for auto filters
-   - Improved auto width calculations
-   - Improved charts
-   - Updated examples to output to a single workbook with multiple sheets
-   - Added access to app and core package objects so you can set the creator and other properties of the package
-   - The beginning of password protected xlsx files - roadmapped for January release.
-	
-- **December.8.11**: 1.0.13 release
-   -  Fixing .gemspec errors that caused gem to miss the lib directory. Sorry about that.
-
-- **December.7.11**: 1.0.12 release
-    DO NOT USE THIS VERSION = THE GEM IS BROKEN
-  - changed dependency from 'zip' gem to 'rubyzip' and added conditional code to force binary encoding to resolve issue with excel 2011
-  - Patched bug in app.xml that would ignore user specified properties.
-- **December.5.11**: 1.0.11 release
-  - Added [] methods to worksheet and workbook to provide name based access to cells.
-  - Added support for functions as cell values
-  - Updated color creation so that two character shorthand values can be used like 'FF' for 'FFFFFFFF' or 'D8' for 'FFD8D8D8'
-  - Examples for all this fun stuff added to the readme
-  - Clean up and support for 1.9.2 and travis integration
-  - Added support for string based cell referencing to chart start_at and end_at. That means you can now use :start_at=>"A1" when using worksheet.add_chart, or chart.start_at ="A1" in addition to passing a cell or the x, y coordinates.
  
 Please see the {file:CHANGELOG.md} document for past release information.
 
 #Thanks!
 --------
-ochko https://github.com/ochko
+[ochko](https://github.com/ochko) - for performance fixes, kicking the crap out of axlsx and helping to maintain my general sanity.
+
+[kleine2](https://github.com/kleine2) - for generously donating in return for the image hyperlink feature.
+
 #Copyright and License
 ----------
 

data/examples/example.rb

@@ -24,7 +24,7 @@
      end
 
 ##Using Custom Formatting and date1904
-
+     require 'date'
      wb.styles do |s|
        date = s.add_style(:format_code => "yyyy-mm-dd", :border => Axlsx::STYLE_THIN_BORDER)
        padded = s.add_style(:format_code => "00#", :border => Axlsx::STYLE_THIN_BORDER)
@@ -32,7 +32,7 @@
        wb.date1904 = true # required for generation on mac
        wb.add_worksheet(:name => "Formatting Data") do |sheet|
          sheet.add_row ["Custom Formatted Date", "Percent Formatted Float", "Padded Numbers"], :style => Axlsx::STYLE_THIN_BORDER
-         sheet.add_row [Time.now, 0.2, 32], :style => [date, percent, padded]
+         sheet.add_row [Date::strptime('2012-01-19','%Y-%m-%d'), 0.2, 32], :style => [date, percent, padded]
        end
      end
 
@@ -47,6 +47,18 @@
        end
      end  
 
+##Add an Image with a hyperlink
+
+     wb.add_worksheet(:name => "Image with Hyperlink") do |sheet|
+       img = File.expand_path('examples/image1.jpeg') 
+       sheet.add_image(:image_src => img, :noSelect => true, :noMove => true, :hyperlink=>"http://axlsx.blogspot.com") do |image|
+         image.width=720
+         image.height=666
+         image.hyperlink.tooltip = "Labeled Link"
+         image.start_at 2, 2
+       end
+     end  
+
 ##Asian Language Support
 
      wb.add_worksheet(:name => "Unicode Support") do |sheet|

data/lib/axlsx/content_type/content_type.rb

@@ -17,7 +17,7 @@ module Axlsx
           each { |type| type.to_xml(xml) }
         }
       end
-      builder.to_xml
+      builder.to_xml(:save_with => 0)
     end
   end
 end

data/lib/axlsx/doc_props/app.rb

@@ -172,7 +172,7 @@ module Axlsx
           end
         }
       end      
-      builder.to_xml
+      builder.to_xml(:save_with => 0)
     end
   end
 end

data/lib/axlsx/doc_props/core.rb

@@ -28,7 +28,7 @@ module Axlsx
           xml['cp'].revision 0
         }
       end  
-      builder.to_xml
+      builder.to_xml(:save_with => 0)
     end
   end
 end

data/lib/axlsx/drawing/chart.rb

@@ -145,7 +145,7 @@ module Axlsx
           
         }
       end
-      builder.to_xml
+      builder.to_xml(:save_with => 0)
     end
 
     # This is a short cut method to set the start anchor position

data/lib/axlsx/drawing/drawing.rb

@@ -29,6 +29,7 @@ module Axlsx
 
   require 'axlsx/drawing/picture_locking.rb'
   require 'axlsx/drawing/pic.rb'
+  require 'axlsx/drawing/hyperlink.rb'
 
   # A Drawing is a canvas for charts. Each worksheet has a single drawing that manages anchors.
   # The anchors reference the charts via graphical frames. This is not a trivial relationship so please do follow the advice in the note.
@@ -79,6 +80,13 @@ module Axlsx
       charts.map { |a| a.object.chart }
     end
 
+    # An array of hyperlink objects associated with this drawings images
+    # @return [Array]
+    def hyperlinks
+      links = self.images.select { |a| a.hyperlink.is_a?(Hyperlink) }
+      links.map { |a| a.hyperlink }
+    end
+
     # An array of image objects that are associated with this drawing's anchors
     # @return [Array]
     def images
@@ -120,6 +128,9 @@ module Axlsx
       images.each do |image|
         r << Relationship.new(IMAGE_R, "../#{image.pn}")
       end
+      hyperlinks.each do |hyperlink|
+        r << Relationship.new(HYPERLINK_R, hyperlink.href, :target_mode => :External)
+      end
       r
     end
 
@@ -131,7 +142,7 @@ module Axlsx
           anchors.each {|anchor| anchor.to_xml(xml) }
         }        
       end
-      builder.to_xml
+      builder.to_xml(:save_with => 0)
     end
   end
 end

data/lib/axlsx/drawing/hyperlink.rb

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+  # a hyperlink object adds an action to an image when clicked so that when the image is clicked the link is fecthed.
+  # @note using the hyperlink option when calling add_image on a drawing object is the recommended way to manage hyperlinks
+  # @see {file:README} README
+  class Hyperlink
+
+    # The destination of the hyperlink stored in the drawing's relationships document.
+    # @return [String]
+    attr_accessor :href
+
+    # The spec says: Specifies the URL when it has been determined by the generating application that the URL is invalid. That is the generating application can still store the URL but it is known that this URL is not correct.
+    #
+    # What exactly that means is beyond me so if you ever use this, let me know!
+    # @return [String]
+    attr_accessor :invalidUrl
+
+    #An action to take when the link is clicked. The specification says "This can be used to specify a slide to be navigated to or a script of code to be run." but in most cases you will not need to do anything with this. MS does reserve a few interesting strings. @see http://msdn.microsoft.com/en-us/library/ff532419%28v=office.12%29.aspx
+    # @return [String]
+    attr_accessor :action
+
+    # Specifies if all sound events should be terminated when this link is clicked.
+    # @return [Boolean]
+    attr_reader :endSnd
+
+    # @see endSnd
+    # @param [Boolean] v The boolean value indicating the termination of playing sounds on click
+    # @return [Boolean]
+    def endSnd=(v) Axlsx::validate_boolean(v); @endSnd = v end
+
+    # indicates that the link has already been clicked.
+    # @return [Boolean]
+    attr_reader :highlightClick
+    
+    # @see highlightClick
+    # @param [Boolean] v The value to assign
+    def highlightClick=(v) Axlsx::validate_boolean(v); @highlightClick = v end
+
+    # From the specs: Specifies whether to add this URI to the history when navigating to it. This allows for the viewing of this presentation without the storing of history information on the viewing machine. If this attribute is omitted, then a value of 1 or true is assumed. 
+    # @return [Boolean]
+    attr_reader :history
+
+    # @see history
+    # param [Boolean] v The value to assing
+    def history=(v) Axlsx::validate_boolean(v); @history = v end
+
+    # From the specs: Specifies the target frame that is to be used when opening this hyperlink. When the hyperlink is activated this attribute is used to determine if a new window is launched for viewing or if an existing one can be used. If this attribute is omitted, than a new window is opened.
+    # @return [String]
+    attr_accessor :tgtFrame
+
+    # Text to show when you mouse over the hyperlink. If you do not set this, the href property will be shown.
+    # @return [String]
+    attr_accessor :tooltip
+
+    #Creates a hyperlink object 
+    # parent must be a Pic for now, although I expect that other object support this tag and its cNvPr parent
+    # @param [Pic] parent
+    # @option options [String] tooltip message shown when hyperlinked object is hovered over with mouse.
+    # @option options [String] tgtFrame Target frame for opening hyperlink
+    # @option options [String] invalidUrl supposedly use to store the href when we know it is an invalid resource. 
+    # @option options [String] href the target resource this hyperlink links to.
+    # @option options [String] action A string that can be used to perform specific actions. For excel please see this reference: http://msdn.microsoft.com/en-us/library/ff532419%28v=office.12%29.aspx
+    # @option options [Boolean] endSnd terminate any sound events when processing this link
+    # @option options [Boolean] history include this link in the list of visited links for the applications history.
+    # @option options [Boolean] highlightClick indicate that the link has already been visited.
+    def initialize(parent, options={})
+      DataTypeValidator.validate "Hyperlink.parent", [Pic], parent
+      @parent = parent
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+     
+    end
+
+
+    # Serializes the hyperlink
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml) 
+      h =  self.instance_values.merge({:'r:id' => "rId#{id}", :'xmlns:r' => XML_NS_R })
+      h.delete('href')
+      h.delete('parent')
+      xml[:a].hlinkClick h
+    end
+
+    private
+    # The relational ID for this hyperlink    
+    # @return [Integer]
+    def id
+      @parent.anchor.drawing.charts.size + @parent.anchor.drawing.images.size + @parent.anchor.drawing.hyperlinks.index(self) + 1
+    end
+
+  end
+end

data/lib/axlsx/drawing/hyperlink.rb~

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+  # a hlinkClick object adds a click behaviour to a drawing object.
+  # using the hlink_click method on a drawing object is the recommended way to manage hlinks
+  # @see Pic#link_to
+  class Hyperlink
+
+    # the type of hyper link defines the onclick or mouseover trigger.
+    # type must be one of :hlinkClick or :hlinkMouse
+    def type
+      @type ||= :hlinkClick
+    end
+
+    # sets the type of the object. 
+    # @param [Symbol] type one of :hlinkClick or hlinkMouse
+    def type(v) RestrictionValidator.validate "Hyperlink.type", [:hlinkClick, :hlinkMouse], v; @type = v end
+
+    # The destination of the hyperlink
+    # This value is actually stored in the drawings .rels. doc as a relationship.
+    attr_accessor :href
+
+    # The docs say:
+    #      Specifies the URL when it has been determined by the generating application that the URL is invalid. That is the generating application can still store the URL but it is known that this URL is not correct.
+    attr_accessor :invalidUrl
+
+    # Specifies the target frame that is to be used when opening this hyperlink. When the hyperlink is activated this attribute is used to determine if a new window is launched for viewing or if an existing one can be used. If this attribute is omitted, than a new window is opened.
+    attr_accessor :tgtFrame
+
+    # Specifies the tooltip that should be displayed when the hyperlink text is hovered over with the mouse. If this attribute is omitted, than the hyperlink text itself can be displayed.
+    attr_accessor :tooltip
+
+    #Creates a hyperlink object 
+    # parent must be a Pic for now, although I expect that other object support this tag and its cNvPr parent
+    # @param [Pic] parent
+    # @option [String] tooltip message shown when hyperlinked object is hovered over with mouse.
+    # @option [String] tgtFrame Target frame for opening hyperlink
+    # @option [String] invalidUrl supposedly use to store the href when we know it is an invalid resource. 
+    # @option [String] href the target resource this hyperlink links to.
+    def initialize(parent, options=>{})
+      DataTypeValidator.validate "Hyperlink.parent", [Pic], parent
+      @parent = parent
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # The index of this hyperlink in the owning document's hyperlinks collection
+    # @returns [Integer]
+    def index
+      self.parent.anchor.drawing.hyperlinks.index(self)
+    end
+
+    # The relational ID for this hyperlink    
+    # @returns [String]
+    def r:id
+      reference_count = self.parent.anchor.drawing.charts.size + self.parent.anchor.drawing.images.size + index
+      
+    end
+
+    def to_xml(xml) 
+      xml.send(type, 
+    end
+  end
+end