active_model_serializers 0.10.0 → 0.10.6

data/docs/general/serializers.md

@@ -31,10 +31,21 @@ Serialization of the resource `title`
 |---------------------------- |-------------|
 | `attribute :title`          | `{ title: 'Some Title' } `
 | `attribute :title, key: :name` | `{ name: 'Some Title' } `
-| `attribute :title { 'A Different Title'}` | `{ title: 'A Different Title' } `
+| `attribute(:title) { 'A Different Title'}` | `{ title: 'A Different Title' } `
 | `attribute :title`<br>`def title 'A Different Title' end` | `{ title: 'A Different Title' }`
 
-[PR please for conditional attributes:)](https://github.com/rails-api/active_model_serializers/pull/1403)
+An `if` or `unless` option can make an attribute conditional. It takes a symbol of a method name on the serializer, or a lambda literal.
+
+e.g.
+
+```ruby
+attribute :private_data, if: :is_current_user?
+attribute :another_private_data, if: -> { scope.admin? }
+
+def is_current_user?
+  object.id == current_user.id
+end
+```
 
 ### Associations
 
@@ -53,6 +64,10 @@ Where:
   - `unless:`
   - `virtual_value:`
   - `polymorphic:` defines if polymorphic relation type should be nested in serialized association.
+  - `type:` the resource type as used by JSON:API, especially on a `belongs_to` relationship.
+  - `class_name:` used to determine `type` when `type` not given
+  - `foreign_key:` used by JSON:API on a `belongs_to` relationship to avoid unnecessarily loading the association object.
+  - `namespace:` used when looking up the serializer and `serializer` is not given.  Falls back to the parent serializer's `:namespace` instance options, which, when present, comes from the render options. See [Rendering#namespace](rendering.md#namespace] for more details.
 - optional: `&block` is a context that returns the association's attributes.
   - prevents `association_name` method from being called.
   - return value of block is used as the association value.
@@ -129,7 +144,7 @@ class PictureSerializer < ActiveModel::Serializer
 end
 ```
 
-For more context, see the [tests](../../test/adapter/polymorphic_test.rb) for each adapter.
+You can specify the serializers by [overriding serializer_for](serializers.md#overriding-association-serializer-lookup). For more context about polymorphic relationships, see the [tests](../../test/adapter/polymorphic_test.rb) for each adapter.
 
 ### Caching
 
@@ -162,18 +177,25 @@ end
 
 #### ::type
 
-The `::type` method defines the JSONAPI [type](http://jsonapi.org/format/#document-resource-object-identification) that will be rendered for this serializer.
+When using the `:json_api` adapter, the `::type` method defines the JSONAPI [type](http://jsonapi.org/format/#document-resource-object-identification) that will be rendered for this serializer.
+
+When using the `:json` adapter, the `::type` method defines the name of the root element.
+
 It either takes a `String` or `Symbol` as parameter.
 
-Note: This method is useful only when using the `:json_api` adapter.
+Note: This method is useful only when using the `:json_api` or `:json` adapter.
 
 Examples:
 ```ruby
 class UserProfileSerializer < ActiveModel::Serializer
   type 'profile'
+
+  attribute :name
 end
 class AuthorProfileSerializer < ActiveModel::Serializer
   type :profile
+
+  attribute :name
 end
 ```
 
@@ -183,7 +205,20 @@ With the `:json_api` adapter, the previous serializers would be rendered as:
 {
   "data": {
     "id": "1",
-    "type": "profile"
+    "type": "profile",
+    "attributes": {
+      "name": "Julia"
+    }
+  }
+}
+```
+
+With the `:json` adapter, the previous serializer would be rendered as:
+
+``` json
+{
+  "profile": {
+    "name": "Julia"
   }
 }
 ```
@@ -194,10 +229,10 @@ With the `:json_api` adapter, the previous serializers would be rendered as:
 link :self do
   href "https://example.com/link_author/#{object.id}"
 end
-link :author { link_author_url(object) }
-link :link_authors { link_authors_url }
+link(:author) { link_author_url(object) }
+link(:link_authors) { link_authors_url }
 link :other, 'https://example.com/resource'
-link :posts { link_author_posts_url(object) }
+link(:posts) { link_author_posts_url(object) }
 ```
 
 #### #object
@@ -206,7 +241,17 @@ The object being serialized.
 
 #### #root
 
-PR please :)
+Resource root which is included in `JSON` adapter. As you can see at [Adapters Document](adapters.md), `Attribute` adapter (default) and `JSON API` adapter does not include root at top level.
+By default, the resource root comes from the `model_name` of the serialized object's class.
+
+There are several ways to specify root:
+* [Overriding the root key](rendering.md#overriding-the-root-key)
+* [Setting `type`](serializers.md#type)
+* Specifying the `root` option, e.g. `root: 'specific_name'`, during the serializer's initialization:
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(foo, root: 'bar')
+```
 
 #### #scope
 
@@ -255,7 +300,7 @@ In the controller, the scope/scope_name options are equal to
 the [`serialization_scope`method](https://github.com/rails-api/active_model_serializers/blob/d02cd30fe55a3ea85e1d351b6e039620903c1871/lib/action_controller/serialization.rb#L13-L20),
 which is `:current_user`, by default.
 
-Specfically, the `scope_name` is defaulted to `:current_user`, and may be set as
+Specifically, the `scope_name` is defaulted to `:current_user`, and may be set as
 `serialization_scope :view_context`.  The `scope` is set to `send(scope_name)` when `scope_name` is
 present and the controller responds to `scope_name`.
 
@@ -303,17 +348,64 @@ So that when we render the `#edit` action, we'll get
 
 Where `can_edit` is `view_context.current_user.admin?` (true).
 
+You can also tell what to set as `serialization_scope` for specific actions.
+
+For example, use `admin_user` only for `Admin::PostSerializer` and `current_user` for rest.
+
+```ruby
+class PostsController < ActionController::Base
+
+  before_action only: :edit do
+    self.class.serialization_scope :admin_user
+  end
+
+  def show
+    render json: @post, serializer: PostSerializer
+  end
+
+  def edit
+    @post.save
+    render json: @post, serializer: Admin::PostSerializer
+  end
+
+  private
+
+  def admin_user
+    User.new(id: 2, name: 'Bob', admin: true)
+  end
+
+  def current_user
+    User.new(id: 2, name: 'Bob', admin: false)
+  end
+end
+```
+
 #### #read_attribute_for_serialization(key)
 
 The serialized value for a given key. e.g. `read_attribute_for_serialization(:title) #=> 'Hello World'`
 
 #### #links
 
-PR please :)
+Allows you to modify the `links` node. By default, this node will be populated with the attributes set using the [::link](#link) method. Using `links: nil` will remove the `links` node.
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(
+  @post,
+  adapter: :json_api,
+  links: {
+    self: {
+      href: 'http://example.com/posts',
+      meta: {
+        stuff: 'value'
+      }
+    }
+  }
+)
+```
 
 #### #json_key
 
-PR please :)
+Returns the key used by the adapter as the resource root. See [root](#root) for more information.
 
 ## Examples
 
@@ -370,3 +462,19 @@ class PostSerializer < ActiveModel::Serializer
   end
 end
 ```
+
+## Overriding association serializer lookup
+
+If you want to define a specific serializer lookup for your associations, you can override
+the `ActiveModel::Serializer.serializer_for` method to return a serializer class based on defined conditions.
+
+```ruby
+class MySerializer < ActiveModel::Serializer
+  def self.serializer_for(model, options)
+    return SparseAdminSerializer if model.class == 'Admin'
+    super
+  end
+
+  # the rest of the serializer
+end
+```

data/docs/howto/add_pagination_links.md

@@ -10,9 +10,9 @@ the resource is paginated and if you are using the ```JsonApi``` adapter.
 If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari)
 or [WillPaginate](https://github.com/mislav/will_paginate).
 
-Although the others adapters does not have this feature, it is possible to
+Although the other adapters do not have this feature, it is possible to
 implement pagination links to `JSON` adapter. For more information about it,
-please see in our docs 
+please check our docs.
 
 ###### Kaminari examples
 
@@ -72,18 +72,18 @@ ActiveModelSerializers pagination relies on a paginated collection with the meth
 
 ### JSON adapter
 
-If you are using `JSON` adapter, pagination links will not be included automatically, but it is possible to do so using `meta` key.
+If you are not using `JSON` adapter, pagination links will not be included automatically, but it is possible to do so using `meta` key.
 
 Add this method to your base API controller.
 
 ```ruby
-def pagination_dict(object)
+def pagination_dict(collection)
   {
-    current_page: object.current_page,
-    next_page: object.next_page,
-    prev_page: object.prev_page,
-    total_pages: object.total_pages,
-    total_count: object.total_count
+    current_page: collection.current_page,
+    next_page: collection.next_page,
+    prev_page: collection.prev_page, # use collection.previous_page when using will_paginate
+    total_pages: collection.total_pages,
+    total_count: collection.total_count
   }
 end
 ```
@@ -117,23 +117,22 @@ ex.
 You can also achieve the same result if you have a helper method that adds the pagination info in the meta tag. For instance, in your action specify a custom serializer.
 
 ```ruby
-render json: @posts, each_serializer: PostPreviewSerializer, meta: meta_attributes(@post)
+render json: @posts, each_serializer: PostPreviewSerializer, meta: meta_attributes(@posts)
 ```
 
 ```ruby
 #expects pagination!
-def meta_attributes(resource, extra_meta = {})
+def meta_attributes(collection, extra_meta = {})
   {
-    current_page: resource.current_page,
-    next_page: resource.next_page,
-    prev_page: resource.prev_page,
-    total_pages: resource.total_pages,
-    total_count: resource.total_count
+    current_page: collection.current_page,
+    next_page: collection.next_page,
+    prev_page: collection.prev_page, # use collection.previous_page when using will_paginate
+    total_pages: collection.total_pages,
+    total_count: collection.total_count
   }.merge(extra_meta)
 end
 ```
 
-
 ### Attributes adapter
 
 This adapter does not allow us to use `meta` key, due to that it is not possible to add pagination links.

data/docs/howto/add_relationship_links.md

@@ -0,0 +1,140 @@
+[Back to Guides](../README.md)
+
+# How to add relationship links
+
+ActiveModelSerializers offers you many ways to add links in your JSON, depending on your needs.
+The most common use case for links is supporting nested resources.
+
+The following examples are without included relationship data (`include` param is empty),
+specifically the following Rails controller was used for these examples:
+
+```ruby
+class Api::V1::UsersController < ApplicationController
+  def show
+    render jsonapi: User.find(params[:id]),
+      serializer: Api::V1::UserSerializer,
+      include: []
+  end
+end
+```
+
+Bear in mind though that ActiveModelSerializers are [framework-agnostic](outside_controller_use.md), Rails is just a common example here.
+
+### Links as an attribute of a resource
+**This is applicable to JSON and Attributes adapters**
+
+You can define an attribute in the resource, named `links`.
+
+```ruby
+class Api::V1::UserSerializer < ActiveModel::Serializer
+  include Rails.application.routes.url_helpers
+
+  attributes :id, :name
+
+  attribute :links do
+    id = object.id
+    {
+      self: api_v1_user_path(id),
+      microposts: api_v1_microposts_path(user_id: id)
+    }
+  end
+end
+```
+
+Using the `JSON` adapter, this will result in:
+
+```json
+{
+  "user": {
+    "id": "1",
+    "name": "John",
+    "links": {
+      "self": "/api/v1/users/1",
+      "microposts": "/api/v1/microposts?user_id=1"
+    }
+  }
+}
+```
+
+
+### Links as a property of the resource definiton
+**This is only applicable to JSONAPI adapter**
+
+You can use the `link` class method to define the links you need in the resource's primary data.
+
+```ruby
+class Api::V1::UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+
+  link(:self) { api_v1_user_path(object.id) }
+  link(:microposts) { api_v1_microposts_path(user_id: object.id) }
+end
+```
+
+Using the `JSONAPI` adapter, this will result in:
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "Example User"
+    },
+    "links": {
+      "self": "/api/v1/users/1",
+      "microposts": "/api/v1/microposts?user_id=1"
+    }
+  }
+}
+```
+
+### Links that follow the JSONAPI spec
+**This is only applicable to JSONAPI adapter**
+
+If you have a JSONAPI-strict client that you are working with (like `ember-data`)
+you need to construct the links inside the relationships. Also the link to fetch the
+relationship data must be under the `related` attribute, whereas to manipulate the
+relationship (in case of many-to-many relationship) must be under the `self` attribute.
+
+You can find more info in the [spec](http://jsonapi.org/format/#document-resource-object-relationships).
+
+Here is how you can do this:
+
+```ruby
+class Api::V1::UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+
+  has_many :microposts, serializer: Api::V1::MicropostSerializer do
+    link(:related) { api_v1_microposts_path(user_id: object.id) }
+
+    microposts = object.microposts
+    # The following code is needed to avoid n+1 queries.
+    # Core devs are working to remove this necessity.
+    # See: https://github.com/rails-api/active_model_serializers/issues/1325
+    microposts.loaded? ? microposts : microposts.none
+  end
+end
+```
+
+This will result in:
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "Example User"
+    },
+    "relationships": {
+      "microposts": {
+        "data": [],
+        "links": {
+          "related": "/api/v1/microposts?user_id=1"
+        }
+      }
+    }
+  }
+}
+```

