Class DS.EmbeddedRecordsMixin

Show:

Module: ember-data
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "comments": [{
      "id": "1",
      "body": "Rails is unagi"
    }, {
      "id": "2",
      "body": "Omakase O_o"
    }]
  }
}
Module: ember-data
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 the 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.

Module: ember-data
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:

1
2
3
4
5
6
7
8
9
10
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
1
2
3
4
5
6
7
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:

1
2
3
4
5
6
7
8
9
10
{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "author": {
      "id": "2"
      "name": "dhh"
    }
  }
}
Module: ember-data
snapshot
DS.Snapshot
json
Object
relationship
Object

Serializes hasMany relationships when it is configured as embedded objects.

This example of a post model has many comments:

1
2
3
4
5
6
7
8
9
10
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
1
2
3
4
5
6
7
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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "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, ids-and-types 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
1
2
3
4
5
6
7
import DS from 'ember-data';

export default DS.RESTSerializer.extend(DS.EmbeddedRecordsMixin, {
  attrs: {
    comments: { serialize: 'ids', deserialize: 'records' }
  }
})
1
2
3
4
5
6
7
8
{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "body": "I want this for my ORM, I want that for my template language..."
    "comments": ["1", "2"]
  }
}

To embed the relationship as a collection of objects with id and type keys, set ids-and-types for the related object.

This is particularly useful for polymorphic relationships where records don't share the same table and the id is not enough information.

For example having a user that has many pets:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
User = DS.Model.extend({
  name:    DS.attr('string'),
  pets: DS.hasMany('pet', { polymorphic: true })
});

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

Cat = Pet.extend({
  // ...
});

Parrot = Pet.extend({
  // ...
});
app/serializers/user.js
1
2
3
4
5
6
7
import DS from 'ember-data';

export default DS.RESTSerializer.extend(DS.EmbeddedRecordsMixin, {
  attrs: {
    pets: { serialize: 'ids-and-types', deserialize: 'records' }
  }
});
1
2
3
4
5
6
7
8
9
10
{
  "user": {
    "id": "1"
    "name": "Bertin Osborne",
    "pets": [
      { "id": "1", "type": "Cat" },
      { "id": "1", "type": "Parrot"}
    ]
  }
}