YAAF (Yet Another Active Form) is a gem that let you create form objects in an easy and Rails friendly way. It makes use of
ActiveModel features in order to provide you with a form object that behaves pretty much like a Rails model, and still be completely configurable.
We were going to name this gem
ActiveForm to follow Rails naming conventions but given there are a lot of form object gems named like that we preferred to go with
Table of Contents
- Sample app
- Code of Conduct
Form Objects is a design pattern that allows us to:
- Keep views, models and controllers clean
- Create/update multiple models at the same time
- Keep business logic validations out of models
There are some other form objects gems but we felt none of them provided us all the features that we expected:
- Form objects that behave like Rails models
- Simple to use and to understand the implementation (no magic)
- Easy to customize
- Gem is well tested and maintained
For this reason we decided to build our own Form Object implementation. After several months in production without issues we decided to extract it into a gem to share it with the community.
If you want to learn more about Form Objects you can check out these great articles.
It is 71 lines long. As you can imagine, we did no magic in such a few lines of code, we just leveraged Rails modules in order to provide our form objects with a Rails-like behavior. You can review the code, it's easy to understand.
It provides a similar API to
ActiveModelmodels so you can treat them interchangeably.
You can customize it 100%. We encourage you to have your own
ApplicationFormwhich inherits from
YAAF::Formand make the customizations you'd like for your app.
It helps decoupling the frontend from the database. This is particularly important when using Rails as a JSON API with a frontend in React/Ember/Vue/Angular/you name it. If you were to use
accepts_nested_attributes_foryour frontend would need to know your database structure in order to build the request. With
YAAFyou can provide a the interface you think it's best.
It easily supports nested models, collection of models and associated models. You have full control on their creation.
It helps you keep your models, views and controllers thin by providing a better place where to put business logic. In the end, this will improve the quality of your codebase and make it easier to maintain and extend.
It is an abstraction from production code. It has been working well for us, I'm confident it will work well for you too :)
Add this line to your application's Gemfile:
And then execute:
$ bundle install
Or install it yourself as:
$ gem install yaaf
In the following sections we explain some basic usage and the API provided by the gem. You can also find some recipes here.
Setting up a form object
In order to use a
YAAF form object, you need to inherit from
YAAF::Form and define the
@models of the form, for example:
# app/forms/registration_form.rb class RegistrationForm < :: attr_accessor :user_attributes def initialize(attributes) super(attributes) @models = [user] end def user @user ||= User.new(user_attributes) end end
By doing that you can work with your form object in your controller such as you'd do with a model.
# app/controllers/registrations_controller.rb class RegistrationsController < ApplicationController def create registration_form = RegistrationForm.new(user_attributes: user_params) if registration_form.save redirect_to registration_form.user else render :new end end private def user_params params.require(:user).permit(:email, :password, :password_confirmation) end end
When saving or validating a form object, it will automatically validate all its models and promote the error to the form object itself, so they are accessible to you directly from the form object.
Form objects can also define validations like:
# app/forms/registration_form.rb class RegistrationForm < :: validates :phone, presence: true validate :a_custom_validation # ... def a_custom_validation # ... end end
Validations can be skipped the same way as for
# app/controllers/registrations_controller.rb class RegistrationsController < ApplicationController def create registration_form = RegistrationForm.new(user_attributes: user_params) registration_form.save!(validate: false) end private def user_params params.require(:user).permit(:email, :password, :password_confirmation) end end
Form objects support the saving of multiple models at the same time, to prevent leaving the system in a bad state all the models are saved within a DB transaction.
A good practice would be to create an empty
ApplicationForm and make your form objects inherit from it. This way you have a centralized place to customize any
YAAF default behavior you would like.
class ApplicationForm < :: # Customized behavior end
.new method should be called with the arguments that the form object needs.
When initializing a
YAAF form object, there are two things to keep in mind
- You need to define the
@modelsinstance variables to be an array of all the models that you want to be validated/saved within the form object.
- To leverage
ActiveModel's features, you can call
superto automatically make the attributes be stored in instance variables. If you use it, make sure to also add
#valid? method will perform both the form object validations and the models validations. It will return
false and store the errors in the form object.
YAAF form objects will store model errors in the form object under the same key. For example if a model has an
#invalid? method is exactly the same as the
.valid? method but will return the opposite boolean value.
#errors method will return an
ActiveModel::Errors object such as any other
#save method will run validations. If it's invalid it will return
false, otherwise it will save all the models within a DB transaction and return
Defined callbacks will be called in the following order:
validate: falseis send as options to the
savecall, it will skip validations.
#save! method is exactly the same as the
.save method, just that if it is invalid it will raise an exception.
YAAF form objects support validations the same way as
ActiveModel models. For example:
class RegistrationForm < :: validates :email, presence: true validate :some_custom_validation # ... end
YAAF form objects support callbacks the same way as
ActiveModel models. For example:
class RegistrationForm < :: before_validation :normalize_attributes after_commit :send_confirmation_email # ... end
Available callbacks are (listed in execution order):
- How to improve maintainability in Rails applications using patterns. Part I
- 7 Patterns to Refactor Fat ActiveRecord Models
- ActiveModel Form Objects
- Form Objects Design Pattern
- Form Object from Railscasts
- Validating Form Objects
- Disciplined Rails: Form Object Techniques & Patterns — Part 1
- Complex form objects with Rails
- How to keep your controllers thin with form objects
After checking out the repo, run
bin/setup to install dependencies. Then, run
bundle exec rspec to run the tests. You can also run
bin/console for an interactive prompt that will allow you to experiment.
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, which will create a git tag for the version, push git commits and tags, and push the
.gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/rootstrap/yaaf. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the YAAF project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.