flatter-extensions 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 836dcba21ba1e7372ffb7ba02c0c830caab448da
-  data.tar.gz: d6a27a477a4de896ab938cc9098b5e7e60ebabce
+  metadata.gz: a3ccff2224155cdb168ccd7de33cadeacb42d34b
+  data.tar.gz: 16f61b126dc24a8b68dc04fa8dff925bc2fd6a7b
 SHA512:
-  metadata.gz: 3b456cbd8bc8a4064969f0f3182951c779c12b58836d8821f6a1a6ac5737543349c7d16f58ecbeabad18eaec8d9c2a8e81f472a778c65eaedfd59d7c8019c14e
-  data.tar.gz: 44cceaca1a35835e7b0d29be5840baf3edd7747c033f2351e60c53d5ad99d47b97696ca161a475dfb05cd792a1fd9ac1d0924bdd763f1ee0e832cc815571ed38
+  metadata.gz: a0405d1ce282f152a014365af8c51d26d9f7e18c3f2f8ca5ffac5971e55551e289359a74408f78051e6fbc5f0226092558171c4b8060ad58ca82c95ac11647b7
+  data.tar.gz: a72f133129b400d4c281a0694278d73c5dabd3c7fbe0bdd924787158c717bf68917131457280de05a880aab24f57e62d1068be6b3d3a0246216c70cd00b6832f

data/README.md

@@ -1,5 +1,7 @@
 # Flatter::Extensions
 
