active_model_serializers 0.10.0 → 0.10.12

data/docs/general/deserialization.md

@@ -1,100 +0,0 @@
-[Back to Guides](../README.md)
-
-# Deserialization
-
-This is currently an *experimental* feature. The interface may change.
-
-## JSON API
-
-The `ActiveModelSerializers::Deserialization` defines two methods (namely `jsonapi_parse` and `jsonapi_parse!`), which take a `Hash` or an instance of `ActionController::Parameters` representing a JSON API payload, and return a hash that can directly be used to create/update models. The bang version throws an `InvalidDocument` exception when parsing fails, whereas the "safe" version simply returns an empty hash.
-
-- Parameters
-  - document: `Hash` or `ActionController::Parameters` instance
-  - options:
-    - only: `Array` of whitelisted fields
-    - except: `Array` of blacklisted fields
-    - keys: `Hash` of fields the name of which needs to be modified (e.g. `{ :author => :user, :date => :created_at }`)
-
-Examples:
-
-```ruby
-class PostsController < ActionController::Base
-  def create
-    Post.create(create_params)
-  end
-
-  def create_params
-    ActiveModelSerializers::Deserialization.jsonapi_parse(params, only: [:title, :content, :author])
-  end
-end
-```
-
-
-
-Given a JSON API document,
-
-```
-document = {
-  'data' => {
-    'id' => 1,
-    'type' => 'post',
-    'attributes' => {
-      'title' => 'Title 1',
-      'date' => '2015-12-20'
-    },
-    'associations' => {
-      'author' => {
-        'data' => {
-          'type' => 'user',
-          'id' => '2'
-        }
-      },
-      'second_author' => {
-        'data' => nil
-      },
-      'comments' => {
-        'data' => [{
-          'type' => 'comment',
-          'id' => '3'
-        },{
-          'type' => 'comment',
-          'id' => '4'
-        }]
-      }
-    }
-  }
-}
-```
-
-The entire document can be parsed without specifying any options:
-```ruby
-ActiveModelSerializers::Deserialization.jsonapi_parse(document)
-#=>
-# {
-#   title: 'Title 1',
-#   date: '2015-12-20',
-#   author_id: 2,
-#   second_author_id: nil
-#   comment_ids: [3, 4]
-# }
-```
-
-and fields, relationships, and polymorphic relationships can be specified via the options:
-
-```ruby
-ActiveModelSerializers::Deserialization
-  .jsonapi_parse(document, only: [:title, :date, :author],
-                           keys: { date: :published_at },
-                           polymorphic: [:author])
-#=>
-# {
-#   title: 'Title 1',
-#   published_at: '2015-12-20',
-#   author_id: '2',
-#   author_type: 'user'
-# }
-```
-
-## Attributes/Json
-
-There is currently no deserialization for those adapters.

data/docs/general/getting_started.md

