What are form objects?
I've been over the use case for form objects in this post on moving away from fat models but wanted to go into more detail on how and why I use them here. I really believe in the utility of these objects; their ability to abstract and isolate logic in a simple and effective manner is unmatched, IMO.
The basic classification of a form object is a class that contains writable attributes, validations and logic to persist the attributes to ActiveRecord objects. These forms can also include other side-effects like background job triggers, emails, and push-notifications etc.
The simplest way to understand the concept is to think of them as a representation of a controller action where all of the business logic that happens in that controller action is abstracted into a form object. They can also be rendered, presented, or serialized like ActiveRecord objects.
Similar to the physical form above, there's also another reason we might want to use forms; conceptually they do make more sense. Our endpoints often contain logic and data relating to more than one ActiveRecord object. With forms we can build a boundary around a concept, e.g. a tax return form will collect user data, earnings data, and withholdings data etc. With a TaxReturnForm we can encapsulate this logic and create a tangible concept within our applications.
Maybe we need to validate that the user has supplied their ID number when they return their tax forms but not when they are updating their account email address. With forms we can isolate these validations to the correct objects, making our apps cleaner and responsibilities more well defined. No more custom attributes to tell our ActiveRecord models when to run a validation and when to skip it - it's implicitly defined.
Maybe we need to validate that the user has supplied their ID number when they return their tax forms but not when they are updating their account email address. With forms we can isolate these validations to the correct objects, making our apps cleaner and responsibilities more well defined. No more custom attributes to tell our ActiveRecord models when to run a validation and when to skip it - it's implicitly defined.
Let's see the code!
Let's look at how we can write forms with this ActiveForm
- The ActiveForm::Base module contains all of the logic to set up the form helpers.
- The ActiveForm::SimpleFormHelpers module contains some additional logic to allow simple_form to auto detect the input types.
- ActiveRecord::Base includes some methods around the typecasting that are not yet implemented for ActiveModel::Attributes, fortunately it's easy to set up. Alternatively you could always just specify the simple_form inputs 'as:' option e.g. <%= f.input :date_of_birth, as: :date %>
class UserRegistrationForm
include ActiveForm::Base
include ActiveForm::SimpleFormHelpers
attr_accessor :user
attribute :first_name
attribute :last_name
attribute :email
attribute :password
with_options presence: true do
validates :first_name
validates :last_name
validates :email, format: { with: Devise.email_regexp, allow_blank: true }
validates :password, length: { minimum: 8, maximum: 100 }
end
validate :email_unique?, if: -> { email.present? }
def process
return false unless valid?
self.user = User.create(attributes)
UserRegistrationJob.perform_later(user)
UserMailer.registration_confirmation(user).deliver_later
true
end
# uniqueness validations need to be done manually but we can still use the
# default messages
private def email_unique?
return true unless User.exists?(email: email)
errors.add(:email, :taken)
end
end
Looking for a new challenge? Join Our Team
Do I still need to use strong params? ActiveForm has the attribute allow-listing by default. Any attribute in the list will be allowed, and any defined as attr_{accessor,reader,writer} will not be populated when passed in as params. This means we no longer need to use strong_params in the controllers because the form has a clear definition of what it expects and protects us by design.
What if I need to pass in a resource? In the above example we're creating a user, but perhaps we are updating one. In this case we might want to pass in the current_user. We can do this by defining an attr_accessor and then passing the current_user in when initializing the form. For example:
UserEditForm.new(params: params, user: current_user)
Why process, not save? This is entirely up to you. However, it's good to stay consistent across your team so there's no confusion. I began using save but found there are some cases for forms where you aren't saving anything, such as when you are just triggering a job or push-notification. I found using process fits more cases so that's what I use. This is also typically the only method that is public on my forms.
How do I handle failures when persisting multiple objects? I recommend using ActiveRecord::Base.transaction blocks for any logic that updates more than one table. However, sometimes actions can't be rolled back and it is unfortunately unavoidable. For example, consider when we send emails during the call to process. If we send before saving a record and that record fails to save what do we do? We can't unsend that email. This situation is up to the developer to solve for each use case. I typically save everything I can first, and then call the side-effects afterwards. If the side-effects fail I can handle them elsewhere and retry when necessary.
Why do I have to write uniqueness validations myself? ActiveRecord does some magic internally to make uniqueness validations work. When you call unique on an AR instance, self is the object so ruby knows which attribute is being compared to the others in the database. This is important when validating uniqueness of a persisted record. If you are checking uniqueness of a new object and you only check if the attribute exists in the db, if it's persisted already you need to scope to any object other than the current one. While it's technically possible to implement this in ActiveForm, it's not straightforward. Writing the uniqueness validations yourself is easy so I felt it was better to leave this up to the developer
How can we use this in the controllers?
class RegistrationsController
def new
@form = UserRegistrationForm.new
end
def create
@form = UserRegistrationForm.new(params: params[:form])
if @form.process
redirect_to welcome_path, notice: 'Welcome, your registration was successful!'
else
render :new
end
end
end
The forms are simple to initialize. You can pass in params through the params keyword argument. Remember we don't need strong params anymore as the forms already handle rejecting invalid parameters for us so we can just pass in the raw params (remember you need to pass in the form params not the root params, if you name you instance variable form, then you can always just pass in params[:form]).
We can render the forms in the views and as we include ActiveForm::Validations we can also render the error messages. The controllers feel very familiar to using ActiveRecord models but we get the benefit of isolating request specific logic without cramming it into a ActiveRecord model that will be used in multiple controllers/actions.
While you could move logic for user authentication into forms, Devise is widely used and there are already well worn paths on how to manage authentication. I recommend following the traditional route and authenticate_user in the controllers then pass current_user into the form as a resource. Same goes for policies, I like pundit and continue to use that outside of my forms. I think that's ok.
What does rendering the form look like?
# app/views/registrations/new.html.erb
<%= simple_form_for @form, url: registrations_path, method: :post do |f| %>
<%= f.input :first_name %>
<%= f.input :last_name %>
<%= f.input :email %>
<%= f.input :password %>
<%= f.submit 'Register' %>
<% end %>
No surprises here - it looks almost identical to ActiveRecord forms. I really like simple_form so I added a few helpers to correctly identify the input type. You can use this by including the ActiveForm::SimpleFormHelpers module in your form.
Notice how we specify the url and method. This is because ActiveRecord provides the persisted? method which form_for and simple_form_for use to check if it's a new or existing record and subsequently changes the method from post to put and also changes the text on the submit button automatically. I prefer to be explicit with this as it's clear and less magic. However, if you prefer you can easily define this method on your forms - just need to define def persisted? and return true or false.
So that's it?
Yeah pretty much. It's a small utility with lots of potential for creating maintainable apps.
There are some added bonuses here as well.
before_initilization and after_initialization callbacks
I use these callbacks a lot to find or initialize attributes or resources. e.g.
attr_accessor :user, :device
attribute :device_uid, :uuid
before_initialization -> { self.device = user.device if user.present? }
before_initialization -> { self.device_uid = SecureRandom.uuid }
Date fields
Date fields are handled differently to other fields in Rails. When you create a date select, Rails splits the field into 3 selects inputs: time inputs split into 5, e.g. year, month, day, hour, minute. These values are passed to the backend, not as params: { 'date' => '01/01/2001' } but as params: { 'date(1i)' => '01', 'date(2i)' => '01', 'date(3i)' => '2001' }. ActiveForm will automatically deserialize these dates and times based on the attribute type, e.g. if the attribute :date, :date exists then the params will try to merge these into a date object before assigning it to the form.
Boolean attributes
Boolean attributes include an aliased question mark method by default. We're all familiar with ActiveRecord boolean columns having two accessors, e.g. admin and admin?, ActiveForm will behave the same way e.g. attribute :admin, boolean will create an alias, admin?, for the admin attribute.
The 'attributes' method
ActiveRecord::Base#attributes is cast to indifferent_access but ActiveModel::Model#attributes isn't. This means calling attributes[:email] fails, while attribute['email'] doesn't. ActiveForm overrides attributes and calls indifferent_access on the result so we can access with string or symbol keys.
ActiveModel::Attributes extendable nature
ActiveModel::Attributes are extendable so you can create your own types easily. I've created many over the time I've been using this lib. For example I have an EmailType to cast the email attributes to downcased automatically, no more mixed case emails (of course you could also do this in postgres). Don't forget to tell Rails about your attributes in an initializer
class EmailType < ActiveModel::Type::String
def cast(value)
return nil unless value.is_a?(String) && value.present?
super(value.downcase)
end
end
Is this a gem?
For now I feel ActiveForm is still a bit early to transition to a gem as there are still things to improve and work out. One day I'll invest more time into making it extendable and release it as a gem. For now I feel it's an unnecessary complexity.
If you would like to use it please download it from our GitHub, import it into your app and start building your own form objects. Feedback is 100% welcomed and pull-requests will also be accepted. I will continue to use form objects and push changes into the repo when I feel they are universally relevant and valuable.
My reasoning for not gemifying ActiveForm is that the custom not-rails-core logic is relatively small, and while ActiveForm currently fits 99% of my use cases, I do sometimes make modifications based on the product requirements. Manually importing the library into app/lib/active_form/ makes modification a lot simpler. I've utilized as many Rails modules as I can to make maintenance a lot easier as I just have to update Rails and I get the updates for free. By utilizing Rails core modules, it's a really small library - there are only 10 methods in the Base module!
You can checkout the source code in the repo above. It's two files with a lot of comments. If you need help understanding anything feel free to reach out. I am happy to explain parts you don't understand. The comments explain a lot so hopefully it won't be necessary. Also reach out if you have ideas on how to make it better.
