[skip ci] Update pagination and links doc

Author: Yohan Robert

docs/README.md

@@ -22,10 +22,10 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10.
 
 ## How to
 
+- [How to use ActiveModelSerializers outside of rails controllers](howto/outside_controller_use.md)
 - [How to add root key](howto/add_root_key.md)
-- [How to add pagination links](howto/add_pagination_links.md)
-- [How to add relationship links](howto/add_relationship_links.md)
-- [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
+- [How to add links](howto/add_links.md)
+- [How to handle pagination in JSON response](howto/handle_pagination.md)
 - [Testing ActiveModelSerializers](howto/test.md)
 - [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
 - [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)

docs/howto/add_link.md

@@ -0,0 +1,337 @@
+[Back to Guides](../README.md)
+
+# How to add links
+
+`ActiveModelSerializers` offers you many ways to add links in your JSON reponse depending on the adapter you are using.
+
+## JSON API adapter
+
+The JSON API specification allows the usage of the `links` member for representing links in three cases:
+* [Top level links](http://jsonapi.org/format/#document-top-level)
+* [Resource link](http://jsonapi.org/format/#document-resource-object-links)
+* [Relationship links](http://jsonapi.org/format/#document-resource-object-relationships)
+
+`ActiveModelSerializers` provides tools to handle these links.
+
+### [Top level links](http://jsonapi.org/format/#document-top-level)
+
+In order to provide top-level links, you will need to specify the `links` option to the serialization:
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+end
+
+user = User.new(id: 1, name: "John")
+links = {
+  home: "https://www.example.com/"
+}
+resource = ActiveModelSerializers::SerializableResource.new(
+  user,
+  adapter: :json_api,
+  links: links
+)
+resource.to_json
+```
+
+This would result in:
+
+```json
+{
+  "links": {
+    "home": "https://www.example.com/"
+  },
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "John"
+    }
+  }
+}
+```
+
+When using Rails, you can add top-level links by providing the `links` option to `render` method:
+
+```ruby
+class UserController < ActionController::Base
+  def show
+    user = User.new(id: 1, name: "John")
+    links = {
+      home: "https://www.example.com/"
+    }
+    render json: user, adapter: :json_api, links: links
+  end
+end
+```
+
+#### Pagination
+
+`ActiveModelSerializers` will provides automatic pagination links for collections if use [Kaminari](https://github.com/amatsuda/kaminari)
+or [WillPaginate](https://github.com/mislav/will_paginate):
+
+```ruby
+class UserController < ActionController::Base
+  def kaminari
+    users = User.all.to_a # .all.to_a used as example
+    users = Kaminari.paginate_array(page).page(3).per(1)
+    render json: users, adapter: :json_api
+  end
+
+  def will_paginate
+    users = User.all.to_a # .all.to_a used as example
+    users = users.paginate(page: 3, per_page: 1)
+    render json: users, adapter: :json_api
+  end
+end
+```
+
+Any of these actions would result in:
+```json
+{
+  "data": [
+    {
+      "type": "users",
+      "id": "3",
+      "attributes": {
+        "name": "John"
+      }
+    }
+  ],
+  "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"
+  }
+}
+```
+
+Note that `ActiveModelSerializers` pagination relies on a collection that has 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). If you want to have paginated links your collections but don't want to use neither Kaminari nor WillPaginate, make sure to define these methods.
+
+### [Resource link](http://jsonapi.org/format/#document-resource-object-links)
+
+You can use the `link` class method to define the links you need in the resource's primary data:
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+
+  link(:self) { user_path(object.id) }
+  link(:posts) { posts_path(user_id: object.id) }
+end
+
+user = User.new(id: 1, name: "Kelly")
+resource = ActiveModelSerializers::SerializableResource.new(user, adapter: :json_api)
+resource.to_json
+```
+
+This will result in:
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "Kelly"
+    },
+    "links": {
+      "self": "/users/1",
+      "posts": "/posts?user_id=1"
+    }
+  }
+}
+```
+
+### [Relationship links](http://jsonapi.org/format/#document-resource-object-relationships)
+
+You can use the `link` method wihtin you relationship block in order to define the links you need in the relationships:
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+  has_many :posts do
+    link(:self) do
+      user_posts_path(object.id) # Rails url helper automatically available
+    end 
+  end
+end
+
+user = User.new(id: 1, name: "Kelly", posts: [])
+resource = ActiveModelSerializers::SerializableResource.new(user, adapter: :json_api)
+resource.to_json
+```
+
+Note that `user_posts_path` method is one of Rails' url helpers, which are automatically available within the `link` block if you are using Rails.
+
+The previous snippet would result in:
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "Kelly"
+    },
+    "relationships": {
+      "posts": {
+        "data": [],
+        "links": {
+          "self": "users/1/posts"
+        }
+      }
+    }
+  }
+}
+```
+
+If you only want the `links` member to appear you can set `include_data false` within the relationship block:
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+  has_many :posts do
+    link(:self) do
+      include_data false
+      user_posts_path(object.id) # Rails url helper automatically available
+    end 
+  end
+end
+
+user = User.new(id: 1, name: "Kelly", posts: [ Post.new(id: 1) ])
+resource = ActiveModelSerializers::SerializableResource.new(user, adapter: :json_api)
+resource.to_json
+```
+
+This would result in:
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "users",
+    "attributes": {
+      "name": "Kelly"
+    },
+    "relationships": {
+      "posts": {
+        "links": {
+          "self": "users/1/posts"
+        }
+      }
+    }
+  }
+}
+```
+
+## JSON adapter
+
+The `json` is not able to handle links defined by the `link` class method. However, you can either use the `meta`  member or define a `links` attribute on the serializer.
+
+### Via `meta`
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name
+end
+user = User.new(id: 1, name: "John")
+meta = {
+  links: {
+    self: "/users/#{user.id}",
+    posts: "/posts?user_id=#{user.id}"
+  }
+}
+resource = ActiveModelSerializer::SerializableResource.new(
+  user,
+  adapter: :json,
+  meta: meta
+)
+resource.to_json
+```
+
+This would result in:
+
+```json
+{
+  "meta": {
+    "links": {
+      "self": "/users/1",
+      "posts": "/posts?user_id=1"
+    }
+  },
+  "user": {
+    "id": "1",
+    "name": "Example User",
+  }
+}
+```
+
+When using Rails, you can add links by providing the `meta` option to `render` method:
+
+```ruby
+class UserController < ActionController::Base
+  def show
+    user = User.new(id: 1, name: "John")
+     meta = {
+      links: {
+        self: "/users/#{user.id}",
+        posts: "/posts?user_id=#{user.id}"
+      }
+    }
+    render json: user, adapter: :json, meta: meta
+  end
+end
+```
+
+### Via an attribute
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :id, :name, :links
+  attribute :links do
+    {
+      self: "/users/#{object.id}",
+      posts: "/posts?user_id=#{object.id}"
+    }
+  end
+end
+
+user = User.new(id: 1, name: "John")
+resource = ActiveModelSerializer::SerializableResource.new(user, adapter: :json)
+resource.to_json
+```
+ 
+This would result in:
+```json
+{
+  "user": {
+    "id": "1",
+    "name": "Example User",
+    "links": {
+      "self": "/users/1",
+      "posts": "/posts?user_id=1"
+    }
+  }
+}
+```
+
+If you want to use the Rails' url/path helpers such as `user_path`, you need to `include` the `ActiveModelSerializers::SerializationContext::UrlHelpers` module into your serializer:
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  include ActiveModelSerializers::SerializationContext::UrlHelpers
+
+  attributes :id, :name, :links
+  attribute :links do
+    {
+      self: user_path(object.id),
+      posts: posts_path(user_id: object.id)
+    }
+  end
+end
+```
+
+## Attributes adapter
+
+The only way to provide pagination with the `attributes` adapter is to define a `links` attribute [as described for the JSON adapter above](#via-an-attribute).