Two kinds of multi-step forms

The creation of multi-step forms is a relatively common challenge faced in Rails programming (and probably in web development in general of course). Unlike regular CRUD interfaces, there’s not a prescribed “Rails Way” to do multi-step forms. This, plus the fact that multi-step forms are often inherently complicated, can make them a challenge.

Following is an explanation of I do multi-step forms. First, it’s helpful to understand that there are two types of them. There’s an easy kind and a hard kind.

After I explain what the easy kind and the hard kind of multi-step forms are, I’ll show an illustration of the hard kind.

The easy kind

The easy kind of multi-step form is when each step involves just one Active Record model.

In this scenario you can have a one-to-one mapping between a controller and a step in the form.

For example, let’s say that you have a form with two steps. In the first step you collect information about a user’s vehicle. The corresponding model to this first step is Vehicle. In the second step you collect information about the user’s home. The corresponding model for the second step is Home.

Your multi-step form code could involve two controllers, one called Intake::VehiclesController and the other called Intake::HomesController. (I’m making up the Instake namespace prefix because maybe we’ll decide to call this multi-step form the “intake” form.)

To be clear, the Intake::VehiclesController would exist in addition to the main scaffold-generated VehiclesController, not instead of it. Same of course with the Intake::HomesController. The reason for this is that it’s entirely likely that the “intake” controllers would have different behavior from the main controllers for those resources. For example, Intake::VehiclesController would probably only have the new and create actions, and none of the other ones like delete. Intake::VehiclesController#create action would also probably have a redirect_to that sends the user to the second step, Intake::HomesController#new, once the vehicle information is successfully collected.

To summarize the solution to the easy type of multi step form: For each step of your form, create a controller that corresponds to the Active Record model that’s associated with that step.

Again, this solution only works if your form steps and your Active Record models have a one-to-one relationship. If that’s not the case, you’re probably not dealing with the easy type of multi-step form. You’re probably dealing with the hard kind.

The hard kind

The more difficult kind of multi-step form is when there’s not a tidy one-to-one mapping between models and steps.

Let’s say, for example, that the multi-step form needs to collect user profile/account information. The first step collects first name and last name. The second step collects email and password. All four of these attributes (first name, last name, email and password) exist on the same model, User. How do we validate the first name and last name attributes in the first step when the User model wants to validate a whole User object at a time?

The answer is that we create two new concepts/objects called, perhaps, Intake::UserProfile and Intake::UserAccount. The Intake::UserProfile object knows how to validate first_name and last_name. The Intake::UserAccount knows how to validate email and password. Only after each form step is validated do we attempt to save a User record to the database.

If you found the last paragraph difficult to follow, it’s probably because I was describing a scenario that isn’t very common in Rails applications. I’m talking about creating models that don’t inherit from ActiveRecord::Base but rather that mix in ActiveModel::Model in order to gain some Active-Record-like capabilities.

All this is easier to illustrate with an example than to describe with words, so let’s get into the details of how this might be accomplished.

The tutorial

Overview

This tutorial will illustrate a multi-step form where the first step collects “user profile” information (first name and last name) and the second step collects “user account” information (email and password).

Although I’m aware of the Wicked gem, my approach doesn’t use any external libraries. I think gems lend themselves well to certain types of problems/tasks, like tasks where a uniform solution works pretty well for everyone. In my experience multi-step forms are different enough from case to case that a gem to “take out the repetitive work” doesn’t really make sense because most of the time-consuming work is unique to that app, and the rest of the work is easily handled by the benefits that Rails itself already provides.

Here’s the code for my multi-step form, starting with the user profile model.

The user profile model

What will ultimately be created in the database as a result of the user completing the multi-step form is a single User record.

For each of the two forms (again, user profile and user account) we want to be able to validate the form but we don’t necessarily want to persist the data yet. We only want to persist the data after the successful completion of the last step.

One way to achieve this is to create forms that don’t connect to an ActiveRecord::Base object, but instead connect to an ActiveModel::Model object.

If you mix in ActiveModel::Model into a plain old Ruby object, you gain the ability to plug that object into a Rails form just as you would with a regular ActiveRecord object. You also gain the ability to do validations just as you would with a regular ActiveRecord object.

Below I’ve created a class that will be used in the user profile step. I’ve called it UserProfile and put it under an arbitrarily-named Intake namespace.

module Intake
  class UserProfile
    include ActiveModel::Model
    attr_accessor :first_name, :last_name
    validates :first_name, presence: true
    validates :last_name, presence: true
  end
end

The user profile controller

This model will connect to a controller I’m calling UserProfilesController. Similar to how I put the UserProfile model class inside a namespace, I’ve put my controller class inside a namespace just so my root-level namespace doesn’t get cluttered up with the complex details of my multi-step form.

