Active Model Basics¶ ↑
This guide should provide you with all you need to get started using model classes. Active Model allows for Action Pack helpers to interact with plain Ruby objects. Active Model also helps build custom ORMs for use outside of the Rails framework.
After reading this guide, you will be able to add to plain Ruby objects:
-
The ability to behave like an Active Record model.
-
Callbacks and validations like Active Record.
-
Serializers.
-
Integration with the Rails internationalization (i18n) framework.
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.
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
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
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
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
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 if any attribute has changed. 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 will be an array of the old and new value for that field. person.changes # => {"first_name"=>[nil, "First Name"]}
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 what was 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, else returns nil.
# attr_name_change person.first_name_change # => [nil, "First Name"] person.last_name_change # => nil
Validations¶ ↑
ActiveModel::Validations
module adds the ability to validate
class 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
Naming¶ ↑
ActiveModel::Naming
adds a number of class methods which make
the 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"
Model¶ ↑
ActiveModel::Model
adds the ability to 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.
Serialization¶ ↑
ActiveModel::Serialization
provides a 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
.
person = Person.new person.serializable_hash # => {"name"=>nil} person.name = "Bob" person.serializable_hash # => {"name"=>"Bob"}
ActiveModel::Serializers¶ ↑
Rails provides two serializers ActiveModel::Serializers::JSON
and ActiveModel::Serializers::Xml
. Both of these modules
automatically include the ActiveModel::Serialization
.
ActiveModel::Serializers::JSON¶ ↑
To use the ActiveModel::Serializers::JSON
you only need to
change from ActiveModel::Serialization
to
ActiveModel::Serializers::JSON
.
class Person include ActiveModel::Serializers::JSON attr_accessor :name def attributes {'name' => nil} end end
With the as_json
you have a hash representing the model.
person = Person.new person.as_json # => {"name"=>nil} person.name = "Bob" person.as_json # => {"name"=>"Bob"}
From a JSON string you define the attributes of the model. You need to have
the attributes=
method defined 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 the attributes
using from_json
.
json = { name: 'Bob' }.to_json person = Person.new person.from_json(json) # => #<Person:0x00000100c773f0 @name="Bob"> person.name # => "Bob"
ActiveModel::Serializers::Xml¶ ↑
To use the ActiveModel::Serializers::Xml
you only need to
change from ActiveModel::Serialization
to
ActiveModel::Serializers::Xml
.
class Person include ActiveModel::Serializers::Xml attr_accessor :name def attributes {'name' => nil} end end
With the to_xml
you have a XML representing the model.
person = Person.new person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<person>\n <name nil=\"true\"/>\n</person>\n" person.name = "Bob" person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<person>\n <name>Bob</name>\n</person>\n"
From a XML string you define the attributes of the model. You need to have
the attributes=
method defined on your class:
class Person include ActiveModel::Serializers::Xml 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 the attributes
using from_xml
.
xml = { name: 'Bob' }.to_xml person = Person.new person.from_xml(xml) # => #<Person:0x00000100c773f0 @name="Bob"> person.name # => "Bob"
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
you can transform attribute
names into a more human format. The human format is defined in your locale
file.
-
config/locales/app.pt-BR.yml
yml pt-BR: activemodel: attributes: person:
name: 'Nome'
Person.human_attribute_name('name') # => "Nome"
Lint Tests¶ ↑
ActiveModel::Lint::Tests
allow 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 def setup @model = Person.new end end
$ rake 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.
SecurePassword¶ ↑
ActiveModel::SecurePassword
provides a way to securely store
any password in an encrypted form. On including this module, a
has_secure_password
class method is provided which defines an
accessor named password
with certain validations on it.
Requirements¶ ↑
ActiveModel::SecurePassword
depends on the 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.
-
This maximum length of a password is 72 (required by
bcrypt
on which ActiveModel::SecurePassword depends)
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 all validations are passed. person.password = person.password_confirmation = 'aditya' person.valid? # => true