base_form 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e17e616e68d129b4df560fbeefdc03a4ba59b6d9
+  data.tar.gz: 8d8abb13435b58487acc419ae77f4bdd4ca7f5fb
+SHA512:
+  metadata.gz: 92584db37f2726475eb530296972649793e615c45d69ee7f14e867af6aa51565fe76129c0d748aa8dec9967b5bf47c9daf47c2b12b00adc62178310680a6732a
+  data.tar.gz: 2215a7f4b46b1d2648979e2a7b3ce9bc1a78dc9082561d5912dae0a3451bfbbf8c9ffcbf2c74cf3eac26415b497aa0fbf686bd8a7c30553ffc6c30208b9e1861

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 andrerpbts
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,190 @@
+# BaseForm
+[![Code Climate](https://codeclimate.com/github/andrerpbts/base_form/badges/gpa.svg)](https://codeclimate.com/github/andrerpbts/base_form)
+[![Test Coverage](https://codeclimate.com/github/andrerpbts/base_form/badges/coverage.svg)](https://codeclimate.com/github/andrerpbts/base_form/coverage)
+[ ![Codeship Status for andrerpbts/base_form](https://app.codeship.com/projects/8d9be4e0-811f-0134-3da7-7e60ebb19227/status?branch=master)](https://app.codeship.com/projects/182157)
+
+A simple and small Form Objects Rails plugin for ActiveRecord based projects.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'base_form'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install base_form
+```
+
+## Usage
+In a development day-to-day basis, we commonly are confronted with situation where we
+need to save data in more than one database table, running it's own validations, and
+the validations of the all context together. In most cases a Form Object is a perfect
+solution to deliver those records in a fun and maintenable code.
+
+Actually, there's a lot of another gems to do that, like the great
+[reform](https://github.com/apotonick/reform) or
+[activeform-rails](https://github.com/GCorbel/activeform-rails), which are a more complete
+solution for this problem. But, if you are looking for something lighter, maybe this
+gem could fit well for you.
+
+That said, let me show some simple examples to you. Let's suppose you want to create a
+signup form (you can check this example in the dummy app on this gem specs), with
+receiving a user email, a user password, a user password confirmation, and a plan. In your
+signup form, you need to create an account for this user, associate it to a entrance plan
+if it's not given, and make this user as an owner of this recently created account. Of course,
+in this case, a simple user model saving will not be sufficient to save all those data and
+accomplish with the requested business logic. So, you go to the Form Objects way,
+installs this gem, creates your Ruby class to handle all this logic:
+
+```ruby
+class SignupForm < BaseForm::Form
+
+end
+```
+
+With this empty class created, the easy way to start may be adding the attributes expected
+in this form, like:
+
+```ruby
+class SignupForm < BaseForm::Form
+  attribute :email
+  attribute :password
+  attribute :password_confirmation
+  attribute :plan, Plan, default: proc { Plan.default }
+end
+```
+
+Note, if you don't specifies a Plan to this form, it will call a default value, which in
+this case is calling a proc that will call a `default` method in `Plan` model and probably
+this will return the default plan instance, fetched from the database or something like that.
+
+Let's put some form specific validation here. For example, we don't want the Plan being forced
+with an empty string for example:
+
+```ruby
+class SignupForm < BaseForm::Form
+  # ... attributes, validations ...
+
+  validates :plan, presence: true
+end
+```
+
+Now you may be asking: What about email and password? Did not should be validated as well?
+Well, you could, in fact, perform all validations in this form, but sometimes this can happen.
+Then, I'm showing here the case that `User` model has those validations. Don't be mad ok? :)
+
+The form validations are the first validations tha are performed before it try to persist
+something here. If this validation fails, for an example, the persist method will not even
+be called, and the talk is over. Otherwise, it wil try to persist your logic, that we'll
+implement next.
+
+Ok, now, you need to set the records that you will persist here.
+In this case is the `:user` you want to save, and the `:account` you will want to associate
+to this user. So, you put it there (I recommend you let this in the top of the class to make
+it clear):
+
+```ruby
+class SignupForm < BaseForm::Form
+  use_form_records :user, :account
+
+  # ... attributes, validations ...
+end
+```
+
+This line will automatically generate `attr_readers` to each record there, and will add this
+symbols in an array called `form_records` in your class. To understand it better, let's talk
+about the `persist` implementation itself.
+
+By the rule, `persist` method is obligatory, and not implementing it, will cause your form
+raise a `NotImplementedError` when calling `save` to it.
+
+All things written inside `persist` method, will automatically run in a ActiveRecord transaction,
+and if some record have its validation failed, this will perform a Rollback and deliver the form
+to you with those erros grouped through `errors` method, like any AR model you are already
+familiar with.
+
+Let me stop to talk and show you something we can call as implementation of this:
+
+```ruby
+class SignupForm < BaseForm::Form
+  # form records, attributes, validations, whatever
+
+  private # because isolation is still a necessary evil ;)
+
+  def persist
+    @account ||= Account.create plan: plan
+    @user ||= account.users.create user_params
+  end
+
+  def user_params
+    {
+      email: email,
+      password: password,
+      password_confirmation: password_confirmation,
+      account_owner: true
+    }
+  end
+end
+```
+
+So, here is the thing, see the variables names I've associated there, are the name os
+form_records I've defined before. It tries to create an account, setting a plan to it
+and then tries to create a user associated to this brand new account.
+
+Is this `form_records` that will call each object associated here to check its errors,
+and group it in `errors` object in your form itself in case of some validation brakes,
+but if all is fine, the form instance is returned to you and you will be able to call
+methods like `persisted?`, `account`, `user`, `valid?` and etc...
+
+Are you still there? :D
+
+Let's see this class complete?
+
+```ruby
+class SignupForm < BaseForm
+  use_form_records :account, :user
+
+  attribute :email
+  attribute :password
+  attribute :password_confirmation
+  attribute :plan, Plan, default: proc { Plan.default }
+
+  validates :plan, presence: true
+
+  private
+
+  def persist
+    @account ||= Account.create plan: plan
+    @user ||= account.users.create user_params
+  end
+
+  def user_params
+    {
+      email: email,
+      password: password,
+      password_confirmation: password_confirmation,
+      account_owner: true
+    }
+  end
+end
+```
+
+Hmmmm, seems to be good enough. I hope this helps someone in the same way it
+helped me. Thanks!
+
+## Contributing
+- Fork it
+- Make your implementations
+- Send me a pull request
+
+Thank you!
+
+## License
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'BaseForm'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+

data/lib/base_form.rb

@@ -0,0 +1,10 @@
+# require dependencies gems
+require 'active_support'
+require 'active_model'
+require 'virtus'
+
+# require lib files
+require 'base_form/form'
+
+module BaseForm
+end

data/lib/base_form/form.rb

@@ -0,0 +1,80 @@
+module BaseForm
+  # This class is the main core functionality, by being an inheritable
+  # class, which controls the form attributes assignments, validations
+  # and persisting.
+  #
+  # Basically you should create your own Form Object Class, and inherit
+  # this class (BaseForm::Form). After that you should put all records
+  # in the `@form_records` variable, through `use_form_records` class
+  # method. In your `persist` method implementation, just create the
+  # record objects associating it to each variable in `form_records.`
+  class Form
+    include ActiveModel::Model
+    include Virtus.model
+
+    class << self
+      attr_reader :form_records
+
+      protected
+
+      def use_form_records(*records)
+        attr_reader(*records)
+
+        @form_records = records
+      end
+    end
+
+    def self.save(*params)
+      new(*params).save
+    end
+
+    # This method will make the things happen. It'll try run validations
+    # set in your form class, and if it passes, it'll run your persist
+    # instructions in a block of ActiveRecord transaction. If some
+    # record fails it's persistence/validation, then a rollback will be
+    # raised, the form will return those errors grouped in it. Otherwise
+    # everything is commited and `persisted?` method will return true.
+    def save
+      perform_in_transaction { persist } if valid?
+
+      self
+    end
+
+    def valid?
+      errors.empty? && super
+    end
+
+    def persisted?
+      @persisted
+    end
+
+    protected
+
+    def persist
+      raise NotImplementedError
+    end
+
+    def perform_in_transaction
+      ActiveRecord::Base.transaction do
+        yield if block_given?
+
+        records_errors.each { |error| add_errors_for(error) }
+        raise ActiveRecord::Rollback if errors.any?
+
+        @persisted = true
+      end
+    end
+
+    def records_errors
+      self.class.form_records.map do |form_record|
+        send(form_record).try(:errors)
+      end.compact.flatten
+    end
+
+    def add_errors_for(error)
+      error.each do |attribute, message|
+        errors.add attribute, message
+      end
+    end
+  end
+end

data/lib/base_form/version.rb

@@ -0,0 +1,3 @@
+module BaseForm
+  VERSION = '0.1.1'
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: base_form
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- andrerpbts
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: virtus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: BaseForm is a small and simple Rails plugin to work with Form Objects
+email:
+- andrerpbts@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/base_form.rb
+- lib/base_form/form.rb
+- lib/base_form/version.rb
+homepage: https://github.com/andrerpbts/base_form
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: A simple and small form objects Rails plugin
+test_files: []
+has_rdoc: