simple_report 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 436d5fd858c04f340ae023105f2abba6c52ad104
-  data.tar.gz: 5536e591f8409ea6b6c0e5f0cdb7fce622a516b0
+  metadata.gz: 97d5239a25275c2f4380d2e07e8d0b798c80a310
+  data.tar.gz: 168a60a39f728b261848f5d484dbade74e95d7ec
 SHA512:
-  metadata.gz: 87ed4a06fc85e3f127fad034d15a7e781d96acdf0ae0dec0f00c183744a28e8e8c092e73541010ae8e30cb2215ed9bcf064118c86ee54ba9445b8e87a5f5f0e8
-  data.tar.gz: b8fe72f28ac92cde9219c21dd73ac83e12ce4e78ee596563000f11cbc6956b1b8cf6367ad5bfd8bd9678f829147ee9230ecf6d74fca8bc1c5dbb50d1010acdd1
+  metadata.gz: 1a20a9eb8e08b6e83afc40fddfb612138707c05983d90672c1e4302d471303a1e6072622c54e18dd46af6ad13461eaa3aaa147b561318e616f229c51c7048fa7
+  data.tar.gz: a41ba2c8674e4dd8eb3b2919d41ed4c031d20f334c3ac3e2883bb944773cccd70f9fd03f0603ffdf61ee92a26b3c18deb4b685101e39d1bf1622d6e0df16d251

data/.drone.yml

@@ -0,0 +1,7 @@
+pipeline:
+  build:
+    image: ruby:2.4
+    pull: true
+    commands:
+      - bundle install
+      - bundle exec rake test

data/.ruby-version

@@ -0,0 +1 @@
+2.4.2

data/Jenkinsfile

@@ -0,0 +1,18 @@
+node {
+  withEnv([
+    "PATH=$HOME/.rbenv/bin:$HOME/.rbenv/shims:$PATH",
+    "RBENV_SHELL=sh"
+   ]) {
+
+     stage('Preparation') { // for display purposes
+       // Get some code from a GitHub repository
+       git 'https://github.com/lostapathy/simple_report.git'
+     }
+     stage('Build') {
+       sh "bundle install"
+     }
+     stage('test') {
+       sh "bundle exec rake test"
+    }
+  }
+}

data/README.md

