goaltender 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04e9a394f95b65ed94175af20c9d06f09c12e65b
-  data.tar.gz: 6f71d0fe681e1451c7c91eefc253cfb4d7de83c4
+  metadata.gz: 359c5ed702221fc18627406c2b9067f9b415b5b0
+  data.tar.gz: 77af3103925d36f9c0a5e7ad8760fe7326541b28
 SHA512:
-  metadata.gz: 64815ae11f3e5757035297c2b612056afdf54b17a4c70cb895f2f68ab62b25d3229b0bd8e0188e32055f6939b383b0d1404ed79af558bc146479bfd8e23e6b43
-  data.tar.gz: e7bf2d1441bf6df976ed0172c1b7f6aced4fb31f5b4e98decd704bbc3d5c5a711300fb49915b79d4ec0c3900bff141e43186e4b52ddfb605c7ef6453a7af1ec5
+  metadata.gz: adea5d8dd480ddf7e2d03d10b01b2a433101fefdcd3d14fb4c1f734e348d22bfd24b38e1704e1fa4bc6cbd90c7a7e93f6ff86b8097908efb1a914242ded187b7
+  data.tar.gz: 2ce3768d1d2e6220a326725332c01115bbfe85282b9e0575ddb552ed5481d72d341ca2c03018361d22cb59f400fc53b6479fb70e82505e7179bf4e2217351e7c

data/README.md

