Lite::Form

Lite::Form is a library for using the form object pattern to separate business logic from model from classes.

Installation

Add this line to your application's Gemfile:

gem 'lite-form'

And then execute:

$ bundle

Or install it yourself as:

$ gem install lite-form

Table of Contents

• Setup
• Usage
• Forms

Setup

Generators

Use rails g form NAME will generate the following files:

app/forms/[name]_form.rb

If a ApplicationForm file in the app/forms directory is available, the generator will create file that inherit from ApplicationForm if not it will fallback to Lite::Form::Base.

Forms

You will need to fill this class with the methods and actions you want to perform:

class UserForm < ApplicationForm

  # Setup up your form attributes using active model attributes
  # or PORO attr_*
  attribute :name, :string
  attribute :age, :integer, default: 18

  attr_accessor :signature

  # Setup your form validations like you would on model objects
  validates :name, presence: true

  # Access 6 predefined callbacks to trigger before, after, and
  # around your actions. Available callbacks are `initialize`
  # `commit`, `create`, `rollback`, `save`, and `update`.
  before_create :prepend_signature!
  after_update :append_signature!

  private

  # Action methods are required methods that get executed when
  # you call an active model persistence such as `create`,
  # `save`, and `update`
  def create_action
    # Propagation methods help you perform an action on an object.
    # If successful is returns the result else it adds the object
    # errors to the form object. Available propagation methods are:
    # `create_and_return!(object, params)`,
    # `update_and_return!(object, params)`,
    # `save_and_return!(object)`
    create_and_return!(User, attributes)
  end

  def update_action
    run_callbacks(:commit) do
      ActiveRecord::Base.transaction do
        user = User.find(attributes[:id])
        update_and_return!(user, attributes.slice(:id))

        # The `save_and_return!` supports on/off validation
        user.settings.web_notification = true
        save_and_return!(user.settings, validate: false)
      end
    end
  rescue StandardError => e
    # This will run the `rollback` callback and re-raise the error.
    raise_transaction_rollback(e)
  end

  def prepend_signature!
    self.signature = "Prefix #{name}"
  end

  def append_signature!
    self.signature = "#{signature} Suffix"
  end

end

Usage

To access the form you need to pass the object to the form class and thats it.

form = UserForm.new(params)
form.save #=> UserForm object

# - or -

UserForm.create(params) #=> UserForm object

# - or -

UserForm.perform(:update, params) do |result, success, failure|
  success.call { redirect_to(user_path, notice: "User can be found at: #{result}") }
  failure.call { redirect_to(root_path, notice: "User cannot be found at: #{result}") }
end

Forms

The following mixins are included for you in the form base file so you can use it to setup your form in any way, shape and form. The forms model_name will tried to be inferred from the form object name, if not it will default back to its class name. There are also 4 most common callbacks used with forms already setup to be used.

# Default mixins that are included
extend ActiveModel::Callbacks
extend ActiveModel::Naming
extend ActiveModel::Translation

include ActiveModel::Model
include ActiveModel::Attributes
include ActiveModel::Dirty
include ActiveModel::Serialization

# Default callbacks that are defined
define_model_callbacks :initialize
define_model_callbacks :commit
define_model_callbacks :create
define_model_callbacks :rollback
define_model_callbacks :save
define_model_callbacks :update

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/[USERNAME]/lite-form. 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.

Code of Conduct

Everyone interacting in the Lite::Form project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.