active_model_serializers 0.10.0 → 0.10.9

data/docs/general/configuration_options.md

@@ -46,15 +46,72 @@ Each adapter has a default key transform configured:
 
 | Adapter | Default Key Transform |
 |----|----|
+| `Attributes` | `:unaltered` |
 | `Json` | `:unaltered` |
 | `JsonApi` | `:dash` |
 
 `config.key_transform` is a global override of the adapter default. Adapters
 still prefer the render option `:key_transform` over this setting.
 
+*NOTE: Key transforms can be expensive operations. If key transforms are unnecessary for the
+application, setting `config.key_transform` to `:unaltered` will provide a performance boost.*
 
-## JSON API
+##### default_includes
+
+What relationships to serialize by default.  Default: `'*'`, which includes one level of related
+objects. See [includes](adapters.md#included) for more info.
+
+
+##### serializer_lookup_chain
+
+Configures how serializers are searched for. By default, the lookup chain is
+
+```ruby
+ActiveModelSerializers::LookupChain::DEFAULT
+```
+
+which is shorthand for
+
+```ruby
+[
+  ActiveModelSerializers::LookupChain::BY_PARENT_SERIALIZER,
+  ActiveModelSerializers::LookupChain::BY_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE_NAMESPACE,
+  ActiveModelSerializers::LookupChain::BY_RESOURCE
+]
+```
+
+Each of the array entries represent a proc. A serializer lookup proc will be yielded 3 arguments. `resource_class`, `serializer_class`, and `namespace`.
+
+Note that:
+ - `resource_class` is the class of the resource being rendered
+ - by default `serializer_class` is `ActiveModel::Serializer`
+   - for association lookup it's the "parent" serializer
+ - `namespace` correspond to either the controller namespace or the [optionally] specified [namespace render option](./rendering.md#namespace)
+
+An example config could be:
+
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain = [
+  lambda do |resource_class, serializer_class, namespace|
+    "API::#{namespace}::#{resource_class}"
+  end
+]
+```
+
+If you simply want to add to the existing lookup_chain. Use `unshift`.
 
+```ruby
+ActiveModelSerializers.config.serializer_lookup_chain.unshift(
+  lambda do |resource_class, serializer_class, namespace|
+    # ...
+  end
+)
+```
+
+See [lookup_chain.rb](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/lookup_chain.rb) for further explanations and examples.
+
+## JSON API
 
 ##### jsonapi_resource_type
 
@@ -67,6 +124,19 @@ Possible values:
 - `:singular`
 - `:plural` (default)
 
+##### jsonapi_namespace_separator
+
+Sets separator string for namespaced models to render `type` attribute.
+
+
+| Separator | Example: Admin::User |
+|----|----|
+| `'-'` (default) | 'admin-users'
+| `'--'` (recommended) | 'admin--users'
+
+See [Recommendation for dasherizing (kebab-case-ing) namespaced object, such as `Admin::User`](https://github.com/json-api/json-api/issues/850)
+for more discussion.
+
 ##### jsonapi_include_toplevel_object
 
 Include a [top level jsonapi member](http://jsonapi.org/format/#document-jsonapi-object)
@@ -93,6 +163,21 @@ Default: `{}`.
 
 *Used when `jsonapi_include_toplevel_object` is `true`*
 
+##### jsonapi_use_foreign_key_on_belongs_to_relationship
+
+When true, the relationship will determine its resource object identifier
+without calling the association or its serializer.  This can be useful when calling
+the association object is triggering unnecessary queries.
+
+For example, if a `comment` belongs to a `post`, and the comment
+uses the foreign key `post_id`, we can determine the resource object
+identifier `id` as `comment.post_id` and the `type` from the association options.
+Or quite simply, it behaves as `belongs_to :post, type: :posts, foreign_key: :post_id`.
+
+Note: This option has *no effect* on polymorphic associations as we cannot reliably
+determine the associated object's type without instantiating it.
+
+Default: `false`.
 
 ## Hooks
 

data/docs/general/deserialization.md

@@ -42,7 +42,7 @@ document = {
       'title' => 'Title 1',
       'date' => '2015-12-20'
     },
-    'associations' => {
+    'relationships' => {
       'author' => {
         'data' => {
           'type' => 'user',

data/docs/general/fields.md

@@ -0,0 +1,31 @@
+[Back to Guides](../README.md)
+
+# Fields
+
+If for any reason, you need to restrict the fields returned, you should use `fields` option.
+
+For example, if you have a serializer like this
+
+```ruby
+class UserSerializer < ActiveModel::Serializer
+  attributes :access_token, :first_name, :last_name
+end
+```
+
+and in a specific controller, you want to return `access_token` only, `fields` will help you:
+
+```ruby
+class AnonymousController < ApplicationController
+  def create
+    render json: User.create(activation_state: 'anonymous'), fields: [:access_token], status: 201
+  end
+end
+```
+
+Note that this is only valid for the `json` and `attributes` adapter. For the `json_api` adapter, you would use
+
+```ruby
+render json: @user, fields: { users: [:access_token] }
+```
+
+Where `users` is the JSONAPI type.

data/docs/general/getting_started.md

@@ -37,7 +37,7 @@ and
 class CommentSerializer < ActiveModel::Serializer
   attributes :name, :body
 
-  belongs_to :post_id
+  belongs_to :post
 end
 ```
 

data/docs/general/logging.md

@@ -12,3 +12,10 @@ You may customize the logger in an initializer, for example:
 ```ruby
 ActiveModelSerializers.logger = Logger.new(STDOUT)
 ```
+
+You can also disable the logger, just put this in `config/initializers/active_model_serializers.rb`:
+
+```ruby
+require 'active_model_serializers'
+ActiveSupport::Notifications.unsubscribe(ActiveModelSerializers::Logging::RENDER_EVENT)
+```

data/docs/general/rendering.md

@@ -48,42 +48,36 @@ render json: @posts, serializer: CollectionSerializer, each_serializer: PostPrev
 
 ## Serializing non-ActiveRecord objects
 
-All serializable resources must pass the
-[ActiveModel::Serializer::Lint::Tests](../../lib/active_model/serializer/lint.rb#L17).
-
-See the ActiveModelSerializers::Model for a base class that implements the full
-API for a plain-old Ruby object (PORO).
+See [README](../../README.md#what-does-a-serializable-resource-look-like)
 
 ## SerializableResource options
 
-The `options` hash passed to `render` or `ActiveModelSerializers::SerializableResource.new(resource, options)`
-are partitioned into `serializer_opts` and `adapter_opts`. `adapter_opts` are passed to new Adapters;
-`serializer_opts` are passed to new Serializers.
-
-The `adapter_opts` are specified in [ActiveModelSerializers::SerializableResource::ADAPTER_OPTIONS](../../lib/active_model_serializers/serializable_resource.rb#L5).
-The `serializer_opts` are the remaining options.
-
-(In Rails, the `options` are also passed to the `as_json(options)` or `to_json(options)`
-methods on the resource serialization by the Rails JSON renderer.  They are, therefore, important
-to know about, but not part of ActiveModelSerializers.)
-
-See [ARCHITECTURE](../ARCHITECTURE.md) for more information.
+See [README](../../README.md#activemodelserializersserializableresource)
 
 ### adapter_opts
 
 #### fields
 
-PR please :)
+If you are using `json` or `attributes` adapter
+```ruby
+render json: @user, fields: [:access_token]
+```
+
+See [Fields](fields.md) for more information.
 
 #### adapter
 
-PR please :)
+This option lets you explicitly set the adapter to be used by passing a registered adapter. Your options are `:attributes`, `:json`, and `:json_api`.
+
+```
+ActiveModel::Serializer.config.adapter = :json_api
+```
 
 #### key_transform
 
 ```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
 
-See [Key Transforms](key_transforms.md) for more informaiton.
+See [Key Transforms](key_transforms.md) for more information.
 
 #### meta
 
@@ -209,7 +203,7 @@ link(:link_name) { url_for(controller: 'controller_name', action: 'index', only_
 
 #### include
 
-PR please :)
+See [Adapters: Include Option](/docs/general/adapters.md#include-option).
 
 #### Overriding the root key
 
@@ -234,17 +228,61 @@ This will be rendered as:
 ```
 Note: the `Attributes` adapter (default) does not include a resource root. You also will not be able to create a single top-level root if you are using the :json_api adapter.
 
+#### namespace
+
+The namespace for serializer lookup is based on the controller.
+
+To configure the implicit namespace, in your controller, create a before filter
+
+```ruby
+before_action do
+  self.namespace_for_serializer = Api::V2
+end
+```
+
+`namespace` can also be passed in as a render option:
+
+
+```ruby
+@post = Post.first
+render json: @post, namespace: Api::V2
+```
+
+This tells the serializer lookup to check for the existence of `Api::V2::PostSerializer`, and if any relations are rendered with `@post`, they will also utilize the `Api::V2` namespace.  
+
+The `namespace` can be any object whose namespace can be represented by string interpolation (i.e. by calling to_s)
+- Module `Api::V2`
+- String `'Api::V2'`
+- Symbol `:'Api::V2'`
+
+Note that by using a string and symbol, Ruby will assume the namespace is defined at the top level.
+
+
 #### serializer
 
-PR please :)
+Specify which serializer to use if you want to use a serializer other than the default.
+
+For a single resource:
+
+```ruby
+@post = Post.first
+render json: @post, serializer: SpecialPostSerializer
+```
+
+To specify which serializer to use on individual items in a collection (i.e., an `index` action), use `each_serializer`:
+
+```ruby
+@posts = Post.all
+render json: @posts, each_serializer: SpecialPostSerializer
+```
 
 #### scope
 
-PR please :)
+See [Serializers: Scope](/docs/general/serializers.md#scope).
 
 #### scope_name
 
-PR please :)
+See [Serializers: Scope](/docs/general/serializers.md#scope).
 
 ## Using a serializer without `render`
 
@@ -252,4 +290,4 @@ See [Usage outside of a controller](../howto/outside_controller_use.md#serializi
 
 ## Pagination
 
-See [How to add pagination links](https://github.com/rails-api/active_model_serializers/blob/master/docs/howto/add_pagination_links.md).
+See [How to add pagination links](../howto/add_pagination_links.md).

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:` the (String) model name used to determine `type`, when `type` is not given. e.g. `class_name: "Comment"` would imply the type `comments`
+  - `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.
@@ -66,6 +81,7 @@ e.g.
 ```ruby
 has_one :bio
 has_one :blog, key: :site
+has_one :blog, class_name: "Blog"
 has_one :maker, virtual_value: { id: 1 }
 
 has_one :blog do |serializer|
@@ -99,6 +115,7 @@ e.g.
 has_many :comments
 has_many :comments, key: :reviews
 has_many :comments, serializer: CommentPreviewSerializer
+has_many :comments, class_name: "Comment"
 has_many :reviews, virtual_value: [{ id: 1 }, { id: 2 }]
 has_many :comments, key: :last_comments do
   last(1)
@@ -112,6 +129,7 @@ e.g.
 ```ruby
 belongs_to :author, serializer: AuthorPreviewSerializer
 belongs_to :author, key: :writer
+belongs_to :author, class_name: "Author"
 belongs_to :post
 belongs_to :blog
 def blog
@@ -129,7 +147,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 +180,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 +208,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 +232,19 @@ 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) }
+```
+
+Just like attributes, links also support conditions in options
+```ruby
+link(:secret, if: :internal?) { object.secret_link }
+
+def internal?
+  instance_options[:context] == :internal
+end
 ```
 
 #### #object
@@ -206,7 +253,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
 
@@ -249,13 +306,15 @@ 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).
 
+Keep in mind that the scope can be set to any available controller reference. This can be utilized to provide access to any other data scopes or presentation helpers.
+
 ##### 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
+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`.
 
@@ -266,7 +325,7 @@ current authorization scope when you call `render :json`.
 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`.
+We can change the scope from `current_user` to `view_context`, which is included in subclasses of `ActionController::Base`.
 
 ```diff
 class SomeController < ActionController::Base
@@ -303,17 +362,65 @@ 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
+```
+Note that any controller reference which provides the desired scope is acceptable, such as another controller method for loading a different resource or reference to helpers. For example, `ActionController::API` does not include `ActionView::ViewContext`, and would need a different reference for passing any helpers into a serializer via `serialization_scope`.
+
 #### #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 +477,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.name == '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.