rootstrap/yaaf

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
  • Why YAAF?
• Installation
• Usage
  • Setting up a form object
  • #initialize
  • #valid?
  • #invalid?
  • #errors
  • #save
  • #save!
  • Validations
  • Callbacks
• Sample app
• Links
• Development
• Contributing
• License
• Code of Conduct
• Credits

Form Objects is a design pattern that allows us to:

1. Keep views, models and controllers clean
2. Create/update multiple models at the same time
3. 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:

1. Form objects that behave like Rails models
2. Simple to use and to understand the implementation (no magic)
3. Easy to customize
4. 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 ActiveModel models so you can treat them interchangeably.

• You can customize it 100%. We encourage you to have your own ApplicationForm which inherits from YAAF::Form and 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_for your frontend would need to know your database structure in order to build the request. With YAAF you 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
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

Form 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
end

Validations 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
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 < YAAF::Form
  # Customized behavior
end

The .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

1. You need to define the @models instance variables to be an array of all the models that you want to be validated/saved within the form object.
2. To leverage ActiveModel's features, you can call super to automatically make the attributes be stored in instance variables. If you use it, make sure to also add attr_accessors, otherwise ActiveModel will 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.

Defined callbacks will be called in the following order:

• before_validation
• after_validation
• before_save
• after_save
• after_commit/after_rollback

Options:

• If validate: false is send as options to the save call, 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

  # ...
end

YAAF 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

  # ...
end

Available callbacks are (listed in execution order):

• before_validation
• after_validation
• before_save
• after_save
• after_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.