Reform – Decouple Your Forms From Your Models!

{{{
To cut a long story short: Working on a nested form we decided not to go with @nested_attributes@. In fact, we wanted a form with validations, rendering and processing completely decoupled from the model. I mean, why would a form wanna know about the database layout?

So we, that is one of my lovely co-workers “Garrett Heinlen”:https://twitter.com/GoGoGarrett and myself, came up with “Reform – a framework-agnostic, anti-database form object”:https://github.com/apotonick/reform.

h3. What Does It Look Like?

Let’s assume for now our form was to create a song request for a radio station – for whatever reason this implies creating both a row in the @songs@ and in the @artists@ table. We use an ActiveRecord example here, however, reform is not database-dependent at all.

class SongRequestForm < Reform::Form
  include DSL

  property :title,  on: :song
  property :name,   on: :artist

  validates :name, :title, presence: true
end

As you can see, this is pretty straight-forward. Define the layout and throw in some validations.

h3. What Is The Difference?

The form doesn’t know anything about your database. All you do is specifying what fields you want and where to map those. Also, note we’re using @ActiveModel@’s validations in the class and thus have per-form validations that don’t get in the way in our models.

For a better understanding, here’s how you would instantiate your reform.

@form = SongRequestForm.new(song:   Song.new, 
                             artist: Artist.new)

This would usually happen in your controller action.

Basically, from the key-object hash Reform will create a @Composition@ object that simply delegates accessors to the underlying objects. How does it know how to do that? Well, you just defined it!

  property :title,  on: :song

Calls to @#title@ or @#title=@ will be delegated.

  @form.title #=> @form.song.title

Note that this doesn’t involve any database-magic – it is simple delegation based on your specification.

h3. Rendering.

This simple trick makes it super-easy to use that form with Rails’ form helpers, “simple_form”:https://github.com/plataformatec/simple_form or whatever form rendering you fancy.

= simple_form_for @form do |f|

  = f.input :name
  = f.input :title

I don’t cover the details here but the form object will even expose the necessary @ActiveModel@-compliant methods when “you tell it to do so”:https://github.com/apotonick/reform#simple-integration.

h3. Processing Evil Input.

Now how do we update our form with incoming data, process it, validate it and display possible errors?

if @form.validate(params[:song_request])

The form comes with a @#validate@ method which accepts a hash of data. Validations you defined will be run and @form.errors@ will return potential errors from your confusing input.

Speaking of confusing: You no longer need @attr_accessible@ or @strong_parameters@ anymore. Why is that? Well, again, you defined the form layout earlier!!! Therefore, the form knows its fields and will simply ignore unsolicited input.

Another sweet feature is that the form will display the user’s input in the fields after a validation – without even touching your models.

@form.title => "Sunlit Nights" # from model.
@form.validate(title: "Scarified")
@form.title => "Scarified" # from user input.

h3. Saving Safe Input.

When you decided that the input is alright you can let Reform save the data.

if @form.validate(title: "Scarified")
  @form.save # @form.song.title = "Scarified"

It will pass the incoming data to the respective models. This is nice, but often you want more control. That’s where a block to @#save@ kicks in.

@form.save do |data, nested|
  data.title #=> "Scarified"
  nested[:song] #=> {title: "Scarified}

The block yields two handy arguments. The first @data@ is a plain list of the incoming and validated data (currently implemented as an @OpenStruct@ instance).

The second @nested@ is a hash keyed following your mapping instructions from earlier – remember, the calls to @::property@?

Makes it really easy to use ActiveRecord’s magic without the horror.

@form.save do |data, nested|
  Song.find(params[:id]).update(
    nested[:song]
  )

h3. Why Another Form Object?

I read several “blog posts”:http://pivotallabs.com/form-backing-objects-for-fun-and-profit/ that were really inspiring, however, they were either implementing a create form or an edit form, only. Also, we didn’t like the hard-core ActiveRecord wiring.

Reform gives you all the goodies like validation, parameter filtering and even rendering in a dedicated class. That keeps your UI logic where it should be. Hell yes, forms _are_ part of your UI and shouldn’t be configured in your database models.

In addition to that, “Reform”:https://github.com/apotonick/reform gives you all the flexibility to change internals. If you don’t like the automatically created @Composition@ object, use your own. If you don’t like the “representable”:https://github.com/apotonick/representable/ based mapper, make your own. It’s just 100 lines of code so far. Give it a try!

}}}

Advertisement