README.md in alba-0.8.0 vs README.md in alba-0.9.0
- old
+ new
@@ -23,10 +23,28 @@
$ gem install alba
## Usage
+### Configuration
+
+Alba's configuration is fairly simple.
+
+#### Backend
+
+Backend is the actual part serializing an object into JSON. Alba supports these backends.
+
+* Oj, the fastest. Gem installation required.
+* active_support, mostly for Rails. Gem installation required.
+* default or json, with no external dependencies.
+
+You can set a backend like this:
+
+```ruby
+Alba.backend = :oj
+```
+
### Simple serialization with key
```ruby
class User
attr_accessor :id, :name, :email, :created_at, :updated_at
@@ -123,15 +141,53 @@
# => '{"foo":{"id":1,"articles":[{"title":"Hello World!","body":"Hello World!!!"},{"title":"Super nice","body":"Really nice!"}]}}'
```
Although this might be useful sometimes, it's generally recommended to define a class for both Resource and Serializer.
+### Inheritance and Ignorance
+
+You can `exclude` or `ignore` certain attributes using `ignoring`.
+
+```ruby
+class Foo
+ attr_accessor :id, :name, :body
+
+ def initialize(id, name, body)
+ @id = id
+ @name = name
+ @body = body
+ end
+end
+
+class GenericFooResource
+ include Alba::Resource
+
+ attributes :id, :name, :body
+end
+
+class RestrictedFooResouce < GenericFooResource
+ ignoring :id, :body
+end
+
+RestrictedFooResouce.new(foo).serialize
+# => '{"name":"my foo"}'
+end
+```
+
## Comparison
Alba is faster than alternatives.
For a performance benchmark, see https://gist.github.com/okuramasafumi/4e375525bd3a28e4ca812d2a3b3e5829.
+## Rails
+
+When you use Alba in Rails, you can create an initializer file with the line below for compatibility with Rails JSON encoder.
+
+```ruby
+Alba.backend = :active_support
+```
+
## Why named "Alba"?
The name "Alba" comes from "albatross", a kind of birds. In Japanese, this bird is called "Aho-dori", which means "stupid bird". I find it funny because in fact albatrosses fly really fast. I hope Alba looks stupid but in fact it does its job quick.
## Alba internals
@@ -140,10 +196,10 @@
`Serializer` is a component responsible for rendering JSON output with `Resource`. `Serializer` can add more data to `Resource` such as `metadata`. Users can define one single `Serializer` and reuse it for all `Resource`s. The main interface is `#serialize`.
`Resource` is a component responsible for defining how an object (or a collection of objects) is converted into JSON. The difference between `Serializer` and `Resource` is that while `Serializer` can add arbitrary data into JSON, `Resource` can get data only from the object under it. The main interface is `#serializable_hash`.
-`Value` is either `Attribute`, `One` or `Many`. They are responsible for fetching data from the object for `Resource`. The main interface is `#to_hash`.
+`One` and `Many` are the special object fetching other resources and converting them into Hash.
The main `Alba` module holds config values and one convenience method, `.serialize`.
## Development