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 ActiveRecord and 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 YAAF.
- Motivation
- Installation
- Usage
- Sample app
- Links
- Development
- Contributing
- License
- Code of Conduct
- Credits
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 fromYAAF::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. WithYAAFyou 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:
gem 'yaaf'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.
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 < YAAF::Form
attr_accessor :user_attributes
def initialize(attributes)
super(attributes)
@models = [user]
end
def user
@user ||= User.new(user_attributes)
end
endBy 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
endForm objects supports calls to valid?, invalid?, errors, save, save!, such as any ActiveModel model. The return values match the corresponding ActiveModel methods.
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 < YAAF::Form
validates :phone, presence: true
validate :a_custom_validation
# ...
def a_custom_validation
# ...
end
endValidations can be skipped the same way as for ActiveModel models:
# 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
endForm 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 < YAAF::Form
# Customized behavior
endThe .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 callsuperto automatically make the attributes be stored in instance variables. If you use it, make sure to also addattr_accessors, otherwiseActiveModelwill fail.
The #valid? method will perform both the form object validations and the models validations. It will return true or false and store the errors in the form object.
By default YAAF form objects will store model errors in the form object under the same key. For example if a model has an email attribute that had an error, the form object will provide an error under the email key (e.g. form_object.errors[:email]).
The #invalid? method is exactly the same as the .valid? method but will return the opposite boolean value.
The #errors method will return an ActiveModel::Errors object such as any other ActiveModel model.
The #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 true. Models that were #marked_for_destruction? will be destroyed instead of saved, this can be done by calling #mark_for_destruction on an ActiveRecord model.
Defined callbacks will be called in the following order:
before_validationafter_validationbefore_saveafter_saveafter_commit/after_rollback
Options:
- If
validate: falseis send as options to thesavecall, it will skip validations.
The #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 < YAAF::Form
validates :email, presence: true
validate :some_custom_validation
# ...
endYAAF form objects support callbacks the same way as ActiveModel models. For example:
class RegistrationForm < YAAF::Form
before_validation :normalize_attributes
after_commit :send_confirmation_email
# ...
endAvailable callbacks are (listed in execution order):
before_validationafter_validationbefore_saveafter_saveafter_commit/after_rollback
You can find a sample app making use of the gem here. Its code is also open source, and you can find it here.
- 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.
Everyone interacting in the YAAF project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
YAAF is maintained by Rootstrap with the help of our contributors.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent