Skip to main content

Progressive Forms

A progressive form splits a cm_new or cm_edit form into ordered steps. Each step is rendered on its own screen with a stepper UI, validated before the user moves on, and earlier values are kept in a database draft (ct_form_drafts) until the final step saves the record.

Use it for long forms, conditional flows and setup wizards. For short forms (1–6 fields) or fields users edit out of order, a regular form is faster.

Quick example​

rails generate cm_admin:form_draft
rails db:migrate
cm_new page_title: "Add Post" do
step "Basic details" do
cm_section "Details" do
form_field :title, input_type: :string
end
end

step "Content" do
cm_section "Content" do
form_field :body, input_type: :rich_text
end
end
end

Options​

Declare steps inside cm_new or cm_edit using the step DSL method. Each step contains cm_section and/or row blocks (the same ones used by regular forms), and each section contains form_field declarations. Both section-first and row-first layouts are supported β€” you can mix them freely within a single step.

cm_new page_title: 'Add Post' do
step 'Basic details' do
cm_section 'Details' do
form_field :title, input_type: :string
form_field :status, input_type: :single_select, helper_method: :select_options_for_status
end
end

step 'Content' do
cm_section 'Content' do
form_field :body, input_type: :rich_text
end
end
end

Steps render in declaration order. The first step is shown by default; the user advances with Next, returns with Back, and the final step's button uses the form's submit label (default Submit).

Method signature​

step(name, &block)
ArgumentTypeDescription
nameStringLabel shown in the stepper for this step. Must not be blank.
&blockProcBlock of cm_section and/or row declarations that make up the step.

step may only be used inside cm_new and cm_edit. Using it elsewhere raises an error at boot time.

How it works​

  • Next β€” validates the current step's fields; on success, redirects to the next step (or saves on the final step).
  • Back β€” returns to the previous step without re-validating. Entered values are preserved.
  • Stepper β€” a horizontal indicator at the top of the form showing completed / active / upcoming steps, plus an error state on the active step when validation fails.

Validation scoping​

When the user clicks Next, the whole record is validated (@ar_object.valid?), but only errors for fields that belong to the current step are kept. Errors for fields in other steps are discarded, so a required field in step 3 won't block the user from advancing past step 1.

A field "belongs to a step" if it is declared via form_field inside one of that step's cm_section blocks. Field membership is determined by the step's field_names, which collects field_name from each form_field in the step.

Draft state​

Values from each step are merged into a database draft (ct_form_drafts) instead of the Rails session cookie, so drafts can grow beyond the 4 KB cookie limit and uploaded files survive the steps (see Staged uploads).

Each time a progressive form is rendered it gets a unique form_id (a UUID carried in a hidden field), and a fresh draft is created for the current user β€” replacing their previous draft. Implications:

  • One draft per user β€” opening another progressive form (or refreshing the page) replaces the previous draft, so a refresh always starts the wizard over.
  • The draft is only a mechanism. There is no "Save Draft" button; nothing is written to the record's table until the final step submits.
  • State is cleared when:
    • the record is successfully saved (final step),
    • the user discards the form (staged files are purged too),
    • the user re-opens the form β€” a fresh render replaces the draft.
  • State is not cleared on validation failure or on Back navigation β€” the user can move freely between steps without losing data.

Staged uploads​