data/docs/howto/add_root_key.md

@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # How to add root key
 
 Add the root key to your API is quite simple with ActiveModelSerializers. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```Attributes``` which doesn't have the root key, so your response is something similar to:
@@ -49,3 +51,5 @@ or if it returns a collection:
   ]
 }
 ```
+
+[There are several ways to specify root](../general/serializers.md#root) when using the JSON adapter.

data/docs/howto/grape_integration.md

@@ -0,0 +1,42 @@
+[Back to Guides](../README.md)
+
+The ActiveModelSerializers grape formatter relies on the existence of `env['grape.request']` which is implemeted by `Grape::Middleware::Globals`. You can meet his dependency by calling it before mounting the endpoints.
+
+In the simpliest way:
+
+```
+class API < Grape::API
+  # @note Make sure this is above you're first +mount+
+  use Grape::Middleware::Globals
+end
+```
+
+or more like what is shown in current Grape tutorials:
+
+```
+module MyApi
+  class ApiBase < Grape::API
+    use Grape::Middleware::Globals
+
+    require 'grape/active_model_serializers'
+    include Grape::ActiveModelSerializers
+
+    mount MyApi::V1::ApiBase
+  end
+end
+```
+
+You could meet this dependency with your own middleware. The invocation might look like:
+
+```
+module MyApi
+  class ApiBase < Grape::API
+    use My::Middleware::Thingamabob
+
+    require 'grape/active_model_serializers'
+    include Grape::ActiveModelSerializers
+
+    mount MyApi::V1::ApiBase
+  end
+end
+```

data/docs/howto/outside_controller_use.md

@@ -10,8 +10,8 @@ In ActiveModelSerializers versions 0.10 or later, serializing resources outside
 # Create our resource
 post = Post.create(title: "Sample post", body: "I love Active Model Serializers!")
 
-# Optional options parameters
-options = {}
+# Optional options parameters for both the serializer and instance
+options = {serializer: PostDetailedSerializer, username: 'sample user'}
 
 # Create a serializable resource instance
 serializable_resource = ActiveModelSerializers::SerializableResource.new(post, options)
@@ -19,10 +19,12 @@ serializable_resource = ActiveModelSerializers::SerializableResource.new(post, o
 # Convert your resource into json
 model_json = serializable_resource.as_json
 ```
