active_model_serializers 0.10.3 → 0.10.12

data/docs/howto/add_pagination_links.md

@@ -1,138 +0,0 @@
-[Back to Guides](../README.md)
-
-# How to add pagination links
-
-### JSON API adapter
-
-Pagination links will be included in your response automatically as long as
-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 other adapters do not have this feature, it is possible to
-implement pagination links to `JSON` adapter. For more information about it,
-please check our docs.
-
-###### Kaminari examples
-
-```ruby
-#array
-@posts = Kaminari.paginate_array([1, 2, 3]).page(3).per(1)
-render json: @posts
-
-#active_record
-@posts = Post.page(3).per(1)
-render json: @posts
-```
-
-###### WillPaginate examples
-
-```ruby
-#array
-@posts = [1,2,3].paginate(page: 3, per_page: 1)
-render json: @posts
-
-#active_record
-@posts = Post.page(3).per_page(1)
-render json: @posts
-```
-
-```ruby
-ActiveModelSerializers.config.adapter = :json_api
-```
-
-ex:
-```json
-{
-  "data": [
-    {
-      "type": "articles",
-      "id": "3",
-      "attributes": {
-        "title": "JSON API paints my bikeshed!",
-        "body": "The shortest article. Ever.",
-        "created": "2015-05-22T14:56:29.000Z",
-        "updated": "2015-05-22T14:56:28.000Z"
-      }
-    }
-  ],
-  "links": {
-    "self": "http://example.com/articles?page[number]=3&page[size]=1",
-    "first": "http://example.com/articles?page[number]=1&page[size]=1",
-    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
-    "next": "http://example.com/articles?page[number]=4&page[size]=1",
-    "last": "http://example.com/articles?page[number]=13&page[size]=1"
-  }
-}
-```
-
-ActiveModelSerializers pagination relies on a paginated collection with the methods `current_page`, `total_pages`, and `size`, such as are supported by both [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
-
-
-### 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.
-
-Add this method to your base API controller.
-
-```ruby
-def pagination_dict(object)
-  {
-    current_page: object.current_page,
-    next_page: object.next_page,
-    prev_page: object.prev_page, # use object.previous_page when using will_paginate
-    total_pages: object.total_pages,
-    total_count: object.total_count
-  }
-end
-```
-
-Then, use it on your render method.
-
-```ruby
-render json: posts, meta: pagination_dict(posts)
-```
-
-ex.
-```json
-{
-  "posts": [
-    {
-      "id": 2,
-      "title": "JSON API paints my bikeshed!",
-      "body": "The shortest article. Ever."
-    }
-  ],
-  "meta": {
-    "current_page": 3,
-    "next_page": 4,
-    "prev_page": 2,
-    "total_pages": 10,
-    "total_count": 10
-  }
-}
-```
-
-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)
-```
-
-```ruby
-#expects pagination!
-def meta_attributes(resource, extra_meta = {})
-  {
-    current_page: resource.current_page,
-    next_page: resource.next_page,
-    prev_page: resource.prev_page, # use resource.previous_page when using will_paginate
-    total_pages: resource.total_pages,
-    total_count: resource.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

@@ -1,137 +0,0 @@
-[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
-```
-
-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 JSONAPI, JSON and Attributes adapters**
-
-You can define an attribute in the resource, named `links`.
-
-```ruby
-class Api::V1::UserSerializer < ActiveModel::Serializer
-  attributes :id, :name, :links
-
-  def links
-    {
-      self: api_v1_user_path(object.id),
-      microposts: api_v1_microposts_path(user_id: object.id)
-    }
-  end
-end
-```
-
-This will resilt in (example is in jsonapi adapter):
-```json
-{
-  "data": {
-    "id": "1",
-    "type": "users",
-    "attributes": {
-      "name": "Example User",
-      "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 `links` 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
-```
-
-This will resilt in (example is in jsonapi adapter):
-```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) }
-  end
-
-  #this is needed to avoid n+1, gem core devs are working to remove this necessity
-  #more on: https://github.com/rails-api/active_model_serializers/issues/1325
-  def microposts
-    object.microposts.loaded ? object.microposts : object.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,55 +0,0 @@
-[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:
-
-```json
-{
-  "id": 1,
-  "title": "Awesome Post Tile",
-  "content": "Post content"
-}
-```
-
-In order to add the root key you need to use the ```JSON``` Adapter, you can change this in an initializer:
-
-```ruby
-ActiveModelSerializers.config.adapter = :json
-```
-
-You can also specify a class as adapter, as long as it complies with the ActiveModelSerializers adapters interface.
-It will add the root key to all your serialized endpoints.
-
-ex:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "Awesome Post Tile",
-    "content": "Post content"
-  }
-}
-```
-
-or if it returns a collection:
-
-```json
-{
-  "posts": [
-    {
-      "id": 1,
-      "title": "Awesome Post Tile",
-      "content": "Post content"
-    },
-    {
-      "id": 2,
-      "title": "Another Post Tile",
-      "content": "Another post content"
-    }
-  ]
-}
-```
-
-[There are several ways to specify root](../general/serializers.md#root) when using the JSON adapter.

data/docs/howto/grape_integration.md

@@ -1,42 +0,0 @@
-[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

@@ -1,65 +0,0 @@
-[Back to Guides](../README.md)
-
-## Using ActiveModelSerializers Outside Of A Controller
-
-### Serializing a resource
-
-In ActiveModelSerializers versions 0.10 or later, serializing resources outside of the controller context is fairly simple:
-
-```ruby
-# Create our resource
-post = Post.create(title: "Sample post", body: "I love Active Model Serializers!")
-
-# Optional options parameters
-options = {}
-
-# Create a serializable resource instance
-serializable_resource = ActiveModelSerializers::SerializableResource.new(post, options)
-
-# 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.
-
-### Looking up the Serializer for a Resource
-
-If you want to retrieve the serializer class for a specific resource, you can do the following:
-
-```ruby
-# Create our resource
-post = Post.create(title: "Another Example", body: "So much fun.")
-
-# Optional options parameters
-options = {}
-
-# Retrieve the default serializer for posts
-serializer = ActiveModel::Serializer.serializer_for(post, options)
-```
-
-You could also retrieve the serializer via:
-
-```ruby
-ActiveModelSerializers::SerializableResource.new(post, options).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
-
-At times, you might want to use a serializer without rendering it to the view. For those cases, you can create an instance of `ActiveModelSerializers::SerializableResource` with
-the resource you want to be serialized and call `.as_json`.
-
-```ruby
-def create
-  message = current_user.messages.create!(message_params)
-  message_json = ActiveModelSerializers::SerializableResource.new(message).as_json
-  MessageCreationWorker.perform(message_json)
-  head 204
-end
-```

data/docs/howto/passing_arbitrary_options.md

@@ -1,27 +0,0 @@
-[Back to Guides](../README.md)
-
-# Passing Arbitrary Options To A Serializer
-
-In addition to the [`serialization_scope`](../general/serializers.md#scope), any options passed to `render`
-that are not reserved for the [adapter](../general/rendering.md#adapter_opts)
-are available in the serializer as [instance_options](../general/serializers.md#instance_options).
-
-For example, we could pass in a field, such as `user_id` into our serializer.
-
-```ruby
-# posts_controller.rb
-class PostsController < ApplicationController
-  def dashboard
-    render json: @post, user_id: 12
-  end
-end
-
-# post_serializer.rb
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  def comments_by_me
-    Comments.where(user_id: instance_options[:user_id], post_id: object.id)
-  end
-end
-```