rails-excel-reporter 0.1.0

data/lib/rails_excel_reporter/base.rb

@@ -0,0 +1,210 @@
+require 'caxlsx'
+require 'tempfile'
+require 'ostruct'
+require 'stringio'
+require_relative 'styling'
+require_relative 'streaming'
+
+module RailsExcelReporter
+  class Base
+    include Styling
+    include Streaming
+
+    attr_reader :collection, :worksheet_name, :progress_callback
+
+    def initialize(collection, worksheet_name: nil, &progress_callback)
+      @collection = collection
+      @worksheet_name = worksheet_name || default_worksheet_name
+      @progress_callback = progress_callback
+      @rendered = false
+    end
+
+    def self.attributes(*attrs)
+      if attrs.empty?
+        @attributes ||= []
+      else
+        @attributes = attrs.map do |attr|
+          case attr
+          when Symbol
+            { name: attr, header: attr.to_s.humanize }
+          when Hash
+            symbolize_hash_keys(attr)
+          else
+            { name: attr.to_sym, header: attr.to_s.humanize }
+          end
+        end
+      end
+    end
+
+    def self.symbolize_hash_keys(hash)
+      result = {}
+      hash.each do |key, value|
+        result[key.to_sym] = value
+      end
+      result
+    end
+
+    def self.attribute(name, options = {})
+      @attributes ||= []
+      @attributes << { name: name.to_sym, header: options[:header] || name.to_s.humanize }
+    end
+
+    def self.inherited(subclass)
+      super
+      subclass.instance_variable_set(:@attributes, @attributes.dup) if @attributes
+    end
+
+    def attributes
+      self.class.attributes
+    end
+
+    def file
+      render unless @rendered
+      @tempfile
+    end
+
+    def to_xlsx
+      render unless @rendered
+      @tempfile.rewind
+      @tempfile.read
+    end
+
+    def save_to(path)
+      File.open(path, 'wb') do |file|
+        file.write(to_xlsx)
+      end
+    end
+
+    def filename
+      timestamp = Time.now.strftime(RailsExcelReporter.config.date_format).gsub('-', '_')
+      "#{worksheet_name.parameterize}_report_#{timestamp}.xlsx"
+    end
+
+    def stream
+      StringIO.new(to_xlsx)
+    end
+
+    def to_h
+      {
+        worksheet_name: worksheet_name,
+        attributes: attributes,
+        data: collection_data,
+        collection_size: collection_size,
+        streaming: should_stream?
+      }
+    end
+
+    def before_render; end
+
+    def after_render; end
+
+    def before_row(object); end
+
+    def after_row(object); end
+
+    private
+
+    def default_worksheet_name
+      if self.class.name
+        self.class.name.demodulize.underscore.humanize
+      else
+        'Report'
+      end
+    end
+
+    def render
+      validate_attributes!
+
+      before_render
+
+      @tempfile = Tempfile.new([filename.gsub('.xlsx', ''), '.xlsx'],
+                               RailsExcelReporter.config.temp_directory)
+
+      package = ::Axlsx::Package.new
+      workbook = package.workbook
+
+      worksheet = workbook.add_worksheet(name: worksheet_name)
+
+      add_headers(worksheet)
+      add_data_rows(worksheet)
+
+      package.serialize(@tempfile.path)
+
+      @rendered = true
+
+      after_render
+    end
+
+    def validate_attributes!
+      raise 'No attributes defined. Use `attributes` class method to define columns.' if attributes.empty?
+    end
+
+    def add_headers(worksheet)
+      header_values = attributes.map { |attr| attr[:header] }
+      header_style = build_caxlsx_style(get_header_style)
+
+      if header_style.any?
+        style_id = worksheet.workbook.styles.add_style(header_style)
+        worksheet.add_row(header_values, style: style_id)
+      else
+        worksheet.add_row(header_values)
+      end
+
+      worksheet.auto_filter = "A1:#{column_letter(attributes.size)}1"
+    end
+
+    def add_data_rows(worksheet)
+      with_progress_tracking do |object, _progress|
+        before_row(object)
+
+        row_values = attributes.map do |attr|
+          get_attribute_value(object, attr[:name])
+        end
+
+        row_styles = attributes.map do |attr|
+          style_options = build_caxlsx_style(get_column_style(attr[:name]))
+          worksheet.workbook.styles.add_style(style_options) if style_options.any?
+        end
+
+        worksheet.add_row(row_values, style: row_styles)
+
+        after_row(object)
+      end
+    end
+
+    def get_attribute_value(object, attribute_name)
+      if respond_to?(attribute_name)
+        @object = object
+        result = send(attribute_name)
+        @object = nil
+        result
+      elsif object.respond_to?(attribute_name)
+        object.send(attribute_name)
+      elsif object.respond_to?(:[])
+        object[attribute_name] || object[attribute_name.to_s]
+      end
+    end
+
+    attr_reader :object
+
+    def collection_data
+      @collection_data ||= stream_data.map do |item|
+        attributes.map do |attr|
+          get_attribute_value(item, attr[:name])
+        end
+      end
+    end
+
+    def column_letter(column_number)
+      result = ''
+      while column_number > 0
+        column_number -= 1
+        result = ((column_number % 26) + 65).chr + result
+        column_number /= 26
+      end
+      result
+    end
+  end
+
+  ReportBase = Base
+end

