spreadsheet_architect 3.3.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f38d9c89007db3a758dfb45a1264a930656da06f23c49c2e3bdd7873d6dfbd0
-  data.tar.gz: 0ec2f5822b9b9ea05bed50f25ee295eed4b686757895e36bef32320d0d3312f2
+  metadata.gz: 64bcbae2181e3941b235d571b72bc217c5161c558075b2839376590e88e1ff74
+  data.tar.gz: 3c1d88c58d960945e7ca89266e57cf39bfc1b50259133dd4b31064398cba24a4
 SHA512:
-  metadata.gz: 4bcc69430c518e210ed758b992a4cfc6976881b3e641c52b03793c7c2b1b010ddfd654660cfa7e19b6fb6648ea0cd6fd21dccedd1be243c7bc69d49e754fd961
-  data.tar.gz: cd4e755539d61e4c9da6131c2f8b34a3d60fbd0aeeeccf2aa0c1407e2011c518229e912137392426330983ce69f5f7d8a0ecda45212207302aa2611058c296b8
+  metadata.gz: 3ef5eff17a279f7235617000780bf6c1fae69f8c4a7a034567821cb836a9417a20716f38aa4632720d32d1f461f503fca0f5c4563566f5fe23ccb49b1e676dcd
+  data.tar.gz: 41e889c83d74da214d9eddc7c7eafb00d9c170e391be1ad6aa1cc3000c06b3c804e28c80c15d957b57639036cd5c37cdefcf86d9703074405378276654bf0c9b

data/CHANGELOG.md

@@ -2,7 +2,15 @@ CHANGELOG
 ---------
 
 - **Unreleased**
