active_model_serializers 0.8.3 → 0.10.0.rc3

data/Rakefile

@@ -1,18 +1,39 @@
-#!/usr/bin/env rake
-require "bundler/gem_tasks"
-require "rake/testtask"
+begin
+  require 'simplecov'
+rescue LoadError
+end
 
-desc 'Run tests'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
+require 'bundler/gem_tasks'
+
+begin
+  require 'rubocop'
+  require 'rubocop/rake_task'
+rescue LoadError
+else
+  Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
+  if !defined?(::Rubinius)
+    Rake::Task[:rubocop].clear if Rake::Task.task_defined?(:rubocop)
+    desc 'Execute rubocop'
+    RuboCop::RakeTask.new(:rubocop) do |task|
+      task.options = ['--rails', '--display-cop-names', '--display-style-guide']
+      task.fail_on_error = true
+    end
+  else
+    desc 'No-op rubocop to avoid rbx segfault'
+    task :rubocop do
+      puts 'Skipping rubocop on rbx due to segfault'
+      puts 'https://github.com/rubinius/rubinius/issues/3499'
+    end
+  end
 end
 
-desc 'Benchmark'
-task :bench do
-  load 'bench/perf.rb' 
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.ruby_opts = ['-r./test/test_helper.rb']
+  t.verbose = true
 end
 
 task :default => :test

data/active_model_serializers.gemspec

@@ -1,24 +1,50 @@
-# -*- encoding: utf-8 -*-
-
-$:.unshift File.expand_path("../lib", __FILE__)
-require "active_model/serializers/version"
-
-Gem::Specification.new do |gem|
-  gem.authors       = ["José Valim", "Yehuda Katz"]
-  gem.email         = ["jose.valim@gmail.com", "wycats@gmail.com"]
-  gem.description   = %q{Making it easy to serialize models for client-side use}
-  gem.summary       = %q{Bringing consistency and object orientation to model serialization. Works great for client-side MVC frameworks!}
-  gem.homepage      = "https://github.com/rails-api/active_model_serializers"
-
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  gem.files         = `git ls-files`.split("\n")
-  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  gem.name          = "active_model_serializers"
-  gem.require_paths = ["lib"]
-  gem.version       = ActiveModel::Serializer::VERSION
-
-  gem.add_dependency 'activemodel', '>= 3.0'
-  gem.add_development_dependency "rails", ">= 3.0"
-  gem.add_development_dependency "pry"
-  gem.add_development_dependency "minitest"
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'active_model/serializer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'active_model_serializers'
+  spec.version       = ActiveModel::Serializer::VERSION
+  spec.platform      = Gem::Platform::RUBY
+  spec.authors       = ['Steve Klabnik']
+  spec.email         = ['steve@steveklabnik.com']
+  spec.summary       = 'Conventions-based JSON generation for Rails.'
+  spec.description   = 'ActiveModel::Serializers allows you to generate your JSON in an object-oriented and convention-driven manner.'
+  spec.homepage      = 'https://github.com/rails-api/active_model_serializers'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 1.9.3'
+
+  rails_versions = '>= 4.0'
+  spec.add_runtime_dependency 'activemodel', rails_versions
+    # 'activesupport', rails_versions
+    # 'builder'
+
+  spec.add_runtime_dependency 'actionpack', rails_versions
+    # 'activesupport', rails_versions
+    # 'rack'
+    # 'rack-test', '~> 0.6.2'
+
+  spec.add_runtime_dependency 'railties', rails_versions
+    # 'activesupport', rails_versions
+    # 'actionpack', rails_versions
+    # 'rake', '>= 0.8.7'
+
+  # 'activesupport', rails_versions
+    # 'i18n,
+    # 'tzinfo'
+    # 'minitest'
+    # 'thread_safe'
+
+  # Soft dependency for pagination
+  spec.add_development_dependency 'kaminari', ' ~> 0.16.3'
+  spec.add_development_dependency 'will_paginate', '~> 3.0', '>= 3.0.7'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'timecop', '~> 0.7'
 end