+The object that is passed to `ActiveModelSerializers::SerializableResource.new` can be a single resource or a collection.
+The additional options are the same options that are passed [through controllers](../general/rendering.md#explicit-serializer).
 
 ### Looking up the Serializer for a Resource
 
-If you want to retrieve a serializer for a specific resource, you can do the following:
+If you want to retrieve the serializer class for a specific resource, you can do the following:
 
 ```ruby
 # Create our resource
@@ -41,7 +43,13 @@ You could also retrieve the serializer via:
 ActiveModelSerializers::SerializableResource.new(post, options).serializer
 ```
 
-Both approaches will return an instance, if any, of the resource's serializer.
+Both approaches will return the serializer class that will be used for the resource.
+
+Additionally, you could retrieve the serializer instance for the resource via:
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(post, options).serializer_instance
+```
 
 ## Serializing before controller render
 

data/docs/howto/passing_arbitrary_options.md

@@ -11,7 +11,7 @@ For example, we could pass in a field, such as `user_id` into our serializer.
 ```ruby
 # posts_controller.rb
 class PostsController < ApplicationController
-  def dashboard  
+  def dashboard
     render json: @post, user_id: 12
   end
 end
@@ -20,7 +20,7 @@ end
 class PostSerializer < ActiveModel::Serializer
   attributes :id, :title, :body
 
-  def comments_by_me  
+  def comments_by_me
     Comments.where(user_id: instance_options[:user_id], post_id: object.id)
   end
 end

data/docs/howto/serialize_poro.md

@@ -2,13 +2,16 @@
 
 # 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:
+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 in most situations:
+
 ```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]
@@ -21,12 +24,50 @@ class MyModel
 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:
+The [ActiveModel::Serializer::Lint::Tests](../../lib/active_model/serializer/lint.rb)
+define and validate which methods ActiveModelSerializers expects to be implemented.
+
+An implementation of the complete spec is included either for use or as reference:
+[`ActiveModelSerializers::Model`](../../lib/active_model_serializers/model.rb).
+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
+  attributes :id, :name, :level
+end
+```
+
+The default serializer would be `MyModelSerializer`.
+
+*IMPORTANT*: There is a surprising behavior (bug) in the current implementation of ActiveModelSerializers::Model that
+prevents an accessor from modifying attributes on the instance.  The fix for this bug
+is a breaking change, so we have made an opt-in configuration.
+
+New applications should set:
+
+```ruby
+ActiveModelSerializers::Model.derive_attributes_from_names_and_fix_accessors
+```
+
+Existing applications can use the fix *and* avoid breaking changes
+by making a superclass for new models. For example:
+
+```ruby
+class SerializablePoro < ActiveModelSerializers::Model
+  derive_attributes_from_names_and_fix_accessors
 end
 ```
 
-The default serializer would be `MyModelSerializer`.
+So that `MyModel` above would inherit from `SerializablePoro`.
+
+`derive_attributes_from_names_and_fix_accessors` prepends the `DeriveAttributesFromNamesAndFixAccessors`
+module and does the following:
+
+- `id` will *always* be in the attributes. (This is until we separate out the caching requirement for POROs.)
+- Overwrites the `attributes` method to that it only returns declared attributes.
+ `attributes` will now be a frozen hash with indifferent access.
+
+For more information, see [README: What does a 'serializable resource' look like?](../../README.md#what-does-a-serializable-resource-look-like).

data/docs/howto/test.md

@@ -1,3 +1,5 @@
+[Back to Guides](../README.md)
+
 # How to test
 
 ## Controller Serializer Usage