README.md in decanter-0.6.2 vs README.md in decanter-0.6.3
- old
+ new
@@ -6,12 +6,14 @@
What is Decanter?
---
-Decanter is a Rails gem that makes it easy to manipulate form data before it hits the model. The basic idea is that form data entered by a user often needs to be processed before it is stored into the database. A typical example of this is a datepicker. A user selects January 15th, 2015 as the date, but this is going to come into our controller as a string like "01/15/2015", so we need to convert this string to a Ruby Date object before it is stored in our database. Many developers perform this conversion right in the controller, which results in errors and unnecessary complexity, especially as the application grows.
+Decanter is a Rails gem that makes it easy to transform incoming data before it hits the model. The basic idea is that form data entered by a user often needs to be processed before it is stored into the database. A typical example of this is a datepicker. A user selects January 15th, 2015 as the date, but this is going to come into our controller as a string like "01/15/2015", so we need to convert this string to a Ruby Date object before it is stored in our database. Many developers perform this conversion right in the controller, which results in errors and unnecessary complexity, especially as the application grows.
+You can think of Decanter as the opposite of Active Model Serializer. Whereas AMS transforms your outbound data into a format that your frontend consumes, Decanter transforms your incoming data into a format that your backend consumes.
+
Installation
---
```ruby
gem "decanter"
@@ -71,10 +73,21 @@
render "new"
end
end
```
+Or, if you would prefer to get the parsed hash and then do your own logic, you can do the following:
+
+```ruby
+def create
+ parsed_params = Trip.decant(params[:trip])
+ @trip = Trip.new(parsed_params)
+
+ # save logic here
+end
+```
+
Basic Example
---
We have a form where users can create a new Trip, which has the following attributes: name, start_date, and end_date
@@ -132,11 +145,11 @@
input :start_date, :date
input :end_date, :date
end
```
-You'll also notice that instead of ```@trip = Trip.new(params[:trip])``` we do ```@trip = Trip.decant_new(params[:trip])```. ```decant_new`` is where the magic happens. It is converting the params from this:
+You'll also notice that instead of ```@trip = Trip.new(params[:trip])``` we do ```@trip = Trip.decant_new(params[:trip])```. ```decant_new``` is where the magic happens. It is converting the params from this:
```ruby
{
name: "My Trip",
start_date: "01/15/2015",
@@ -269,11 +282,11 @@
Each of the destinations in our params[:trip] are automatically parsed according to the DestinationDecanter inputs set above. This means that ```arrival_date``` and ```departure_date``` are converted to Ruby Date objects for each of the destinations passed through the nested params. Yeehaw!
Non Database-Backed Objects
---
-Decanter will work for you non database-backed objects as well. We just need to call ```decant``` to parse our params according to our decanter logic.
+Decanter will work for your non database-backed objects as well. We just need to call ```decant``` to parse our params according to our decanter logic.
Let's say we have a search filtering object called ```SearchFilter```. We start by generating our decanter:
```
rails g decanter SearchFilter start_date:date end_date:date city:string state:string
@@ -334,13 +347,36 @@
```ruby
# app/decanter/squashers/date_squasher.rb
class SquashDateParser < Decanter::Parser::Base
- parser do |name, values, options|
- day = values[0]
- month = values[1]
- year = values[2]
+ parser do |name, values, options|
+ day, month, year = values.map(&:to_i)
Date.new(year, month, day)
end
+end
+```
+
+No Need for Strong Params
+---
+
+Since you are already defining your expected inputs in Decanter, you really don't need strong_params anymore.
+
+In order to tell Decanter to ignore the params not defined in your Decanter, just add the ```strict``` flag to your Decanters:
+
+```ruby
+class TripDecanter < Decanter::Base
+ strict true
+
+ input :name
+end
+```
+
+Or to raise exceptions when parameters arrive in your Decanter that you didn't expect:
+
+```ruby
+class TripDecanter < Decanter::Base
+ strict :with_exception
+
+ input :name
end
```