@@ -5,7 +5,9 @@
 [![Test Coverage](https://codeclimate.com/github/lostapathy/simple_report/badges/coverage.svg)](https://codeclimate.com/github/lostapathy/simple_report/coverage)
 
 
-simple_report is a gem for building simple reports from Enumerable collections.  It was extracted from a larger application and only supports Excel exports for now, but other formats could be added.
+simple_report is a gem for building simple reports from Enumerable collections.  It was extracted from a larger application and only supports Excel exports for now, but we plan to add support for HTML reports as well (see TODO below).  Other formats could be added if requested.
+
+simple_report is meant to provide a simple way to get a collection of data out of your application and out to the user in a reasonable report, and do so without any hassle.  It's not intended to collect, analyze, or transform data for you.
 
 ## Installation
 
@@ -25,7 +27,135 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Like a typical spreadsheet, each report may have multiple Sheets.  Each sheet has multiple fields/columns.  The data sources passed in can be any Enumerable collection, whether that's a simple Array or an ActiveRecord query does not matter.
+
+Let's build our first report:
+
+```ruby
+class CustomerReport < SimpleReport::Base
+  def build_report
+    data = Customer.all
+
+    add_sheet('Customers', data) do |sheet|
+      sheet.add_field('Username', :username)
+      sheet.add_field('Full Name', width: 30) { |x| x.first_name + " " x.last_name }
+      sheet.add_field('Billing Rate', :billing_rate, format: :money)
+      sheet.add_field('SLA %', :sla, format: :percent)
+      sheet.add_field('Placeholder', value: 'TBD')
+    end
+  end
+end
+
+report = CustomerReport.new
+File.write('report.xlsx', report.to_xlsx)
+```
+
+This is pretty straightforward, and covers the entire API.  We'll go over it in detail below.
+
+
+```ruby
+class CustomerReport < SimpleReport::Base
+  def build_report
+```
+Each report must subclass ```SimpleReport::Base``` and define the report in the build_report method.  For this example, we're report on an an ActiveRecord collection of all ```Customer```ruby records.
+
+```ruby
+    data = Customer.all
+```
+Our report data will be all the ```Customer``` objects returned by ActiveRecord
+
+```ruby
+    add_sheet('Customers', data) do |sheet|
+```
+We want to add a Sheet to our report.  It'll be labeled 'Customers', and include one row for every element in ```data```.  To include multiple Sheets in your report, simple add additional add_sheet blocks.
+
+
+```ruby
+      sheet.add_field('Username', :username)
+```
+Adds a column labeled Username to the report, and populates it by invoking the :username method on each record in the data collection.
+
+
+```ruby
+      sheet.add_field('Full Name', width: 30) { |x| x.first_name + " " x.last_name }
+```
+Adds a column labeled 'Full Name' to the report, and populates it by calling the provided block on each record.  In this case, it's concatenating the user's name together.  We're also setting a field width of 30.
+
+
+```ruby
+      sheet.add_field('Billing Rate', :billing_rate, format: :money)
+```
+Add a column named 'Billing Rate', populate it by invoking :billing_rate on each record, and format the results as money.
+
+
+```ruby
+      sheet.add_field('SLA %', :sla, format: :percent)
+```
+Add a column named 'SLA %', populate it by invoking :sla on each record, and format the results as a percentage.
+
+```ruby
+      sheet.add_field('Placeholder', value: 'TBD')
+```
+Add a column 'Plaeholder' and populate it with the supplied value. This seemingly useless capability is surprisingly useful when you have to match a report full of boilerplate.
+
+```ruby
+report = CustomerReport.new
+File.write('report.xlsx', report.to_xlsx)
+```
+Instantiate the report, then write it to file.
+
+## Advanced Usage
+
+Your report object and build_report method are just plain ruby code, so you can add logic to how your reports are generated.  For example:
+
+```ruby
+class FancyReport < SimpleReport::Base
+  attr_accessor :include_wholesale
+
+  def initialize
+    @include_wholesale = true
+  end
+
+  def build_report
+    data = Product.all
+    add_sheet('Products', data) do |sheet|
+      sheet.add_field('Name', :name)
+      sheet.add_field('MSRP', :msrp, format: :money)
+      sheet.add_field('Wholesale', :wholesale, format: :money) if @include_wholesale
+    end
+  end
+end
+
+report = FancyReport.new
+report.include_wholesale = false
+File.write('my_report.xlsx, report.to_xlsx)
+```
+
+You can also add attributes to the report to pass data into the report, rather than compute the data in the report as our simple examples have thus far:
+```ruby
+class AnotherReport < SimpleReport::Base
+  attr_accessor :data
+
+  def build_report
+    add_sheet 'Something', @data do |sheet|
+      // define some fields
+    end
+  end
+end
+
+report = AnotherReport.new
+report.data = Customer.all
+File.write('another_report.xlsx', report.to_xlsx)
+
+```
+
+
+
+
+## TODO
+
+* Add to_html method to render out as a simple table-based HTML report.  We'll generate a table, with thead/tbody/tfoot, apply css classes based on formats, and apply basic text formatting such as number_to_currency or percent (%) characters.  That will give the end-user enough flexibility to do whatever they want with the output, while still keeping the gem extremely simple
+* Add some concept of a footer/summary to the reports that allows operations like sum, average, minimum, maximum.  When exported to xlsx, these will be exported as formulas.  Actual values should be computed for HTML reports.
 
 ## Development
 

data/lib/simple_report/base.rb

@@ -33,16 +33,16 @@ module SimpleReport
           output_sheet.set_column(index, index, f.width)
           output_sheet.write(0, index, f.name, @formats[:heading])
         end
-        sheet.collection.each_with_index do |ic, row|
+        sheet.collection.each_with_index do |ic, record_num|
           sheet.fields.each_with_index do |field, column|
             if field.field
               value = ic.send(field.field)
             elsif field.value
               value = field.value
             elsif field.block
-              value = field.block.call(ic)
+              value = field.block.call(ic, record_num + 2)
             end
-            output_sheet.write(row + 1, column, value, find_format(field.format))
+            output_sheet.write(record_num + 1, column, value, find_format(field.format))
           end
         end
       end
@@ -62,7 +62,7 @@ module SimpleReport
       add_format :heading, heading
 
       percent = @workbook.add_format
-      percent.set_num_format('0%')
+      percent.set_num_format('0.0%')
       add_format :percent, percent
     end
 

data/lib/simple_report/version.rb

@@ -1,3 +1,3 @@
 module SimpleReport
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_report
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Joe Francis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-18 00:00:00.000000000 Z
+date: 2017-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -74,9 +74,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".drone.yml"
 - ".gitignore"
+- ".ruby-version"
 - ".travis.yml"
 - Gemfile
+- Jenkinsfile
 - LICENSE.txt
 - README.md
 - Rakefile