From b21297cb92b20e687b313a58262932c5a5fe388e Mon Sep 17 00:00:00 2001 From: Christina Kung Date: Sat, 7 Jun 2014 23:22:38 -0400 Subject: [PATCH 1/3] Update README with store usage --- README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2536c25..52f23e4 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,71 @@ existingUser.set('name', 'Kris'); existingUser.get('isDirty'); // => true existingUser.save(); // PUT /users/1 ``` +## Store API *experimental* +At this time Ember Model supports two ways of managing model life-cycle. + +1. Store API +2. Model API - see below + +Once you load Ember Model, the store is created and available for use on all routes and controllers. You can then use the store api methods to create and find records. + +`store.modelFor()` - returns a model class from type string. Does a +`container.lookupFactory(model:)` + +`store.adapterFor()` - returns an adapter class from the type string. Will look for an adapter in the following order: + +1. Return the adpater defined on the model class. +2. Return the adapter resolved from `container.lookupFactory(adapter:)` +3. Return the adapter resolved from `container.lookupFactory(adapter:application)` +4. Finally return a RESTAdapter if not adapter is defined + +`store.createRecord()` - create a new record of string type passed in - (`'post'` for example) + +`store.find()` - find all records, returns a promise + +`store.find()` - find by primary key (multiple calls within a single run loop can coalesce to a findMany), returns a promise + +`store.find()` - find query - object gets passed directly to your adapter, returns a promise + +###Store Advantages +The main advantage of the Store API is that it can reduce boilerplate in your route modules . For example, +``` +App.PostRoute = Ember.Route.extend({ + model: function(params) { + var data = Ember.$.getJSON('/posts/'+params.post_id); + return App.Post.create(data); + } +}); +``` +is now: +``` +App.PostRoute = Ember.Route.extend({}); +``` + +You will also be able to look up relationships via container so you don't need to pass object nor maintain global App.ModelName. For example, +``` +App.Post = Ember.Model.extend({ + id: Ember.attr(), + comments: Ember.hasMany(App.Comment, {embedded: true}) +}); +``` +is now: +``` +var Post = Ember.Model.extend({ + id: Ember.attr(), + comments: Ember.hasMany('comment', {embedded: true}) +}); +``` + +###Store Warnings +The store still needs work! Most of the gotchas revolve around relationship definitions. If you define relationships as a simple string i.e. `Ember.hasMany('comment', {embedded: true})` + +1. You must create all of your models via store.createRecord() + +2. Be consistent. Use that syntax for all of your relationships. + + + ## Model API @@ -178,7 +243,7 @@ Relationships are defined by using relationship computed property macros in plac Both relationships take two arguments. -- `type` - Class of the related model or string representation (eg. App.Comment or 'App.Comment'). +- `type` - Class of the related model or string representation (eg. App.Comment or 'App.Comment'). As of latest release, can just be a string 'comment'- see Store API section. - `options` - An object with two properties, `key` which is required and `embedded` which is optional and defaults to `false`. From 921c71a26266290e23154a555665f875dd286214 Mon Sep 17 00:00:00 2001 From: Christina Kung Date: Sat, 7 Jun 2014 23:35:12 -0400 Subject: [PATCH 2/3] Update README with relationship key default details --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 52f23e4..7781c3c 100644 --- a/README.md +++ b/README.md @@ -247,7 +247,7 @@ Both relationships take two arguments. - `options` - An object with two properties, `key` which is required and `embedded` which is optional and defaults to `false`. - - `key` - indicates what property of the JSON backing the model will be accessed to access the relationship + - `key` - Indicates what property of the JSON backing the model will be accessed to access the relationship. This will default to the model's attribute name if no key is passed. - `embedded` - If `true` the related objects are expected to be present in the data backing the model. If `false` only the primaryKeys are present in the data backing the model. These keys will be used to load the correct model. ### Relationship Examples @@ -275,7 +275,7 @@ App.Post = Ember.Model.extend({ id: Ember.attr(), title: Ember.attr(), body: Ember.attr(), - comments: Ember.hasMany('App.Comment', {key: 'comments', embedded: true}) + comments: Ember.hasMany('App.Comment', {embedded: true}) //key is implicitly comments }); App.Comment = Ember.Model.extend({ From b897159d665901abdffba02e7b2a3e11fdc1b5ca Mon Sep 17 00:00:00 2001 From: Christina Kung Date: Sat, 7 Jun 2014 23:40:32 -0400 Subject: [PATCH 3/3] Update README with cache transient details --- README.md | 21 ++++++++++----------- packages/ember-model/lib/store.js | 9 +++++++++ 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 7781c3c..fa06367 100644 --- a/README.md +++ b/README.md @@ -78,13 +78,6 @@ Once you load Ember Model, the store is created and available for use on all rou `store.modelFor()` - returns a model class from type string. Does a `container.lookupFactory(model:)` -`store.adapterFor()` - returns an adapter class from the type string. Will look for an adapter in the following order: - -1. Return the adpater defined on the model class. -2. Return the adapter resolved from `container.lookupFactory(adapter:)` -3. Return the adapter resolved from `container.lookupFactory(adapter:application)` -4. Finally return a RESTAdapter if not adapter is defined - `store.createRecord()` - create a new record of string type passed in - (`'post'` for example) `store.find()` - find all records, returns a promise @@ -98,7 +91,7 @@ The main advantage of the Store API is that it can reduce boilerplate in your ro ``` App.PostRoute = Ember.Route.extend({ model: function(params) { - var data = Ember.$.getJSON('/posts/'+params.post_id); + var data = App.Post.find(params.post_id); return App.Post.create(data); } }); @@ -128,9 +121,7 @@ The store still needs work! Most of the gotchas revolve around relationship defi 1. You must create all of your models via store.createRecord() -2. Be consistent. Use that syntax for all of your relationships. - - +2. Be consistent. If you are using the store to create/find models, use the store convention everywhere. I.E. relationships defined as 'comment' not App.Comment ## Model API @@ -475,7 +466,15 @@ App.User.adapter = Ember.RESTAdapter.create({ }); ``` +### Cache +There is an internal cache in Ember Model. You can turn off all caching on the model level with the transient property. +``` +App.User = Ember.Model.extend({ + name: attr() +}); +App.User.transient = true; +``` ## Building Ember Model Ember Model uses [node.js](http://nodejs.org/) and [grunt](http://gruntjs.com/) as a build system, diff --git a/packages/ember-model/lib/store.js b/packages/ember-model/lib/store.js index 3828518..3483ffe 100644 --- a/packages/ember-model/lib/store.js +++ b/packages/ember-model/lib/store.js @@ -5,6 +5,15 @@ Ember.Model.Store = Ember.Object.extend({ return this.container.lookupFactory('model:'+type); }, + /** + * Returns an Ember.Adapter in following priority: + 1. Adapter defined on the model class. + 2. Adapter resolved from `container.lookupFactory(adapter:)` + 3. Adapter resolved from `container.lookupFactory(adapter:application)` + 4. RESTAdapter if no adapter is defined + * @param type + * @returns Ember.Adapter + */ adapterFor: function(type) { var adapter = this.modelFor(type).adapter, container = this.container;