From 558769981ec1dbdbac73052e9d076be8e6f6b381 Mon Sep 17 00:00:00 2001 From: CodedBeardedSignedTaylor Date: Sun, 28 Feb 2016 22:41:26 -0500 Subject: [PATCH 1/7] rough draft --- docs/general/passing_arbitrary_options.md | 46 +++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/general/passing_arbitrary_options.md diff --git a/docs/general/passing_arbitrary_options.md b/docs/general/passing_arbitrary_options.md new file mode 100644 index 000000000..523163d79 --- /dev/null +++ b/docs/general/passing_arbitrary_options.md @@ -0,0 +1,46 @@ +## Passing Arbitrary Options to A Serializer + +Let's say you have a basic Post Controller: + +``` +class PostController < ApplicationController + def dashboard + render json: @posts + end +end +``` + +Odds are, your serializer will look something like this: + +``` +class PostSerializer < ActiveModel::Serializer + attributes :id, :title, :body +end +``` + +This works all fine and well, but maybe you passing in some "artibrary" options +into the serializer. Here's what you would do: + +### posts_controller.rb + +``` +... + def dashboard + render json: @posts, user_id: 12 + end +... +``` + +### posts_serializer.rb + +``` +... + def comments_by_me + Comments.where(user_id: instance_options[:user_id], post_id: object.id) + end +... +``` + +These options can be anything that isn't already reserved for use by AMS. For example, +you won't be able to pass in a `meta` or `root` option like the example above. Those +parameters are reserved for specific behavior within the app. From 6a8da1f6646d3bb10079876d395d9d6e4b08e3b9 Mon Sep 17 00:00:00 2001 From: CodedBeardedSignedTaylor Date: Sun, 28 Feb 2016 22:45:45 -0500 Subject: [PATCH 2/7] adding ruby tag to code blocks --- docs/general/passing_arbitrary_options.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/general/passing_arbitrary_options.md b/docs/general/passing_arbitrary_options.md index 523163d79..4039a12cd 100644 --- a/docs/general/passing_arbitrary_options.md +++ b/docs/general/passing_arbitrary_options.md @@ -2,7 +2,7 @@ Let's say you have a basic Post Controller: -``` +```ruby class PostController < ApplicationController def dashboard render json: @posts @@ -12,7 +12,7 @@ end Odds are, your serializer will look something like this: -``` +```ruby class PostSerializer < ActiveModel::Serializer attributes :id, :title, :body end @@ -23,7 +23,7 @@ into the serializer. Here's what you would do: ### posts_controller.rb -``` +```ruby ... def dashboard render json: @posts, user_id: 12 @@ -33,7 +33,7 @@ into the serializer. Here's what you would do: ### posts_serializer.rb -``` +```ruby ... def comments_by_me Comments.where(user_id: instance_options[:user_id], post_id: object.id) From e9f259697af154a1fc88a046f33c18ce6ef161e4 Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Mon, 29 Feb 2016 10:56:14 -0500 Subject: [PATCH 3/7] addressing pull request comments --- docs/general/passing_arbitrary_options.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/general/passing_arbitrary_options.md b/docs/general/passing_arbitrary_options.md index 4039a12cd..2be164065 100644 --- a/docs/general/passing_arbitrary_options.md +++ b/docs/general/passing_arbitrary_options.md @@ -1,4 +1,4 @@ -## Passing Arbitrary Options to A Serializer +## Passing Arbitrary Options To A Serializer Let's say you have a basic Post Controller: @@ -18,7 +18,7 @@ class PostSerializer < ActiveModel::Serializer end ``` -This works all fine and well, but maybe you passing in some "artibrary" options +This works all fine and well, but maybe you passing in some "arbitrary" options into the serializer. Here's what you would do: ### posts_controller.rb @@ -41,6 +41,5 @@ into the serializer. Here's what you would do: ... ``` -These options can be anything that isn't already reserved for use by AMS. For example, -you won't be able to pass in a `meta` or `root` option like the example above. Those -parameters are reserved for specific behavior within the app. +These options can be anything that isn't already reserved for use by +ActiveModelSerializers' adapter options. From da55cd181c3df7db2ee8737d7a4fed2aa91fd7f2 Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Tue, 1 Mar 2016 08:40:45 -0500 Subject: [PATCH 4/7] addressing comments / concerns --- docs/README.md | 1 + docs/general/passing_arbitrary_options.md | 28 +++++++++++------------ 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7f0a8ac02..8d559d8bc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10. - [Instrumentation](general/instrumentation.md) - [JSON API Schema](jsonapi/schema.md) - [ARCHITECTURE](ARCHITECTURE.md) +- [Passing Arbitrary Options](general/passing_arbitrary_options.md) ## How to diff --git a/docs/general/passing_arbitrary_options.md b/docs/general/passing_arbitrary_options.md index 2be164065..0bb8f78eb 100644 --- a/docs/general/passing_arbitrary_options.md +++ b/docs/general/passing_arbitrary_options.md @@ -1,4 +1,6 @@ -## Passing Arbitrary Options To A Serializer +[Back to Guides](../README.md) + +# Passing Arbitrary Options To A Serializer Let's say you have a basic Post Controller: @@ -18,28 +20,26 @@ class PostSerializer < ActiveModel::Serializer end ``` -This works all fine and well, but maybe you passing in some "arbitrary" options -into the serializer. Here's what you would do: +This works all fine and well, but maybe you passing in some arbitrary options +into the serializer. These options can be anything that isn't already reserved for use by +ActiveModelSerializers' adapter options. -### posts_controller.rb +Here's an example: ```ruby -... +# posts_controller.rb +class PostController < ApplicationController def dashboard render json: @posts, user_id: 12 end -... -``` +end -### posts_serializer.rb +# post_serializer.rb +class PostSerializer < ActiveModel::Serializer + attributes :id, :title, :body -```ruby -... def comments_by_me Comments.where(user_id: instance_options[:user_id], post_id: object.id) end -... +end ``` - -These options can be anything that isn't already reserved for use by -ActiveModelSerializers' adapter options. From 32c6bccec72cda66b7baf219b17d3c5dba97dacd Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Fri, 4 Mar 2016 11:09:38 -0500 Subject: [PATCH 5/7] edits and rearranging logic --- docs/README.md | 2 +- docs/general/passing_arbitrary_options.md | 45 ----------------------- docs/howto/passing_arbitrary_options.md | 30 +++++++++++++++ 3 files changed, 31 insertions(+), 46 deletions(-) delete mode 100644 docs/general/passing_arbitrary_options.md create mode 100644 docs/howto/passing_arbitrary_options.md diff --git a/docs/README.md b/docs/README.md index 8d559d8bc..d4b13ad56 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,7 +16,6 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10. - [Instrumentation](general/instrumentation.md) - [JSON API Schema](jsonapi/schema.md) - [ARCHITECTURE](ARCHITECTURE.md) -- [Passing Arbitrary Options](general/passing_arbitrary_options.md) ## How to @@ -24,6 +23,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10. - [How to add pagination links](howto/add_pagination_links.md) - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md) - [Testing ActiveModelSerializers](howto/test.md) +- [Passing Arbitrary Options](how-to/passing_arbitrary_options.md) ## Integrations diff --git a/docs/general/passing_arbitrary_options.md b/docs/general/passing_arbitrary_options.md deleted file mode 100644 index 0bb8f78eb..000000000 --- a/docs/general/passing_arbitrary_options.md +++ /dev/null @@ -1,45 +0,0 @@ -[Back to Guides](../README.md) - -# Passing Arbitrary Options To A Serializer - -Let's say you have a basic Post Controller: - -```ruby -class PostController < ApplicationController - def dashboard - render json: @posts - end -end -``` - -Odds are, your serializer will look something like this: - -```ruby -class PostSerializer < ActiveModel::Serializer - attributes :id, :title, :body -end -``` - -This works all fine and well, but maybe you passing in some arbitrary options -into the serializer. These options can be anything that isn't already reserved for use by -ActiveModelSerializers' adapter options. - -Here's an example: - -```ruby -# posts_controller.rb -class PostController < ApplicationController - def dashboard - render json: @posts, 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 -``` diff --git a/docs/howto/passing_arbitrary_options.md b/docs/howto/passing_arbitrary_options.md new file mode 100644 index 000000000..789063f22 --- /dev/null +++ b/docs/howto/passing_arbitrary_options.md @@ -0,0 +1,30 @@ +[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 +``` + +Since `user_id` isn't a reserved adapter option, we can process it via a serializer +method. The option is passed via the `instance_options` hash. From 60a207bb0d95f006e7152e3f295d72a69c3037c8 Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Fri, 4 Mar 2016 11:12:09 -0500 Subject: [PATCH 6/7] wrong link --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index d4b13ad56..437ad0c36 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,7 +23,7 @@ This is the documentation of ActiveModelSerializers, it's focused on the **0.10. - [How to add pagination links](howto/add_pagination_links.md) - [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md) - [Testing ActiveModelSerializers](howto/test.md) -- [Passing Arbitrary Options](how-to/passing_arbitrary_options.md) +- [Passing Arbitrary Options](howto/passing_arbitrary_options.md) ## Integrations From 48f8a892e64251337597928903f2635808b5ee31 Mon Sep 17 00:00:00 2001 From: Taylor Jones Date: Fri, 4 Mar 2016 11:14:43 -0500 Subject: [PATCH 7/7] a little bit more trimming --- docs/howto/passing_arbitrary_options.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/howto/passing_arbitrary_options.md b/docs/howto/passing_arbitrary_options.md index 789063f22..e7fd84095 100644 --- a/docs/howto/passing_arbitrary_options.md +++ b/docs/howto/passing_arbitrary_options.md @@ -25,6 +25,3 @@ class PostSerializer < ActiveModel::Serializer end end ``` - -Since `user_id` isn't a reserved adapter option, we can process it via a serializer -method. The option is passed via the `instance_options` hash.