Skip to content
Browse files

Adding documentation for ActiveModel::Serialization

  • Loading branch information...
1 parent e606328 commit 19814df40d171b2ed83875a36d7361881ccf2e70 @mikel mikel committed Jan 17, 2010
View
14 activemodel/README
@@ -141,4 +141,16 @@ functionality from the following modules:
functions.
{Learn more}[link:classes/ActiveModel/Observer.html]
-
+
+* Making your object serializable
+
+ 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}"
+ s.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
+
+ {Learn more}[link:classes/ActiveModel/Serialization.html]
+
View
58 activemodel/lib/active_model/serialization.rb
@@ -2,6 +2,64 @@
require 'active_support/core_ext/hash/slice'
module ActiveModel
+
+ # Provides a basic serialization to a serializable_hash for your object.
+ #
+ # A minimal implementation could be:
+ #
+ # class Person
+ #
+ # include ActiveModel::Serialization
+ #
+ # attr_accessor :name
+ #
+ # def attributes
+ # @attributes ||= {'name' => 'nil'}
+ # end
+ #
+ # end
+ #
+ # Which would provide you with:
+ #
+ # person = Person.new
+ # person.serializable_hash # => {"name"=>nil}
+ # person.name = "Bob"
+ # person.serializable_hash # => {"name"=>"Bob"}
+ #
+ # You need to declare some sort of attributes hash which contains the attributes
+ # you want to serialize and their current value.
+ #
+ # Most of the time though, you will want to include the JSON or XML
+ # serializations. Both of these modules automatically include the
+ # ActiveModel::Serialization module, so there is no need to explicitly
+ # include it.
+ #
+ # So a minimal implementation including XML and JSON would be:
+ #
+ # class Person
+ #
+ # include ActiveModel::Serializers::JSON
+ # include ActiveModel::Serializers::Xml
+ #
+ # attr_accessor :name
+ #
+ # def attributes
+ # @attributes ||= {'name' => 'nil'}
+ # end
+ #
+ # end
+ #
+ # Which would provide you with:
+ #
+ # person = Person.new
+ # person.serializable_hash # => {"name"=>nil}
+ # person.to_json # => "{\"name\":null}"
+ # person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
+ #
+ # person.name = "Bob"
+ # person.serializable_hash # => {"name"=>"Bob"}
+ # person.to_json # => "{\"name\":\"Bob\"}"
+ # person.to_xml # => "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<serial-person...
module Serialization
def serializable_hash(options = nil)
options ||= {}
View
4 activemodel/lib/active_model/serializers/xml.rb
@@ -85,8 +85,8 @@ def initialize(serializable, options = nil)
@options[:except] = Array.wrap(@options[:except]).map { |n| n.to_s }
end
- # To replicate the behavior in ActiveRecord#attributes,
- # <tt>:except</tt> takes precedence over <tt>:only</tt>. If <tt>:only</tt> is not set
+ # To replicate the behavior in ActiveRecord#attributes, <tt>:except</tt>
+ # takes precedence over <tt>:only</tt>. If <tt>:only</tt> is not set
# for a N level model but is set for the N+1 level models,
# then because <tt>:except</tt> is set to a default value, the second
# level model can have both <tt>:except</tt> and <tt>:only</tt> set. So if

0 comments on commit 19814df

Please sign in to comment.
Something went wrong with that request. Please try again.