riveter 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9bfaea301720bade36e0378d57aadda384fa61a1
-  data.tar.gz: 19f28abaef62981f1a906b384b824a1adabd5848
+  metadata.gz: 9ebc95b71c75212a93969b10807e5ed3e1d1748c
+  data.tar.gz: fa04871bf94a6a4a3fabd6144f161da7662ac802
 SHA512:
-  metadata.gz: e1c175fbea035404cb7196f5f5a7688ab6bc542d351e8218ac78fe35dd240258f351c0d84055d8e1b8bd7bb28c830b67ecccefe962b54de123d102beee6a5dc5
-  data.tar.gz: 9fe76bfa914ad8d3c86ab89beb1220b3935d1a932a14c463ec3d28f1da081d74612b987bb4e646f24b05f2a4a56e614790eab35743f8983cd5345c790537a514
+  metadata.gz: 654cb072df071d5b1ce69f10b85047750d514ee2d104245aae1ce0fc151ba7b2ef77110b226d9c811acd8f1f7073c2c149d3c1af430e30759a722562baa30183
+  data.tar.gz: 94a50c282014f605438bed1304124041ae735db5bd494e5d586380588673a6b2291a0b70d9df98e65affb173e11c7a6b3d23915604d43b25f664227c1b70f874

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    riveter (0.0.6)
-      actionpack
-      activemodel
-      activerecord
-      activesupport
+    riveter (0.0.7)
+      actionpack (~> 4.0.0)
+      activemodel (~> 4.0.0)
+      activerecord (~> 4.0.0)
+      activesupport (~> 4.0.0)
       railties (~> 4.0.0)