data/lib/rails_excel_reporter/configuration.rb

@@ -0,0 +1,40 @@
+module RailsExcelReporter
+  class Configuration
+    attr_accessor :default_styles, :date_format, :streaming_threshold, :temp_directory
+
+    def initialize
+      @default_styles = {
+        header: {
+          bg_color: '4472C4',
+          fg_color: 'FFFFFF',
+          bold: true,
+          border: { style: :thin, color: '000000' }
+        },
+        cell: {
+          border: { style: :thin, color: 'CCCCCC' }
+        }
+      }
+      @date_format = '%Y-%m-%d'
+      @streaming_threshold = 1000
+      @temp_directory = nil
+    end
+
+    def temp_directory
+      @temp_directory || Dir.tmpdir
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def config
+      configuration
+    end
+  end
+end

data/lib/rails_excel_reporter/controller_helpers.rb

@@ -0,0 +1,34 @@
+module RailsExcelReporter
+  module ControllerHelpers
+    def send_excel_report(report, options = {})
+      filename = options[:filename] || report.filename
+      disposition = options[:disposition] || 'attachment'
+
+      send_data(
+        report.to_xlsx,
+        filename: filename,
+        type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        disposition: disposition
+      )
+    end
+
+    def stream_excel_report(report, options = {})
+      filename = options[:filename] || report.filename
+
+      response.headers['Content-Type'] = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+      response.headers['Content-Disposition'] = "attachment; filename=\"#{filename}\""
+      response.headers['Content-Transfer-Encoding'] = 'binary'
+      response.headers['Last-Modified'] = Time.now.httpdate
+
+      self.response_body = report.stream
+    end
+
+    def excel_report_response(report, options = {})
+      if report.should_stream?
+        stream_excel_report(report, options)
+      else
+        send_excel_report(report, options)
+      end
+    end
+  end
+end

data/lib/rails_excel_reporter/railtie.rb

@@ -0,0 +1,35 @@
+require 'rails/railtie'
+
+module RailsExcelReporter
+  class Railtie < Rails::Railtie
+    initializer 'rails_excel_reporter.configure_rails_initialization' do |app|
+      app.config.paths.add 'app/reports', eager_load: true
+    end
+
+    initializer 'rails_excel_reporter.include_controller_helpers' do
+      ActiveSupport.on_load(:action_controller) do
+        include RailsExcelReporter::ControllerHelpers
+      end
+    end
+
+    config.after_initialize do
+      if defined?(Rails.application) && Rails.application
+        begin
+          reports_path = Rails.root.join('app/reports')
+
+          if Rails.application.paths['app/reports']
+            unless Rails.application.paths['app/reports'].paths.include?(reports_path.to_s)
+              Rails.application.paths['app/reports'] << reports_path.to_s
+            end
+
+            if Rails.application.paths['app/reports'].respond_to?(:eager_load!)
+              Rails.application.paths['app/reports'].eager_load!
+            end
+          end
+        rescue StandardError => e
+          Rails.logger.warn("RailsExcelReporter: Failed to configure app/reports path: #{e.message}") if Rails.logger
+        end
+      end
+    end
+  end
+end

data/lib/rails_excel_reporter/streaming.rb

@@ -0,0 +1,81 @@
+module RailsExcelReporter
+  module Streaming
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def streaming_threshold
+        @streaming_threshold || RailsExcelReporter.config.streaming_threshold
+      end
+
+      def streaming_threshold=(value)
+        @streaming_threshold = value
+      end
+    end
+
+    def should_stream?
+      collection_size >= self.class.streaming_threshold
+    end
+
+    def collection_size
+      return @collection_size if defined?(@collection_size)
+
+      @collection_size = if @collection.respond_to?(:count)
+                           @collection.count
+                         elsif @collection.respond_to?(:size)
+                           @collection.size
+                         elsif @collection.respond_to?(:length)
+                           @collection.length
+                         else
+                           @collection.to_a.size
+                         end
+    end
+
+    def stream_data(&block)
+      return enum_for(:stream_data) unless block_given?
+
+      if should_stream?
+        stream_large_dataset(&block)
+      else
+        stream_small_dataset(&block)
+      end
+    end
+
+    def with_progress_tracking
+      return enum_for(:with_progress_tracking) unless block_given?
+
+      total = collection_size
+      current = 0
+
+      stream_data do |item|
+        current += 1
+        progress = OpenStruct.new(current: current, total: total, percentage: (current.to_f / total * 100).round(2))
+
+        @progress_callback&.call(progress)
+
+        yield item, progress
+      end
+    end
+
+    private
+
+    def stream_large_dataset(&block)
+      if @collection.respond_to?(:find_each)
+        @collection.find_each(batch_size: 1000, &block)
+      elsif @collection.respond_to?(:each)
+        @collection.each(&block)
+      else
+        @collection.to_a.each(&block)
+      end
+    end
+
+    def stream_small_dataset(&block)
+      if @collection.respond_to?(:each)
+        @collection.each(&block)
+      else
+        @collection.to_a.each(&block)
+      end
+    end
+  end
+end

