model-resource.js

/**
Model Resource

@module model-resource
**/

var ModelResource,

    isFunction  = Y.Lang.isFunction,
    noop        = function(){};

/**
Provides a RESTful HTTP `Model` sync implementation.

@class      ModelResource
@extends    Resource
@constructor
**/
ModelResource = Y.Base.create('modelResource', Y.Resource, [], {

    // *** Prototype *** //
    
    // *** Public Methods *** //
    
    /**
    This method is indented to be delegated to from a `Model`’s `sync` method.
    
    @example
        var resource = new Y.ModelResource({ uri: '/foo/{id}/' });
        var FooModel = Y.Base.create('fooModel', Y.Model, [], {
            resource: resource,
            sync    : function (action, options, callback) {
                (options || (options = {})).model = this;
                this.resource.sync(action, options, callback);
            }
        });

    @method sync
    @param {String} action Sync action to perform. May be one of the following:

      * `create`: Store a newly-created model for the first time.
      * `delete`: Delete an existing model.
      * 'read'  : Load an existing model.
      * `update`: Update an existing model.

    @param {Object} [options] Sync options.
      @param {Object} options.model Reference to the `Model` or `ModelList`
      which is being synced. The `Model` is used both as the HTTP request
      entity body and to provide a value for a `id` parameter.
    @param {callback} [callback] Called when the sync operation finishes.
      @param {Error|null} callback.err If an error occurred, this parameter will
        contain the error. If the sync operation succeeded, _err_ will be
        falsy.
      @param {mixed} [callback.response] The server's response. This value will
        be passed to the `parse()` method, which is expected to parse it and
        return an attribute hash.
    **/
    sync : function (action, options, callback) {
        isFunction(callback) || (callback = noop);
        var model   = options.model,
            isModel = model instanceof Y.Model,
            request;
        
        switch (action) {
        case 'create':
            request = {
                method : 'POST',
                params : { id: '' },    // chop off id placeholder from URI
                entity : model
            };
            break;
            
        case 'read':
            request = {
                method : 'GET',
                params : { id: isModel ? model.get('id') : '' }
            };
            break;
            
        case 'update':
            request = {
                method : 'PUT',
                params : { id: model.get('id') },
                entity : model
            };
            break;
            
        case 'delete':
            request = {
                method : 'DELETE',
                params : { id: model.get('id') }
            };
            break;
        }
        
        request.on = {
            success : function(e){ callback(null, e.entity); },
            failure : callback
        };
        
        this.sendRequest(request);
    },
    
    // *** Private Methods *** //
    
    _setHeaders : function (headers) {
        return Y.merge(ModelResource.HEADERS, headers);
    }

}, {

    // *** Static *** //
    
    HEADERS : {
        'Accept'        : 'application/json',
        'Content-Type'  : 'application/json'
    },
    
    ATTRS : {
        headers : {
            valueFn : function(){ return ModelResource.HEADERS; },
            setter  : '_setHeaders'
        }
    }

});

// *** Namespace *** //

Y.ModelResource = ModelResource;