active_model_serializers 0.10.0.rc4 → 0.10.0.rc5

data/docs/general/deserialization.md

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

@@ -80,6 +80,32 @@ 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,
@@ -96,3 +122,12 @@ class PostsController < ApplicationController
 
 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

@@ -17,7 +17,7 @@ Payload (example):
 ```ruby
 {
   serializer: PostSerializer,
-  adapter: ActiveModel::Serializer::Adapter::Attributes
+  adapter: ActiveModelSerializers::Adapter::Attributes
 }
 ```
 

data/docs/general/key_transforms.md

@@ -0,0 +1,40 @@
+[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/rendering.md

@@ -56,11 +56,11 @@ API for a plain-old Ruby object (PORO).
 
 ## SerializableResource options
 
-The `options` hash passed to `render` or `ActiveModel::SerializableResource.new(resource, 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 [ActiveModel::SerializableResource::ADAPTER_OPTIONS](../../lib/active_model/serializable_resource.rb#L4).
+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)`
@@ -79,10 +79,20 @@ PR please :)
 
 PR please :)
 
+#### key_transform
+
+```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```
+
+See [Key Transforms](key_transforms.md) for more informaiton.
+
 #### meta
 
-If you want a `meta` attribute in your response, specify it in the `render`
-call:
+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 }
@@ -94,16 +104,106 @@ The key can be customized using `meta_key` option.
 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`,
-as JsonAPI and Json adapters, the default adapter (Attributes) doesn't have `root`.
+`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`.
 
-#### meta_key
 
-PR please :)
+##### 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
 
-PR please :)
+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
 
@@ -111,12 +211,14 @@ PR please :)
 
 PR please :)
 
-#### root
+#### Overriding the root key
+
+Overriding the resource root only applies when using the JSON adapter.
 
-The resource root is derived from the class name of the resource being serialized.
+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.
 
-Specify the root by passing it as an argument to `render`. For example:
+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
@@ -130,7 +232,7 @@ This will be rendered as:
     }
   }
 ```
-Note: the `Attributes` adapter (default) does not include a resource root.
+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
 

data/docs/general/serializers.md

@@ -46,6 +46,16 @@ e.g.
 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
 ```
 
 #### ::has_many
@@ -76,6 +86,18 @@ def 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
@@ -107,23 +129,42 @@ end
 
 #### ::type
 
-e.g.
+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
 ```
 
-#### ::link
+With the `:json_api` adapter, the previous serializers would be rendered as:
 
-e.g.
+``` json
+{
+  "data": {
+    "id": "1",
+    "type": "profile"
+  }
+}
+```
+
+#### ::link
 
 ```ruby
-link :other, 'https://example.com/resource'
 link :self do
- href "https://example.com/link_author/#{object.id}"
+  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
@@ -136,7 +177,98 @@ PR please :)
 
 #### #scope
 
-PR please :)
+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)