ActForm
ActForm is the gem that provide a simple way to create form object or command object or service object, it only depends on activemodel >= 5 and provides few api.
About v0.5.0
With the power of dry-schema, ActForm now can support all the features of dry-schema, like:
class UserForm < ActForm::Base
params do
required(:name).filled.desc('Name')
optional(:age).value(:integer).desc('Age')
optional(:address).desc('Address')
optional(:nickname).default('nick').desc('Nick')
# below will support in the future
# attribute :desc, default: ->{ 'desc' }
end
endAdd we can integrate with grape easyly.
module WorkWithGrapeSpec
class API < Grape::API
format :json
contract UserForm.contract
get '/foo' do
'hello world'
end
contract UserForm.contract do
required(:desc).filled
end
get '/bar' do
'hello world'
end
end
endUsage
API - attribute
class UserForm < ActForm::Base
attribute :name, required: true
attribute :age, type: :integer
attribute :address
attribute :nickname, default: 'nick'
attribute :desc, default: ->{ 'desc' }
end
form = UserForm.new(name: 'su', age: '18', address: 'somewhere')
form.name # => 'su'
form.age # => 18
form.address # => 'somewhere'
form.nickname # => 'nick'
form.desc # => 'desc'
# override default
form.nickname = 'hello'
form.nickname # => 'hello'
# required
form = UserForm.new(age: '18', address: 'somewhere')
form.valid? # => false
form.errors.full_messages # => ["Name require a value"]Difference between required and validates_presence_of
required will run before the validation, and it will cancel other validations if return false.
form object
API - valid?
Compliant with the active model api
class PhoneForm < ActForm::Base
attribute :phone
validates_format_of :phone, with: /\A\d{11}\z/i
end
form = PhoneForm.new
form.valid? # => false
form.errors.full_messages # => ["Phone is invalid"]
PhoneForm.new(phone: '12345678901').valid? # => trueAPI - sync
sync only copy attributes to target, will not trigger validate
target = Class.new do
attr_accessor :phone
end.new
form = PhoneForm.new(phone: '12345678901')
form.sync(target)
target.phone # => '12345678901'API - save
sync to the target and call the save method when passed the validation
target = Class.new do
attr_accessor :phone
attr_reader :saved
def save
@saved = true
end
end.new
form = PhoneForm.new(phone: '12345678901')
form.save(target) # same as form.sync(target) and target.save
target.phone # => '12345678901'
target.saved # => true
form.persisted? # => trueAPI - init_by
init_by will copy attributes form target to the form, and set default target.
target = Class.new do
attr_accessor :phone
attr_reader :saved
def save
@saved = true
end
end.new
target.phone = '12345678901'
form = PhoneForm.new
form.init_by(target)
form.phone # => '12345678901'
form.save # => true
target.saved # => trueAPI - combine
form can combine to other forms
class PhoneForm < ActForm::Base
attribute :phone
validates_format_of :phone, with: /\A\d{11}\z/i
end
class EmailForm < ActForm::Base
attribute :email
validate :check_email
def check_email
errors.add(:email, :blank) if email.blank?
end
end
class UserForm < ActForm::Base
combine PhoneForm, EmailForm
end
class AdminForm < ActForm::Base
combine PhoneForm
end
user_form = UserForm.new
user_form.valid?
user_form.errors.full_messages # => ["Phone is invalid", "Email can't be blank"]
UserForm.new(phone: '12345678901', email: '1').valid? # => true
admin_form = AdminForm.new
admin_form.valid?
admin_form.errors.full_messages # => ["Phone is invalid"]
AdminForm.new(phone: '12345678901').valid? # => truecommand/service object
Command object almost like form object. Command object can't init by new, and it has some new features.
API - perform, run, success?, failure?, setup
command object must respond to perform method.
class CreateUserCommand < ActForm::Command
combine UserForm
# Do some pre-inialize actions.
setup do
@name = 'foo'
end
def perform
attributes[:name] = @name
User.create(attributes)
end
end
CreateUserCommand.new
# => NoMethodError: private method `new' called for CreateUserCommand:Class
command = CreateUserCommand.run(phone: '12345678901')
if command.success?
@user = command.result
# do something...
else
command.errors.full_messages # => ["Email can't be blank"]
# do something...
endInstallation
Add this line to your application's Gemfile:
gem 'act_form'And then execute:
$ bundle
Or install it yourself as:
$ gem install act_form
Development
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.
Unit Tests
$ bundle exec rake test
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/simple-and-powerful/act_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.