diff --git a/docs/README.md b/docs/README.md index 8d559d8b..d4b13ad5 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 0bb8f78e..00000000 --- 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 00000000..789063f2 --- /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.