OnForm
A pragmatism-first library to help Rails applications migrate from complex nested attribute models to tidy form objects.
Our goal is that you can migrate large forms to OnForm incrementally, without having to refactor large amounts of code in a single release.
Data and validations flow back and forward from the model layer automatically once you've defined which model attributes should be exposed.
Forms backed by multiple models are supported natively, with no concept of a single main model.
ActiveModel/ActiveRecord idioms such as validations and callbacks can be used directly in the form object.
Whereever possible, the terminology and experience should be familiar to Rails developers, to minimize relearning time.
Installation
Add this line to your application's Gemfile:
gem 'on_form', '~> 1.0'
And then execute:
$ bundle
Or install it yourself as:
$ gem install on_form
Usage
This version of OnForm should work with Rails 5.0 and 4.2.
This version of OnForm depends on both the activemodel
and activerecord
gems. Rails 5.0 has refactored some of the necessary ActiveRecord code across to ActiveModel, so the activerecord
dependency may be dropped once Rails 4.2 support is dropped.
Simple example of wrapping a model
Let's say you have a big fat legacy model called Customer
, and you have a preferences controller:
class PreferencesController
def show
@customer = Customer.find(params[:id])
end
def update
@customer = Customer.find(params[:id])
@customer.update!(params[:customer].permit(:name, :email, :phone_number)
redirect_to preferences_path(@customer)
rescue ActiveRecord::RecordInvalid
render :show
end
end
Let's wrap the customer object in a form object. Ideally we'd call this @customer_form
, but you may not feel you have time to go and update all your view code, so in this example we'll keep calling it @customer
.
class PreferencesController
def show
@customer = PreferencesForm.new(Customer.find(params[:id]))
end
def update
@customer = PreferencesForm.new(Customer.find(params[:id]))
@customer.update!(params[:customer])
rescue ActiveRecord::RecordInvalid
render :show
end
end
Now we need to make our form object. At this point we need to tell the form object which attributes on the model we want to expose
. (In this example we have just one model and a couple of attributes, but you wouldn't bother using this library if this was all you had.)
class PreferencesForm < OnForm::Form
expose %i(name email phone_number), on: :customer
def initialize(customer)
@customer = customer
end
end
The form object responds to the usual persistance methods like email
, email=
, save
, save!
, update
, and update!
.
It will automatically write those exposed attributes back onto the models, and it exposes any validation errors from those fields on the form object itself - you don't have to copy them back manually or move your field validation code over to get started. It'll also expose any errors on base on the models whose attributes you exposed. See the Validations section below for more.
A multi-model form
You aren't limited to having one primary model - if your form is backed by multiple models just call expose
for each one. They'll automatically be saved in the same order you declared them.
In this example, the new models we're exposing are associated with the first one, so we don't need to pass them in to the constructor.
class HouseListingForm < OnForm::Form
expose %i(street_number street_name city), on: :house
expose %i(name phone_number), on: :vendor
def initialize(house)
@house = house
@vendor = house.vendor
end
end
Transactions will automatically be started so that all database updates will be rolled back if any record fails to save (for example, due to a validation error).
Note that the on:
kwarg gives the name of the method on the form object which returns the record - nothing to do with class names. In this example, vendor might actually be an instance of our Customer
model from the earlier examples.
Model accessor methods
In the previous example, the constructor set @house
and @vendor
because these variables correspond to the name passed to expose
in the on
option. expose
will automatically add an attr_reader
for this name, meaning you only need to set the instance variables.
But if you prefer, you can define a method with the same name yourself, for example using delegation. expose
won't run attr_reader
if you've already defined the method, and there's no requirement to set an instance variable.
class HouseListingForm < OnForm::Form
delegate :vendor, :to => :house
expose %i(street_number street_name city), on: :house
expose %i(name phone_number), on: :vendor
def initialize(house)
@house = house
end
end
You can also define your own method over the top of the attr_reader
. Just remember it will be called more than once, so it must be idempotent.
View helpers & acting like ActiveModel/ActiveRecord
Since OnForm doesn't require a single "main" model, forms don't automatically have any particular identity value (ie. an id
attribute or a value to return from to_param
).
So although by default forms will work fine with all the 'raw' form field helpers and with helpers like fields_for
, they're not automatically usable with the resource form methods like form_for
, which assumes you have a one-to-one correspondance between your models and your views (in other words, that you have no form object layer).
You have several options. First, you can start your form tags completely manually, optionally choosing the name for the params:
<%= form_tag customer_path(edit_details_form.customer), method: :put do %>
<%# if the controller has set an ivar called @edit_details_form %>
<%= fields_for :edit_details_form do |f| %>
<%# produces a field called edit_details_form[name] %>
<%= f.text_field :name %>
<% end %>
<%# or you can give it a different name, to control what the form params will be named %>
<%= fields_for :customer, @edit_details_form do |f| %>
<%# produces a field called customer[name], which is what a normal resource controller expects %>
<%= f.text_field :name %>
<% end %>
<% end %>
Secondly, you can combine these calls into a form_for
call using some of its optional arguments:
<%= form_for @edit_details_form, as: :customer, url: customer_path(edit_details_form.customer), method: :put do |f| %>
<%# produces a field called customer[name] %>
<%= f.text_field :name %>
<% end %>
Thirdly, you can delegate the identity question to one of the models that backs the form using takes_identity_from
. When you do this, the form objects start to return that model from to_model
and the to_key
and to_param
values of that model as their own. This is the recommended approach when dealing with standard resource ('RESTful') controllers.
class EditPostForm < OnForm::Form
take_identity_from :post
expose %i(title body), on: :post
def initialize(post)
@post = post
end
end
<%= form_for @edit_details_form do |f| %>
<%# produces a field called customer[name] %>
<%= f.text_field :name %>
<% end %>
Note that we no longer have to specify the as
,url
, or method
options, because these will be automatically derived from the customer
model instead of from the form object itself.
When you choose an identity model, it will also become the default model for expose
calls, which helps DRY up single-model form objects.
class EditPostForm < OnForm::Form
take_identity_from :post
expose %i(title body)
def initialize(post)
@post = post
end
end
Renaming attributes
By default the attribute names exposed on the form object are the same as the attributes on the backing models. Sometimes this leads to unclear meanings, and sometimes you'll have duplicate attribute names in a multi-model form.
To address this you can use the prefix
and/or suffix
options to expose
, or if you need to change the name completely, the as
option.
class AccountHolderForm < OnForm::Form
expose %i(name date_of_birth), on: :customer, prefix: "account_holder_"
expose %i(email), on: :customer, suffix: "_for_billing"
expose %i(phone_number), on: :customer, as: "mobile_number"
def initialize(customer)
@customer = customer
end
end
This is especially useful if you like to use helpers like error_messages_on
which will "humanize" the attribute names and use them in the human-readable page.
Try to use this only when it makes the attribute names more meaningful. In particular, automatically renaming all of your attributes with a prefix matching the backing model is considered a bad habit because it leads to unnecessary coupling between the views and the current backing data model schema.
Validations
Validations on the underlying models not only get used, but their validation errors show up on the form's errors
object directly when you call valid?
or any of the save/update methods.
But you can also declare validations on the form object itself, which is useful when you have business rules applicable to this form that aren't intrinsic to the domain model.
class AddEmergencyContactForm < OnForm::Form
expose %i(next_of_kin_name next_of_kin_phone_number), on: :customer
validates_presence_of :next_of_kin_name, :next_of_kin_phone_number
def initialize(customer)
@customer = customer
end
end
Note that when you call save!
, update!
, or update_attributes!
on the form object, validation errors from records will still raise ActiveRecord::RecordInvalid
, but validation errors from validations defined on the form itself will raise ActiveModel::ValidationError
. You will usually want to rescue both.
Callbacks
You can also use the before_validation
, before_save
, after_save
, and around_save
validations. Like ActiveRecord, these will run inside the database transaction when you're calling one of the save or update methods, which is especially useful if you need to take locks on parent records.
class NewBranchForm < OnForm::Form
expose %w(bank_id branch_number branch_name), on: :branch
before_save :lock_bank
protected
def lock_bank
branch.bank.lock!
end
end
Model validations and validation callbacks occur between the form validation before and after callbacks, and model save calls are nested inside the form save calls, but the save calls all follow the validations and validation callbacks.
form before_validation
model before_validation
model validate (validations defined on the model)
model after_validation
form validate (validations defined on the form itself)
form after_validation
form before_save
form around_save begins
model before_save
model around_save begins
model saved
model around_save ends
model after_save
form around_save ends
form after_save
Adding artifical attributes
In addition to mapping attributes between models and the form, you can introduce new attributes which are not directly persisted anywhere. You can use any of the "standard" (non-database-specific) ActiveRecord types, and you can add default
, scale
, and precision
options.
class ChangeEmailForm < OnForm::Form
expose %i(email), on: :customer, as: :new_email
attribute :email_confirmation, :string, :default => "(please confirm)"
validate :email_confirmation_matches
def initialize(customer)
@customer = customer
end
def email_confirmation_matches
errors[:email_confirmation] << "does not match" unless email_confirmation == new_email
end
end
Model-less forms
Taking this one step further, you can define forms which have no exposed model attributes.
To actually perform a data change in response to the form submission, you can add a before_save
or after_save
callback and from there call your existing model code or service objects. It's best to keep the code in the form object to just the bits specific to the form - try not to put your business logic in your form objects!
class ChangePasswordForm < OnForm::Form
attribute :current_password, :string
attribute :password, :string
attribute :password_confirmation, :string
validate :current_password_correct
validate :password_confirmation_matches
before_save :set_new_password
def initialize(customer)
@customer = customer
end
def current_password_correct
unless @customer.password_correct?(current_password)
errors[:current_password] << "is incorrect"
end
end
def password_confirmation_matches
unless password_confirmation == password
errors[:password_confirmation] << "doesn't match"
end
end
def set_new_password
@customer.change_password!(password)
end
end
Note that when you have no exposed models, OnForm will still wrap the save process in a database transaction for you, using ActiveRecord::Base.transaction
. If you have multiple database connections, you may need to start transactions on the other connections yourself.
Reusing and extending forms
You can descend form classes from other form classes and expose additional models or additional attributes on existing models.
class AdminHouseListingForm < HouseListingForm
expose %i(listing_approved), on: :house
end
This works well for some use cases, but can quickly become cumbersome if you have a lot of partial form reuse, and it may not be obvious to other developers that the parent form is also used to derive the other forms. Consider breaking your form parts into reuseable modules, and defining each form separately.
You can use standard Ruby hooks for this:
module AccountFormComponent
def self.included(form)
form.expose %i(email phone_number), on: :customer
end
end
class NewAccountForm < OnForm::Form
include AccountFormComponent
expose %i(name), on: :customer
def initialize(customer)
@customer = customer
end
end
class EditAccountForm < OnForm::Form
include AccountFormComponent
delegate :name, to: :customer
def initialize(customer)
@customer = customer
end
end
In this example the initialize method could actually be moved to the module as well, but that makes it harder to compose forms from multiple modules.
If you prefer, you can use the Rails included
block syntax in the module instead of def self.included
.
Development
After checking out the repo, pick the rails version you'd like to run tests against, and run:
RAILS_VERSION=5.2.0 bundle update
You should then be able to run the test suite:
bundle exec rake
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/powershop/on_form.
Roadmap
- The author is currently assessing other use cases for ActiveRecord nested attributes, such as one-to-many associations and auto-building/deleting associated records. Feedback welcome.
License
The gem is available as open source under the terms of the MIT License.
Copyright © Flux Federation Limited, 2016-2018.