Class DS.EmbeddedRecordsMixin

Defined in: packages/ember-data/lib/serializers/embedded-records-mixin.js:8

Module: ember-data

Using Embedded Records

DS.EmbeddedRecordsMixin supports serializing embedded records.

To set up embedded records, include the mixin when extending a serializer then define and configure embedded (model) relationships.

Below is an example of a per-type serializer ('post' type).

app/serializers/post.js

import DS from 'ember-data';

export default DS.RESTSerializer.extend(DS.EmbeddedRecordsMixin, {
  attrs: {
    author: { embedded: 'always' },
    comments: { serialize: 'ids' }
  }
});

Note that this use of { embedded: 'always' } is unrelated to the { embedded: 'always' } that is defined as an option on DS.attr as part of defining a model while working with the ActiveModelSerializer. Nevertheless, using { embedded: 'always' } as an option to DS.attr is not a valid way to setup embedded records.

The attrs option for a resource { embedded: 'always' } is shorthand for:

{
  serialize: 'records',
  deserialize: 'records'
}

Configuring Attrs

A resource's attrs option may be set to use ids, records or false for the serialize and deserialize settings.

The attrs property can be set on the ApplicationSerializer or a per-type serializer.

In the case where embedded JSON is expected while extracting a payload (reading) the setting is deserialize: 'records', there is no need to use ids when extracting as that is the default behavior without this mixin if you are using the vanilla EmbeddedRecordsMixin. Likewise, to embed JSON in the payload while serializing serialize: 'records' is the setting to use. There is an option of not embedding JSON in the serialized payload by using serialize: 'ids'. If you do not want the relationship sent at all, you can use serialize: false.

EmbeddedRecordsMixin defaults

If you do not overwrite attrs for a specific relationship, the EmbeddedRecordsMixin will behave in the following way:

BelongsTo: { serialize: 'id', deserialize: 'id' } HasMany: { serialize: false, deserialize: 'ids' }

Model Relationships

Embedded records must have a model defined to be extracted and serialized. Note that when defining any relationships on your model such as belongsTo and hasMany, you should not both specify async:true and also indicate through the serializer's attrs attribute that the related model should be embedded for deserialization. If a model is declared embedded for deserialization (embedded: 'always', deserialize: 'record' or deserialize: 'records'), then do not use async:true.

To successfully extract and serialize embedded records the model relationships must be setup correcty See the defining relationships section of the Defining Models guide page.

Records without an id property are not considered embedded records, model instances must have an id property to be used with Ember Data.

Example JSON payloads, Models and Serializers

When customizing a serializer it is important to grok what the customizations are. Please read the docs for the methods this mixin provides, in case you need to modify it to fit your specific needs.

For example review the docs for each method of this mixin:

Show: Inherited Protected Private Deprecated

initializeStore (applicationOrRegistry)

Module: ember-data

Defined in packages/ember-data/lib/instance-initializers/initialize-store-service.js:1

applicationOrRegistry: Ember.ApplicationInstance

Configures a registry for use with an Ember-Data store.

initializeStoreInjections (registry)

Module: ember-data

Defined in packages/ember-data/lib/initializers/store-injections.js:1

registry: Ember.Registry

Configures a registry with injections on Ember applications for the Ember-Data store. Accepts an optional namespace argument.

initializeTransforms (registry)

Module: ember-data

Defined in packages/ember-data/lib/initializers/transforms.js:8

registry: Ember.Registry

Configures a registry for use with Ember-Data transforms.

normalize (typeClass, hash, prop) Object

Module: ember-data

Defined in packages/ember-data/lib/serializers/embedded-records-mixin.js:100

typeClass: DS.Model
hash: Object; to be normalized
prop: String; the hash has been referenced by
returns: Object; the normalized hash

Normalize the record and recursively normalize/extract all the embedded records while pushing them into the store as they are encountered

A payload with an attr configured for embedded records needs to be extracted:

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "comments": [{
      "id": "1",
      "body": "Rails is unagi"
    }, {
      "id": "2",
      "body": "Omakase O_o"
    }]
  }
}

removeEmbeddedForeignKey (snapshot, embeddedSnapshot, relationship, json)

Module: ember-data

Defined in packages/ember-data/lib/serializers/embedded-records-mixin.js:343

snapshot: DS.Snapshot
embeddedSnapshot: DS.Snapshot
relationship: Object
json: Object

When serializing an embedded record, modify the property (in the json payload) that refers to the parent record (foreign key for relationship).

Serializing a belongsTo relationship removes the property that refers to the parent record

Serializing a hasMany relationship does not remove the property that refers to the parent record.

serializeBelongsTo (snapshot, json, relationship)

Module: ember-data

Defined in packages/ember-data/lib/serializers/embedded-records-mixin.js:141

snapshot: DS.Snapshot
json: Object
relationship: Object

Serialize belongsTo relationship when it is configured as an embedded object.

This example of an author model belongs to a post model:

Post = DS.Model.extend({
  title:    DS.attr('string'),
  body:     DS.attr('string'),
  author:   DS.belongsTo('author')
});

Author = DS.Model.extend({
  name:     DS.attr('string'),
  post:     DS.belongsTo('post')
});

Use a custom (type) serializer for the post model to configure embedded author

app/serializers/post.js

import DS from 'ember-data;

export default DS.RESTSerializer.extend(DS.EmbeddedRecordsMixin, {
  attrs: {
    author: { embedded: 'always' }
  }
})

A payload with an attribute configured for embedded records can serialize the records together under the root attribute's payload:

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "author": {
      "id": "2"
      "name": "dhh"
    }
  }
}

serializeHasMany (snapshot, json, relationship)

Module: ember-data

Defined in packages/ember-data/lib/serializers/embedded-records-mixin.js:228

snapshot: DS.Snapshot
json: Object
relationship: Object

Serialize hasMany relationship when it is configured as embedded objects.

This example of a post model has many comments:

Post = DS.Model.extend({
  title:    DS.attr('string'),
  body:     DS.attr('string'),
  comments: DS.hasMany('comment')
});

Comment = DS.Model.extend({
  body:     DS.attr('string'),
  post:     DS.belongsTo('post')
});

Use a custom (type) serializer for the post model to configure embedded comments

app/serializers/post.js

import DS from 'ember-data;

export default DS.RESTSerializer.extend(DS.EmbeddedRecordsMixin, {
  attrs: {
    comments: {embedded: 'always'}
  }
})

A payload with an attribute configured for embedded records can serialize the records together under the root attribute's payload:

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "body": "I want this for my ORM, I want that for my template language..."
    "comments": [{
      "id": "1",
      "body": "Rails is unagi"
    }, {
      "id": "2",
      "body": "Omakase O_o"
    }]
  }
}

The attrs options object can use more specific instruction for extracting and serializing. When serializing, an option to embed ids or records can be set. When extracting the only option is records.

So { embedded: 'always' } is shorthand for: { serialize: 'records', deserialize: 'records' }

To embed the ids for a related object (using a hasMany relationship):

app/serializers/post.js

import DS from 'ember-data;

export default DS.RESTSerializer.extend(DS.EmbeddedRecordsMixin, {
  attrs: {
    comments: { serialize: 'ids', deserialize: 'records' }
  }
})

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "body": "I want this for my ORM, I want that for my template language..."
    "comments": ["1", "2"]
  }
}