| Path: | README |
| Last Update: | Wed Dec 19 23:41:27 -0600 2007 |
Compatible with Rails v1.2.2 through v2.0.2 (Active Record v1.15.2 through v2.0.2)
This RubyGem and Rails plugin adds a validates_constancy_of validation to Active Record. It allows you to prevent particular database fields from being changed after a record is created. A validation error occurs on updates if an attribute of a model object is different from its value in the database.
The code is packaged as both a RubyGem and a Rails plugin. You can use either one, depending on what your needs are.
The Validates Constancy gem is compatible with various versions of Rails (Active Record) — see the test subdirectories of constancy.rubyforge.org/svn/gem/branches. You can install the gem with the command:
gem install validates_constancy
The Validates Constancy plugin is compatible with the latest released version of the Rails framework (and possibly also other versions — see constancy.rubyforge.org/svn/plugin/test). You can install the plugin with the command:
ruby script/plugin install http://constancy.rubyforge.org/svn/plugin/validates_constancy
Use the gem (constancy.rubyforge.org/svn/gem) if you‘re using Active Record apart from Rails, or for compatibility with a version of Rails (Active Record) that is not supported by the plugin. Use the plugin if your Rails version is up to date and if you like the convenience of a Rails plugin.
Here‘s how to use this validation in your code.
class Person < ActiveRecord::Base
# Prevent changes to Person#social_security_number.
validates_constancy_of :social_security_number
end
The validation takes two options, :if and :message. These may be familiar because several of Active Record‘s validations also use them. The :if option takes a Proc, or a symbol, or string with a model object argument and a return value of true or false.
class Comment < ActiveRecord::Base
# Prevent changes to Comment#text if it is "locked."
validates_constancy_of :text, :if => Proc.new { |comment| comment.locked? }
end
The default error message is "can‘t be changed". Use your own error message by specifying the :message option.
class LicensePlate < ActiveRecord::Base
# Prevent changes to LicensePlate#number.
validates_constancy_of :number,
:message => 'is off-limits! What are you thinking?'
end
More than one model attribute can be specified. Any specified options will be applied to all the specified attributes.
With associations, validate the constancy of a foreign key, not the instance variable itself: validates_constancy_of :invoice_id instead of validates_constancy_of :invoice.
Also note the warning under Inheritable callback queues in api.rubyonrails.org/classes/ActiveRecord/Callbacks.html. "In order for inheritance to work for the callback queues, you must specify the callbacks before specifying the associations. Otherwise, you might trigger the loading of a child before the parent has registered the callbacks and they won‘t be inherited." Validates Constancy uses these callback queues, so you‘ll want to specify associations after validates_constancy_of statements in your model classes.
There‘s a suite of tests that exercises all the functionality of Validates Constancy. You can check out a version of the test suite from the repository according to the version of Rails (Active Record) it works with.
Then read rails_*/doc/README_FOR_APP for instructions on how to run the tests.
Copyright © 2007 Nils Jonsson (nils@alumni.rice.edu)
Released under the MIT license.