data/appveyor.yml

@@ -0,0 +1,25 @@
+version: '{build}'
+
+skip_tags: true
+
+environment:
+  matrix:
+    - ruby_version: "193"
+    - ruby_version: "193-x64"
+    - ruby_version: "200"
+    - ruby_version: "200-x64"
+    - ruby_version: "21"
+    - ruby_version: "21-x64"
+
+install:
+  - SET PATH=C:\Ruby%ruby_version%\bin;%PATH%
+  - ruby --version
+  - gem --version
+  - gem install bundler
+  - bundler --version
+  - bundle install --retry=3
+
+test_script:
+  - bundle exec rake
+
+build: off

data/docs/README.md

@@ -0,0 +1,29 @@
+# Docs - ActiveModel::Serializer 0.10.x
+
+This is the documentation of AMS, it's focused on the **0.10.x version.**
+
+-----
+
+## General
+
+- [Getting Started](general/getting_started.md)
+- [Adapters](general/adapters.md)
+- [Configuration Options](general/configuration_options.md)
+
+## How to
+
+- [How to add root key](howto/add_root_key.md)
+- [How to add pagination links](howto/add_pagination_links.md)
+- [Using AMS Outside Of Controllers](howto/outside_controller_use.md)
+
+## Getting Help
+
+If you find a bug, please report an [Issue](https://github.com/rails-api/active_model_serializers/issues/new).
+
+If you have a question, please [post to Stack Overflow](http://stackoverflow.com/questions/tagged/active-model-serializers).
+
+Thanks!
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/rails-api/active_model_serializers/blob/master/CONTRIBUTING.md)

data/docs/general/adapters.md

@@ -0,0 +1,110 @@
+# Adapters
+
+AMS does this through two components: **serializers** and **adapters**.
+Serializers describe _which_ attributes and relationships should be serialized.
+Adapters describe _how_ attributes and relationships should be serialized.
+You can use one of the built-in adapters (```FlattenJSON``` is the default one) or create one by yourself, but you won't need to implement an adapter unless you wish to use a new format or media type with AMS.
+
+## Built in Adapters
+
+### FlattenJSON - Default
+
+It's the default adapter, it generates a json response without a root key.
+Doesn't follow any specifc convention.
+
+### JSON
+
+It also generates a json response but always with a root key. The root key **can't be overridden**, and will be automatically defined accordingly to the objects being serialized.
+Doesn't follow any specifc convention.
+
+### JSONAPI
+
+This adapter follows **version 1.0** of the format specified in
+[jsonapi.org/format](http://jsonapi.org/format). It will include the associated
+resources in the `"included"` member when the resource names are included in the
+`include` option.
+
+```ruby
+render @posts, include: ['authors', 'comments']
+```
+
+or
+
+```ruby
+render @posts, include: 'authors,comments'
+```
+
+The format of the `include` option can be either a String composed of a comma-separated list of [relationship paths](http://jsonapi.org/format/#fetching-includes), an Array of Symbols and Hashes, or a mix of both.
+
+## Choosing an adapter
+
+If you want to use a specify a default adapter, such as JsonApi, you can change this in an initializer:
+
+```ruby
+ActiveModel::Serializer.config.adapter = ActiveModel::Serializer::Adapter::JsonApi
+```
+
+or
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json_api
+```
+
+If you want to have a root key for each resource in your responses, you should use the Json or
+JsonApi adapters instead of the default FlattenJson:
+
+```ruby
+ActiveModel::Serializer.config.adapter = :json
+```
+
+## Advanced adapter configuration
+
+### Registering an adapter
+
+The default adapter can be configured, as above, to use any class given to it.
+
+An adapter may also be specified, e.g. when rendering, as a class or as a symbol.
+If a symbol, then the adapter must be, e.g. `:great_example`,
+`ActiveModel::Serializer::Adapter::GreatExample`, or registered.
+
+There are two ways to register an adapter:
+
+1) The simplest, is to subclass `ActiveModel::Serializer::Adapter`, e.g. the below will
+register the `Example::UsefulAdapter` as `:useful_adapter`.
+
+```ruby
+module Example
+  class UsefulAdapter < ActiveModel::Serializer::Adapter
+  end
+end
+```
+
+You'll notice that the name it registers is the class name underscored, not the full namespace.
+
+Under the covers, when the `ActiveModel::Serializer::Adapter` is subclassed, it registers
+the subclass as `register(:useful_adapter, Example::UsefulAdapter)`
+
+2) Any class can be registered as an adapter by calling `register` directly on the
+`ActiveModel::Serializer::Adapter` class. e.g., the below registers `MyAdapter` as
+`:special_adapter`.
+
+```ruby
+class MyAdapter; end
+ActiveModel::Serializer::Adapter.register(:special_adapter, MyAdapter)
+```
+
+### Looking up an adapter
+
+| Method | Return value |
+| :------------ |:---------------|
+| `ActiveModel::Serializer::Adapter.adapter_map` | A Hash of all known adapters `{ adapter_name => adapter_class }` |
+| `ActiveModel::Serializer::Adapter.adapters` | A (sorted) Array of all known `adapter_names` |
+| `ActiveModel::Serializer::Adapter.lookup(name_or_klass)` |  The `adapter_class`, else raises an `ActiveModel::Serializer::Adapter::UnknownAdapter` error |
+| `ActiveModel::Serializer::Adapter.adapter_class(adapter)` | Delegates to `ActiveModel::Serializer::Adapter.lookup(adapter)` |
+| `ActiveModel::Serializer.adapter` | A convenience method for `ActiveModel::Serializer::Adapter.lookup(config.adapter)` |
+
+The registered adapter name is always a String, but may be looked up as a Symbol or String.
+Helpfully, the Symbol or String is underscored, so that `get(:my_adapter)` and `get("MyAdapter")`
+may both be used.
+
+For more information, see [the Adapter class on GitHub](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/adapter.rb)

data/docs/general/configuration_options.md

@@ -0,0 +1,11 @@
+# Configuration Options
+
+The following configuration options can be set on `ActiveModel::Serializer.config` inside an initializer.
+
+## General
+
+- `adapter`: The [adapter](adapters.md) to use. Possible values: `:flatten_json, :json, :json_api`. Default: `:flatten_json`.
+
+## JSON API
+
+- `jsonapi_resource_type`: Whether the `type` attributes of resources should be singular or plural. Possible values: `:singular, :plural`. Default: `:plural`.

data/docs/general/getting_started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+## Installation
+
+### ActiveModel::Serializer is already included on Rails >= 5
+
+Add this line to your application's Gemfile:
+
+```
+gem 'active_model_serializers'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+## 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 seralizer 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
+```
+
+## Rails Integration
+
+AMS will automatically integrate with you Rails app, you won't need to update your controller, this is a example of how it will look like:
+
+```ruby
+class PostsController < ApplicationController
+
+  def show
+    @post = Post.find(params[:id])
+    render json: @post
+  end
+
+end
+```

data/docs/howto/add_pagination_links.md

@@ -0,0 +1,112 @@
+# 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 a ```JSON-API``` adapter.
+
+If you want pagination links in your response, use [Kaminari](https://github.com/amatsuda/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
+
+###### 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
+ActiveModel::Serializer.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"
+  }
+}
+```
+
+AMS 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.
+
+In your action specify a custom serializer.
+```ruby
+render json: @posts, serializer: PaginatedSerializer, each_serializer: PostPreviewSerializer
+```
+
+And then, you could do something like the following class.
+```ruby
+class PaginatedSerializer < ActiveModel::Serializer::ArraySerializer
+  def initialize(object, options={})
+    meta_key = options[:meta_key] || :meta
+    options[meta_key] ||= {}
+    options[meta_key] = {
+      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
+    }
+    super(object, options)
+  end
+end
+```
+ex.
+```json
+{
+  "articles": [
+    {
+      "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
+  }
+}
+```
+
+### FlattenJSON 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

@@ -0,0 +1,51 @@
+# How to add root key
+
+Add the root key to your API is quite simple with AMS. The **Adapter** is what determines the format of your JSON response. The default adapter is the ```FlattenJSON``` 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
+ActiveModel::Serializer.config.adapter = :json
+```
+
+You can also specify a class as adapter, as long as it complies with the AMS 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

@@ -0,0 +1,42 @@
+## Using AMS Outside Of A Controller
+
+### Serializing a resource 
+
+In AMS 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 = ActiveModel::SerializableResource.new(post, options)
+
+# Convert your resource into json
+model_json = serializable_resource.as_json
+``` 
+
+### Retrieving a Resource's Active Model Serializer
+
+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
+ActiveModel::SerializableResource.new(post, options).serializer 
+```
+
+Both approaches will return an instance, if any, of the resource's serializer.

data/lib/action_controller/serialization.rb

@@ -1,32 +1,14 @@
+require 'active_support/core_ext/class/attribute'
+
 module ActionController
-  # Action Controller Serialization
-  #
-  # Overrides render :json to check if the given object implements +active_model_serializer+
-  # as a method. If so, use the returned serializer instead of calling +to_json+ on the object.
-  #
-  # This module also provides a serialization_scope method that allows you to configure the
-  # +serialization_scope+ of the serializer. Most apps will likely set the +serialization_scope+
-  # to the current user:
-  #
-  #    class ApplicationController < ActionController::Base
-  #      serialization_scope :current_user
-  #    end
-  #
-  # If you need more complex scope rules, you can simply override the serialization_scope:
-  #
-  #    class ApplicationController < ActionController::Base
-  #      private
-  #
-  #      def serialization_scope
-  #        current_user
-  #      end
-  #    end
-  #
   module Serialization
     extend ActiveSupport::Concern
 
     include ActionController::Renderers
 
+    # Deprecated
+    ADAPTER_OPTION_KEYS = ActiveModel::SerializableResource::ADAPTER_OPTION_KEYS
+
     included do
       class_attribute :_serialization_scope
       self._serialization_scope = :current_user
@@ -37,18 +19,36 @@ module ActionController
         respond_to?(_serialization_scope, true)
     end
 
-    def default_serializer_options
+    def get_serializer(resource, options = {})
+      if !use_adapter?
+        warn 'ActionController::Serialization#use_adapter? has been removed. '\
+          "Please pass 'adapter: false' or see ActiveSupport::SerializableResource.new"
+        options[:adapter] = false
+      end
+      serializable_resource = ActiveModel::SerializableResource.new(resource, options)
+      if serializable_resource.serializer?
+        serializable_resource.serialization_scope ||= serialization_scope
+        serializable_resource.serialization_scope_name = _serialization_scope
+        begin
+          serializable_resource.adapter
+        rescue ActiveModel::Serializer::ArraySerializer::NoSerializerError
+          resource
+        end
+      else
+        resource
+      end
+    end
+
+    # Deprecated
+    def use_adapter?
+      true
     end
 
     [:_render_option_json, :_render_with_renderer_json].each do |renderer_method|
       define_method renderer_method do |resource, options|
-        json = ActiveModel::Serializer.build_json(self, resource, options)
-
-        if json
-          super(json, options)
-        else
-          super(resource, options)
-        end
+        options.fetch(:context) { options[:context] = request }
+        serializable_resource = get_serializer(resource, options)
+        super(serializable_resource, options)
       end
     end