I’ve annotated the controller code with comments to explain what’s happening.

module Intake
  class UserProfilesController < ApplicationController
    def new
      # An instance of UserProfile is created just the
      # same as you would for any Active Record object.
      @user_profile = UserProfile.new
    end

    def create
      # Again, an instance of UserProfile is created
      # just the same as you would for any Active
      # Record object.
      @user_profile = UserProfile.new(user_profile_params)

      # The valid? method is also called just the same
      # as for any Active Record object.
      if @user_profile.valid?

        # Instead of persisting the values to the
        # database, we're temporarily storing the
        # values in the session.
        session[:user_profile] = {
          'first_name' => @user_profile.first_name,
          'last_name' => @user_profile.last_name
        }

        redirect_to new_intake_user_account_path
      else
        render :new
      end
    end

    private

    # The strong params work exactly as they would
    # for an Active Record object.
    def user_profile_params
      params.require(:intake_user_profile).permit(
        :first_name,
        :last_name
      )
    end
  end
end

The user profile view

Similar to how the user profile controller is very nearly the same as a “regular” controller even though no Active Record class or underlying database table is involved, the user profile form markup is indistinguishable from the code that would be used for an Active-Record-backed class.

<h2>User Profile Information</h2>

<%= form_with(model: @user_profile, url: local: true) do |f| %>
  <% if @user_profile.errors.any? %>
    <div id="error_explanation">
      <b><%= pluralize(@user_profile.errors.count, "error") %> prohibited this user profile from being saved:</b>

      <ul>
        <% @user_profile.errors.full_messages.each do |message| %>
          <li><%= message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>

  <div class="form-group">
    <%= f.label :first_name %>
    <%= f.text_field :first_name, class: 'form-control' %>
  </div>

  <div class="form-group">
    <%= f.label :last_name %>
    <%= f.text_field :last_name, class: 'form-control' %>
  </div>

  <%= f.submit 'Next Step', class: 'btn btn-primary' %>
<% end %>

The user account model

The user account model follows the exact same principles as the user profile model. Instead of inheriting from ActiveRecord::Base, it mixes in ActiveModel::Model.

module Intake
  class UserAccount
    include ActiveModel::Model
    attr_accessor :email, :password
    validates :email, presence: true
    validates :password, presence: true
  end
end

The user account controller

The user account controller differs slightly from the user profile controller because the user account controller step is the last step of the multi-step form process. I’ve added annotations to this controller’s code to explain the differences.

module Intake
  class UserAccountsController < ApplicationController
    def new
      @user_account = UserAccount.new
    end

    def create
      @user_account = UserAccount.new(user_account_params)

      if @user_account.valid?

        # The values from the previous form step need to be
        # retrieved from the session store.
        full_params = user_account_params.merge(
          first_name: session['user_profile']['first_name'],
          last_name: session['user_profile']['last_name']
        )

        # Here we finally carry out the ultimate objective:
        # creating a User record in the database.
        User.create!(full_params)

        # Upon successful completion of the form we need to
        # clean up the session.
        session.delete('user_profile')

        redirect_to users_path
      else
        render :new
      end
    end

    private

    def user_account_params
      params.require(:intake_user_account).permit(
        :email,
        :password
      )
    end
  end
end

The user account view

Like the user profile view, the user account view is indistinguishable from a regular Active Record view.

<h2>User Account Information</h2>

<%= form_with(model: @user_account, local: true) do |f| %>
  <% if @user_account.errors.any? %>
    <div id="error_explanation">
      <b><%= pluralize(@user_account.errors.count, "error") %> prohibited this user account from being saved:</b>

      <ul>
        <% @user_account.errors.full_messages.each do |message| %>
          <li><%= message %></li>
        <% end %>
      </ul>
    </div>
  <% end %>

  <div class="form-group">
    <%= f.label :email %>
    <%= f.email_field :email, class: 'form-control' %>
  </div>

  <div class="form-group">
    <%= f.label :password %>
    <%= f.password_field :password, class: 'form-control' %>
  </div>

  <%= f.submit 'Save and Finish', class: 'btn btn-primary' %>
<% end %>

Routing

Lastly, we need to tie everything together with some routing directives.

Rails.application.routes.draw do
  namespace :intake do
    resources :user_profiles, only: %i[new create]
    resources :user_accounts, only: %i[new create]
  end
end

Takeaways

There are two types of multi-step forms. The easy kind is where each step corresponds to a single Active Record model. In those cases you can use a dedicated controller per step and redirect among the steps. The harder kind is where there’s not a one-to-one mapping. In those cases you can mix in ActiveModel::Model to lend Active-Record-like behaviors to plain old Ruby objects.

