report_logic 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5e25770ff6e1144dbbdba31d2cd5ce7c18b754fc
-  data.tar.gz: 01b93068112f0428369d7bf05f7c595cfc483e71
+  metadata.gz: 6cea2b2274f2df932ea10af17de0b1a67a784132
+  data.tar.gz: c42344ccba2cc912cb674f51fbea93d1ca4d0ad1
 SHA512:
-  metadata.gz: e7cc1c97d098b1595c8799f45c1d69954976b6628655c9868e30eff3038c1ba33a9680b41ba919a71c50256e0c49b455ec9dc2391214b3d507589b5476ff5ed4
-  data.tar.gz: fff161688583ee20d397030165b647b15e3b419ee196d81892e311b717fb0b38b264975a05f645394053bf0e190ac784ed2898734d04140e54b981838b4f4c5a
+  metadata.gz: 51970b4691bf3dd8c0b156829ea95c926bd1d4f565e74647b1a85b7f9de513be51ddb7b2b23454ec40361fe502b938440b99bc94e67ec14d4908a2909ebfa81b
+  data.tar.gz: d32eb19919641f367dbf782212597645f32b4c16bc1b26d719e868ca0c7b3c519a81fe0974adb5af8574acbf742d49d6f0f08920627b17fe3052d3faae3fca61

data/README.md

@@ -9,12 +9,170 @@ Using this, you can so export this report to any format you want.
 gem install report_logic
 ```
 
-Using bundler:
+Using Bundler:
 
 ```ruby