-      validates_timeliness
+      validates_timeliness (~> 3.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -55,7 +55,7 @@ GEM
       thor
     debugger-linecache (1.2.0)
     diff-lcs (1.2.5)
-    docile (1.1.4)
+    docile (1.1.5)
     erubis (2.7.0)
     haml (4.0.5)
       tilt
@@ -72,8 +72,8 @@ GEM
     method_source (0.8.2)
     mime-types (1.25.1)
     minitest (4.7.5)
-    multi_json (1.10.0)
-    polyglot (0.3.4)
+    multi_json (1.10.1)
+    polyglot (0.3.5)
     pry (0.9.12.6)
       coderay (~> 1.0)
       method_source (~> 0.8)
@@ -97,7 +97,7 @@ GEM
       activesupport (= 4.0.5)
       rake (>= 0.8.7)
       thor (>= 0.18.1, < 2.0)
-    rake (10.3.1)
+    rake (10.3.2)
     rest-client (1.6.7)
       mime-types (>= 1.16)
     rspec-core (2.14.8)
@@ -120,7 +120,7 @@ GEM
       simplecov-html (~> 0.8.0)
     simplecov-html (0.8.0)
     slop (3.5.0)
-    sprockets (2.11.0)
+    sprockets (2.12.1)
       hike (~> 1.2)
       multi_json (~> 1.0)
       rack (~> 1.0)
@@ -132,7 +132,7 @@ GEM
     term-ansicolor (1.3.0)
       tins (~> 1.0)
     thor (0.19.1)
-    thread_safe (0.3.3)
+    thread_safe (0.3.4)
     tilt (1.4.1)
     timeliness (0.3.7)
     tins (1.3.0)
@@ -147,14 +147,14 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  ammeter
-  bundler (~> 1.5)
-  coveralls
-  haml-rails
-  pry
-  pry-byebug
-  rails (~> 4.0.5)
-  rake
+  ammeter (~> 1.0.0)
+  bundler (~> 1.6.0)
+  coveralls (~> 0.7.0)
+  haml-rails (~> 0.5.0)
+  pry (~> 0.9.0)
+  pry-byebug (~> 1.3.0)
+  rails (~> 4.0.0)
+  rake (~> 10.3.0)
   riveter!
-  rspec-rails
+  rspec-rails (~> 2.14.0)
   shoulda-matchers (~> 2.6.1)

data/README.md

@@ -6,19 +6,238 @@
 [![Coverage Status](https://coveralls.io/repos/virtualstaticvoid/riveter/badge.png)](https://coveralls.io/r/virtualstaticvoid/riveter)
 [![Dependency Status](https://gemnasium.com/virtualstaticvoid/riveter.svg)](https://gemnasium.com/virtualstaticvoid/riveter)
 
-Provides several useful patterns, packaged in a gem, for use in Rails.
-Includes generators to help you improve consistency in your applications.
-
-* Enumerated
-* Query
-* QueryFilter
-* Enquiry
-* EnquiryController
-* Command
-* CommandController
-* Service
-* Presenter
-* Worker
+Provides several useful patterns, packaged in a gem, for use in Rails and other web based applications, including generators to help improve
+consistency in your applications.
+
+## Motivation
+In an effort to refactor large Rails applications, a number of patterns emerged, which this gem seeks to formalize. Encapsulating
+each pattern helps provide consistency and promotes standardization of implementation in a team of developers. Also, having generators
+to create all the necessary classes and specs helps developers follow the standards more easily and prevents unnecessary coding and
+ensures the focus remains on the business problem being solved instead.
+
+Some of these patterns have been discussed at length within the Ruby and Rails communities, with many people making cases for
+and against some of these patterns. The important thing to bear in mind is that there is no "one" solution for everything, nor
+"one" way to solve a problem, so these patterns will _not_ always be applicable. Please use them where it makes sense to do so, and
+the solution to the problem you are trying to solve becomes clearer by doing so.
+
+## Patterns Included
+The following patterns are included, and an explaination of each follows:
+
+### Enumerated
+Rails 4+ now has support for enumerated attributes on models, however the `Riverter::Enumerated` module is a slightly different take on
+the idea but can still be used on conjunction with the default functionality.
+
+You define an enumerated type by creating a module, adding the desired members as constants and then include the `Riveter::Enumerated` module.
+
+E.g. Module containing enumeration members:
+```ruby
+module FooStatusEnum
+  Bar = 1
+  Baz = 2
+
+  include Riveter::Enumerated
+end
+```
+
+The `FooStatusEnum` module will now have the following methods exposed:
+
+* `::All` - a constant which behaves like an `Array` for enumerating the members. E.g. `FooBarStatusEnum::All #=> [FooBarStatusEnum::Member1, FooBarStatusEnum::Member2]`
+* `human` - if a locale file is provided, gives the human name for the enumeration. E.g. `FooStatusEnum.human #=> "Foo Status"`
+* `names` - lists all the member names. E.g. `FooStatusEnum.names #=> [Bar, Baz]`
+* `values` - lists all the member values. E.g. `FooStatusEnum.values #=> [1, 2]`
+* `collection` - provides a collection of the members for use in form inputs.
+
+And when enumerating over the members using `FooStatusEnum::All`, each member will have the following methods:
+
+* `name` - the member name
+* `human` - if a locale file is provided, gives the human name for the member
+* `value` - the member value
+
+### QueryFilter
+A common requirement in a Rails application is to collect criteria from the user and then prepairing a query using those criteria
+within the `where` clauses. The query filter pattern encapsulates the criteria attributes so that they can be converted from params
+and validated prior to building up the query.
+
+Create a class which inherits from `Riveter::QueryFilter::Base` and then define the attributes, their default values and validations as needed.
+
+E.g. Query filter example class
+```ruby
+class FooQueryFilter < Riveter::QueryFilter::Base
+  attr_string :bar_like, :required => true
+  attr_boolean :baz, :default => true
+  attr_date :qux, :default => { Time.now }
+end
+```
+
+There are a number of `attr_*` methods as follows:
+
+  * `attr_string`
+  * `attr_integer`
+  * `attr_decimal`
+  * `attr_date`
+  * `attr_date_range`
+  * `attr_time`
+  * `attr_boolean`
+  * `attr_enum`
+  * `attr_array`
+  * `attr_hash`
+  * `attr_model`
+  * `attr_object`
+
+In your controller, create an instance of the query filter as if it were a model. It can be used within your views easily as there is
+a view helper method, `query_filter_form_for`, which makes it easy to build HTML forms for the specified attributes.
+If you have `simple_form` installed, it will behave like a `simple_form_for`, otherwise the standard Rails `form_for` is used.
+
+E.g. Controller example
+```ruby
+class FooController < ApplicationController
+
+  def new_search
+    @query_filter = FooQueryFilter.new()
+  end
+
+  def search
+    @query_filter = FooQueryFilter.new(foo_query_filter_params)
+    respond_to do |format|
+      if @query_filter.valid?
+        # E.g. your query logic here
+        @list = BarModel.where(:bar => @query_filter.bar_like)
+                        .where(:baz => @query_filter.baz)
+                        .where(:qux => @query_filter.qux)
+        format.html
+      else
+        format.html {render :action => :new_search}
+      end
+    end
+  end
+
+private
+  def foo_query_filter_params
+    params.require(:foo_query_filter).permit(:bar_like, :baz, :qux)
+  end
+end
+```
+
+### Query
+Given that the query filter is encapsulated, it follows that the query, which is built using the query filter, should be encapsulated too.
+Also, considering the controller example code above, it would be better to encapsulate the building of the query into it's own class, instead
+of coding it in the controller, especially if the criteria is applied conditionally to the query.
+
+By abstracting the query filter and query as separate classes, it is easier to test each component individually, and there are greater
+possibility for reuse of either class in other scenarios.
+
+Create a class which inherits from `Riveter::Query::Base` class and implement the `build_relation` method to define the query.
+
+E.g. The query class
+```ruby
+class FooQuery < Riveter::Query::Base
+  def build_relation(filter)
+    query = FooModel.all
+
+    # apply criteria to the query conditionally...
+    if filter.bar_like.present?
+      query = query.where(:bar => filter.bar_like)
+    end
+
+    ...
+
+    query
+  end
+end
+```
+
+The `FooQuery` with now have the following methods, which help in rendering the results in your views:
+
+* `has_data?` - given the relation provided, yields true to indicate whether there is result data
+* `relation` - the built relation
+* `find_each` - this method is used to enumerate over the result data in the most efficient way
+
+### Enquiry
+Since the query filter and query encapsulate filtering and querying, and as they are defined individually, it follows that
+there should be a way to bring them together, and thus make them easier to work with in controllers and views.
+
+An enquiry is defined by specifying the query filter and query to use. Provide a class which inherits from `Riveter::Enquiry::Base` and
+specify which query filter and query to use with the `filter_with` and `query_with` methods respectively.
+
+E.g. A simple enquiry class
+```ruby
+class FooEnquiry < Riveter::Enquiry::Base
+  filter_with FooQueryFilter
+  query_with FooQuery
+end
+```
+
+In your controller, create an instance of the enquiry as if it were a model. It can be used within your views as there is
+a view helper method, `enquiry_form_for`, which makes it easy to build HTML forms for the specified attributes of the query filter.
+If you have `simple_form` installed, it will behave like a `simple_form_for`, otherwise the standard Rails `form_for` is used.
+
+Then on submission of the form, call the `submit` method passing in the form parameters, and then enumerate over the resultant data
+using the `find_each` method.
+
+E.g. An example enquiry controller
+```ruby
+class FooEnquiryController < ApplicationController
+  def index
+    @enquiry = FooEnquiry.new()
+    respond_to do |format|
+      unless @enquiry.submit(enquiry_params)
+        flash[:notice] = 'Invalid enquiry criteria, please correct and try again.'
+      end
+      format.html
+    end
+  end
+
+private
+  def enquiry_params
+    params
+      .require(:foo_enquiry)
+      .permit(:bar_like, :baz, :qux)
+      .merge(:page => params.fetch(:page, 1))
+  end
+end
+```
+
+And the corresponding view, in HAML using `simple_form_for` to build the criteria inputs and Kaminari for pagination:
+```haml
+.criteria
+  = enquiry_form_for(@enquiry) do |f|
+    = f.input :bar_like
+    = f.input :baz
+    = f.input :qux
+
+.results
+  %table
+    %tr
+      %th Foo
+      %th Bar
+      %th Baz
+    - unless @enquiry.has_data?
+      %tr
+        %td(colspan=3)
+          No data found for enquiry...
+    - else
+      - @enquiry.find_each do |result|
+        %tr
+          %td= result.bar
+          %td= result.bax
+          %td= result.qux
+  = paginate_enquiry(@enquiry)
+```
+
+### EnquiryController
+_TDB_
+
+### Command
+_TDB_
+
+### CommandController
+_TDB_
+
+### Service
+_TDB_
+
+### Presenter
+_TDB_
 
 ## Installation
 
@@ -44,9 +263,7 @@ To get the list of available generators, execute:
 
 The generator names are prefixed with `riveter`.
 
-E.g.
-
-To generate an enquiry controller, query filter, query, views and associated specs, execute:
+E.g. To generate an enquiry controller, query filter, query, views and associated specs, execute:
 
     $ rails generate riveter:enquiry SomeEnquiryName filter1:string filter2:integer:required
 

data/app/helpers/riveter/enquiry_form_helper.rb

@@ -12,5 +12,9 @@ module Riveter
         simple_form_for(enquiry.query_filter, options, &block) :
         form_for(enquiry.query_filter, options, &block)
     end
+
+    def paginate_enquiry(enquiry, options={}, &block)
+      paginate(enquiry.query, options, &block) if respond_to?(:paginate)
+    end
   end
 end

data/config/locales/validators.en.yml

@@ -24,3 +24,8 @@ en:
     messages:
       booleaness: is not valid
       email: is not valid
+      invalid_date: is not a valid date
+      invalid_time: is not a valid time
+      date_range: is not a valid date range
+      date_range_date_from: "must be before %{date_to}"
+      date_range_date_to: "must be after %{date_from}"

data/lib/generators/riveter/command/templates/command.rb

@@ -25,6 +25,7 @@ class <%= class_name %>Command < Riveter::Command::Base
   #   attr_integer
   #   attr_decimal
   #   attr_date
+  #   attr_date_range
   #   attr_time
   #   attr_boolean
   #   attr_enum

data/lib/generators/riveter/query_filter/templates/query_filter.rb

@@ -25,6 +25,7 @@ class <%= class_name %>QueryFilter < Riveter::QueryFilter::Base
   #   attr_integer
   #   attr_decimal
   #   attr_date
+  #   attr_date_range
   #   attr_time
   #   attr_boolean
   #   attr_enum
@@ -37,4 +38,4 @@ class <%= class_name %>QueryFilter < Riveter::QueryFilter::Base
 <% end -%>
 
 end
-<% end -%>
+<% end -%>

data/lib/riveter.rb

@@ -12,8 +12,11 @@ module Riveter
   autoload :AttributeDefaultValues, 'riveter/attribute_default_values'
   autoload :AssociatedTypeRegistry, 'riveter/associated_type_registry'
   autoload :Attributes, 'riveter/attributes'
+  autoload :BooleanessValidator, 'riveter/booleaness_validator'
   autoload :Command, 'riveter/command'
   autoload :CommandController, 'riveter/command_controller'
+  autoload :DateRangeValidator, 'riveter/date_range_validator'
+  autoload :EmailValidator, 'riveter/email_validator'
   autoload :Enquiry, 'riveter/enquiry'
   autoload :EnquiryController, 'riveter/enquiry_controller'
   autoload :Enumerated, 'riveter/enumerated'
@@ -28,6 +31,7 @@ end
 module ActiveModel
   module Validations
     autoload :BooleanessValidator, 'riveter/booleaness_validator'
+    autoload :DateRangeValidator, 'riveter/date_range_validator'
     autoload :EmailValidator, 'riveter/email_validator'
   end
 end
@@ -40,6 +44,4 @@ require 'riveter/rails/railtie' if defined?(::Rails::Railtie)
 require 'riveter/rails/engine' if defined?(::Rails)
 
 # include locale in load path
-Dir[File.join(File.expand_path('../../config', __FILE__), 'locales', '*.yml')].each do |file|
-  I18n.load_path << file
-end
+I18n.load_path += Dir.glob(File.expand_path('../../config/locales/*.yml', __FILE__))

data/lib/riveter/attributes.rb

@@ -54,6 +54,62 @@ module Riveter
 
       alias :attr_datetime :attr_time
 
+      def attr_date_range(name, options={}, &block)
+        options = {
+          :validate => true
+        }.merge(options)
+
+        required = (true == options.delete(:required))
+
+        # expecting the default value to be a date range
+        # so extract out the first and last parts for the from and to
+        # otherwise, it may just be a date or nil
+        default = options.delete(:default)
+        default = default.is_a?(Range) ? default : (default..default)
+        defaults = {
+          :from => default.first,
+          :to => default.last
+        }
+
+        converter = block_given? ? block : Converters.converter_for(:date)
+
+        # return from and to as range
+        define_method name do
+          # can't have range starting or ending with nil, so return nil
+          send(:"#{name}_from")..send(:"#{name}_to") rescue nil
+        end
+
+        define_method "#{name}=" do |value|
+          value ||= nil..nil
+          range = value.is_a?(Range) ? value : value..value
+          send(:"#{name}_from=", range.first)
+          send(:"#{name}_to=", range.last)
+        end
+
+        validates name,
+                  :allow_nil => !required,
+                  :date_range => true if options[:validate]
+
+        add_attr(name, :date_range)
+
+        # break down into parts
+        [:from, :to].each do |part|
+          attr_reader_with_converter :"#{name}_#{part}", converter
+
+          define_method :"#{name}_#{part}?" do
+            send(:"#{name}_#{part}").present?
+          end
+
+          attr_writer :"#{name}_#{part}"
+
+          validates :"#{name}_#{part}",
+                    :allow_nil => !required,
+                    :timeliness => { :type => :date } if options[:validate]
+
+          add_attr(:"#{name}_#{part}", :date, converter, options.merge(:default => defaults[part]))
+        end
+      end
+
       def attr_boolean(name, options={}, &block)
         options = {
           :validate => true
@@ -65,11 +121,6 @@ module Riveter
         attr_reader_with_converter name, converter
         alias_method "#{name}?", name
 
-        validates name,
-                  :allow_blank => !required,
-                  :allow_nil => !required,
-                  :booleaness => true if options[:validate]
-
         attr_writer name
 
         add_attr(name, :boolean, converter, options)
@@ -100,7 +151,7 @@ module Riveter
         validates name,
                   :allow_blank => !required,
                   :allow_nil => !required,
-                  :inclusion => { :in => enum.all } if options[:validate]
+                  :inclusion => { :in => enum.values } if options[:validate]
 
         attr_writer name
 
@@ -244,7 +295,7 @@ module Riveter
         add_attr(name, type, converter, options)
       end
 
-      def add_attr(name, type, converter, options={})
+      def add_attr(name, type, converter=nil, options={})
         self._attributes[name] = attribute_info = AttributeInfo.new(name, type, converter, options)
         validates name, :presence => true if attribute_info.required?
         attribute_info