excelinator 1.0.0

data/README.md

@@ -0,0 +1,146 @@
+Excelinator
+===========
+Small gem for generating _real_ Excel spreadsheets from existing CSV data and
+HTML tables that fully supports UTF-8 characters.
+
+Why?
+----
+Well, when you're starting up and things are small and then things grow and
+then people want reports and they'd like them in Excel most of the time and
+then you realize you can just throw some cheap CSV views at them and Excel
+will be fine with them and then you get even bigger and you start getting,
+like, friggin' _international_ and then the French dudes are like, "My umlauts
+look like chewed croissant" and you try prefixing your CSV with a UTF-8 BOM
+and that makes some Excels happy (Windows) but not others (Mac) and you think
+man I totally want to just, y'know, _eat_ the croissant like it was meant to
+be eaten y'know? and there's a zillion spreadsheet gems out there already
+except they all like merge back to that one spreadsheet gem, and you could go
+XMLDoc maybe, but then it's just like lemme use the CSV I've already got and
+try to not make me work much?
+
+No Rails Required
+-----------------
+The heart of this gem has a couple of small methods to handle the
+transformations. If that's all you need, you're good to go.
+
+###CSV
+
+Call `Excelinator.csv_to_xls(csv_content)`. The csv_content will be parsed by
+FasterCSV and converted to Excel spreadsheet contents ready to be saved to
+file or sent across the wire.
+
+###HTML
+
+Call `Excelinator.html_as_xls(html_content)`. The table element from the HTML
+content is extracted, a meta tag indicating utf-8 encoding is prepended and
+that's it. The resulting content isn't actually an Excel spreadsheet, just the
+HTML data. But write this out to a file with an .xls extension and Excel will
+open the contents and translate the `<table>` for you, formatting and all.
+	
+_NOTE: While some spreadsheet programs (e.g. Google Docs) will not translate
+HTML tables like this, both Excel on Windows and Mac will as well as
+OpenOffice._
+
+But I Need Rails
+----------------
+As you wish. As always, [TMTOWTDI](http://en.wikipedia.org/wiki/There's_more_than_one_way_to_do_it),
+but here are a few usage options. All examples work in Rails 2 and 3, except
+where noted.
+
+If you want to make an explicit xls view that has CSV content in it:
+
+```ruby
+class FooController < ApplicationController
+  def report
+    respond_to do |format|
+      format.html
+      format.csv
+      format.xls { render :xls => 'foo_report.xls' }
+    end
+  end
+end
+```
+
+Rails 2 doesn't support custom renderers, but the guts of our :xls renderer
+are mixed into the controllers, so you can call it directly this way:
+
+```ruby
+      format.xls { send_xls_data 'foo_report.xls' }
+```
+
+If you want to re-use an existing HTML view:
+
+```ruby
+      format.xls { send_xls_data 'foo_report.xls', :file => 'foo/report.html.erb' }
+```
+_`:template` also works in place of `:file` in Rails 3. `render :xls =>` also
+works in place of `send_xls_data` in Rails 3._
+
+Also note, `send_xls_data` (the guts of `render :xls`) will parse the given
+content and detect CSV or HTML, so no need to specify which is being passed in.
+
+You can even go with just an explicit xls view and no controller code, but
+you'll need to convert the CSV content yourself inside the view:
+
+```ruby
+<%= Excelinator.csv_to_xls(render :file => 'foo/xls_view.csv.erb').html_safe %>
+```
+_`:template` works in place of `:file` here as well in Rails 3._
+
+Or ... refactor the CSV content to a format-less partial:
+
+```ruby
+# _report.erb
+<%= generate_csv_report %>
+
+# report.csv.erb
+<%= render :partial => 'report' %>
+
+# report.xls.erb
+<%= Excelinator.csv_to_xls(render :partial => 'report').html_safe %>
+```
+
+There are test apps included in the source repo that exercise these different
+options.
+
+FAQ
+---
+
+###You lied when you said "_real_ Excel spreadsheets from ... HTML tables." What about converting HTML tables to a _real_ Excel file?
+
+I did, and I apologize. Lemme know when your pull request is ready.
+
+###Are there any options to re-use CSV/HTML views with No additional controller/view code?
+
+I've tinkered with it, but it requires a bit of duck punching of the Rails
+rendering code.
+
+###What if I want to generate a real Excel spreadsheet from scratch with all sorts of awesome in it?
+
+This gem uses `spreadsheet` under the covers. There are also others that
+support a wide variety of Excel features:
+
+- http://spreadsheet.rubyforge.org/
+- http://surpass.ananelson.com/ 
+- https://github.com/randym/axlsx
+
+With any of these, you can create specific .xls views and have them use the
+classes in these gems that let you define a Workbook with multiple Worksheets
+with rows and columns of formatted formulas.
+
+For support higher up the ladder within Rails and/or ActiveRecord, here are a
+few options I've found, though I can't vouch for any. Search rubygems and
+github for 'spreadsheet' 'excel' and 'xls' and you'll find lots of additional
+projects. Most appear to use either the above Spreadsheet gem or generate
+XMLDoc.
+
+- https://github.com/glebm/to_spreadsheet 
+- https://github.com/splendeo/to_xls 
+- https://github.com/asanghi/excel_rails 
+- https://github.com/hallelujah/rails-excel
+- https://github.com/liangwenke/to_xls-rails
+
+###Some of the links in the test Rails apps don't work
+
+They're not all supposed to work. Think of it more as a workshop for example
+code.

data/lib/excelinator.rb

@@ -0,0 +1,12 @@
+require 'excelinator/xls'
+require 'excelinator/rails'
+require 'excelinator/version'
+require 'spreadsheet'
+require 'fastercsv'
+
+if defined?(Rails)
+  Excelinator::Rails.setup
+  class ActionController::Base
+    include Excelinator::Rails::ACMixin
+  end
+end

data/lib/excelinator/rails.rb

@@ -0,0 +1,25 @@
+module Excelinator
+  module Rails
+    def self.setup
+      require 'action_controller'
+
+      Mime::Type.register Excelinator::MIME_TYPE, :xls
+
+      self.add_renderer if ::Rails::VERSION::MAJOR >= 3
+    end
+
+    def self.add_renderer
+      ActionController::Renderers.add :xls do |filename, options|
+        send_xls_data(filename, options)
+      end
+    end
+
+    module ACMixin
+      def send_xls_data(filename, options={})
+        content = render_to_string(options)
+        xls_content = Excelinator.convert_content(content)
+        send_data(xls_content, :filename => filename, :type => Excelinator::MIME_TYPE, :disposition => 'inline')
+      end
+    end
+  end
+end

data/lib/excelinator/version.rb

@@ -0,0 +1,3 @@
+module Excelinator
+  VERSION = '1.0.0'
+end

data/lib/excelinator/xls.rb

@@ -0,0 +1,39 @@
+module Excelinator
+  MIME_TYPE = 'application/vnd.ms-excel'
+
+  # Detects HTML table content (with a rather stupid regex: /<table/) and re-uses it, or attempts to convert from
+  # CSV if HTML not detected.
+  def self.convert_content(content)
+    content =~ /<table/ ? Excelinator.html_as_xls(content) : Excelinator.csv_to_xls(content)
+  end
+
+  def self.csv_to_xls(csv_content)
+    ary = FasterCSV.parse(csv_content)
+    book = Spreadsheet::Workbook.new
+    sheet = book.create_worksheet
+    ary.each_with_index do |row_ary, index|
+      row = sheet.row(index)
+      row.push(*row_ary)
+    end
+    content = ''
+    ios = StringIO.new(content)
+    book.write(ios)
+    content
+  end
+
+  # This only strips a <table> out of the html and adds a meta tag for utf-8 support. Excel will open an .xls file
+  # with this content and grok it correctly (including formatting); however, many alternate spreadsheet applications
+  # will not do this.
+  #
+  # If the html_content is very large, the default behavior of scanning out the table contents will consume a lot
+  # of memory. If the :do_not_strip option is passed, this expensive scan call will be skipped and the entire
+  # contents will be returned.
+  #
+  # If you don't have need of utf-8 encoding, or want to prepend that yourself, there's no need to use this method.
+  def self.html_as_xls(html_content, options={})
+    encoding_meta_tag = '<meta http-equiv="Content-Type" content="text/html; charset=utf-8">'
+    encoding_meta_tag + (options.delete(:do_not_strip) ? html_content : html_content.scan(/<table.*\/table>/mi).to_s)
+  end
+
+  # def self.html_to_xls might be nice to do - convert html table to _real_ xls file
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification 
+name: excelinator
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- chrismo
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-08-03 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: spreadsheet
+  prerelease: false
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 0
+        - 6
+        - 8
+        version: 0.6.8
+  type: :runtime
+  requirement: *id001
+- !ruby/object:Gem::Dependency 
+  name: fastercsv
+  prerelease: false
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  requirement: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  requirement: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  requirement: *id004
+description: convert your csv data and html tables to excel data
+email: 
+- chrismo@clabs.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- lib/excelinator.rb
+- lib/excelinator/rails.rb
+- lib/excelinator/version.rb
+- lib/excelinator/xls.rb
+has_rdoc: true
+homepage: https://github.com/livingsocial/excelinator
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Excel Converter
+test_files: []
+