Merge pull request #1673 from DrSayre/adding_poro_howto

Adding poro howto

Author: NullVoxPopuli

CHANGELOG.md

@@ -64,6 +64,7 @@ Fixes:
 - [#1488](https://github.com/rails-api/active_model_serializers/pull/1488) Require ActiveSupport's string inflections (@nate00)
 
 Misc:
+- [#1673](https://github.com/rails-api/active_model_serializers/pull/1673) Adds "How to" guide on using AMS with POROs (@DrSayre)
 - [#1608](https://github.com/rails-api/active_model_serializers/pull/1608) Move SerializableResource to ActiveModelSerializers (@groyoh)
 - [#1602](https://github.com/rails-api/active_model_serializers/pull/1602) Add output examples to Adapters docs (@remear)
 - [#1557](https://github.com/rails-api/active_model_serializers/pull/1557) Update docs regarding overriding the root key (@Jwan622)

docs/README.md

@@ -27,6 +27,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
 - [Testing ActiveModelSerializers](howto/test.md)
 - [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
+- [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)
 
 ## Integrations
 

docs/howto/serialize_poro.md

@@ -0,0 +1,32 @@
+[Back to Guides](../README.md)
+
+# How to serialize a Plain-Old Ruby Object (PORO)
+
+When you are first getting started with ActiveModelSerializers, it may seem only `ActiveRecord::Base` objects can be serializable, but pretty much any object can be serializable with ActiveModelSerializers.  Here is an example of a PORO that is serializable:
+```ruby
+# my_model.rb
+class MyModel
+  alias :read_attribute_for_serialization :send
+  attr_accessor :id, :name, :level
+  
+  def initialize(attributes)
+    @id = attributes[:id]
+    @name = attributes[:name]
+    @level = attributes[:level]
+  end
+
+  def self.model_name
+    @_model_name ||= ActiveModel::Name.new(self)
+  end
+end
+```
+
+Fortunately, ActiveModelSerializers provides a [`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb) which you can use in production code that will make your PORO a lot cleaner.  The above code now becomes:
+```ruby
+# my_model.rb
+class MyModel < ActiveModelSerializers::Model
+  attr_accessor :id, :name, :level
+end
+```
+
+The default serializer would be `MyModelSerializer`.