meta_reports 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 047dacfc577bc3d983838e553a621b90ea01155e
+  data.tar.gz: 1340266ae16c7c7895102590da7d679bf5aee3c1
+SHA512:
+  metadata.gz: db88d50eded3305cae337775669a4ee8c7be2d3fc611d66446916e398e940be3021983db449f4531caacb28fde590da4d795bdaa887ba2d9353f654e43b92ea7
+  data.tar.gz: 814b4bfed9dd99f40e8b053ecdb896555594d45ee14b2c39d8b904c345866ee1d141b0127ea8b9f3c3ff77bf07bcc7a55c278eb1eaa5c57538d40fff740425b5

data/Guardfile

@@ -0,0 +1,15 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2, zeus: false, parallel: false, all_on_start: false, all_after_pass: false do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^spec/support/(.+)\.rb$})                              { "spec" }
+  watch(%r{^app/models/meta_reports/(.+)\.rb$})                   { |m| "spec/models/#{m[1]}_spec.rb" }
+  watch(%r{^app/controllers/meta_reports/(.+)_(controller)\.rb$}) { |m| "spec/#{m[2]}s/#{m[1]}_#{m[2]}_spec.rb" }
+  watch('lib/generators/meta_reports/install_generator.rb')       { "spec/generators/install_spec.rb" }
+  watch('spec/dummy/app/controllers/application_controller.rb')   { "spec/controllers" }
+  # dummy app 
+  watch(%r{^spec/dummy/app/(.+)\.rb$})                            { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/dummy/app/(.*)(\.erb|\.haml)$})                  { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^spec/dummy/app/views/(.+)/.*\.(erb|haml)$})           { |m| "spec/requests/#{m[1]}_spec.rb" }
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+#MetaReports
+**A rails report engine**
+
+##Description
+
+**MetaReports** is a [Rails](https://github.com/rails/rails) engine for reports. It provides a common metadata structure that can be exported in any desired format. If your report fits within the metadata convention you do not even need a template. However, it is very easy to create reports specific templates also.
+
+MetaReports exports to HTML, PDF, and XLSX formats. [More are to come](#todo).
+
+---
+
+##Provides
+
+- An ActiveRecord and other data models, a controller, and some generic views. 
+- Default views for all formats, that expect a title, subtitle, description, and one or more tables of data.
+- Use css classes for easy styling
+
+##Philosophy
+
+MetaReports is avowedly fat model. It is also ActiveRecord based. This could change if a better way makes sense. 
+
+- **Fat model:** All reports are class methods in the MetaReports::Report class. This allows one to generate reports in various contexts without creating an instance (e.g. a mailer.) The reports themselves are meant to be pure data without formatting, except for class names, and html cell content if that is needed. 
+- **ActiveRecord:** Right now a database record is required in addition to the class method. So far this is for convenience in listing available reports and handling permissions. Someday, the code for a report might also be stored in a database, or an abstract description of a report with a web based query builder could be implemented. 
+- **Non ActiveRecord:** A non ActiveRecord implementation and install generator will be implemented. 
+- **That pesky formatting:** The class names / html content may broken out into helpers or a decorator pattern or something else in the future. It is difficult to think of a useful generic way to specify HTML content (e.g. an HTML link within a paragraph of text) outside of the report method itself. A reports controller already breaks strict REST ideology (where does a report belong that combines 5 models?) and unnecessary work for an ideology does not help create a useful tool.
+
+##Usage
+
+###Installation
+
+Add meta_reports your Gemfile:
+
+```ruby
+gem 'meta_reports'
+```
+
+Run the `bundle` command to install it.
+
+Now run the generator:
+
+    rails generate meta_reports:install
+
+This copies over the meta_reports migration, model, views, and controller: 
+
+- `db/migrate/<number>_create_meta_reports_reports.rb`
+- `app/models/meta_reports/report.rb`
+- `app/controllers/meta_reports/reports_controller.rb`
+- `app/views/meta_reports/reports/*`
+
+Run the migration:
+
+    rake db:migrate
+
+Add authentication/authorization to the reports controller if desired.
+
+###Writing a report
+
+- Write the data method using a static method in the `app/models/meta_reports/report.rb` model. The method should accept the params hash as its single argument. It should return the data in the form of a MetaReports::Data object or a hash. 
+- Create a new report record using the reports page. The name must match the data method name.
+- If not using the default templates, write your own templates.
+
+###MetaData
+
+The key component of MetaReports is the metadata format. This allows you to write a data method once and export it to any supported format. If you follow convention, the default templates will work out of the box.
+
+- **Data:** A MetaReports::Data instance, which is a thinly wrapped hash. Returned by each report method. Methods:
+  - **title:** The report title.
+  - **subtitle:** The report subtitle, displayed just below the title.
+  - **description:** A description, usually displayed in paragraph form between the subtitle and tables of data.
+  - **tables:** A hash, where each key is the table title and the value is the data for each table (can be nil).
+  - **template:** Specify a template if you are not using the default template.
+  - **page_orientation:** :landscape or :portrait. Used on PDF and XLSX formats. 
+  - **page_margin:** The page margin in pixels (72/inch), in single number or four value array format (top, right, bottom, left.) Used on PDF and XLSX formats. Specify XLSX header/footer margins by specifying a 5th and 6th value respectively.
+  - **page_size:** The page size. Used on the PDF format. See the [Prawn documentation](http://prawn.majesticseacreature.com/docs/0.11.1/Prawn/Document/PageGeometry.html).
+
+- **Table:** A MetaReports::Table instance, which is a thinly wrapped two dimensional array of cells.
+  - **options:** The options for the whole table. If you are using a plain array, this hash must be the last item in the table.
+    - **column_widths:** Column widths hash, used only on Prawn PDF output. 
+    - **font_size:** Font size for content. Used on PDF and XLSX output.
+    - **row_classes:** A hash with keys specifying row number (0 first), and values being a string of classes. 
+    - **table_header:** Defaults to true. First row in the table is a header row. Causes the row to be repeated on Prawn PDF tables if it breaks to another page.
+
+- **Cell:** A cell is either a single value, or a hash specifying options:
+  - **content:** The default content. 
+  - **html:** Special content for the HTML report. Used to provide links and other markup.
+  - **class:** The class for this content. Used to specify color, alignment, style. For HTML, classes are directly added to the td tags and you are expected to provide appropriate CSS.
+    - **left, center, right:** A class of left/center/right or ending with such values will align the content. It is expected you will provide the HTML styles.
+    - **bold, strong:** A class of bold or strong will make the content bold.
+  - **image:** Specify an image. Only used on PDF output.
+
+###Examples
+
+Here is a simple example. See the [example class](spec/dummy/app/models/meta_reports/report.rb) for more.
+
+```ruby
+  def self.moo(params)
+    MetaReports::Data.new do |d|
+      d.title = 'Le Moo'
+      d.subtitle = 'Ahem'
+      d.tables["The Big Moo"] = MetaReports::Table.new do |t|
+        t << ['Number', 'Title', 'Hey']
+        t << [1, 'Ode to Moo', 'Ow']
+        t << [2, 'Odious Moo', 'Eww']
+        t << [3, "#{params[:moo_type]} Moo", 'No Way!']
+        t << [3, 'Format', {content: "PDF/XLSX", html: "<span>HTML</span>", class: 'attention'}]
+      end
+    end
+  end
+```
+
+###Colors
+
+There is currently an imperfect implementation of shared colors. You will define your colors by name in the MetaReports::Report class in the COLORS hash constant. If a table row contains a corresponding class name it will have that color in HTML, PDF, and XLSX format. Currently it is only applied in the PDF format. HTML is not far away. It is also intended to implement a means of specifying cell background and text color.
+
+```ruby
+COLORS = {
+  even:                   'efefef',
+  odd:                    'ffffff',
+  attention:              'ff9999 !important',
+}
+```
+
+Note that you can specify `!important` and it will be reproduced in the HTML style.
+
+For HTML, necessary styles will either be injected into the HTML output, or a rake task will be created that will generate an appropriate css file to be included in the layout. I have the latter solution working in a test app, but it is not working as a generic rake task.
+
+##TODO
+
+- Common colors: This needs a common color mechanism, where all outputs that support color can have the same row / cell / text color. Any input on this is appreciated.
+- More formats (e.g. csv, json, text)
+- Direct to email / print (using IPP) / fax
+- Improved metadata conventions
+
+##Changelog
+
+- **0.1.0:** (9/29/13) Initial release
+
+##Development
+
+Fork the project on [github](https://github.com/straydogstudio/meta_reports 'straydogstudio / MetaReports on Github'), edit away, and pull.
+
+### Rspec, and generator testing
+
+##Authors, License and Stuff
+
+Code by [Noel Peden](http://straydogstudio.com) and released under [MIT license](http://www.opensource.org/licenses/mit-license.php).

data/Rakefile

@@ -0,0 +1,29 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'MetaReports'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+

data/app/assets/javascripts/meta_reports/reports.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/app/controllers/meta_reports/application_controller.rb

@@ -0,0 +1,4 @@
+module MetaReports
+  class ApplicationController < ::ApplicationController
+  end
+end

data/app/controllers/meta_reports/reports_controller.rb

@@ -0,0 +1,91 @@
+require_dependency "meta_reports/application_controller"
+
+module MetaReports
+  class ReportsController < ApplicationController
+    # remember to add authentication/authorization. E.g:
+      # before_filter :require_user
+      # load_and_authorize_resource
+
+    def index
+      @reports = Report.order("meta_reports_reports.title") || []
+    end
+
+    def show
+      if params[:id].to_s =~ /^\d+$/
+        _report = Report.find(params[:id])
+      elsif Report.respond_to?(params[:id])
+        _report = Report.find_by_name(params[:id])
+      else
+        redirect_to root_url, notice: 'That report does not exist'
+        return
+      end
+      @report = _report.run(params)
+      template = {template: "meta_reports/reports/templates/" + (@report[:template] || "default") }
+
+      respond_to do |format|
+        format.html { render template }
+        format.pdf { render template }
+        format.xlsx { render template }
+      end
+      _report.view
+    end
+
+    def new
+      @report = Report.new
+    end
+
+    def edit
+      @report = Report.find params[:id]
+    end
+
+    def create
+      @report = Report.new(params[:report])
+      if @report.save
+        flash[:notice] = 'Report was successfully created.'
+        redirect_to(edit_report_path(@report))
+      else
+        render action: "new"
+      end
+    end
+
+    def update
+      @report = Report.find params[:id]
+      if @report.update_attributes(params[:meta_report])
+        flash[:notice] = 'Report was successfully updated.'
+        redirect_to(edit_report_path(@report))
+      else
+        format.html { render action: "edit" }
+      end
+    end
+
+    def destroy
+      @report = Report.find params[:id]
+      @report.destroy
+      flash[:notice] = 'Report was successfully deleted.'
+      
+      redirect_to root_url
+    end
+
+    def file
+      dir = params[:dir].to_sym
+      path = Report::FILE_DIRS[dir] + params[:file].gsub(/\/../,'')
+      if File.exists?(path)
+        send_file path, type: "application/pdf", x_sendfile: true, disposition: 'inline'
+      else
+        puts "file doesn't exist: #{path}"
+      end
+    end
+
+    def form
+      if params[:id].to_s =~ /^\d+$/
+        @report = Report.find(params[:id])
+      elsif Report.respond_to?(params[:id])
+        @report = Report.find_by_name(params[:id])
+      else
+        redirect_to reports_url, notice: 'That report does not exist'
+        return
+      end
+      render "meta_reports/reports/forms/form"
+    end
+  end
+end

data/app/helpers/meta_reports/reports_helper.rb

@@ -0,0 +1,140 @@
+module MetaReports
+  module ReportsHelper
+    def convert_margins_to_xlsx(margins)
+      margins = [*margins].compact.map {|val| val/72.0}
+      page_margins = {}
+      unless margins.blank?
+        len = margins.length
+        [:top, :right, :bottom, :left].each_with_index { |dir, i| page_margins[dir] = margins[i%len] }
+        if len == 6
+          page_margins[:header] = margins[5]
+          page_margins[:footer] = margins[6]
+        end
+      end
+      page_margins
+    end
+
+    def html_cell(cell, tag = :td)
+      if cell.is_a? Hash
+        tags = cell.reject {|k,v| k == :content || k == :html}
+        tags[:class] ||= 'textcenter'
+        content_tag tag, (cell[:html] || cell[:content]).to_s.html_safe, tags
+      elsif cell.is_a? Array
+      else
+        content_tag tag, cell, :class => 'textcenter'
+      end
+    end
+
+    def prep_pdf_table(table, styling)
+      if table.is_a?(Array)
+        opts = table.last.is_a?(Hash) && table.pop || {}
+        data = table
+      else
+        data = table.to_a
+        opts = table.options
+      end
+      styling[:column_widths] = opts[:column_widths] if opts[:column_widths]
+      row_classes = opts[:row_classes] || {}
+      row_colors = {}
+      row_classes.each do |i, klass|
+        if color = MetaReports::Report.color(klass, i)
+          row_colors[i] = color
+        end
+      end
+      styling[:row_colors] = row_colors
+      data.each_index do |i|
+        data[i].each_index do |j|
+          if data[i][j].is_a? Hash
+            [:html, :title, :id].each {|sym| data[i][j].delete(sym)}
+            _class = data[i][j].delete(:class)
+            [:right, :left, :center].each do |sym|
+              set_style(styling, sym, i, j) if _class =~ /\b#{sym}\b|[^a-z]#{sym}/i
+            end
+            if _class =~ /\bbold\b|\bstrong\b/
+              set_style(styling, :bold, i, j)
+            end
+            unless data[i][j][:image]
+              data[i][j][:content] = data[i][j][:content].to_s unless data[i][j][:content].is_a? String
+            end
+          end
+        end
+      end
+      data
+    end
+
+    def prep_xlsx_table(table, styling)
+      data = table.to_a
+      data.each_index do |i|
+        data[i].each_index do |j|
+          if data[i][j].nil?
+            data[i][j] = ''
+          elsif data[i][j].is_a? Hash
+            _class = data[i][j][:class]
+            [:right, :left, :center].each do |sym|
+              set_style(styling, sym, i, j) if _class =~ /\b#{sym}\b|[^a-z]#{sym}/i
+            end
+            if _class =~ /\bbold\b|\bstrong\b/
+              set_style(styling, :bold, i, j)
+            end
+            data[i][j] = data[i][j][:content].to_s
+          end
+        end
+      end
+      data
+    end
+
+    def report_link(report, title = report.title)
+      if report.direct
+        content_tag :span do
+          links = []
+          if report.format? :html
+            links << link_to(title, meta_reports.short_show_path(report), target: '_blank')
+          elsif report.format? :pdf
+            links << link_to(title, meta_reports.short_show_path(report, format: :pdf), target: '_blank')
+          elsif report.format? :xlsx
+            links << link_to(title, meta_reports.short_show_path(report, format: :xlsx), target: '_blank')
+          end
+          if report.format? :pdf
+            links << link_to(image_tag('meta_reports/print.png'), meta_reports.short_show_path(report, format: :pdf), target: '_blank')
+          end
+          if report.format? :xlsx
+            links << link_to(image_tag('meta_reports/spreadsheet.png'), meta_reports.short_show_path(report, format: :xlsx), target: '_blank')
+          end
+          links.join(' ').html_safe
+        end
+      else
+        content_tag :span do
+         link_to title, meta_reports.short_form_path(report)
+        end
+      end
+    end
+
+    def report_alt_links(report, params)
+      links = []
+      if report.format? :pdf
+        links << link_to(image_tag('meta_reports/print.png'), params.merge({:format => :pdf}), :target => '_blank')
+      end
+      if report.format? :xlsx
+        links << link_to(image_tag('meta_reports/spreadsheet.png'), params.merge({:format => :xlsx}), :target => '_blank')
+      end
+      links.join(' ').html_safe
+    end
+
+    def set_style(styling, style, row, col)
+      styling[style] ||= []
+      styling[style] << [row,col]
+    end
+
+    def to_xls_col(column)
+      index = column.to_i.abs
+      chars = []
+      while index >= 26 do
+        chars << ((index % 26) + 65).chr
+        index = (index / 26).to_i - 1
+      end
+      chars << (index + 65).chr
+      chars.reverse.join
+    end
+
+  end
+end