-gem 'report_logic'
+gem 'report_logic', '~> 0.0.2'
 ```
 
 ## Usage
 
-Building...
+The goal here is to provide an easy way to extract report's logic to a Plain Old
+Ruby Object. With this extraction, it's easy to use the same report class to
+render reports in different formats. The report is defined by doing this:
+
+```ruby
+# Create a class inheriting from ReportLogic::Base
+class MyReport < ReportLogic::Base
+
+  # Override this method to define your report
+  def build
+    # Create as many sessions as you need. Sessions group fields that you can
+    # then display later.
+    session(:header) do
+      field 'ID'    # `field` creates a ReportLogic::Field in the session,
+                    # which `name` will be the value passed to it.
+      field 'Name'
+    end
+
+    # If you pass a collection to a session, it will become a matrix, instead of
+    # an array of Field. For each object in the collection, the block will be
+    # yielded with it so you can define what Fields will compose this matrix.
+    session(:row, collection) do |record|
+      value record.id     # `value` creates a ReportLogic::Field in the session,
+                          # which `value` will be the value passed to it.
+      value record.name
+    end
+  end
+end
+```
+
+And that's the basics. Now, to show this report:
+
+```ruby
+report = MyReport.new(MyModel.all)
+
+# Printing a title
+puts 'MY REPORT'
+
+# Printing the headers
+report.each(:header) do |field|
+  print field.name
+  print ' | '
+end
+puts
+
+# Printing the rows
+report.each(:row) do |row|
+  row.each do |field|
+    print field.value
+    print ' | '
+  end
+end
+puts
+```
+
+This output sucks, but it shows how simple it is to read a report
+and output it in any ways you want. You could use ERB to generate HTML or XLS
+outputs in Rails, or even Prawn to generate PDF's.
+
+## Decorators
+
+This gem uses the Decorator pattern to allow you to modify a Field before
+printing. To do so, you just need to inherit from `ReportLogic::Decorator`,
+like so:
+
+```ruby
+class MyDecorator < ReportLogic::Decorator
+  # This method is invoked when the report is built. Override this if you
+  # want to customize the whole behaviour of your decorator.
+  def decorate(field)
+    decorate_name(field)
+    decorate_value(field)
+  end
+
+  # This method is called by default from ReportLogic::Decorator, as
+  # you can see above. Override this if you just want to decorate the name
+  # attribute of your fields.
+  def decorate_name(field); end
+
+  # This method is called by default from ReportLogic::Decorator as well.
+  # Override this if you just want to decorate the value attribute of your fields.
+  def decorate_value(field); end
+end
+```
+
+This sample decorator is, in fact, pretty much the same as
+`ReportLogic::Decorator`. For more details, take a look at the class itself.
+
+You can then apply a decorator in many ways:
+
+```ruby
+class MyReport < ReportLogic::Base
+  def build
+    session(:row, collection) do |record|
+      field 'Name', record.name
+      field 'Gender', record.gender
+
+      decorate_with MyDecorator.new    # This decorator applies to this session
+    end
+
+    decorate_with AnotherDecorator.new # This decorator applies to the whole report
+  end
+end
+```
+
+You can apply a decorator to a specific field. To do so, you need to:
+
+```ruby
+field 'Name', record.name, decorate_with: SpecifiDecorator.new
+```
+
+## I18n Support
+
+There is a built-in decorator that handles internationalization for you. To use
+it, you need to do this:
+
+```ruby
+class MyReport < ReportLogic::Base
+  include ReportLogic::I18nSupport  # Include de module
+
+  def build
+    i18n_decorate                   # Invoke the decorator to be added
+
+    session(:row, collection) do |record|
+      field 'Name', record.name
+      field 'Gender', record.gender
+    end
+  end
+end
+```
+
+This way, your fields' names and values will be translated **if they are symbols**.
+So, to make it work, you need to use symbols:
+
+```ruby
+class MyReport < ReportLogic::Base
+  include ReportLogic::I18nSupport
+
+  def build
+    i18n_decorate
+
+    session(:filter) do
+      field :name  , 'Test'   # The field's name will be translated using
+                              # 'report.names.name'
+      field :gender, :male    # The field's name will be translated using
+                              # 'report.names.gender' and the value will use
+                              # 'report.values.male'.
+    end
+  end
+end
+```
+
+## Contributing
+
+Do you have an idea or a bug fix to add to the gem? Please do!
+
+1. Fork it
+2. Make your changes and commits
+3. Create a pull request

data/lib/report_logic/base.rb

@@ -17,6 +17,8 @@ module ReportLogic
     def session(key, collection = nil, &block)
       @current_session = sessions[key] ||= Session.new(key, self)
       @current_session.process(collection, &block)
+    ensure
+      @current_session = nil
     end
 
     def count
@@ -31,6 +33,14 @@ module ReportLogic
       end
     end
 
+    def decorate_with(*args)
+      if @current_session
+        @current_session.decorate_with(*args)
+      else
+        super
+      end
+    end
+
     protected
 
     def ensure_built_and_decorated

data/report_logic.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name        = 'report_logic'
-  s.version     = '0.0.1'
-  s.date        = '2014-09-17'
+  s.version     = '0.0.2'
+  s.date        = '2014-09-18'
   s.summary     = "Generating report logic."
   s.description = "This gem provides an easy way to generate reports' logic. "\
     "Using this, you can so export this report to any format you want."

data/spec/app/my_report.rb

@@ -15,6 +15,17 @@ class MyReport < ReportLogic::Base
     session(:test_context) do
       context_value
     end
+
+    session(:test_master_decorator) do
+      field :decorable, 2
+    end
+
+    session(:exclusive_decorator) do
+      value 2
+      decorate_with MyDecorator.new
+    end
+
+    decorate_with MyDecorator.new(key: :decorable)
   end
 
   def context_value

data/spec/report_logic/base_spec.rb

@@ -29,4 +29,12 @@ describe ReportLogic::Base do
   it "counts records" do
     expect(report.count).to eq 2
   end
+
+  it "scopes decorators" do
+    s1 = report.each(:test_master_decorator).to_a
+    s2 = report.each(:exclusive_decorator  ).to_a
+
+    expect(s1.first.value).to eq(3)
+    expect(s2.first.value).to eq(3)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: report_logic
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Diego Aguir Selzlein
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-17 00:00:00.000000000 Z
+date: 2014-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n