2423ca4999
The `:attributes` adapter is the default one, but it did not support key transformation. This was very surprising behavior, since the "Configuration Options" page in the guides didn't mention that this behavior was not supported by the attributes adapter. This commit adds key transform support to the attributes adapter, and adds documentation about the default transform for the attributes adapter (which is `:unaltered`). This commit also handles arrays when transforming keys, which was needed in the case where you're serializing a collection with the Attributes adapter. With the JSON adapter, it was always guaranteed to pass a hash to the KeyTransform functions because of the top-level key. Since there is no top-level key for the Attributes adapter, the return value could be an array. |
||
|---|---|---|
| .github | ||
| bin | ||
| docs | ||
| lib | ||
| test | ||
| .gitignore | ||
| .rubocop.yml | ||
| .simplecov | ||
| .travis.yml | ||
| active_model_serializers.gemspec | ||
| appveyor.yml | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| Gemfile | ||
| MIT-LICENSE | ||
| Rakefile | ||
| README.md | ||
ActiveModelSerializers
| Build Status |
|
| Code Quality |
|
| Issue Stats | Pulse |
About
ActiveModelSerializers brings convention over configuration to your JSON generation.
ActiveModelSerializers works through two components: serializers and adapters.
Serializers describe which attributes and relationships should be serialized.
Adapters describe how attributes and relationships should be serialized.
SerializableResource co-ordinates the resource, Adapter and Serializer to produce the
resource serialization. The serialization has the #as_json, #to_json and #serializable_hash
methods used by the Rails JSON Renderer. (SerializableResource actually delegates
these methods to the adapter.)
By default ActiveModelSerializers will use the Attributes Adapter (no JSON root). But we strongly advise you to use JsonApi Adapter, which follows 1.0 of the format specified in jsonapi.org/format. Check how to change the adapter in the sections below.
0.10.x is not backward compatible with 0.9.x nor 0.8.x.
0.10.x is based on the 0.8.0 code, but with a more flexible
architecture. We'd love your help. Learn how you can help here.
It is generally safe and recommended to use the master branch.
Installation
Add this line to your application's Gemfile:
gem 'active_model_serializers', '~> 0.10.0'
And then execute:
$ bundle
Getting Started
See Getting Started for the nuts and bolts.
More information is available in the Guides and High-level behavior.
Getting Help
If you find a bug, please report an Issue and see our contributing guide.
If you have a question, please post to Stack Overflow.
If you'd like to chat, we have a community slack.
Thanks!
Documentation
High-level behavior
Choose an adapter from adapters:
ActiveModelSerializers.config.adapter = :json_api # Default: `:attributes`
Given a serializable model:
# either
class SomeResource < ActiveRecord::Base
# columns: title, body
end
# or
class SomeResource < ActiveModelSerializers::Model
attr_accessor :title, :body
end
And initialized as:
resource = SomeResource.new(title: 'ActiveModelSerializers', body: 'Convention over configuration')
Given a serializer for the serializable model:
class SomeSerializer < ActiveModel::Serializer
attribute :title, key: :name
attributes :body
end
The model can be serialized as:
options = {}
serialization = ActiveModelSerializers::SerializableResource.new(resource, options)
serialization.to_json
serialization.as_json
SerializableResource delegates to the adapter, which it builds as:
adapter_options = {}
adapter = ActiveModelSerializers::Adapter.create(serializer, adapter_options)
adapter.to_json
adapter.as_json
adapter.serializable_hash
The adapter formats the serializer's attributes and associations (a.k.a. includes):
serializer_options = {}
serializer = SomeSerializer.new(resource, serializer_options)
serializer.attributes
serializer.associations
See ARCHITECTURE.md for more information.
Contributing
See CONTRIBUTING.md