1 Introduction
Active Model is a library containing various modules used in developing classes that need some features present on Active Record. Some of these modules are explained below.
1.1 Attribute Methods
The ActiveModel::AttributeMethods
module can add custom prefixes and suffixes
on methods of a class. It is used by defining the prefixes and suffixes and
which methods on the object will use them.
class Person include ActiveModel::AttributeMethods attribute_method_prefix 'reset_' attribute_method_suffix '_highest?' define_attribute_methods 'age' attr_accessor :age private def reset_attribute(attribute) send("#{attribute}=", 0) end def attribute_highest?(attribute) send(attribute) > 100 end end person = Person.new person.age = 110 person.age_highest? # => true person.reset_age # => 0 person.age_highest? # => false
1.2 Callbacks
ActiveModel::Callbacks
gives Active Record style callbacks. This provides an
ability to define callbacks which run at appropriate times.
After defining callbacks, you can wrap them with before, after and around
custom methods.
class Person extend ActiveModel::Callbacks define_model_callbacks :update before_update :reset_me def update run_callbacks(:update) do # This method is called when update is called on an object. end end def reset_me # This method is called when update is called on an object as a before_update callback is defined. end end
1.3 Conversion
If a class defines persisted?
and id
methods, then you can include the
ActiveModel::Conversion
module in that class, and call the Rails conversion
methods on objects of that class.
class Person include ActiveModel::Conversion def persisted? false end def id nil end end person = Person.new person.to_model == person # => true person.to_key # => nil person.to_param # => nil
1.4 Dirty
An object becomes dirty when it has gone through one or more changes to its
attributes and has not been saved. ActiveModel::Dirty
gives the ability to
check whether an object has been changed or not. It also has attribute based
accessor methods. Let's consider a Person class with attributes first_name
and last_name
:
class Person include ActiveModel::Dirty define_attribute_methods :first_name, :last_name def first_name @first_name end def first_name=(value) first_name_will_change! @first_name = value end def last_name @last_name end def last_name=(value) last_name_will_change! @last_name = value end def save # do save work... changes_applied end end
1.4.1 Querying object directly for its list of all changed attributes.
person = Person.new person.changed? # => false person.first_name = "First Name" person.first_name # => "First Name" # returns true if any of the attributes have unsaved changes. person.changed? # => true # returns a list of attributes that have changed before saving. person.changed # => ["first_name"] # returns a Hash of the attributes that have changed with their original values. person.changed_attributes # => {"first_name"=>nil} # returns a Hash of changes, with the attribute names as the keys, and the # values as an array of the old and new values for that field. person.changes # => {"first_name"=>[nil, "First Name"]}
1.4.2 Attribute based accessor methods
Track whether the particular attribute has been changed or not.
# attr_name_changed? person.first_name # => "First Name" person.first_name_changed? # => true
Track the previous value of the attribute.
# attr_name_was accessor person.first_name_was # => nil
Track both previous and current value of the changed attribute. Returns an array if changed, otherwise returns nil.
# attr_name_change person.first_name_change # => [nil, "First Name"] person.last_name_change # => nil
1.5 Validations
The ActiveModel::Validations
module adds the ability to validate objects
like in Active Record.
class Person include ActiveModel::Validations attr_accessor :name, :email, :token validates :name, presence: true validates_format_of :email, with: /\A([^\s]+)((?:[-a-z0-9]\.)[a-z]{2,})\z/i validates! :token, presence: true end person = Person.new person.token = "2b1f325" person.valid? # => false person.name = 'vishnu' person.email = 'me' person.valid? # => false person.email = 'me@vishnuatrai.com' person.valid? # => true person.token = nil person.valid? # => raises ActiveModel::StrictValidationFailed
1.6 Naming
ActiveModel::Naming
adds a number of class methods which make naming and routing
easier to manage. The module defines the model_name
class method which
will define a number of accessors using some ActiveSupport::Inflector
methods.
class Person extend ActiveModel::Naming end Person.model_name.name # => "Person" Person.model_name.singular # => "person" Person.model_name.plural # => "people" Person.model_name.element # => "person" Person.model_name.human # => "Person" Person.model_name.collection # => "people" Person.model_name.param_key # => "person" Person.model_name.i18n_key # => :person Person.model_name.route_key # => "people" Person.model_name.singular_route_key # => "person"
1.7 Model
ActiveModel::Model
adds the ability for a class to work with Action Pack and
Action View right out of the box.
class EmailContact include ActiveModel::Model attr_accessor :name, :email, :message validates :name, :email, :message, presence: true def deliver if valid? # deliver email end end end
When including ActiveModel::Model
you get some features like:
- model name introspection
- conversions
- translations
- validations
It also gives you the ability to initialize an object with a hash of attributes, much like any Active Record object.
email_contact = EmailContact.new(name: 'David', email: 'david@example.com', message: 'Hello World') email_contact.name # => 'David' email_contact.email # => 'david@example.com' email_contact.valid? # => true email_contact.persisted? # => false
Any class that includes ActiveModel::Model
can be used with form_for
,
render
and any other Action View helper methods, just like Active Record
objects.
1.8 Serialization
ActiveModel::Serialization
provides basic serialization for your object.
You need to declare an attributes Hash which contains the attributes you want to
serialize. Attributes must be strings, not symbols.
class Person include ActiveModel::Serialization attr_accessor :name def attributes {'name' => nil} end end
Now you can access a serialized Hash of your object using the serializable_hash
method.
person = Person.new person.serializable_hash # => {"name"=>nil} person.name = "Bob" person.serializable_hash # => {"name"=>"Bob"}
1.8.1 ActiveModel::Serializers
Active Model also provides the ActiveModel::Serializers::JSON
module
for JSON serializing / deserializing. This module automatically includes the
previously discussed ActiveModel::Serialization
module.
1.8.1.1 ActiveModel::Serializers::JSON
To use ActiveModel::Serializers::JSON
you only need to change the
module you are including from ActiveModel::Serialization
to ActiveModel::Serializers::JSON
.
class Person include ActiveModel::Serializers::JSON attr_accessor :name def attributes {'name' => nil} end end
The as_json
method, similar to serializable_hash
, provides a Hash representing
the model.
person = Person.new person.as_json # => {"name"=>nil} person.name = "Bob" person.as_json # => {"name"=>"Bob"}
You can also define the attributes for a model from a JSON string.
However, you need to define the attributes=
method on your class:
class Person include ActiveModel::Serializers::JSON attr_accessor :name def attributes=(hash) hash.each do |key, value| send("#{key}=", value) end end def attributes {'name' => nil} end end
Now it is possible to create an instance of Person
and set attributes using from_json
.
json = { name: 'Bob' }.to_json person = Person.new person.from_json(json) # => #<Person:0x00000100c773f0 @name="Bob"> person.name # => "Bob"
1.9 Translation
ActiveModel::Translation
provides integration between your object and the Rails
internationalization (i18n) framework.
class Person extend ActiveModel::Translation end
With the human_attribute_name
method, you can transform attribute names into a
more human-readable format. The human-readable format is defined in your locale file(s).
- config/locales/app.pt-BR.yml
pt-BR: activemodel: attributes: person: name: 'Nome'
Person.human_attribute_name('name') # => "Nome"
1.10 Lint Tests
ActiveModel::Lint::Tests
allows you to test whether an object is compliant with
the Active Model API.
-
app/models/person.rb
class Person include ActiveModel::Model end
-
test/models/person_test.rb
require 'test_helper' class PersonTest < ActiveSupport::TestCase include ActiveModel::Lint::Tests setup do @model = Person.new end end
$ rails test Run options: --seed 14596 # Running: ...... Finished in 0.024899s, 240.9735 runs/s, 1204.8677 assertions/s. 6 runs, 30 assertions, 0 failures, 0 errors, 0 skips
An object is not required to implement all APIs in order to work with Action Pack. This module only intends to provide guidance in case you want all features out of the box.
1.11 SecurePassword
ActiveModel::SecurePassword
provides a way to securely store any
password in an encrypted form. When you include this module, a
has_secure_password
class method is provided which defines
a password
accessor with certain validations on it.
1.11.1 Requirements
ActiveModel::SecurePassword
depends on bcrypt
,
so include this gem in your Gemfile
to use ActiveModel::SecurePassword
correctly.
In order to make this work, the model must have an accessor named password_digest
.
The has_secure_password
will add the following validations on the password
accessor:
- Password should be present.
- Password should be equal to its confirmation (provided
password_confirmation
is passed along). - The maximum length of a password is 72 (required by
bcrypt
on which ActiveModel::SecurePassword depends)
1.11.2 Examples
class Person include ActiveModel::SecurePassword has_secure_password attr_accessor :password_digest end person = Person.new # When password is blank. person.valid? # => false # When the confirmation doesn't match the password. person.password = 'aditya' person.password_confirmation = 'nomatch' person.valid? # => false # When the length of password exceeds 72. person.password = person.password_confirmation = 'a' * 100 person.valid? # => false # When only password is supplied with no password_confirmation. person.password = 'aditya' person.valid? # => true # When all validations are passed. person.password = person.password_confirmation = 'aditya' person.valid? # => true
Feedback
You're encouraged to help improve the quality of this guide.
Please contribute if you see any typos or factual errors. To get started, you can read our documentation contributions section.
You may also find incomplete content or stuff that is not up to date. Please do add any missing documentation for master. Make sure to check Edge Guides first to verify if the issues are already fixed or not on the master branch. Check the Ruby on Rails Guides Guidelines for style and conventions.
If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.
And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome on the rubyonrails-docs mailing list.