Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fields doc #1808

Merged
merged 8 commits into from
Jun 24, 2016
Merged

Fields doc #1808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d56c6c5
Added docs for the fields
luizkowalski Jun 15, 2016
6e6b6f7
Added docs for the fields
luizkowalski Jun 15, 2016
ac9cdbf
Removed extra info
luizkowalski Jun 22, 2016
a870649
Updated from origin
luizkowalski Jun 22, 2016
9915190
Added docs for the fields
luizkowalski Jun 15, 2016
98a162d
Added docs for the fields
luizkowalski Jun 15, 2016
a733190
Merge branch 'fields_doc' of https://github.com/luizkowalski/active_m…
luizkowalski Jun 22, 2016
7df9cf5
Changelog
luizkowalski Jun 22, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Features:
Fixes:

Misc:
- [#1808](https://github.com/rails-api/active_model_serializers/pull/1808) Adds documentation for `fields` option. (@luizkowalski)

### [v0.10.1 (2016-06-16)](https://github.com/rails-api/active_model_serializers/compare/v0.10.0...v0.10.1)

Expand Down
31 changes: 31 additions & 0 deletions docs/general/fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
[Back to Guides](../README.md)

# Fields

If for any reason, you need to restrict the fields returned, you should use `fields` option.

For example, if you have a serializer like this

```ruby
class UserSerializer < ActiveModel::Serializer
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should begin recommending ApplicationSerializer...

attributes :access_token, :first_name, :last_name
end
```

and in a specific controller, you want to return `access_token` only, `fields` will help you:

```ruby
class AnonymousController < ApplicationController
def create
render json: User.create(activation_state: 'anonymous'), fields: [:access_token], status: 201
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as for the other comment. This snippet is only valid for the json and attributes adapters. Could you either add a small note or add the missing snippet for the json_api adapter?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

def create
  if user = User.create(activation_state: 'anonymous')
    # using the :json adapter
    render json: user, fields: [:access_token], adapter: :json, status: :created
    # using the :json_api adapter
    render json: user, fields: { users: [:access_token] }, adapter: :json_api, status: :created
    # using the registered jsonapi renderer
    render jsonapi: user, fields: { users: [:access_token] }, status: :created

@groyoh question: when I serialize a collection with JSONAPI I might have

      render_options[:fields] = {items: [:id, :title, :description], locations: [:name]}
      render_options[:include] = [:location]

but I'm not sure how this would look with the :json adapter (lazy me did not review code or check for tests)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bf4 There is no way of doing that. The attributes and json adapter only allow to specify fields for the first level.

end
end
```

Note that this is only valid for the `json` and `attributes` adapter. For the `json_api` adapter, you would use

```ruby
render json: @user, fields: { users: [:access_token] }
```

Where `users` is the JSONAPI type.
9 changes: 7 additions & 2 deletions docs/general/rendering.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,12 @@ See [ARCHITECTURE](../ARCHITECTURE.md) for more information.

#### fields

PR please :)
If you are using `json` or `attributes` adapter
```ruby
render json: @user, fields: [:access_token]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is only valid for the json and attributes adapter. For the json_api adapter, you would use

render json: @user, fields: { users: [:access_token] }

Where users is the JSONAPI type.

Could you add the missing code snippet with a brief description (stating for which adapter each snippet is valid) or add a description above your code that states that it only valid for json and attributes adapter?

```

See [Fields](fields.md) for more information.

#### adapter

Expand All @@ -83,7 +88,7 @@ PR please :)

```render json: posts, each_serializer: PostSerializer, key_transform: :camel_lower```

See [Key Transforms](key_transforms.md) for more informaiton.
See [Key Transforms](key_transforms.md) for more information.

#### meta

Expand Down