aboutsummaryrefslogtreecommitdiffstats
path: root/activemodel
diff options
context:
space:
mode:
authorMislav Marohnić <mislav.marohnic@gmail.com>2010-07-22 09:59:58 +0200
committerMislav Marohnić <mislav.marohnic@gmail.com>2010-07-22 10:03:55 +0200
commit3e196db6ad57abcd9fc07ec2c5044b85bb13217e (patch)
tree5a2d420319b0ece5bb625a48da912d5d932fa2f6 /activemodel
parent6b11d0bf68ecb1960f6a6dc5b11bb8cc904df5a8 (diff)
downloadrails-3e196db6ad57abcd9fc07ec2c5044b85bb13217e.tar.gz
rails-3e196db6ad57abcd9fc07ec2c5044b85bb13217e.tar.bz2
rails-3e196db6ad57abcd9fc07ec2c5044b85bb13217e.zip
improve Active Model README
- fix indentation problems - revised introductory text to state right away what the library is - improved examples: reduce heavy usage of ellipsis, don't mark paragraphs of text as code
Diffstat (limited to 'activemodel')
-rw-r--r--activemodel/README.rdoc124
1 files changed, 51 insertions, 73 deletions
diff --git a/activemodel/README.rdoc b/activemodel/README.rdoc
index 6f162ef408..89cacbcab4 100644
--- a/activemodel/README.rdoc
+++ b/activemodel/README.rdoc
@@ -1,21 +1,21 @@
-= Active Model - defined interfaces for Rails
-
-Prior to Rails 3.0, if a plugin or gem developer wanted to be able to have
-an object interact with Action Pack helpers, it was required to either
-copy chunks of code from Rails, or monkey patch entire helpers to make them
-handle objects that did not look like Active Record. This generated code
-duplication and fragile applications that broke on upgrades.
-
-Active Model is a solution for this problem.
-
-Active Model provides a known set of interfaces that your objects can implement
-to then present a common interface to the Action Pack helpers. You can include
-functionality from the following modules:
-
-* Adding attribute magic to your objects
-
- Add prefixes and suffixes to defined attribute methods...
-
+= Active Model -- model interfaces for Rails
+
+Active Model provides a known set of interfaces for usage in model classes.
+They allow for Action Pack helpers to interact with non-ActiveRecord models,
+for example. Active Model also helps building custom ORMs for use outside of
+the Rails framework.
+
+Prior to Rails 3.0, if a plugin or gem developer wanted to have an object
+interact with Action Pack helpers, it was required to either copy chunks of
+code from Rails, or monkey patch entire helpers to make them handle objects
+that did not exacly conform to the Active Record interface. This would result
+in code duplication and fragile applications that broke on upgrades.
+
+Active Model solves this. You can include functionality from the following
+modules:
+
+* Add attribute magic to objects
+
class Person
include ActiveModel::AttributeMethods
@@ -23,17 +23,18 @@ functionality from the following modules:
define_attribute_methods [:name, :age]
attr_accessor :name, :age
-
+
def clear_attribute(attr)
send("#{attr}=", nil)
end
end
- ...gives you clear_name, clear_age.
+ person.clear_name
+ person.clear_age
{Learn more}[link:classes/ActiveModel/AttributeMethods.html]
-* Adding callbacks to your objects
+* Callbacks for certain operations
class Person
extend ActiveModel::Callbacks
@@ -45,26 +46,16 @@ functionality from the following modules:
end
end
end
-
- ...gives you before_create, around_create and after_create class methods that
- wrap your create method.
-
+
+ This generates +before_create+, +around_create+ and +after_create+
+ class methods that wrap your create method.
+
{Learn more}[link:classes/ActiveModel/CallBacks.html]
-* For classes that already look like an Active Record object
+* Tracking value changes
- class Person
- include ActiveModel::Conversion
- end
-
- ...returns the class itself when sent :to_model
-
- {Learn more}[link:classes/ActiveModel/Conversion.html]
+ The ActiveModel::Dirty module allows for tracking attribute changes:
-* Tracking changes in your object
-
- Provides all the value tracking features implemented by ActiveRecord...
-
person = Person.new
person.name # => nil
person.changed? # => false
@@ -75,14 +66,14 @@ functionality from the following modules:
person.name = 'robert'
person.save
person.previous_changes # => {'name' => ['bob, 'robert']}
-
+
{Learn more}[link:classes/ActiveModel/Dirty.html]
-* Adding +errors+ support to your object
+* Adding +errors+ interface to objects
- Provides the error messages to allow your object to interact with Action Pack
- helpers seamlessly...
-
+ Exposing error messages allows objects to interact with Action Pack
+ helpers seamlessly.
+
class Person
def initialize
@@ -102,51 +93,38 @@ functionality from the following modules:
end
- ... gives you...
-
person.errors.full_messages
# => ["Name Can not be nil"]
+
person.errors.full_messages
# => ["Name Can not be nil"]
{Learn more}[link:classes/ActiveModel/Errors.html]
-* Testing the compliance of your object
+* Model name introspection
- Use ActiveModel::Lint to test the compliance of your object to the
- basic ActiveModel API...
-
- {Learn more}[link:classes/ActiveModel/Lint/Tests.html]
-
-* Providing a human face to your object
-
- ActiveModel::Naming provides your model with the model_name convention
- and a human_name attribute...
-
class NamedPerson
extend ActiveModel::Naming
end
- ...gives you...
-
NamedPerson.model_name #=> "NamedPerson"
NamedPerson.model_name.human #=> "Named person"
{Learn more}[link:classes/ActiveModel/Naming.html]
-* Adding observer support to your objects
+* Observer support
- ActiveModel::Observers allows your object to implement the Observer
- pattern in a Rails App and take advantage of all the standard observer
- functions.
+ ActiveModel::Observers allows your object to implement the Observer
+ pattern in a Rails App and take advantage of all the standard observer
+ functions.
{Learn more}[link:classes/ActiveModel/Observer.html]
-* Making your object serializable
+* Making objects serializable
- ActiveModel::Serialization provides a standard interface for your object
- to provide to_json or to_xml serialization...
-
+ ActiveModel::Serialization provides a standard interface for your object
+ to provide +to_json+ or +to_xml+ serialization.
+
s = SerialPerson.new
s.serializable_hash # => {"name"=>nil}
s.to_json # => "{\"name\":null}"
@@ -154,36 +132,36 @@ functionality from the following modules:
{Learn more}[link:classes/ActiveModel/Serialization.html]
-* Integrating with Rail's internationalization (i18n) handling through
- ActiveModel::Translations...
+* Internationalization (i18n) support
class Person
extend ActiveModel::Translation
end
+
+ Person.human_attribute_name('my_attribute')
+ #=> "My attribute"
{Learn more}[link:classes/ActiveModel/Translation.html]
-* Providing a full Validation stack for your objects...
+* Validation support
class Person
include ActiveModel::Validations
attr_accessor :first_name, :last_name
-
validates_each :first_name, :last_name do |record, attr, value|
record.errors.add attr, 'starts with z.' if value.to_s[0] == ?z
end
end
-
person = Person.new
person.first_name = 'zoolander'
- person.valid? #=> false
+ person.valid? #=> false
{Learn more}[link:classes/ActiveModel/Validations.html]
-* Make custom validators
+* Custom validators
class Person
include ActiveModel::Validations
@@ -196,7 +174,7 @@ functionality from the following modules:
record.errors[:name] = "must exist" if record.name.blank?
end
end
-
+
p = ValidatorPerson.new
p.valid? #=> false
p.errors.full_messages #=> ["Name must exist"]