In addition to the bare functionality I described above, you can imagine multi-step forms involving more sophisticated requirements, like the ability to go back to previous steps, for example. I didn’t want to clutter my tutorial with those details but I think those behaviors would be manageable enough to add on top of the underlying overall approach I describe.

As a last side note, you don’t have to use session storage to save the data from each form step until the final aggregation at the end. You could store that data any way you want, including using a full-blown Active Record class for each step. There are pros and cons to the various possible ways of doing it. One thing I like about this approach is that I don’t have any “residual” data lying around at the end that I have to clean up. I can imagine other scenarios where other approaches would be more appropriate though, e.g. multi-step forms that the user would want to be able to save and finishing filling out at a later time.

The most important thing in my mind is to keep the multi-step form code easily understandable and to make its code sufficiently modularized (e.g. using namespaces) that it doesn’t clutter up the other concerns in the application.

Is a knife a good thing?

There seem to be two main camps regarding Rails concerns. One camp says concerns are good. The other camp says concerns are bad.

I don’t buy this dichotomy. To state what ought to be obvious, not everything is either good or bad.

I’ll make a small digression to illustrate my point, using the example of a knife.

You could use a knife to stab me in the leg, or you could use a knife to whittle me a magnificent wooden sculpture.

Or, if you weren’t too familiar with knives, you could try to use a knife instead of a spoon in a misguided attempt to eat a bowl of soup.

You get the idea.

I want to discuss where concerns might be a good idea and where they might not be. In order to do this it might be helpful to start by articulating which types of problems people tend to use concerns to try to solve.

The problems that people try to solve with concerns

There are two problems I’m aware of that people try to use concerns to solve.

1. Models that are too big to be easily understood
2. Duplication across models

Both these problems could be solved in a number of ways, including by using concerns.

(Another way could be to decompose the model object into a number of smaller plain old Ruby objects. Yet more options include service objects or Interactors. All these approaches have pros and cons and could be used appropriately or inappropriately.)

The objections some programmers have to concerns

Here are some objections to concerns that I’ve read. Some I agree with. Some I don’t.

Concerns are inheritance, and composition is better than inheritance

I totally agree with this one. An often-repeated piece of advice in OOP is “prefer composition over inheritance”. I think it’s good advice.

Having said that, the advice is not “don’t ever use inheritance!” There are a lot of cases where inheritance is more appropriate than composition, even if inheritance isn’t the first thing I reach for. In the same way, the argument that “concerns are inheritance and composition is better than inheritance” does not translate to “concerns are always bad” any more than “prefer composition over inheritance” means “inheritance is always bad”.

Concerns don’t necessarily remove dependencies, they just spread them across multiple files

I agree with this point as well. It’s totally possible to slice a model up into several concerns and end up with the result that the “after” code is actually harder to understand than the “before” code.

My response to this point would be: If you’re going to use concerns, don’t use them like that!

Concerns create circular dependencies

As far as I can reason, this is true. A well-defined inheritance relationship doesn’t create a circular dependency because the parent class doesn’t know anything about the child class. Similarly, in a well-defined composition relationship, the “finer-grained” class doesn’t know about the “coarser-grained” one.

Concerns often don’t work this way. Concerns often refer to the particulars of the models that use them.

But I would say: Why, exactly, is this sort of circular dependency bad? And if I choose not to use a concern in a particular case because I want to avoid a circular dependency, what exactly my alternative? The drawbacks of whatever I use instead of a concern aren’t automatically guaranteed not to be worse than the drawbacks of using a concern.

When code is spread across multiple files, it can be unclear where methods are defined

This argument has some merit, although a very small amount. This argument could be made equally for not just concerns but for inheritance as well. So it’s really not an argument against concerns specifically, it’s an argument against concerns and inheritance equally, or perhaps an argument against spreading code across multiple files in general.

But in any case, the problem can be easily overcome using search.

What I do when I encounter fat or duplicative models

When I encounter a fat or duplicative model, concerns are pretty much never the first solution that enters my mind.

My first instinct, again, is to consider decomposing my model into some number of plain old Ruby objects. I think sometimes Rails developers forget that plain old OOP, using plain old objects, can get you a very long way.

I often find that a large class will have one or more “hidden abstractions” inside it. There’s some sub-concept hiding in the class that doesn’t yet have a name or a cohesive bundle of code. It’s there, it’s just hiding.

In those cases I try to come up with a name for the hidden abstraction. Then I create a class named after that abstraction and move the appropriate code into my new class.

I don’t always find a hidden abstraction though. Sometimes some of the bloat is just some extra flab that neither fits neatly into the model it’s in nor makes sense as a standalone concept. This is when I (sometimes) think of using a concern.