data/lib/rails_excel_reporter/styling.rb

@@ -0,0 +1,87 @@
+module RailsExcelReporter
+  module Styling
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def style(target, options = {})
+        @styles ||= {}
+        @styles[target.to_sym] = options
+      end
+
+      def styles
+        @styles ||= {}
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@styles, @styles.dup) if @styles
+      end
+    end
+
+    def apply_style(worksheet, cell_range, style_name)
+      style_options = self.class.styles[style_name.to_sym] || {}
+      return unless style_options.any?
+
+      worksheet.add_style(cell_range, style_options)
+    end
+
+    def build_caxlsx_style(style_options)
+      caxlsx_options = {}
+
+      caxlsx_options[:bg_color] = style_options[:bg_color] if style_options[:bg_color]
+
+      caxlsx_options[:fg_color] = style_options[:fg_color] if style_options[:fg_color]
+
+      caxlsx_options[:b] = style_options[:bold] if style_options[:bold]
+
+      caxlsx_options[:i] = style_options[:italic] if style_options[:italic]
+
+      caxlsx_options[:alignment] = style_options[:alignment] if style_options[:alignment]
+
+      caxlsx_options[:border] = style_options[:border] if style_options[:border]
+
+      caxlsx_options[:sz] = style_options[:font_size] if style_options[:font_size]
+
+      caxlsx_options[:font_name] = style_options[:font_name] if style_options[:font_name]
+
+      caxlsx_options
+    end
+
+    def merge_styles(*style_names)
+      merged = {}
+      style_names.each do |style_name|
+        style_options = self.class.styles[style_name.to_sym] || {}
+        merged = deep_merge_hashes(merged, style_options)
+      end
+      merged
+    end
+
+    def get_column_style(column_name)
+      column_style = self.class.styles[column_name.to_sym] || {}
+      default_style = RailsExcelReporter.config.default_styles[:cell] || {}
+      deep_merge_hashes(default_style, column_style)
+    end
+
+    def get_header_style
+      header_style = self.class.styles[:header] || {}
+      default_style = RailsExcelReporter.config.default_styles[:header] || {}
+      deep_merge_hashes(default_style, header_style)
+    end
+
+    private
+
+    def deep_merge_hashes(hash1, hash2)
+      result = hash1.dup
+      hash2.each do |key, value|
+        result[key] = if result[key].is_a?(Hash) && value.is_a?(Hash)
+                        deep_merge_hashes(result[key], value)
+                      else
+                        value
+                      end
+      end
+      result
+    end
+  end
+end

data/lib/rails_excel_reporter/version.rb

@@ -0,0 +1,3 @@
+module RailsExcelReporter
+  VERSION = '0.1.0'
+end

data/lib/rails_excel_reporter.rb

@@ -0,0 +1,19 @@
+require 'active_support/core_ext/string'
+require 'active_support/core_ext/hash'
+require 'active_support/core_ext/time'
+require 'tmpdir'
+
+module RailsExcelReporter
+  class Error < StandardError; end
+  class AttributeNotFoundError < Error; end
+  class InvalidConfigurationError < Error; end
+end
+
+require 'rails_excel_reporter/version'
+require 'rails_excel_reporter/configuration'
+require 'rails_excel_reporter/styling'
+require 'rails_excel_reporter/streaming'
+require 'rails_excel_reporter/base'
+require 'rails_excel_reporter/controller_helpers'
+
+require 'rails_excel_reporter/railtie' if defined?(Rails)

data/rails_excel_reporter.gemspec

@@ -0,0 +1,36 @@
+require_relative 'lib/rails_excel_reporter/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'rails-excel-reporter'
+  spec.version       = RailsExcelReporter::VERSION
+  spec.authors       = ['Elí Sebastian Herrera Aguilar']
+  spec.email         = ['esrbastianherrera@gmail.com']
+
+  spec.summary       = 'Generate Excel reports (.xlsx) in Rails with a simple DSL'
+  spec.description   = 'A Ruby gem that integrates seamlessly with Ruby on Rails to generate Excel reports using a simple DSL. Features include streaming, styling, callbacks, and Rails helpers.'
+  spec.homepage      = 'https://github.com/EliSebastian/rails-excel-reporter.git'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/EliSebastian/rails-excel-reporter.git'
+  spec.metadata['changelog_uri'] = 'https://github.com/EliSebastian/rails-excel-reporter.git/blob/main/CHANGELOG.md'
+
+  spec.files = Dir['{lib,spec}/**/*', '*.md', '*.gemspec', 'Gemfile*']
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '~> 8.0'
+  spec.add_dependency 'caxlsx', '~> 4.0'
+  spec.add_dependency 'rails', '~> 8.0'
+
+  spec.add_development_dependency 'pry', '~> 0.14'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec-rails', '~> 5.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'sqlite3', '~> 1.4'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end