+[![Build Status](https://secure.travis-ci.org/akuzko/flatter-extensions.png)](http://travis-ci.org/akuzko/flatter-extensions)
+
 A set of extensions to be used with [Flatter](https://github.com/akuzko/flatter) gem.
 
 ## Installation
@@ -20,11 +22,232 @@ Or install it yourself as:
 
 ## Usage
 
-Coming soon.
+All extensions can be included at a runtime using `Flatter.use` method. Usually,
+this is done in your app initializer with a `Flatter.configure`, like so:
+
+```ruby
+Flatter.configure do |f|
+  f.use :order
+  f.use :skipping
+  f.use :active_record
+end
+```
+
+Bellow is a list of available extensions with description.
+
+### Multiparam
+
+```ruby
+Flatter.use :multiparam
+```
+
+Allows you to define multiparam mappings by using `:multiparam` option to mapping.
+Works pretty much like `Rails` multiparam attribute assignment:
+
+```ruby
+class PersonMapper < Flatter::Mapper
+  map :first_name, :last_name
+  map dob: :date_of_birth, multiparam: Date
+end
+
+# ...
+
+mapper = PersonMapper.new(person)
+mapper.write(first_name: 'John', 'dob(1i)' => '2015', 'dob(2i)' => '01', 'dob(3i)' => '15')
+person.date_of_birth # => Thu, 15 Jan 2015
+```
+
+### Skipping
+
+```ruby
+Flatter.use :skipping
+```
+
+Allows to skip mappers (mountings) from the processing chain by calling `skip!`
+method on a particular mapper. This is usually used in before callbacks to
+avoid processing specific mappers if they fail to match some processing condition.
+For example:
+
+```ruby
+class Person < ActiveRecord::Base
+  has_many :phones
+end
+
+class PhoneMapper < Flatter::Mapper
+  map phone_number: :number
+
+  validates_presence_of :phone_number
+end
+
+class PersonMapper < Flatter::Mapper
+  mount :phone, foreign_key: :person_id
+
+  set_callback :validate, :before, :skip_empty_phone
+
+  def skip_empty_phone
+    # avoids validation and creation of new phone number
+    # if provided `phone_number` field was blank.
+    mounting(:phone).skip! if phone_number.blank?
+  end
+end
+```
+
+### Order
+
+```ruby
+Flatter.use :order
+```
+
+Allows you to manually control processing order of mappers and their mountings.
+Provides `:index` option for mountings, which can be either a Number, which means
+order for both validation and saving routines, or a hash like `{validate: -1, save: 2}`.
+By default all mappers have index of `0` and processed from top to bottom.
+
+This extension will be very handy when using with `:active_record` extension, since
+all targets (records) are saved **without** callbacks and validation, which means
+you won't have such things as associations autosave. That means that to properly
+save records with foreign key dependencies, you have to do it in proper order.
+For example, in following scenario we use `PersonMapper` to manage people. If
+additionally `email` was supplied, `User` record will be created, and `Person`
+record will be associated with it. This means that we need to skip User *before*
+validation if there was no email provided, but save it *before* person mounter.
+
+```ruby
+class Person < ActiveRecord::Base
+  belongs_to :user
+end
+
+class User < ActiveRecord::Base
+  has_one :person
+end
+
+class UserMapper < Flatter::Mapper
+  map :email
+
+  validates_presence_of :email
+end
+
+class PersonMapper < Flatter::Mapper
+  trait :management do
+    mount :user, index: {save: -1}, mounter_foreign_key: :user_id
+
+    set_callback :validate, :before, :skip_user
+
+    def skip_user
+      mounting(:user).skip! if email.blank?
+    end
+  end
+end
+```
+
+### ActiveRecord
+
+```ruby
+Flatter.use :active_record
+```
+
+Probably, the most important extension, the reason why Flatter (former FlatMap)
+was initially built. This extension allows you to build mappers that will handle
+complexity of ActiveRecord associations in a graph of related records to provide a
+single mapper object with plain hash of attributes that can be used to render a form,
+used as a form object itself to distribute form params among records, or used in
+your API, encapsulating processing logic with reusable traits.
+
+`:active_record` extension depends on `:skipping` extension to be able to utilize
+it properly. This means that if you use `:active_record` extension, `:skipping`
+will be used automatically. Although there will be no harm using it explicitly
+like:
+
+```ruby
+Flatten.configure do |f|
+  f.use :order
+  f.use :skipping
+  f.use :active_record
+end
+```
+
+When using `:active_record` extension, you should keep in mind following things:
+
+#### Mounted target from association
+
+If mapper's target is an `ActiveRecord::Base` object, target for mounted mappers
+will be tried to be derived from relevant association. For example:
+
+```ruby
+class Person < ActiveRecord::Base
+  belongs_to :user
+  has_one :location
+  has_many :phones
+end
+
+class PersonMapper < Flatter::Mapper
+  mount :user
+  mount :location
+  mount :phone
+end
+```
+
+Here we have:
+- `:user` is a `:belongs_to` association. Target for mounted `UserMapper` will
+  be by default fetched as `person.user || person.build_user`.
+- `:location` is a `:has_one` association. Just like `:user`, target for mounted
+  `LocationMapper` will be fetched as `person.location || person.build_location`.
+- `:phones` is a `:has_many` association, and we map **singular** phone. In this
+  case target for `PhoneMapper` is fetched as `person.phones.build`. Thus, you may
+  want to `skip!` this mounting before save or validation to prevent creating
+  freshly-built record, if it was not populated with any values.
+
+Mounting collection associations and working with them as with collections is
+not supported for now.
+
+Keep in mind that you can always pass `:target` option to control targets of
+mounted mappers.
+
+#### Saving is performed without callbacks and validation
+
+That's right. On save your models will not be validated and their `:save` callbacks
+will not be executed. All such form-related business logic should be handled by mappers,
+keeping models clean for taking care about inner application business logic only.
+
+For example, if you have multi-step form and want to put all your validations in
+model, there will be dozens of boolean checks to use specific validations only
+on specific steps. With mappers, you can define necessary sets of validations
+within traits and keep your models clean.
+
+#### Processing order and foreign keys
+
+Since there are no callbacks, there will be no association autosaving, which means
+that your models will be saved exactly once exactly when each mapper starts it's
+saving routines. That also means that you should manually handle foreign keys
+assigning when creating new records. This can be done via before- or after-save
+callbacks, but extension provides a handy mounting options to do it for you:
+`foreign_key` and `mounter_foreign_key`. First option should be set when mounted
+mapper depends on current one. And the second one - when current mapper depends on
+mounted one. In that case `:index` option should be used to force this mounting
+to be processed first:
+
+```ruby
+class PersonMapper < Flatter::Mapper
+  mount :user, mounter_foreign_key: :user_id, index: -1
+  mount :phone, foreign_key: :person_id
+end
+```
+
+#### Transactions
+
+With `:active_record` extension you should mainly use `apply(params)` method for
+updating or creating your models via mappers. It wraps whole saving process (writing
+values, validation and saving) in a transaction. The reason for this is that your
+mappings may have custom db-mutating writers, and if saving fails, such mutations
+should be rolled back. However, `save` method is also wrapped in transaction and
+will return `false` if any mapper in processing chain will fail to save it's
+target. This might happen due to DB constraints, for example.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
 
 ## Contributing
 

data/lib/flatter/extensions/active_record.rb

@@ -59,8 +59,8 @@ if defined? ActiveRecord
 
           def reflection_from_target(target)
             target_class = target.class
-            reflection   = target_class.reflect_on_association(name)
-            reflection || target_class.reflect_on_association(name.pluralize)
+            reflection   = target_class.reflect_on_association(name.to_sym)
+            reflection || target_class.reflect_on_association(name.pluralize.to_sym)
           end
           private :reflection_from_target
         end
@@ -69,7 +69,19 @@ if defined? ActiveRecord
           def apply(*)
             return super unless ar?
 
-            ::ActiveRecord::Base.transaction{ super }
+            !!::ActiveRecord::Base.transaction do
+              super or raise ::ActiveRecord::Rollback
+            end
+          end
+
+          def save
+            !!::ActiveRecord::Base.transaction do
+              begin
+                super
+              rescue ::ActiveRecord::StatementInvalid
+                raise ::ActiveRecord::Rollback
+              end
+            end
           end
 
           def save_target

data/lib/flatter/extensions/version.rb

@@ -1,5 +1,5 @@
 module Flatter
   module Extensions
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flatter-extensions
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Artem Kuzko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-03 00:00:00.000000000 Z
+date: 2015-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: flatter