Forminator

Installation

Add this line to your application's Gemfile:

gem 'forminator'

And then execute:

$ bundle

Or install it yourself as:

$ gem install forminator

Usage

First you need to configure the wizard so it knows the object that you interact with (usually a used model). If you like to persist the model you can supply a callable object that takes care of the persistence. Whether you want to persist after each step or after the final one is up to you.

Forminator.configure do |config|
  config.klass = :user
  config.persist = -> (user) { user.save }
end

To build a form wizard step you need to subclass the Forminator::Step class

class FirstStep < Forminator::Step
  validations do
    required(:email) { filled? }
    required(:password) { filled? }
  end

  # By default this returns false, so if you want to persist the object
  # after each step you need to overwrite the method
  def persist?
    true
  end
end

Then you can do:

user = User.new
some_params = { email: 'test@test.com', password: 'ineedtocryptmypassword' }
FirstStep.(user, some_params)
=> [{ valid: true }, some_params]

Each step always returns an array of 2 elements: a hash with the validity and the initially passed params. This allows for easy chaining of events.

If you want to call a custom persistence logic for a certain step you can pass an optionable callable object like so:

class CustomPersistenceLogic
  def call(user)
    # persistence logic goes here
  end
end
user = User.new
FirstStep.(user, some_params, persist: CustomPersistenceLogic.new)

The callable object will receive the original object that you interact with.

Want to build a whole flow of steps? Just use the Forminator::Flow class

steps = [FirstStep, SecondStep, LastStep]
flow = Forminator::Flow.new(steps: steps)
flow.current_step
=> FirstStep
flow.next_step
=> SecondStep

You can also add steps on the way with:

flow.add(step: IntermediateStep)

Keep in mind that you can only add steps that inherit from Forminator::Step. You can also remove steps:

flow.remove(step: LastStep)
=> LastStep

Calling remove will return the removed step.

Forminator uses Hanami::Validations which in it's own term uses Dry::Validation :heart. You can refer them for a detailed DSL about validations.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec 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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/wizardone/forminator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

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