Files uploaded in a step are uploaded to Active Storage right away and attached to the draft (CtFormDraft#files), with the blob ids recorded per field. On later steps they are re-attached to the record, so users don't have to pick them again; uploading a new file for the same field replaces the staged one. On the final step they are saved with the record. Discarding the form, or destroying the draft, purges the staged files. Drafts expire 30 days after they are created (expiry_at).

Persistence​

  • cm_new β€” the record is instantiated with Model.new(draft_state) on each step render, and only saved on the final step. Nothing is written to the target record's table until the wizard completes.
  • cm_edit β€” the existing record is loaded and assign_attributes(draft_state) is applied on each step render; the cumulative attributes are saved on the final step. Intermediate steps do not persist.

Accessing previous-step data in the current step​

This is one of the most useful capabilities of progressive forms. Because @ar_object on step N is hydrated with all values collected from steps 1..N-1, you can reference prior-step values anywhere the form object is available:

Conditional fields with display_if​

Show a field in step 2 only when a step-1 field has a specific value:

cm_new page_title: 'Add Subscription' do
step 'Plan' do
cm_section 'Plan' do
form_field :plan_type, input_type: :single_select,
collection: [['Free', 'free'], ['Paid', 'paid'], ['Trial', 'trial']]
end
end

step 'Billing' do
cm_section 'Billing' do
# Only relevant when the user picked a paid plan in step 1
form_field :card_number, input_type: :string,
display_if: ->(sub) { sub.plan_type == 'paid' }
form_field :billing_email, input_type: :email,
display_if: ->(sub) { %w[paid trial].include?(sub.plan_type) }
end
end
end

Dynamic collection / helper_method​

Populate a step-2 dropdown based on a step-1 selection. helper_method receives the form object, so it can branch on prior values:

# app/helpers/cm_admin/custom_helper.rb
def select_options_for_shipping_rates(demo_form)
rates = ShippingRate.where(zone: demo_form.country) # country chosen in step 1
rates.map { |r| [r.label, r.id] }
end
step 'Address' do
cm_section 'Address' do
form_field :country, input_type: :single_select, collection: Country.all.map { |c| [c.name, c.code] }
end
end

step 'Shipping' do
cm_section 'Shipping' do
form_field :shipping_rate_id, input_type: :single_select,
helper_method: :select_options_for_shipping_rates
end
end

Model methods and validations​

Because @ar_object carries all prior values, model-level methods and validations can reference them normally:

class Subscription < ApplicationRecord
validates :card_number, presence: true, if: :paid?

def paid?
plan_type == 'paid'
end
end

The if: :paid? validation will fire correctly during step-2 validation because plan_type was set in step 1 and is present on the object.

Note on value types: prior-step values are stored as the raw permitted params (strings/arrays as submitted), exactly like a normal Rails form before save. So a boolean from step 1 will be "0" / "1" until the record is saved. Use Rails' type casting (plan_type == 'paid') or predicate methods rather than expecting true/false.

Recipes​

Basic two-step create form​

cm_new page_title: 'Add Post' do
step 'Details' do
cm_section 'Details' do
form_field :title, input_type: :string, is_required: true
form_field :status, input_type: :single_select, helper_method: :select_options_for_status
end
end

step 'Content' do
cm_section 'Content' do
form_field :body, input_type: :rich_text
form_field :is_featured, input_type: :check_box
end
end
end

Three-step form with row-first side-by-side layout​

A step can use row to place sections side-by-side, cm_section for stacked sections, or a mix of both. The row DSL creates a Bootstrap div.row wrapper, and each cm_section with col_size becomes a column within it:

cm_new page_title: 'Add Event' do
step 'Basics' do
cm_section 'Event details' do
form_field :name, input_type: :string, is_required: true
form_field :description, input_type: :text
end
end

step 'Schedule' do
row do
cm_section 'Timing', col_size: 6 do
form_field :starts_at, input_type: :date_time
form_field :ends_at, input_type: :date_time
end
cm_section 'Recurrence', col_size: 6 do
form_field :recurring, input_type: :switch
form_field :frequency, input_type: :single_select, collection: [['Daily', 'daily'], ['Weekly', 'weekly']]
end
end
end

step 'Location' do
cm_section 'Venue' do
form_field :venue_name, input_type: :string
form_field :address, input_type: :text
form_field :capacity, input_type: :integer
end
end
end

You can also mix row and cm_section within the same step β€” the row renders its columns side-by-side, and sections outside the row stack vertically below:

step 'Additional Details' do
row do
cm_section 'Content', col_size: 6 do
form_field :description, input_type: :text
form_field :body, input_type: :rich_text
end
cm_section 'Settings', col_size: 6 do
form_field :is_active, input_type: :switch
form_field :status, input_type: :single_select, helper_method: :select_options_for_status
end
end

cm_section 'Contact' do
form_field :email, input_type: :email
form_field :phone, input_type: :phone
end
end

Fields inside row blocks are included in per-step validation scoping just like fields in standalone sections.

Edit wizard​

cm_edit works identically; the record's existing attributes are the starting point, and changes are held in the draft until the final Save:

cm_edit page_title: 'Edit User' do
step 'Profile' do
cm_section 'Profile' do
form_field :first_name, input_type: :string
form_field :last_name, input_type: :string
form_field :avatar, input_type: :single_file_upload, image_preview: true
end
end

step 'Access' do
cm_section 'Access' do
form_field :role_id, input_type: :single_select, helper_method: :select_options_for_role
form_field :is_active, input_type: :switch
end
end
end

Conditional step content driven by a prior step​

Combining display_if on fields/sections with prior-step values lets you build branching wizards without separate actions:

cm_new page_title: 'Add Account' do
step 'Type' do
cm_section 'Account type' do
form_field :account_type, input_type: :radio_button_group,
collection: [['Personal', 'personal'], ['Business', 'business']]
end
end

step 'Details' do
cm_section 'Personal details', display_if: ->(a) { a.account_type == 'personal' } do
form_field :date_of_birth, input_type: :date
end
cm_section 'Business details', display_if: ->(a) { a.account_type == 'business' } do
form_field :company_name, input_type: :string
form_field :tax_id, input_type: :string
end
end
end

Nested fields inside a step​

Nested (has_many) field blocks work inside steps just like in regular forms:

step 'Items' do
cm_section 'Line items' do
nested_form_field :line_items
end
end

Best practices​

  • Order steps from required to optional. Put the minimum required fields in step 1 so the user can't get stuck on a later step because of a missing earlier value.
  • Keep steps focused. Aim for 4–8 fields per step. More than that defeats the purpose of splitting the form.
  • Use display_if for branching, not separate wizards. One wizard with conditional sections is easier to maintain than several near-duplicate cm_new actions.
  • Validate at the model level with if: conditions that reference prior-step values, rather than hand-rolling per-step validation. The progressive form already scopes errors to the current step's fields, so model validations naturally "belong" to whichever step declares the relevant field.
  • Name steps clearly. The step name is the only label the user sees in the stepper β€” "Billing" is better than "Step 2".
  • Don't duplicate fields across steps. A field declared in two steps will be validated in both, which can produce confusing error messages. Declare each field in exactly one step.
  • Prefer cm_edit wizards for complex records. Editing a 20-field record one section at a time is often calmer than a giant form, and the draft means the user won't lose in-progress edits if they step back or forward.

Caveats and limitations​

  • Prior-step fields are not re-rendered on later steps. Each step shows only its own fields. To edit a prior value the user must go Back. If you need a read-only summary of prior steps on the current screen, that is not built in today β€” render a custom partial above the form if required.
  • Button labels are not per-step customizable. "Back" and "Next" are fixed; the final step uses the form's submit_button_text (default Submit). If you need different labels, customize submit_button_text on the action and style the Back/Next buttons via CSS.
  • One draft per user, cleared on refresh. A fresh render of the form replaces the previous draft, so state does not survive a page refresh β€” it is an in-memory-style scratchpad, only present to carry the wizard to its final submit. For cross-session or multi-device persistence, model draft records explicitly in your app.
  • No partial save. For cm_new, nothing is persisted until the final step. If the user abandons the wizard midway, no record is created. If you need draft persistence, model it explicitly (e.g. a status: :draft record saved at each step).
  • Step order is fixed. There is no built-in "skip to step N" jump for the user; navigation is linear Back/Next. Conditional content within a step is supported via display_if, but the step itself always renders.
  • NewDsl β€” the cm_new action that hosts create wizards.
  • EditDsl β€” the cm_edit action that hosts edit wizards.
  • ShowHideContent β€” display_if usage, applicable to fields and sections inside steps.