ATTENTION: This library is no longer supported because it is overly simplistic for most applications. Please consider using Ember Data instead. @dgeb 2014-02-19
Ember-REST
A very simple library for RESTful resources in Ember.js.
This was extracted from a simple example app: https://github.com/dgeb/ember_rest_example
Requirements
Ember.js and jQuery.js
Changes
This library is a work in progress. All breaking changes and significant updates will be reported in CHANGELOG
Usage
Ember.Resource
Create models that extend Ember.Resource. For example:
App.Contact = Ember.Resource.extend({
resourceUrl: '/contacts',
resourceName: 'contact',
resourceProperties: ['first_name', 'last_name'],
validate: function() {
if (this.get('first_name') === undefined || this.get('first_name') === '' ||
this.get('last_name') === undefined || this.get('last_name') === '') {
return 'Contacts require a first and a last name.';
}
},
fullName: Ember.computed(function() {
return this.get('first_name') + ' ' + this.get('last_name');
}).property('first_name', 'last_name')
});
Define the following properties for your models:
resourceIdField
-- the id field for this resource ('id' by default)resourceUrl
-- the base url of the resource (e.g. '/contacts'); will append '/' + id for individual resourcesresourceName
-- the name used to contain the serialized data in this object's JSON representation (required only for serialization)resourceProperties
-- an array of property names to be returned in this object's JSON representation (required only for serialization)
Note that because resourceName
and resourceProperties
are only used for serialization, they aren't required for read-only resources.
You may wish to override / define the following methods:
serialize()
- generate this resource's JSON representationserializeProperty(prop)
- generate an individual property's JSON representationdeserialize(json)
deserializeProperty(prop, value)
validate()
- parse values and return an error string or object if appropriateisNew()
- determines whether this a new resource based on the presence of itsid
The following CRUD methods are available on resources:
findResource()
- loads a resourcesaveResource()
- create a new resource or update an existing onedestroyResource()
- delete an existing resource
Here's an example of loading a single resource with findResource()
:
var contact = Contact.create({id: 1});
contact.findResource()
.fail( function(e) {
App.displayError(e);
})
.done(function() {
alert("Loaded!");
});
Here's an example of creating a new resource with saveResource()
:
submit: function(event) {
var self = this;
var contact = this.get("contact");
event.preventDefault();
contact.saveResource()
.fail( function(e) {
App.displayError(e);
})
.done(function() {
App.contactsController.pushObject(contact);
self.get("parentView").hideNew();
});
}
Here's an almost identical example of updating an existing resource with saveResource()
:
submit: function(event) {
var self = this;
var contact = this.get("contact");
event.preventDefault();
contact.saveResource()
.fail( function(e) {
App.displayError(e);
})
.done( function() {
var parentView = self.get("parentView");
parentView.get("contact").duplicateProperties(contact);
parentView.hideEdit();
});
}
And an example of deleting an existing resource with destroyResource()
:
destroyRecord: function() {
var contact = this.get("contact");
contact.destroyResource()
.done(function() {
App.contactsController.removeObject(contact);
});
}
Ember.ResourceController
Extend Ember.ResourceController to create controllers of resources. For example:
App.contactsController = Ember.ResourceController.create({
resourceType: App.Contact
});
Define the following properties for your controller:
resourceType
-- an Ember.Resource class; the class must have aserialize()
method that returns a JSON representation of the objectresourceUrl
-- (optional) the base url of the resource (e.g. '/contacts/active'); will default to theresourceUrl
forresourceType
The following methods are available:
load(json)
-- create and load a singleEmber.Resource
from JSONloadAll(json)
-- create and loadEmber.Resource
objects from a JSON arrayfindAll()
-- replacecontents
with an ajax call toresourceUrl
clearAll()
-- clearcontents
(without deleting resources)
Ember.ResourceAdapter
Ember.ResourceAdapter is mixed in to both Ember.Resource and Ember.ResourceController to perform resource requests. The default implementation is a thin wrapper around jQuery.ajax().
If you would like to completely override Ember.ResourceAdapter, define your own version before including ember-rest.js. For example:
Ember.ResourceAdapter = Ember.Mixin.create({
_resourceRequest: function(params) {
// TODO - your implementation here
}
});
If you would just like to modify the behavior of Ember.ResourceAdapter, just reopen it. A _prepareResourceRequest()
hook has been provided to allow modifications to the params passed to jQuery.ajax()
.
Here's an example that adds oauth support (note: this is not completely generalized - it depends on MyApp.oauthToken
):
Ember.ResourceAdapter.reopen({
_prepareResourceRequest: function(params) {
params.beforeSend = function (xhr, settings) {
xhr.withCredentials = true;
xhr.setRequestHeader('Authorization', 'Bearer ' + MyApp.oauthToken);
}
}
});
Tests
QUnit and Sinon are used for tests. Simply open tests/index.html
in your browser to run all the tests. No local server required.
Contributions
Please file issues on Github. Pull requests are welcome too.
License
Copyright 2012 Cerebris Corporation. MIT License (see LICENSE for details).