Schoolgirl Uniform

🐾 Multistep form concept for Rails projects. Allows to create complex forms for a few models simultaneously. Supports selectable per step validations without data persistence into db.

Currently uses session to store data before actual save. If your sessions are stored in cookies then it has a 4 KB limit.

Installation

To start using it just add this line to your application's Gemfile:

gem 'schoolgirl_uniform'

Then you need to generate scaffold for future multistep form:

$ rails generate schoolgirl_uniform:install CatgirlsSurvey

You can also use snake case, so catgirls_survey would be identical to CatgirlsSurvey and will generate the same output during scaffolding.

Usage and Config

To achieve working multistep form you need to configure FVC:

• 👚 Form

• 👗 View

• 🎒 Controller

---

👚 Form

e.g. CatgirlsSurveyForm - app/forms/catgirls_survey_form.rb

1. Declare the steps:

def self.steps
  %w[first second third]
end

2. Define form fields:

attribute :username, String
attribute :email, String

# attribute :age, Integer, default: 0
# attribute :page_numbers, Array[Integer]
# attribute :birthday, DateTime
# attribute :published, Boolean, default: false

# attribute :description, String, default: :default_editor_description

# def default_editor_description
#   ...
# end

3. Define validation and select appropriate step for it:

validates :username, presence: true, if: proc { on_step('first') }
validates :email, presence: true,    if: proc { on_step('second') }

4. Inside save! method build your records, set them with form attributes and save them in transaction.
   Use .save!(validate: false) to skip native validations on model.
   In order to return the result set the @identifier with created records reference/references

   ( e.g. simple 1234 or complex {user_id: 1234, personal_data_id: 5678} )

def save!
  user = User.new(username: username)
  personal_data = user.build_personal_data(email: email)
  
  ActiveRecord::Base.transaction do
    user.save!(validate: false)
    personal_data.save!(validate: false)
  end
  
  @identifier = user.id
end

👗 View

• Scaffolding will generate example structure of view files:

  • show.html.erb
  • finish.html.erb
  • _wizard.html.erb
  • _form_errors.html.erb

  and steps/:

  • _first.html.erb
  • _second.html.erb
  • _third.html.erb

❗ Please notice that show and finish are action views, others are partials.
🎨 Feel free to modify html and styles around the form.

♾️ Steps

By default Scaffolding generates 3 steps, but you can modify, delete or add new steps.
Just make sure that steps are _partials and match corresponded names inside Form (e.g. CatgirlsSurveyForm):

# app/views/catgirls_survey/steps/_first.html.erb

<%= form.label :username %>
<%= form.text_field :username %>
<br>
<%= form.label :password %>
<%= form.text_field :password %>

🎒 Controller

e.g. CatgirlsSurveyController - app/controllers/catgirls_survey_controller.rb

1. Make sure you have listed all form fields (used for permit params)

def form_attributes
  [:username, :password, :email, :phone]
end

2. Fetch resource(s) from DB using identifier, which you set in .save!

  def finish
    @record = User.find_by(uuid: params[:identifier])
    ...
    # or if you have a few identifiers
    ...
    @record1 = Book.find_by(title: params[:identifier][:title])
    @record2 = Author.find_by(id: params[:identifier][:author_id])
  end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/vergilet/schoolgirl_uniform

Feel free to contribute:

1. Fork it (https://github.com/vergilet/schoolgirl_uniform/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

The gem is available as open source under the terms of the MIT License.

Copyright © 2016 Yaro.