active_model_serializers 0.10.0 → 0.10.11

data/docs/general/serializers.md

@@ -1,372 +0,0 @@
-[Back to Guides](../README.md)
-
-# Serializers
-
-Given a serializer class:
-
-```ruby
-class SomeSerializer < ActiveModel::Serializer
-end
-```
-
-The following methods may be defined in it:
-
-### Attributes
-
-#### ::attributes
-
-Serialization of the resource `title` and `body`
-
-| In Serializer               | #attributes |
-|---------------------------- |-------------|
-| `attributes :title, :body`  | `{ title: 'Some Title', body: 'Some Body' }`
-| `attributes :title, :body`<br>`def body "Special #{object.body}" end` | `{ title: 'Some Title', body: 'Special Some Body' }`
-
-
-#### ::attribute
-
-Serialization of the resource `title`
-
-| In Serializer               | #attributes |
-|---------------------------- |-------------|
-| `attribute :title`          | `{ title: 'Some Title' } `
-| `attribute :title, key: :name` | `{ name: 'Some 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)
-
-### Associations
-
-The interface for associations is, generically:
-
-> `association_type(association_name, options, &block)`
-
-Where:
-
-- `association_type` may be `has_one`, `has_many`, `belongs_to`.
-- `association_name` is a method name the serializer calls.
-- optional: `options` may be:
-  - `key:` The name used for the serialized association.
-  - `serializer:`
-  - `if:`
-  - `unless:`
-  - `virtual_value:`
-  - `polymorphic:` defines if polymorphic relation type should be nested in serialized association.
-- 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.
-  - yields the `serializer` to the block.
-  - `include_data false` prevents the `data` key from being rendered in the JSON API relationship.
-
-#### ::has_one
-
-e.g.
-
-```ruby
-has_one :bio
-has_one :blog, key: :site
-has_one :maker, virtual_value: { id: 1 }
-
-has_one :blog do |serializer|
-  serializer.cached_blog
-end
-
-def cached_blog
-  cache_store.fetch("cached_blog:#{object.updated_at}") do
-    Blog.find(object.blog_id)
-  end
-end
-```
-
-```ruby
-has_one :blog, if: :show_blog?
-# you can also use a string or lambda
-# has_one :blog, if: 'scope.admin?'
-# has_one :blog, if: -> (serializer) { serializer.scope.admin? }
-# has_one :blog, if: -> { scope.admin? }
-
-def show_blog?
-  scope.admin?
-end
-```
-
-#### ::has_many
-
-e.g.
-
-```ruby
-has_many :comments
-has_many :comments, key: :reviews
-has_many :comments, serializer: CommentPreviewSerializer
-has_many :reviews, virtual_value: [{ id: 1 }, { id: 2 }]
-has_many :comments, key: :last_comments do
-  last(1)
-end
-```
-
-#### ::belongs_to
-
-e.g.
-
-```ruby
-belongs_to :author, serializer: AuthorPreviewSerializer
-belongs_to :author, key: :writer
-belongs_to :post
-belongs_to :blog
-def blog
-  Blog.new(id: 999, name: 'Custom blog')
-end
-```
-
-### Polymorphic Relationships
-
-Polymorphic relationships are serialized by specifying the relationship, like any other association. For example:
-
-```ruby
-class PictureSerializer < ActiveModel::Serializer
-  has_one :imageable
-end
-```
-
-For more context, see the [tests](../../test/adapter/polymorphic_test.rb) for each adapter.
-
-### Caching
-
-#### ::cache
-
-e.g.
-
-```ruby
-cache key: 'post', expires_in: 0.1, skip_digest: true
-cache expires_in: 1.day, skip_digest: true
-cache key: 'writer', skip_digest: true
-cache only: [:name], skip_digest: true
-cache except: [:content], skip_digest: true
-cache key: 'blog'
-cache only: [:id]
-```
-
-#### #cache_key
-
-e.g.
-
-```ruby
-# Uses a custom non-time-based cache key
-def cache_key
-  "#{self.class.name.downcase}/#{self.id}"
-end
-```
-
-### Other
-
-#### ::type
-
-The `::type` method defines the JSONAPI [type](http://jsonapi.org/format/#document-resource-object-identification) that will be rendered for this serializer.
-It either takes a `String` or `Symbol` as parameter.
-
-Note: This method is useful only when using the `:json_api` adapter.
-
-Examples:
-```ruby
-class UserProfileSerializer < ActiveModel::Serializer
-  type 'profile'
-end
-class AuthorProfileSerializer < ActiveModel::Serializer
-  type :profile
-end
-```
-
-With the `:json_api` adapter, the previous serializers would be rendered as:
-
-``` json
-{
-  "data": {
-    "id": "1",
-    "type": "profile"
-  }
-}
-```
-
-#### ::link
-
-```ruby
-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 :other, 'https://example.com/resource'
-link :posts { link_author_posts_url(object) }
-```
-
-#### #object
-
-The object being serialized.
-
-#### #root
-
-PR please :)
-
-#### #scope
-
-Allows you to include in the serializer access to an external method.
-
-It's intended to provide an authorization context to the serializer, so that
-you may e.g. show an admin all comments on a post, else only published comments.
-
-- `scope` is a method on the serializer instance that comes from `options[:scope]`. It may be nil.
-- `scope_name` is an option passed to the new serializer (`options[:scope_name]`).  The serializer
-  defines a method with that name that calls the `scope`, e.g. `def current_user; scope; end`.
-  Note: it does not define the method if the serializer instance responds to it.
-
-That's a lot of words, so here's some examples:
-
-First, let's assume the serializer is instantiated in the controller, since that's the usual scenario.
-We'll refer to the serialization context as `controller`.
-
-| options | `Serializer#scope` | method definition |
-|-------- | ------------------|--------------------|
-| `scope: current_user, scope_name: :current_user` | `current_user` | `Serializer#current_user` calls `controller.current_user`
-| `scope: view_context, scope_name: :view_context` | `view_context` | `Serializer#view_context` calls `controller.view_context`
-
-We can take advantage of the scope to customize the objects returned based
-on the current user (scope).
-
-For example, we can limit the posts the current user sees to those they created:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  # scope comments to those created_by the current user
-  has_many :comments do
-    object.comments.where(created_by: current_user)
-  end
-end
-```
-
-Whether you write the method as above or as `object.comments.where(created_by: scope)`
-is a matter of preference (assuming `scope_name` has been set).
-
-##### Controller Authorization Context
-
-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
-`serialization_scope :view_context`.  The `scope` is set to `send(scope_name)` when `scope_name` is
-present and the controller responds to `scope_name`.
-
-Thus, in a serializer, the controller provides `current_user` as the
-current authorization scope when you call `render :json`.
-
-**IMPORTANT**: Since the scope is set at render, you may want to customize it so that `current_user` isn't
-called on every request.  This was [also a problem](https://github.com/rails-api/active_model_serializers/pull/1252#issuecomment-159810477)
-in [`0.9`](https://github.com/rails-api/active_model_serializers/tree/0-9-stable#customizing-scope).
-
-We can change the scope from `current_user` to `view_context`.
-
-```diff
-class SomeController < ActionController::Base
-+  serialization_scope :view_context
-
-  def current_user
-    User.new(id: 2, name: 'Bob', admin: true)
-  end
-
-  def edit
-    user = User.new(id: 1, name: 'Pete')
-    render json: user, serializer: AdminUserSerializer, adapter: :json_api
-  end
-end
-```
-
-We could then use the controller method `view_context` in our serializer, like so:
-
-```diff
-class AdminUserSerializer < ActiveModel::Serializer
-  attributes :id, :name, :can_edit
-
-  def can_edit?
-+    view_context.current_user.admin?
-  end
-end
-```
-
-So that when we render the `#edit` action, we'll get
-
-```json
-{"data":{"id":"1","type":"users","attributes":{"name":"Pete","can_edit":true}}}
-```
-
-Where `can_edit` is `view_context.current_user.admin?` (true).
-
-#### #read_attribute_for_serialization(key)
-
-The serialized value for a given key. e.g. `read_attribute_for_serialization(:title) #=> 'Hello World'`
-
-#### #links
-
-PR please :)
-
-#### #json_key
-
-PR please :)
-
-## Examples
-
-Given two models, a `Post(title: string, body: text)` and a
-`Comment(name: string, body: text, post_id: integer)`, you will have two
-serializers:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  cache key: 'posts', expires_in: 3.hours
-  attributes :title, :body
-
-  has_many :comments
-end
-```
-
-and
-
-```ruby
-class CommentSerializer < ActiveModel::Serializer
-  attributes :name, :body
-
-  belongs_to :post
-end
-```
-
-Generally speaking, you, as a user of ActiveModelSerializers, will write (or generate) these
-serializer classes.
-
-## More Info
-
-For more information, see [the Serializer class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer.rb)
-
-## Overriding association methods
-
-To override an association, call `has_many`, `has_one` or `belongs_to` with a block:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  has_many :comments do
-    object.comments.active
-  end
-end
-```
-
-## Overriding attribute methods
-
-To override an attribute, call `attribute` with a block:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attribute :body do
-    object.body.downcase
-  end
-end
-```

data/docs/howto/add_pagination_links.md

@@ -1,139 +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 others adapters does not have this feature, it is possible to
-implement pagination links to `JSON` adapter. For more information about it,
-please see in 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,
-    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,
-    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_root_key.md

@@ -1,51 +0,0 @@
-# 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"
-    }
-  ]
-}
-```

data/docs/howto/outside_controller_use.md

@@ -1,58 +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
-```
-
-### Looking up the Serializer for a Resource
-
-If you want to retrieve a serializer 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 an instance, if any, of the resource's serializer.
-
-## 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
-```

data/docs/howto/serialize_poro.md

@@ -1,32 +0,0 @@
-[Back to Guides](../README.md)
-
-# 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:
-```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]
-    @level = attributes[:level]
-  end
-
-  def self.model_name
-    @_model_name ||= ActiveModel::Name.new(self)
-  end
-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:
-```ruby
-# my_model.rb
-class MyModel < ActiveModelSerializers::Model
-  attr_accessor :id, :name, :level
-end
-```
-
-The default serializer would be `MyModelSerializer`.