Adapters and Serializers for Rails's ActiveModel::Serializers
JavaScript HTML Ruby Shell
Clone or download
runspired Merge pull request #99 from Turbo87/node-version
[BREAKING] Increase minimum Node.js version to v4.5
Latest commit 6ccd2d9 Apr 19, 2018
Permalink
Failed to load latest commit information.
addon Fix ember-inflector deprecations Nov 30, 2017
app [bugfix] use old initializer code Feb 18, 2016
bin Point to correct repository in CHANGELOG Oct 16, 2015
config ember-try: Fix `default` scenario Nov 30, 2017
lib Remove unnecessary instance-initializer Oct 16, 2015
tests Update "ember-cli-qunit" to v4.0.1 Oct 23, 2017
vendor cleanup tests, fix bower publishing by generating a new bower.json Jul 1, 2015
.bowerrc Remove execute permission Aug 27, 2015
.editorconfig Remove execute permission Aug 27, 2015
.ember-cli Remove execute permission Aug 27, 2015
.gitignore Remove execute permission Aug 27, 2015
.jshintrc Remove execute permission Aug 27, 2015
.npmignore Remove execute permission Aug 27, 2015
.travis.yml CI: Ignore failures for ember-data@2.0 too Oct 25, 2017
.watchmanconfig update npm and bower dependencies/update to latest ember-cli 2.2.0-be… Dec 14, 2015
CHANGELOG.MD Update changelog for 2.2.0 release Dec 22, 2017
CODE_OF_CONDUCT.md add CODE_OF_CONDUCT.md closes #12 Jul 1, 2015
CONTRIBUTING.md Update CONTRIBUTING.md Jul 23, 2015
LICENSE.md Remove execute permission Aug 27, 2015
README.md [DOC] Add missing ext name (#88) Jun 14, 2016
active-model-adapter-source.gemspec Remove execute permission Aug 27, 2015
babel-options.js Remove execute permission Aug 27, 2015
bower.json Convert "ember-load-initializers" to npm dependency Oct 25, 2017
ember-cli-build.js update npm and bower dependencies/update to latest ember-cli 2.2.0-be… Dec 14, 2015
index.js Remove execute permission Aug 27, 2015
package.json Merge pull request #99 from Turbo87/node-version Apr 19, 2018
testem.json Remove execute permission Aug 27, 2015
yarn.lock Fix ember-inflector deprecations Nov 30, 2017

README.md

Ember Data ActiveModel Adapter Build Status

Installation

Ember CLI

ember install active-model-adapter

Rails

This gem comes bundled with Ember Rails. If you want to specify a specific version in your Gemfile, you can reference the active-model-adapter-source gem and it will get loaded by Ember Rails:

gem 'active-model-adapter-source', '~>2.0' # or whatever version you need

Bower

bower install --save active-model-adapter

Script Tags

Grab a copy of active-model-adapter.js from http://github.com/ember-data/active-model-adapter-dist

Usage

You should make an ApplicationAdapter if you don't already have one:

// app/adapters/application.js
import ActiveModelAdapter from 'active-model-adapter';

export default ActiveModelAdapter.extend();

If you need to subclass the ActiveModelSerializer, you can import it into your serializer:

// app/serializers/post.js

import { ActiveModelSerializer } from 'active-model-adapter';

export default ActiveModelSerializer.extend();

Description

The ActiveModelAdapter is a subclass of the RESTAdapter designed to integrate with a JSON API that uses an underscored naming convention instead of camelCasing.

It has been designed to work out of the box with the active_model_serializers Ruby gem. This Adapter expects specific settings using ActiveModel::Serializers, embed :ids, embed_in_root: true which sideloads the records.

JSON Structure

The ActiveModelAdapter expects the JSON returned from your server to follow the REST adapter conventions substituting underscored keys for camelcased ones. Unlike the DS.RESTAdapter, async relationship keys must be the singular form of the relationship name, followed by "_id" for DS.belongsTo relationships, or "_ids" for DS.hasMany relationships.

Since ActiveModelAdapter 2.1.0 however, you don't need the "_id" or "_ids" suffix on keys for relationships.

Conventional Names

Attribute names in your JSON payload should be the underscored versions of the attributes in your Ember.js models. For example, if you have a Person model:

// app/models/famous-person.js

export default var FamousPerson = DS.Model.extend({
  firstName: DS.attr('string'),
  lastName: DS.attr('string'),
  occupation: DS.attr('string')
});

The JSON returned should look like this:

{
  "famous_person": {
    "id": 1,
    "first_name": "Barack",
    "last_name": "Obama",
    "occupation": "President"
  }
}

Let's imagine that Occupation and Person are just another model:

// app/models/person.js

export default var Person = DS.Model.extend({
  firstName: DS.attr('string'),
  lastName: DS.attr('string'),
  occupation: DS.belongsTo('occupation')
});

// app/models/occupation.js
App.Occupation = DS.Model.extend({
  name: DS.attr('string'),
  salary: DS.attr('number'),
  people: DS.hasMany('person')
});

The JSON needed to avoid extra server calls, should look like this:

{
  "people": [{
    "id": 1,
    "first_name": "Barack",
    "last_name": "Obama",
    "occupation_id": 1
  }],
  "occupations": [{
    "id": 1,
    "name": "President",
    "salary": 100000,
    "person_ids": [1]
  }]
}

Polymorphic Relationships

If your model has polymorphic relationships, the ActiveModelAdapter supports two forms in your response.

When using ActiveModelSerializers in Rails, you can opt into this payload using the polymorphic: true option when calling has_many or belongs_to.

class BookSerializer
  attributes :id, :name
  belongs_to :person, polymorphic: true
end

The first, and preferred format, is to use the name of the relationship as the key and an object with the type and foreign key as the value.

For example, given the following model definitions:

// app/models/book.js
export default var Book = DS.Model.extend({
  name: DS.attr(),
  author: DS.belongsTo('person', {polymorphic: true})
});

// app/models/author.js
export default var Person = DS.Model.extend({
  name: DS.attr(),
  books: DS.hasMany('book')
});

The object would look like:

{
  "type": "person",
  "id": 1
}

and the full payload would look like this:

{
  "book": {
    "id": "1",
    "name": "Yes, Please",
    "author": { // these are the lines
      "id": 1, // that define the
      "type": "person" // polymorphic relationship
    }
  },
  "people": [{
    "id": 1,
    "name": "Amy Poehler"
  }]
}

The second format allows you to specify using two keys in the model's payload following the format of relationship_name_id and relationship_name_type. This format does not work with hasMany relationships. This format may also be removed for Ember Data 3.0; it is currently only supported for legacy reasons.

Using the above model definitions, the single model response would look like this:

{
  "book": {
    "id": "1",
    "name": "Yes, Please",
    "author_id": 1, // these two lines
    "author_type": "person" // tell Ember Data what the polymorphic
                            // relationship is.
  }
}

The full response would be look like this:

{
  "book": {
    "id": "1",
    "name": "Yes, Please",
    "author_id": 1, // these two lines
    "author_type": "person" // tell Ember Data what the polymorphic
                            // relationship is.
  },
  "people": [{
    "id": 1,
    "name": "Amy Poehler"
  }]
}

Development Installation

  • git clone this repository
  • npm install
  • bower install

Running Tests

  • ember test
  • ember test --server

Building

  • ember build

For more information on using ember-cli, visit http://www.ember-cli.com/.