README.md in adequate_serialization-0.1.1 vs README.md in adequate_serialization-1.0.0
- old
+ new
@@ -1,8 +1,7 @@
# AdequateSerialization
-[](https://travis-ci.org/CultureHQ/adequate_serialization)
[](https://github.com/CultureHQ/adeqaute_serialization)
Serializes objects adequately. `AdequateSerialization` allows you to define serializers that will convert your objects into simple hashes that are suitable for variable purposes such as caching or using in an HTTP response. It stems from the simple idea of giving slightly more control over the `as_json` method that gets called when objects are serialized using Rails' default controller serialization.
## Installation
@@ -21,25 +20,33 @@
$ gem install adequate_serialization
## Usage
-First, include `AdequateSerialization::Serializable` in any object that you want to be able to serialize. Then, define a serializer matching the name of that object, postfixed with `"Serializer"`. Use the `AdequateSerialization` DSL to define the attributes that are available to the serializer. You can then call `as_json` on any instance of that object to get the resultant hash. Below is an example:
+There are two ways to define the serialization process for objects.
+For larger objects where it makes sense to define the serialization in a separate class, you should include the `AdequateSerialization::Serializable` in the object that you want to be able to serialize. Then, define a serializer matching the name of that object, postfixed with `"Serializer"`, as in:
+
```ruby
-class User
- include AdequateSerialization::Serializable
+class UserSerializer < AdequateSerialization::Serializer
+ attribute :id, :name, :title
+end
+```
- attr_reader :id, :name, :title
+For smaller objects where it makes sense to define the serialization inline, you can include the result of the `AdequateSerialization::inline` method, as in:
+```ruby
+class User
+ include AdequateSerialization.inline { attribute :id, :name, :title }
+
...
end
+```
-class UserSerializer < AdequateSerialization::Serializer
- attribute :id, :name, :title
-end
+For both types of serialization definition, you can then use the `AdequateSerialization` DSL to define the attributes that are available to the serializer. You can then call `as_json` on any instance of that object to get the resultant hash. Below is an example:
+```ruby
User.new(id: 1, name: 'Clark Kent', title: 'Superman').as_json
# => {:id=>1, :name=>"Clark Kent", :title=>"Superman"}
```
### Defining attributes
@@ -123,15 +130,15 @@
This relies on the objects to which you are attaching having an `id` attribute and the attachable hash being an index of `id` pointing to the attribute value.
### Usage with Rails
-To get `AdequateSerializer` working with Rails, you can call `AdequateSerializion.hook_into_rails!` in an initializer. This will do three things:
+If `::Rails` is defined when `adequate_serialization` is required, it will hook into the serialization process for `ActiveRecord` objects in three ways:
-1. Introduce caching behavior so that when serializing objects they will by default be stored in the Rails cache.
-1. Include `AdequateSerializer::Serializable` in `ActiveRecord::Base` so that all of your models will be serializable.
-2. Overwrite `ActiveRecord::Relation`'s `as_json` method to use the `AdequateSerializer::Rails::RelationSerializer` object, which by default will use the `Rails.cache.fetch_multi` method in order to more efficiently serialize all of the records in the relation.
+1. By introducing caching behavior so that when serializing objects they will by default be stored in the Rails cache.
+2. By including `AdequateSerializer::Serializable` in `ActiveRecord::Base` so that all of your models will be serializable.
+3. By overwriting `ActiveRecord::Relation`'s `as_json` method to use the `AdequateSerializer::Rails::RelationSerializer` object, which by default will use the `Rails.cache.fetch_multi` method in order to more efficiently serialize all of the records in the relation.
You can still use plain objects to be serialized, and if you want to take advantage of the caching behavior, you can define a `cache_key` method on the objects that you're serializing. This will cause `AdequateSerialization` to start putting them into the Rails cache.
The result is that you can now this in your controllers:
@@ -162,10 +169,10 @@
### Advanced
The serialization process happens through a series of `AdequateSerialization::Steps`. The caching behavior mentioned in the `Usage with Rails` section is one such step that gets introduced. You can introduce more yourself like so:
```ruby
-class LoggingStep < AdequateSerialization::Steps::PassthroughStep
+class LoggingStep < AdequateSerialization::Steps::Step
def apply(response)
Logger.log("#{response.object} is being serialized with #{response.opts} options")
apply_next(response)
end
end