-  - Nothing Yet
+  - Nothing yet
+- **4.0.0**
+  - Switch to the `caxlsx` gem (Community Axlsx) from the legacy unmaintained `axlsx` gem. Axlsx has had a long history of being poorly maintained so this community gem improves the situation.
+  - Require Ruby 2.3+
+  - Ensure all options using Hash are automatically converted to symbol only hashes
+  - Add XLSX option `:freeze` to freeze custom sections of your spreadsheet
+  - Add XLSX option `:freeze_headers` to freeze the headers of your spreadsheet
+  - Remove old Axlsx patch for column width
+  - Backport new code for `string_width` calculations to Axlsx 3.0.1 and below.
 - **3.3.1**
   - [Issue #30](https://github.com/westonganger/spreadsheet_architect/issues/30) - Fix duplicate constant warning for XLSX_COLUMN_TYPES
 - **3.3.0**

data/README.md

@@ -26,6 +26,8 @@ gem 'spreadsheet_architect'
 
 ### Tabular (Array) Data
 
+The simplest and preffered usage is to simply create the data array yourself. 
+
 ```ruby
 headers = ['Col 1','Col 2','Col 3']
 data = [[1,2,3], [4,5,6], [7,8,9]]
@@ -34,50 +36,25 @@ SpreadsheetArchitect.to_ods(headers: headers, data: data)
 SpreadsheetArchitect.to_csv(headers: headers, data: data)
 ```
 
-### Rails relation or an array of plain Ruby object instances
-
-```ruby
-posts = Post.order(name: :asc).where(published: true)
-# OR
-posts = 10.times.map{|i| Post.new(number: i)}
+Using this style will allow you to utilize any custom performance optimizations during your data generation process. This will come in handy when the spreadsheets get large and things start to get slow. One of my favourites for Rails is [light_record](https://github.com/Paxa/light_record)
 
-SpreadsheetArchitect.to_xlsx(instances: posts)
-SpreadsheetArchitect.to_ods(instances: posts)
-SpreadsheetArchitect.to_csv(instances: posts)
-```
+### Rails Relations or an Array of plain Ruby object instances
 
-**(Optional)** If you would like to add the methods `to_xlsx`, `to_ods`, `to_csv`, `to_axlsx_package`, `to_rodf_spreadsheet` to some class, you can simply include the SpreadsheetArchitect module to whichever classes you choose. A good default strategy is to simply add it to the ApplicationRecord or another parent class to have it available on all appropriate classes. For example:
+If you would like to add the methods `to_xlsx`, `to_ods`, `to_csv`, `to_axlsx_package`, `to_rodf_spreadsheet` to some class, you can simply include the SpreadsheetArchitect module to whichever classes you choose. A good default strategy is to simply add it to the ApplicationRecord or another parent class to have it available on all appropriate classes. For example:
 
 ```ruby
-class ApplicationRecord < ActiveRecord::Base
+class Post < ApplicationRecord
   include SpreadsheetArchitect
 end
 ```
 
-Then use it on the class or ActiveRecord relations of the class
-
-```ruby
-posts = Post.order(name: :asc).where(published: true)
-posts.to_xlsx
-posts.to_ods
-posts.to_csv
-
-# Plain Ruby Objects
-posts_array = 10.times.map{|i| Post.new(number: i)}
-Post.to_xlsx(instances: posts_array)
-Post.to_ods(instances: posts_array)
-Post.to_csv(instances: posts_array)
-```
-
-# Usage with Instances / ActiveRecord Relations
-
-When NOT using the `:data` option, ie. on an AR Relation or using the `:instances` option, Spreadsheet Architect requires an instance method defined on the class to generate the data. It looks for the `spreadsheet_columns` method on the class. If you are using on an ActiveRecord model and that method is not defined, it would fallback to the models `column_names` method (not recommended). If using the `:data` option this is ignored.
+When using on an AR Relation or using the `:instances` option, SpreadsheetArchitect requires an instance method to be defined on the class to generate the data. By default it looks for the `spreadsheet_columns` method on the class. If you are using on an ActiveRecord model and that method is not defined, it would fallback to the models `column_names` method. If using the `:data` option this is completely ignored.
 
 ```ruby
 class Post
+  include SpreadsheetArchitect
 
   def spreadsheet_columns
-
     ### Column format is: [Header, Cell Data / Method (if symbol) to Call on each Instance, (optional) Cell Type]
     [
       ['Title', :title],
@@ -89,15 +66,30 @@ class Post
       ['Rating', :rating],
       ['Category/Tags', "#{category.name} - #{tags.collect(&:name).join(', ')}"]
     ]
+  end
+
 end
+```
+
+Then use it on the class or ActiveRecord relations of the class
 
-Post.to_xlsx(instances: posts)
+```ruby
+posts = Post.order(name: :asc).where(published: true)
+posts.to_xlsx
+posts.to_ods
+posts.to_csv
+
+# Plain Ruby Objects
+posts_array = 10.times.map{|i| Post.new(number: i)}
+Post.to_xlsx(instances: posts_array)
+Post.to_ods(instances: posts_array)
+Post.to_csv(instances: posts_array)
 ```
 
-If you want to use a different method name then `spreadsheet_columns` you can pass a method name as a Symbol or String to the `spreadsheet_columns` option. Feel free to utilize the model-wide/project-wide defaults features if desired necessary.
+If you want to use a different method name then `spreadsheet_columns` you can pass a method name to the `:spreadsheet_columns` option.
 
 ```ruby
-Post.to_xlsx(instances: posts, spreadsheet_columns: :my_special_columns)
+Post.to_xlsx(instances: posts, spreadsheet_columns: :my_special_method)
 ```
 
 Alternatively, you can pass a Proc/lambda to the `spreadsheet_columns` option. For those purists that really dont want to define any extra `spreadsheet_columns` instance method on your model, this option can help you work with that methodology.
@@ -119,10 +111,19 @@ Post.to_xlsx(instances: posts, spreadsheet_columns: Proc.new{|instance|
 
 # Sending & Saving Spreadsheets
 
-### Method 1: Send Data via Rails Controller
+### Method 1: Save to a file manually
 
 ```ruby
+file_data = SpreadsheetArchitect.to_xlsx(headers: headers, data: data)
 
+File.open('path/to/file.xlsx', 'w+b') do |f|
+  f.write file_data
+end
+```
+
+### Method 2: Send Data via Rails Controller
+
+```ruby
 class PostsController < ActionController::Base
   respond_to :html, :xlsx, :ods, :csv
 
@@ -176,44 +177,27 @@ class PostsController < ActionController::Base
 end
 ```
 
-### Method 2: Save to a file manually
+# Multi Sheet Spreadsheets
 
-```ruby
-### Ex. with ActiveRecord relation
-file_data = Post.order(published_at: :asc).to_xlsx
-File.open('path/to/file.xlsx', 'w+b') do |f|
-  f.write file_data
-end
+### XLSX
 
-file_data = Post.order(published_at: :asc).to_ods
-File.open('path/to/file.ods', 'w+b') do |f|
-  f.write file_data
-end
-
-file_data = Post.order(published_at: :asc).to_csv
-File.open('path/to/file.csv', 'w+b') do |f|
-  f.write file_data
-end
-```
-
-# Multi Sheet XLSX Spreadsheets
 ```ruby
 axlsx_package = SpreadsheetArchitect.to_axlsx_package({headers: headers, data: data})
 axlsx_package = SpreadsheetArchitect.to_axlsx_package({headers: headers, data: data}, package)
 
-File.open('path/to/file.xlsx', 'w+b') do |f|
+File.open('path/to/multi_sheet_file.xlsx', 'w+b') do |f|
   f.write axlsx_package.to_stream.read
 end
 ```
 
 See this file for more details: https://github.com/westonganger/spreadsheet_architect/blob/master/test/spreadsheet_architect/multi_sheet_test.rb
 
-### Multi Sheet ODS Spreadsheets
+### ODS
 ```ruby
 ods_spreadsheet = SpreadsheetArchitect.to_rodf_spreadsheet({headers: headers, data: data})
 ods_spreadsheet = SpreadsheetArchitect.to_rodf_spreadsheet({headers: headers, data: data}, spreadsheet)
 
-File.open('path/to/file.ods', 'w+b') do |f|
+File.open('path/to/multi_sheet_file.ods', 'w+b') do |f|
   f.write ods_spreadsheet
 end
 ```
@@ -240,6 +224,8 @@ See this file for more details: https://github.com/westonganger/spreadsheet_arch
 |**borders**<br>*Array*||[See this example for usage](https://github.com/westonganger/spreadsheet_architect/blob/master/test/unit/kitchen_sink_test.rb)|
 |**column_types**<br>*Array*||Valid types for XLSX are :string, :integer, :float, :date, :time, :boolean, nil = auto determine.|
 |**column_widths**<br>*Array*||Sometimes you may want explicit column widths. Use nil if you want a column to autofit again.|
+|**freeze_headers**<br>*Boolean*||Make all header rows frozen/fixed so they do not scroll.|
+|**freeze**<br>* Hash*|`{rows: (1..4), columns: :all}`|Make all specified rows and columns frozen/fixed so they do not scroll.|
 
 ## `to_axlsx_spreadsheet(options={}, axlsx_package_to_join=nil)`
 Same options as `to_xlsx`
@@ -273,7 +259,9 @@ Same options as `to_ods`
 # Change class-wide default method options
 
 ```ruby
-class Post
+class Post < ApplicationRecord
+  include SpreadsheetArchitect
+
   def spreadsheet_columns
     [:name, :content]
   end

data/lib/spreadsheet_architect/axlsx_string_width_patch.rb

@@ -0,0 +1,21 @@
+if Axlsx::VERSION.to_f < 3.1
+
+  Axlsx::Cell.class_eval do
+    private
+
+    def string_width(string, font_size)
+      font_scale = font_size / 10.0
+      (string.to_s.size + 3) * font_scale
+    end
+  end
+
+  Axlsx::RichTextRun.class_eval do
+    private
+
+    def string_width(string, font_size)
+      font_scale = font_size / 10.0
+      string.to_s.size * font_scale
+    end
+  end
+
+end

data/lib/spreadsheet_architect/class_methods/xlsx.rb

@@ -1,7 +1,7 @@
 require 'axlsx'
 require 'axlsx_styler'
 
-require 'spreadsheet_architect/monkey_patches/axlsx_column_width'
+require 'spreadsheet_architect/axlsx_string_width_patch'
 
 module SpreadsheetArchitect
   module ClassMethods
@@ -107,6 +107,8 @@ module SpreadsheetArchitect
           sheet.add_row row_data, style: styles, types: types
 
           if options[:conditional_row_styles]
+            options[:conditional_row_styles] = SpreadsheetArchitect::Utils.hash_array_symbolize_keys(options[:conditional_row_styles])
+
             conditional_styles_for_row = SpreadsheetArchitect::Utils::XLSX.conditional_styles_for_row(options[:conditional_row_styles], row_index, row_data)
             
             unless conditional_styles_for_row.empty?
@@ -127,6 +129,8 @@ module SpreadsheetArchitect
         end
 
         if options[:borders]
+          options[:borders] = SpreadsheetArchitect::Utils.hash_array_symbolize_keys(options[:borders])
+
           options[:borders].each do |x|
             if x[:range].is_a?(Hash)
               x[:range] = SpreadsheetArchitect::Utils::XLSX.range_hash_to_str(x[:range], max_row_length, num_rows)
@@ -139,6 +143,8 @@ module SpreadsheetArchitect
         end
 
         if options[:column_styles]
+          options[:column_styles] = SpreadsheetArchitect::Utils.hash_array_symbolize_keys(options[:column_styles])
+
           options[:column_styles].each do |x|
             start_row = (options[:headers] ? options[:headers].count : 0) + 1
 
@@ -170,6 +176,8 @@ module SpreadsheetArchitect
         end
 
         if options[:range_styles]
+          options[:range_styles] = SpreadsheetArchitect::Utils.hash_array_symbolize_keys(options[:range_styles])
+
           options[:range_styles].each do |x|
             styles = SpreadsheetArchitect::Utils::XLSX.convert_styles_to_axlsx(x[:styles])
 
@@ -184,6 +192,8 @@ module SpreadsheetArchitect
         end
 
         if options[:merges]
+          options[:merges] = SpreadsheetArchitect::Utils.hash_array_symbolize_keys(options[:merges])
+
           options[:merges].each do |x|
             if x[:range].is_a?(Hash)
               x[:range] = SpreadsheetArchitect::Utils::XLSX.range_hash_to_str(x[:range], max_row_length, num_rows)
@@ -194,6 +204,44 @@ module SpreadsheetArchitect
             sheet.merge_cells x[:range]
           end
         end
+
+        if options[:freeze_headers]
+          sheet.sheet_view.pane do |pane|
+            pane.state = :frozen
+            pane.y_split = options[:headers].count
+          end
+
+        elsif options[:freeze]
+          options[:freeze] = SpreadsheetArchitect::Utils.symbolize_keys(options[:freeze])
+
+          sheet.sheet_view.pane do |pane|
+            pane.state = :frozen
+
+            ### Currently not working
+            #if options[:freeze][:active_pane]
+            #  Axlsx.validate_pane_type(options[:freeze][:active_pane])
+            #  pane.active_pane = options[:freeze][:active_pane]
+            #else
+            #  pane.active_pane = :bottom_right
+            #end
+
+            if !options[:freeze][:rows]
+              raise SpreadsheetArchitect::Exceptions::ArgumentError.new("The :rows key must be specified in the :freeze option hash")
+            elsif options[:freeze][:rows].is_a?(Range)
+              pane.y_split = options[:freeze][:rows].count
+            else
+              pane.y_split = 1
+            end
+
+            if options[:freeze][:columns] && options[:freeze][:columns] != :all
+              if options[:freeze][:columns].is_a?(Range)
+                pane.x_split = options[:freeze][:columns].count
+              else
+                pane.x_split = 1
+              end
+            end
+          end
+        end
       end
 
       return package

data/lib/spreadsheet_architect/utils.rb

@@ -13,7 +13,7 @@ module SpreadsheetArchitect
       elsif options[:headers].is_a?(Array)
         headers = options[:headers]
       else
-        headers = false
+        headers = []
       end
 
       if options[:column_types]
@@ -109,6 +109,10 @@ module SpreadsheetArchitect
     def self.get_options(options, klass)
       verify_option_types(options)
 
+      if options[:freeze] && options[:freeze_headers]
+        raise SpreadsheetArchitect::Exceptions::ArgumentError.new('Cannot use both :freeze and :freeze_headers options at the same time')
+      end
+
       if defined?(klass::SPREADSHEET_OPTIONS)
         if klass::SPREADSHEET_OPTIONS.is_a?(Hash)
           options = SpreadsheetArchitect.default_options.merge(
@@ -137,6 +141,10 @@ module SpreadsheetArchitect
         end
       end
 
+      if options[:freeze] && options[:freeze].is_a?(Hash) && !options[:freeze][:rows]
+        raise SpreadsheetArchitect::Exceptions::ArgumentError.new('Must provide a :rows key when passing a hash to the :freeze option')
+      end
+
       return options
     end
 
@@ -208,6 +216,8 @@ module SpreadsheetArchitect
     end
 
     def self.verify_option_types(options)
+      options = self.symbolize_keys(options, shallow: true)
+
       check_option_type(options, :spreadsheet_columns, [Proc, Symbol, String])
       check_option_type(options, :data, Array)
       check_option_type(options, :instances, Array)
@@ -221,10 +231,13 @@ module SpreadsheetArchitect
       check_option_type(options, :borders, Array)
       check_option_type(options, :column_widths, Array)
       check_option_type(options, :column_types, Array)
+      check_option_type(options, :freeze_headers, [TrueClass, FalseClass])
+      check_option_type(options, :freeze, Hash)
     end
 
-    def self.stringify_keys(hash={})
+    def self.stringify_keys(hash)
       new_hash = {}
+
       hash.each do |k,v|
         if v.is_a?(Hash)
           new_hash[k.to_s] = self.stringify_keys(v)
@@ -232,7 +245,33 @@ module SpreadsheetArchitect
           new_hash[k.to_s] = v
         end
       end
+
       return new_hash
     end
+
+    def self.symbolize_keys(hash, shallow: false)
+      new_hash = {}
+
+      hash.each do |k,v|
+        if v.is_a?(Hash)
+          new_hash[k.to_sym] = shallow ? v : self.symbolize_keys(v)
+        else
+          new_hash[k.to_sym] = v
+        end
+      end
+
+      return new_hash
+    end
+
+    def self.hash_array_symbolize_keys(array)
+      new_array = []
+
+      array.each_with_index do |x,i|
+        new_array[i] = x.is_a?(Hash) ? self.symbolize_keys(x) : x
+      end
+
+      return new_array
+    end
+
   end
 end

data/lib/spreadsheet_architect/utils/xlsx.rb

@@ -26,7 +26,8 @@ module SpreadsheetArchitect
 
       def self.convert_styles_to_axlsx(styles={})
         styles = {} unless styles.is_a?(Hash)
-        styles = self.symbolize_keys(styles)
+
+        styles = SpreadsheetArchitect::Utils.symbolize_keys(styles)
 
         if styles[:fg_color].nil? && styles[:color] && styles[:color].respond_to?(:sub) && !styles[:color].empty?
           styles[:fg_color] = styles.delete(:color).sub('#','')
@@ -176,18 +177,6 @@ module SpreadsheetArchitect
 
       private
 
-      def self.symbolize_keys(hash={})
-        new_hash = {}
-        hash.each do |k, v|
-          if v.is_a?(Hash)
-            new_hash[k.to_sym] = self.symbolize_keys(v)
-          else
-            new_hash[k.to_sym] = v
-          end
-        end
-        new_hash
-      end
-
       ### Limit of 16384 columns as per Excel limitations
       COL_NAMES = Array('A'..'XFD').freeze