tommeier-dynamic_reports 0.0.4

data/HISTORY

@@ -0,0 +1,2 @@
+0.0.0
+  - Initial dynamic reports codebase.

data/README

@@ -0,0 +1,189 @@
+= Dynamic Reports
+
+  A dynamic reporting engine for Ruby / Rails
+
+== Reports
+  
+  The dynamic reports gem was created to fill a HUGE hole that we felt existed in the 
+  Ruby community - the ability to QUICKLY create stylized admin reports and charts for 
+  people to use to view key metrics and data. 
+
+  Sample uses include the ability to quickly display sales data if your an eShop, our 
+  site metrics if you are recording your own site visits, or user feedback if you are storing 
+  feedback in a model somewhere.
+
+  Basically, with DR you can create a stylized table of ANY information found in a model 
+  (kind of like looking at the grid output from a GUI query analyzer) as well as add Google 
+  Charts API powered line, pie, bar or column charts of any numeric data.  All this can 
+  be done by simply creating a report definition and feeding it your data.
+
+  While this library is usable in any Ruby application it was made mainly with Rails in mind.
+  Suppose we have an online store and we wish to add reporting to the admin area quickly and easily.
+  First we define a report in app/reports/orders_report.rb, something like:
+  
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      sub_title "All orders recorded in database"
+      columns :total, :created_at
+    end
+  
+  Then in our admin/reports controller (this can be any controller) we define an action to deliver the report:
+  
+    def orders
+      @orders = Order.find(:all, :limit => 25)
+      render :text => OrdersReport.on(@orders).to_html, :layout => "application"
+    end
+    
+  This will render an html table containing some basic styling and containing the columns 'total' and 'created_at' from the order objects.
+  Note that the report Title will be "Orders Report" and it's name will be :orders_report
+  Report#on expects that it receives an object that responds to #each and
+  That each object that it iterates over is either a
+    * An object
+    * A Hash
+  that responds to a method / has keys for each column defined within the report.
+ 
+
+  Templating engines may also be specified, currently :erb and :haml are supported (we will soon be adding :csv and :pdf) like so:
+
+      render :text => OrdersReport.on(@orders).to_html(:engine => :haml), :layout => "application"
+
+  Note that erb is the default templating engine since it is available by default in Ruby.
+
+  Now let us extend our report definition to specify a template to use!
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      sub_title "All orders recorded in database"
+      columns :total, :created_at
+
+      template :my_custom_template
+    end
+
+  This will look in app/views/reports/ for a template named "my_custom_template.html.erb" by default.
+  If you specify :engine => :haml then it will look for "my_custom_template.html.haml"
+
+  If you happen to have your report templates in a different location you can specify this as follows:
+
+    class OrdersReport < DynamicReports::Report
+       title "Orders Report"
+      sub_title "All orders recorded in database"
+      columns :total, :created_at
+
+      template :my_custom_template
+      views "app/views/admin/reports/"
+    end
+  
+  And DynamicReports will look for the specified template in app/views/reports as well as app/views/admin/reports.
+
+  It is also worth pointing out that you can have as many dynamic reports in a view as you wish, simply include
+  each report render where desired within the view.
+
+== Charts
+  
+  Charts can be defined on a report easily. Let's say we wish to chart the total versus the item quantity sold for our Orders Report exmaple:
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      sub_title "All orders recorded in database"
+      columns :total, :created_at
+
+      chart :total_vs_quantity do
+        columns :total, :quantity
+        label_column "created_at"
+      end
+    end
+
+  This will render a *line* chart by default displaying the columns total and quantity.
+  Chart types may be specified easily:
+  
+        type :bar
+  
+  Available chart types are:
+
+    * :line (default)
+    * :bar
+    * :pie
+
+  Since DynamicReport's charts utilize the Google Chart API, you can easily extend each chart by passing a hash of chart options as part
+  of the block.  The options are appended onto the request to the API so they should follow the Google's API commands (http://code.google.com/apis/chart/)
+
+  For example, to add min, max and average labels to the example chart, you would do something like this:
+
+    chart :total_vs_quantity, {:chxt => "r", :chxl => "0:|min|average|max"} do
+        columns :total, :quantity
+        label_column "created_at"
+    end
+
+== Stylizing
+
+  The reports are, by default, stylized with an inline style sheet.  The styles produce a nicely formatted grid with
+  a white on black header row and black on white columns with a gray border througout.
+
+  You can create your own styles by simply adding a class_name object to the report definition as such:
+
+    class OrdersReport < DynamicReports::Report
+      title "Orders Report"
+      sub_title "All orders recorded in database"
+      columns :total, :created_at
+
+      class_name "my_class_name"
+    end
+
+  This will cause DR to simply not include the inline style.  From there you can customer the styles using the
+  following sub-classes for your class name, for example:
+
+    .my_class_name .report_title {}
+    .my_class_name .report_subtitle {}
+    .my_class_name table tr th {}
+    .my_class_name table tr td {}
+    .my_class_name .report_charts {}        // all charts are displayed within this div
+    .my_class_name .report_chart {}         // represents an individual chart
+
+== Rails Usage
+  
+  Inside the initializer block in config/environment.rb 
+
+    config.gem "dynamic_reports"
+
+  Then define your reports (as exampled above) in app/reports/*_report.rb
+  If you would like to customize the default report simply create your report templates 
+  within app/views/reports/*_report.<content-type>.<engine>.
+
+  Two Rails features that we are currently working on are:
+
+    * generator
+    * render extensions
+
+== Optional Dependencies
+
+  We are currently examining solutions for csv, pdf and charting.
+
+    * Fastercsv     # csv
+    * Prawn         # pdf
+    * flying saucer # html => PDF - if jRuby available
+    * amcharts      # Charting, note that default is built in google charts.
+
+  These will be defined/implemented using DynamicReports plugin API (not implemented yet)
+  Which allows for user defined plugins of arbitrary types beyond html,csv,pdf,xml
+
+== Contact / Feedback
+
+  If you have any suggestions on improvement please send us an email.
+
+== Authors (alphabetically)
+
+  Joshua Lippiner (jlippiner@gmail.com)
+
+  Wayne E. Seguin (wayneeseguin@gmail.com, irc: wayneeseguin)
+
+== Thanks To
+
+  * Daniel Neighman
+  * Kenneth Kalmer (And his friend :))
+  * Yehuda Katz
+
+  For their encouragement, feedback and advise.
+
+== Source
+  http://github.com/wayneeseguin/dynamic_reports
+

data/gemspec.rb

@@ -0,0 +1,25 @@
+require "rubygems"
+
+library="dynamic_reports"
+version="0.0.2"
+
+Gem::Specification::new do |spec|
+  $VERBOSE             = nil
+  spec.name            = library
+  spec.summary         = library
+  spec.version         = version
+  spec.description     = "Dynamic Ruby Reporting Engine with support for Charts"
+  spec.platform        = Gem::Platform::RUBY
+  spec.files           = ["HISTORY", "README", "gemspec.rb", Dir::glob("lib/**/**")].flatten
+  spec.executables     = Dir::glob("bin/*").map{ |script| File::basename script }
+  spec.require_path    = "lib"
+  spec.has_rdoc        = File::exist?("doc")
+  spec.author          = "Wayne E. Seguin & Joshua Lippiner"
+  spec.email           = "wayneeseguin@gmail.com, jlippiner@gmail.com"
+  spec.homepage        = "http://github.com/wayneeseguin/direct_reports"
+  # spec.test_suite_file = "test/#{library}.rb" if File::directory?("test")
+  #spec.add_dependency  "", ">= 0.0"
+  spec.extensions      << "extconf.rb" if File::exists?("extconf.rb")
+  spec.rubyforge_project = library
+end
+        

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification 
+name: tommeier-dynamic_reports
+version: !ruby/object:Gem::Version 
+  version: 0.0.4
+platform: ruby
+authors: 
+- Wayne E.Seguin
+- Joshua Lippiner
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-28 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Dynamic Ruby Reporting Engine with support for Charts
+email: wayneeseguin@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- HISTORY
+- README
+- gemspec.rb
+has_rdoc: true
+homepage: http://github.com/wayneeseguin/direct_reports
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: dynamic_reports
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Dynamic Ruby Reporting Engine with support for Charts
+test_files: []
+