@@ -1,39 +1,264 @@
-# Goaltender
+In my humble opinion, Rails is missing a tool for parsing forms on the backend. Currently the process looks something like this:
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/goaltender`. To experiment with that code, run `bin/console` for an interactive prompt.
+```html
+# new.html.erb
+<%= form_for @trip do |trip_builder| %>
+  <div class="field">
+    <%= trip_builder.label :miles %>
+    <%= trip_builder.text_field :miles, placeholder: '50 miles' %>
+  </div>
+<% end %>
+```
+
+```ruby
+  # trips_controller
+
+  def create
+    @trip = Trip.new(trip_params)
+
+    if @trip.save
+      redirect_to trips_path, notice: "New trip successfully created."
+    else
+      render "new"
+    end
+  end
+```
+
+The problem with this approach is that there is nothing that processes the user inputs before being saved into the database. For example, if the user types "1,000 miles" into the form, Rails would store 0 instead of 1000 into our "miles" column.
+
+The "Services" concept that many Rails developers favor is on point. Every form should have a corresponding Ruby class whose responsibility is to process the inputs and get the form ready for storage.
+
+However, this "Services" concept does not have a supporting framework. It is repetitive for every developer, for example, to write code to parse a decimal field that comes into our Ruby controller as a string (as in the example above).
+
+Here is how it may be done right now:
+
+```ruby
+class Forms::Trip
+
+  attr_accessor :trip
+
+  def initialize(args = {})
+    @trip = Trip.new
+    @trip.miles = parse_miles(args[:miles)
+  end
+
+  def parse_miles(miles_input)
+    regex = /(\d|[.])/ # only care about numbers and decimals
+    miles_input.scan(regex).join.try(:to_f)
+  end
+
+  def save
+    @trip.save
+  end
+
+end
+```
+
+```ruby
+  # trips_controller.rb
+
+  def create
+    form = Forms::Trip.new(trip_params)
+    @trip = form.trip
+
+    if form.save
+      redirect_to trips_path, notice: "New trip successfully created."
+    else
+      render "new"
+    end
+  end
+```
+
+While this process is not so bad with only one field and one model, it gets more complex with many different fields, types of inputs, and especially with nested attributes.
+
+A better solution is to have the form service classes inherit from a base "form parser" class that can handle the common parsing needs of the community. For example:
+
+```ruby
+class Forms::Trip < FormParse::Base
+
+  input :miles, :float
+
+  def after_init(args)
+    @trip = Trip.new(to_hash)
+  end
+
+end
+```
+
+```ruby
+  # trips_controller.rb
+  # same as above
+
+  def create
+    form = Forms::Trip.new(trip_params)
+    @trip = form.trip
+
+    if form.save
+      redirect_to trips_path, notice: "New trip successfully created."
+    else
+      render "new"
+    end
+  end
+```
+
+The FormParse::Base class that Forms::Trip inherits from by default performs the proper regex as seen in the original Forms::Trip service object above. We need only define the input key and the type of input and the base class takes care of the heavy lifting.
 
-TODO: Delete this and the text above, and describe your gem
+The "to_hash" method takes the inputs and converts the parsed values into a hash, which produces the following in this case:
 
-## Installation
+```ruby
+  { miles: 1000.0 }
+```
 
-Add this line to your application's Gemfile:
+A more complex form would end up with a service class like below:
 
 ```ruby
-gem 'goaltender'
+class Forms::Trip
+
+  attr_accessor :trip
+
+  def initialize(args = {})
+    @trip = Trip.new
+    @trip.miles = parse_miles(args[:miles)
+    @trip.origin_city = args[:origin_city]
+    @trip.origin_state = args[:origin_state]
+    @trip.departure_datetime = parse_datetime(args[:departure_datetime])
+    @trip.destination_city = args[:destination_city]
+    @trip.destination_state = args[:destination_state]
+    @trip.arrival_datetime = parse_datetime(args[:arrival_datetime])
+  end
+
+  def parse_miles(miles_input)
+    regex = /(\d|[.])/ # only care about numbers and decimals
+    miles_input.scan(regex).join.try(:to_f)
+  end
+
+  def parse_datetime(datetime_input)
+    Date.strptime(datetime, "%m/%d/%Y")
+  end
+
+  def save
+    @trip.save
+  end
+
+end
 ```
 
-And then execute:
+With a framework, it would only involve the following:
 
-    $ bundle
+```ruby
+class Forms::Trip < FormParse::Base
 
-Or install it yourself as:
+  input :miles, :float
+  input :origin_city, :string
+  input :origin_state, :string
+  input :departure_datetime, :datetime
+  input :destination_city, :string
+  input :destination_state, :string
+  input :arrival_datetime, :datetime
 
-    $ gem install goaltender
+  def after_init(args)
+    @trip = Trip.new(to_hash)
+  end
 
-## Usage
+  # to_hash produces:
+  # {
+  #   miles: 1000.0,
+  #   origin_city: "Chicago",
+  #   origin_state: "IL",
+  #   departure_datetime: # DateTime object
+  #   destination_city: "New York",
+  #   destination_state: "NY",
+  #   arrival_datetime: # DateTime object
+  # }
 
-TODO: Write usage instructions here
+end
+```
 
-## Development
+Taking it a step further, if our form inputs are not database backed, we can even validate within our new service object like so:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+class FormParse::Base
+  include ActiveModel::Model
+
+  # ... base parsing code
+end
+
+class Form::Trip < FormParse::Base
+
+  input :miles, :float
+  input :origin_city, :string
+  input :origin_city, :string
+  input :destination_city, :string
+  input :destination_state, :string
+
+  validates :miles, :origin_city, :origin_state, :destination_city, :destination_state, presence: true
+
+  def after_init(args)
+    @trip = Trip.new(to_hash)
+  end
+
+  def save
+    if valid? && trip.valid?
+      trip.save
+    else
+      return false
+    end
+  end
+
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Of course, the save method could be abstracted to our base class too, assuming we define which object the Form::Trip class is saving like so:
 
-## Contributing
+```ruby
+class Form::Trip
+
+  def object
+    trip
+  end
+
+  # ... above code here
+end
+
+class FormParse::Base
+
+  def save
+    if valid? && object.valid?
+      object.save
+    else
+      return false
+    end
+  end
+end
+
+```
+
+But where we really can see benefits from a "framework" for parsing our Rails forms is when we start to use nested attributes. For example, if we abstract the origin and destination fields to a "Location" model, we could build out a separate service class to handle parsing our "Location" form (even if it is in the context of a parent object like Trip).
+
+```ruby
+class Forms::Location < FormParse::Base
+
+  input :city, :string
+  input :state, :string
+  input :departure_datetime, :datetime
+  input :arrival_datetime, :datetime
+
+  validates :city, :state :presence => true
+
+end
+
+class Forms::Trip < FormParse::Base
+
+  input :miles, :float
+  input :origin_attributes, :belongs_to, class: 'location'
+  input :destination_attributes, :belongs_to, class: 'location'
+
+  validates :miles, presence: true
+
+  def after_init(args)
+    @trip = Trip.new(to_hash)
+  end
+end
+```
 
-1. Fork it ( https://github.com/[my-github-username]/goaltender/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+The FormParse::Base class will recoginze the :belongs_to relationship and utilize the Location service class to parse the part of the params hash that correspond with our destination and origin models. This is great because if there is anywhere that the user can update just the origin or destination of the trip, we could just reuse that Location service object to parse the form.

data/lib/goaltender/base.rb

@@ -1,6 +1,13 @@
 class Goaltender::Base
 
-  include ActiveModel::Model
+  if Rails.version[0].to_i < 4
+    include ActiveModel::Validations
+    include ActiveModel::Conversion
+    extend ActiveModel::Naming
+  else
+    include ActiveModel::Model
+  end
+
   include Goaltender::BaseModule
 
   attr_reader :params, :inputs

data/lib/goaltender/input.rb

@@ -16,7 +16,7 @@ module Goaltender
     end
 
     def value_parser
-      @value_parser ||= "FormParse::ValueParser::#{type.to_s.classify}".constantize.new({
+      @value_parser ||= "Goaltender::ValueParser::#{type.to_s.classify}".constantize.new({
         input_value: input_value,
         parse_format: parse_format,
         form_class: form_class,

data/lib/goaltender/version.rb

@@ -1,3 +1,3 @@
 module Goaltender
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: goaltender
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Ryan Francis