@@ -1,133 +0,0 @@
-[Back to Guides](../README.md)
-
-# Getting Started
-
-## Creating a Serializer
-
-The easiest way to create a new serializer is to generate a new resource, which
-will generate a serializer at the same time:
-
-```
-$ rails g resource post title:string body:string
-```
-
-This will generate a serializer in `app/serializers/post_serializer.rb` for
-your new model. You can also generate a serializer for an existing model with
-the serializer generator:
-
-```
-$ rails g serializer post
-```
-
-The generated serializer will contain basic `attributes` and
-`has_many`/`has_one`/`belongs_to` declarations, based on the model. For example:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :title, :body
-
-  has_many :comments
-  has_one :author
-end
-```
-
-and
-
-```ruby
-class CommentSerializer < ActiveModel::Serializer
-  attributes :name, :body
-
-  belongs_to :post_id
-end
-```
-
-The attribute names are a **whitelist** of attributes to be serialized.
-
-The `has_many`, `has_one`, and `belongs_to` declarations describe relationships between
-resources. By default, when you serialize a `Post`, you will get its `Comments`
-as well.
-
-For more information, see [Serializers](/docs/general/serializers.md).
-
-### Namespaced Models
-
-When serializing a model inside a namespace, such as `Api::V1::Post`, ActiveModelSerializers will expect the corresponding serializer to be inside the same namespace (namely `Api::V1::PostSerializer`).
-
-### Model Associations and Nested Serializers
-
-When declaring a serializer for a model with associations, such as:
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  has_many :comments
-end
-```
-ActiveModelSerializers will look for `PostSerializer::CommentSerializer` in priority, and fall back to `::CommentSerializer` in case the former does not exist. This allows for more control over the way a model gets serialized as an association of an other model.
-
-For example, in the following situation:
-
-```ruby
-class CommentSerializer < ActiveModel::Serializer
-  attributes :body, :date, :nb_likes
-end
-
-class PostSerializer < ActiveModel::Serializer
-  has_many :comments
-  class CommentSerializer < ActiveModel::Serializer
-    attributes :body_short
-  end
-end
-```
-
-ActiveModelSerializers will use `PostSerializer::CommentSerializer` (thus including only the `:body_short` attribute) when serializing a `Comment` as part of a `Post`, but use `::CommentSerializer` when serializing a `Comment` directly (thus including `:body, :date, :nb_likes`).
-
-### Extending a Base `ApplicationSerializer`
-
-By default, new serializers descend from `ActiveModel::Serializer`. However, if
-you wish to share behavior across your serializers, you can create an
-`ApplicationSerializer` at `app/serializers/application_serializer.rb`:
-
-```ruby
-class ApplicationSerializer < ActiveModel::Serializer
-end
-```
-
-Then any newly-generated serializers will automatically descend from
-`ApplicationSerializer`.
-
-```
-$ rails g serializer post
-```
-
-Now generates:
-
-```ruby
-class PostSerializer < ApplicationSerializer
-  attributes :id
-end
-````
-
-## Rails Integration
-
-ActiveModelSerializers will automatically integrate with your Rails app,
-so you won't need to update your controller.
-This is a example of how the controller will look:
-
-```ruby
-class PostsController < ApplicationController
-
-  def show
-    @post = Post.find(params[:id])
-    render json: @post
-  end
-
-end
-```
-
-If you wish to use Rails url helpers for link generation, e.g., `link(:resources) { resources_url }`, ensure your application sets
-`Rails.application.routes.default_url_options`.
-
-```ruby
-Rails.application.routes.default_url_options = {
-    host: 'example.com'
-}
-```

data/docs/general/instrumentation.md

@@ -1,40 +0,0 @@
-[Back to Guides](../README.md)
-
-# Instrumentation
-
-ActiveModelSerializers uses the
-[ActiveSupport::Notification API](http://guides.rubyonrails.org/active_support_instrumentation.html#subscribing-to-an-event),
-which allows for subscribing to events, such as for logging.
-
-## Events
-
-Name:
-
-`render.active_model_serializers`
-
-Payload (example):
-
-```ruby
-{
-  serializer: PostSerializer,
-  adapter: ActiveModelSerializers::Adapter::Attributes
-}
-```
-
-Subscribing:
-
-```ruby
-ActiveSupport::Notifications.subscribe 'render.active_model_serializers' do |name, started, finished, unique_id, data|
-  # whatever
-end
-ActiveSupport::Notifications.subscribe 'render.active_model_serializers' do |*args|
-  event = ActiveSupport::Notifications::Event.new(*args)
-  # event.payload
-  # whatever
-end
-```
-
-## [LogSubscriber](http://api.rubyonrails.org/classes/ActiveSupport/LogSubscriber.html)
-
-ActiveModelSerializers includes an `ActiveModelSerializers::LogSubscriber` that attaches to
-`render.active_model_serializers`.

data/docs/general/key_transforms.md

@@ -1,40 +0,0 @@
-[Back to Guides](../README.md)
-
-# Key Transforms
-
-Key Transforms modify the casing of keys and keys referenced in values in
-serialized responses.
-
-Provided key transforms:
-
-| Option | Result |
-|----|----|
-| `:camel` | ExampleKey |
-| `:camel_lower` | exampleKey |
-| `:dash` | example-key |
-| `:unaltered` | the original, unaltered key |
-| `:underscore` | example_key |
-| `nil` | use the adapter default |
-
-Key translation precedence is as follows:
-
-##### Adapter option
-
-`key_transform` is provided as an option via render.
-
-```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
-
-##### Configuration option
-
-`key_transform` is set in `ActiveModelSerializers.config.key_transform`.
-
-```ActiveModelSerializers.config.key_transform = :camel_lower```
-
-##### Adapter default
-
-Each adapter has a default transform configured:
-
-| Adapter | Default Key Transform |
-|----|----|
-| `Json` | `:unaltered` |
-| `JsonApi` | `:dash` |

data/docs/general/logging.md

@@ -1,14 +0,0 @@
-[Back to Guides](../README.md)
-
-# Logging
-
-The default logger in a Rails application will be `Rails.logger`.
-
-When there is no `Rails.logger`, the default logger is an instance of
-`ActiveSupport::TaggedLogging` logging to STDOUT.
-
-You may customize the logger in an initializer, for example:
-
-```ruby
-ActiveModelSerializers.logger = Logger.new(STDOUT)
-```

data/docs/general/rendering.md