When I use concerns

In DHH’s post about concerns he says “Concerns are also a helpful way of extracting a slice of model that doesn’t seem part of its essence” (emphasis mine). I think that’s a great way to put it.

Good use cases for concerns

To me, the perfect use case for a concern is when I have, say, 10 methods on a model that have a high level of cohesion with one another and then 2 methods that relate to each other but don’t seem to be part of the model’s essence.

If those 2 odd-man-out methods could make a new object of their own, great. I’ll do that. If not, I might consider moving them to a concern.

And if multiple models require highly symmetrical behavior (e.g. some certain file attachment behavior), I’d usually rather factor that symmetrical behavior into a concern than to an inheritance tree. And usually a concern in these cases fits much more tidily over the models than trying to create a composition relationship out of it.

Lastly, I don’t want to give the impression that I use concerns all over the place. In general when I’m programming, concerns are among the last things I reach for, not the first.

My advice concerning concerns

I think concerns are fine and, in certain scenarios, great. That of course doesn’t mean I think concerns are the best solution to every problem.

When faced with any programming problem, take stock of the tools in your toolbox and use what seems appropriate. Object composition can be good. Inheritance can be good. Concerns can be good too.

What this feature is for

The credentials feature is a way of storing secrets that you don’t want to keep in plaintext, like AWS credentials for example. (In fact, the one and only thing I keep in my main Rails project’s credentials are my Active Storage AWS credentials.)

Why the credentials feature is difficult to learn about

I personally have found Rails credentials really hard to understand. I think there are three reasons why this is.

1. The official Rails docs about the credentials feature are a little terse and not easily discoverable.
2. The feature changed somewhat drastically from Rails 4 to Rails 5, even changing names from “secrets” to “credentials”.
3. I only need to use the feature once in a while, when I’m deploying an application for the first time, meaning there’s lots of time in between to forget everything I knew.

How to work with credentials without frustration

There are perhaps five important things to understand about credentials:

• Where they’re stored
• How the master key works
• How editing credentials work
• What the deal is with secrets.yml
• The steps you need to take to set up credentials on a fresh production machine

Credentials are stored in config/credentials.yml.enc

At the risk of stating the obvious, your secrets are stored in config/credentials.yml.enc. That file is encrypted.

There of course needs to be a way to securely decrypt this encrypted file. That’s done using something called a master key. The master key is just a hash string that gets stored in one of two places: a file called config/master.key (which should NOT be committed to version control) or a RAILS_MASTER_KEY environment variable.

The development master key and production master key are the same by default

A key thing to understand, which I found counterintuitive, is that unless you go out of your way to configure it differently, the master key you use in production should be the same as the master key you use in development. If your development master key is stored in config/master.key, create an identical config/master.key on production, containing the same exact key. If your development master key is stored in the RAILS_MASTER_KEY environment variable, set the production RAILS_MASTER_KEY to the exact same value.

I found this counterintuitive because usually I try to make all my passwords, etc. different for each environment I have. I thought I would need to create a different master key for my production environment. No, I need to not create a different master key.

(After I originally posted this article, it was pointed out to me that it is possible to configure different keys per environment. According to this article, keys can be configured specific to e.g. production by running rails credentials:edit --environment production.)

The credentials.yml.enc file is edited in a special way

Since it’s encrypted, the config/credentials.yml.enc file can’t be edited directly. It can only be edited using the rails credentials:edit command.

What often throws me for a loop is that a prerequisite to using rails credentials:edit is having the EDITOR environment variable set, which on a fresh production machine I usually don’t. I’m a Vim guy, so I run export EDITOR=vim and then I’m good to go. Then I can run rails credentials:edit and the command will open the credential file, decrypted, in Vim.

secrets.yml is obsolete

If you find something online that refers to secrets.yml, you’re looking at an old post. Before Rails 5.2, there was a secrets.yml and secrets.yml.enc instead of the new credentials-related files. Don’t make the mistake of conflating Rails secrets with Rails credentials (like I did several times before learning better!).

The steps for setting up credentials in production

1. Take the same master key you’re using in development and put it either in config/master.key or the RAILS_MASTER_KEY environment variable.
2. Set the EDITOR environment variable to your favorite terminal-based editor.
3. Run rails credentials:edit to verify that your master key is working properly.

Helpful links

I hope my credentials guide is the new best guide on the internet but I’ll link to the sources that helped me put this together.

• Securing Rails Applications (official Rails guide)
• Rails 5.2. release notes
• DHH’s credentials pull request
• Stefan Wintermeyer’s credentials post

Best of luck with your credential management endeavors.