Permalink
Browse files

Start writing tests for the new API

  • Loading branch information...
1 parent 90a0b8b commit 39319dbc8c5a999d179c8fd484934e7eb1f853c3 tomhuda committed Dec 11, 2012
View
76 packages/ember-data/lib/system/serializer.js
@@ -1,19 +1,79 @@
var get = Ember.get, set = Ember.set;
/**
- The serializer is responsible for converting the data returned from the
- adapter into the semantics expected by records in Ember Data. It is also
- responsible for converting a record into the form expected by the adapter
- when saving changes that have been made locally.
+ A serializer is responsible for serializing and deserializing a group of
+ records.
- Typically, your application's `DS.Adapter` is responsible for both creating
- a serializer as well as calling the appropriate methods when it needs to
+ `DS.Serializer` is an abstract base class designed to help you build a
+ serializer that can read to and write from any serialized form. While most
+ applications will use `DS.JSONSerializer`, which reads and writes JSON, the
+ serializer architecture allows your adapter to transmit things like XML,
+ strings, or custom binary data.
+
+ Typically, your application's `DS.Adapter` is responsible for both creating a
+ serializer as well as calling the appropriate methods when it needs to
materialize data or serialize a record.
+ The serializer API is designed as a series of layered hooks that you can
+ override to customize any of the individual steps of serialization and
+ deserialization.
+
+ The hooks are organized by the three responsibilities of the serializer:
+
+ 1. Determining naming conventions
+ 2. Serializing records into a serialized form
+ 3. Deserializing records from a serialized form
+
+ Because Ember Data lazily materializes records, the deserialization
+ step, and therefore the hooks you implement, are split into two phases:
+
+ 1. Extraction, where the serialized forms for multiple records are
+ extracted from a single payload. The IDs of each record are also
+ extracted for indexing.
+ 2. Materialization, where a newly-created record has its attributes
+ and relationships initialized based on the serialized form loaded
+ by the adapter.
+
+ Additionally, a serializer can convert values from their JavaScript
+ versions into their serialized versions via a declarative API.
+
+ ## Naming Conventions
+
+ One of the most common uses of the serializer is to map attribute names
+ from the serialized form to your `DS.Model`. For example, in your model,
+ you may have an attribute called `firstName`:
+
+ ```javascript
+ App.Person = DS.Model.extend({
+ firstName: DS.attr('string')
+ });
+ ```
+
+ However, because the web API your adapter is communicating with is
+ legacy, it calls this attribute `FIRST_NAME`.
+
+ You can determine the attribute name used in the serialized form
+ by implementing `keyForAttributeName`:
+
+ ```javascript
+ keyForAttributeName: function(type, name) {
+ return name.underscore.toUpperCase();
+ }
+ ```
+
+ If your attribute names are not predictable, you can re-map them
+ one-by-one using the `map` API:
+
+ ```javascript
+ App.Person.map('App.Person', {
+ firstName: { key: '*API_USER_FIRST_NAME*' }
+ });
+ ```
+
## Serialization
- These methods are responsible for taking a record and
- producing a JSON object.
+ During the serialization process, a record or records are converted
+ from Ember.js objects into their serialized form.
These methods are designed in layers, like a delicious 7-layer
cake (but with fewer layers).
View
6 packages/ember-data/lib/system/store.js
@@ -1443,6 +1443,12 @@ DS.Store = Ember.Object.extend(DS._Mappable, {
@param {Object} data the data to load
*/
load: function(type, id, data) {
+ if (typeof id === 'object' && typeof data === 'object') {
+ var providedId = data.id;
+ data = id;
+ id = providedId;
+ }
+
if (data === undefined) {
data = id;
View
33 packages/ember-data/tests/integration/record_loading_test.js
@@ -0,0 +1,33 @@
+module("Record Loading", {
+
+});
+
+test("after loading a record, a subsequent find materializes the record through the serializer", function() {
+ expect(1);
+
+ var Person = DS.Model.extend({
+ firstName: DS.attr('string'),
+ lastName: DS.attr('string')
+ });
+
+ var adapter = DS.Adapter.create(),
+ serializer = adapter.serializer,
+ store = DS.Store.create({ adapter: adapter });
+
+ serializer.extractId = function(type, data) {
+ ok(false, "extraction is skipped since the id was already provided");
+ };
+
+ serializer.extractAttribute = function(type, data, name) {
+ return data[name];
+ };
+
+ serializer.keyForAttributeName = function(type, name) {
+ return name;
+ };
+
+ store.load(Person, { id: 1, firstName: "Yehuda", lastName: "Katz" }, { id: 1 });
+
+ var person = store.find(Person, 1);
+ equal(person.get('firstName'), "Yehuda", "getting an attribute returned the right value");
+});
View
20 packages/ember-data/tests/unit/serializer_test.js
@@ -0,0 +1,20 @@
+module("DS.Serializer", {
+ setup: function() {
+
+ },
+
+ teardown: function() {
+
+ }
+});
+
+test("Calling extractRecords with an opaque data structure containing multiple records will tear them apart and call loader", function() {
+ //this.extractRecord(type, structure, loader)
+
+ //function extractRecord(type, structure, loader) {
+ //loader.load(type, structure, {
+ //id: this.extractId(structure),
+ //hasMany: { comments: [ 1,2,3 ] }
+ //});
+ //}
+});

0 comments on commit 39319db

Please sign in to comment.