@@ -1,255 +0,0 @@
-[Back to Guides](../README.md)
-
-# Rendering
-
-### Implicit Serializer
-
-In your controllers, when you use `render :json`, Rails will now first search
-for a serializer for the object and use it if available.
-
-```ruby
-class PostsController < ApplicationController
-  def show
-    @post = Post.find(params[:id])
-
-    render json: @post
-  end
-end
-```
-
-In this case, Rails will look for a serializer named `PostSerializer`, and if
-it exists, use it to serialize the `Post`.
-
-### Explicit Serializer
-
-If you wish to use a serializer other than the default, you can explicitly pass it to the renderer.
-
-#### 1. For a resource:
-
-```ruby
-  render json: @post, serializer: PostPreviewSerializer
-```
-
-#### 2. For a resource collection:
-
-Specify the serializer for each resource with `each_serializer`
-
-```ruby
-render json: @posts, each_serializer: PostPreviewSerializer
-```
-
-The default serializer for collections is `CollectionSerializer`.
-
-Specify the collection serializer with the `serializer` option.
-
-```ruby
-render json: @posts, serializer: CollectionSerializer, each_serializer: PostPreviewSerializer
-```
-
-## 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).
-
-## 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.
-
-### adapter_opts
-
-#### fields
-
-PR please :)
-
-#### adapter
-
-PR please :)
-
-#### key_transform
-
-```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
-
-See [Key Transforms](key_transforms.md) for more informaiton.
-
-#### meta
-
-A `meta` member can be used to include non-standard meta-information. `meta` can
-be utilized in several levels in a response.
-
-##### Top-level
-
-To set top-level `meta` in a response, specify it in the `render` call.
-
-```ruby
-render json: @post, meta: { total: 10 }
-```
-
-The key can be customized using `meta_key` option.
-
-```ruby
-render json: @post, meta: { total: 10 }, meta_key: "custom_meta"
-```
-
-`meta` will only be included in your response if you are using an Adapter that
-supports `root`, e.g., `JsonApi` and `Json` adapters. The default adapter,
-`Attributes` does not have `root`.
-
-
-##### Resource-level
-
-To set resource-level `meta` in a response, define meta in a serializer with one
-of the following methods:
-
-As a single, static string.
-
-```ruby
-meta stuff: 'value'
-```
-
-As a block containing a Hash.
-
-```ruby
-meta do
-  {
-    rating: 4,
-    comments_count: object.comments.count
-  }
-end
-```
-
-
-#### links
-
-If you wish to use Rails url helpers for link generation, e.g., `link(:resources) { resources_url }`, ensure your application sets
-`Rails.application.routes.default_url_options`.
-
-##### Top-level
-
-JsonApi supports a [links object](http://jsonapi.org/format/#document-links) to be specified at top-level, that you can specify in the `render`:
-
-```ruby
-  links_object = {
-    href: "http://example.com/api/posts",
-    meta: {
-      count: 10
-    }
-  }
-  render json: @posts, links: links_object
-```
-
-That's the result:
-
-```json
-{
-  "data": [
-    {
-      "type": "posts",
-      "id": "1",
-      "attributes": {
-        "title": "JSON API is awesome!",
-        "body": "You should be using JSON API",
-        "created": "2015-05-22T14:56:29.000Z",
-        "updated": "2015-05-22T14:56:28.000Z"
-      }
-    }
-  ],
-  "links": {
-    "href": "http://example.com/api/posts",
-    "meta": {
-      "count": 10
-    }
-  }
-}
-```
-
-This feature is specific to JsonApi, so you have to use the use the [JsonApi Adapter](adapters.md#jsonapi)
-
-
-##### Resource-level
-
-In your serializer, define each link in one of the following methods:
-
-As a static string
-
-```ruby
-link :link_name, 'https://example.com/resource'
-```
-
-As a block to be evaluated. When using Rails, URL helpers are available.
-Ensure your application sets `Rails.application.routes.default_url_options`.
-
-```ruby
-link :link_name_ do
-  "https://example.com/resource/#{object.id}"
-end
-
-link(:link_name) { "https://example.com/resource/#{object.id}" }
-
-link(:link_name) { resource_url(object) }
-
-link(:link_name) { url_for(controller: 'controller_name', action: 'index', only_path: false) }
-
-```
-
-### serializer_opts
-
-#### include
-
-PR please :)
-
-#### Overriding the root key
-
-Overriding the resource root only applies when using the JSON adapter.
-
-Normally, the resource root is derived from the class name of the resource being serialized.
-e.g. `UserPostSerializer.new(UserPost.new)` will be serialized with the root `user_post` or `user_posts` according the adapter collection pluralization rules.
-
-When using the JSON adapter in your initializer (ActiveModelSerializers.config.adapter = :json), or passing in the adapter in your render call, you can specify the root by passing it as an argument to `render`. For example:
-
-```ruby
-  render json: @user_post, root: "admin_post", adapter: :json
-```
-
-This will be rendered as:
-```json
-  {
-    "admin_post": {
-      "title": "how to do open source"
-    }
-  }
-```
-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.
-
-#### serializer
-
-PR please :)
-
-#### scope
-
-PR please :)
-
-#### scope_name
-
-PR please :)
-
-## Using a serializer without `render`
-
-See [Usage outside of a controller](../howto/outside_controller_use.md#serializing-before-controller-render).
-
-## Pagination
-
-See [How to add pagination links](https://github.com/rails-api/active_model_serializers/blob/master/docs/howto/add_pagination_links.md).