~ubuntu-branches/ubuntu/utopic/ruby-validatable/utopic-proposed

= Validatable

 

Validatable is a library for adding validations.

 

by Jay[http://jayfields.blogspot.com] Fields[http://jayfields.blogspot.com]

 

== Download and Installation

 

You can download Validatable from here[http://rubyforge.org/projects/validatable] or install it with the following command.

 

 $ gem install validatable

 

== License

        

You may use, copy and redistribute this library under the same terms as Ruby itself (see http://www.ruby-lang.org/en/LICENSE.txt).

 

== Examples

 

Validation of an entire hierarchy of objects with errors aggregated at the root object.

 

        class Person

          include Validatable

          validates_presence_of :name

          attr_accessor :name

        end

 

        class PersonPresenter

          include Validatable

          include_validations_for :person

          attr_accessor :person

  

          def initialize(person)

            @person = person

          end

        end

 

        presenter = PersonPresenter.new(Person.new)

        presenter.valid? #=> false

        presenter.errors.on(:name) #=> "can't be blank"

 

Validations that turn off after X times of failed attempts.

 

        class Person

          include Validatable

          validates_presence_of :name, :times => 1

          attr_accessor :name

        end

 

        person = Person.new

        person.valid? #=> false

        person.valid? #=> true

 

Validations can be given levels. If a validation fails on a level the validations for subsequent levels will not be executed.

 

        class Person

          include Validatable

          validates_presence_of :name, :level => 1, :message => "name message"

          validates_presence_of :address, :level => 2

          attr_accessor :name, :address

        end

 

        person = Person.new

        person.valid? #=> false

        person.errors.on(:name) #=> "name message"

        person.errors.on(:address) #=> nil

 

Validations can also be given groups. Groups can be used to validate an object when it can be valid in various states.  For example a mortgage application may be valid for saving (saving a partial application), but that same mortgage application would not be valid for underwriting. In our example a application can be saved as long as a Social Security Number is present; however, an application can not be underwritten unless the name attribute contains a value.

 

  class MortgageApplication

    include Validatable

    validates_presence_of :ssn, :groups => [:saving, :underwriting]

    validates_presence_of :name, :groups => :underwriting

    attr_accessor :name, :ssn

  end

  

  application = MortgageApplication.new

  application.ssn = 377990118

  application.valid_for_saving? #=> true

  application.valid_for_underwriting? #=> false

  

As you can see, you can use an array if the validation needs to be part of various groups.  However, if the validation only applies to one group you can simply use a symbol for the group name.

 

Similar to Rails, Validatable also supports conditional validation.

 

        class Person

          include Validatable

          attr_accessor :name

          validates_format_of :name, :with => /.+/, :if => Proc.new { !name.nil? }

        end

        Person.new.valid? #=> true

                

Validatable also exposes an after_validate hook method.

 

        class Person

          include Validatable

          validates_presence_of :name

          attr_accessor :name

        end

        

        class ValidatesPresenceOf

          after_validate do |result, instance, attribute|

                        instance.errors.add("#{attribute} can't be blank") unless result

                end

        end

 

        person = Person.new

        person.valid? #=> false

        person.errors.on(:name) #=> "name can't be blank"

        

The after_validate hook yields the result of the validation being run, 

the instance the validation was run on, and the attribute that was validated

 

In the above example the attribute "name" is appended to the message.

 

See the tests for more examples

 

== Contributors

Rick Bradley, Anonymous Z, Jason Miller, Ali Aghareza, Xavier Shay, Dan Manges, Karthik Krishnan and Venkat, Clint Bishop