can-model/doc/GREADME.md

can.Model

- <code>[__can-model__ constructor => [can-model](#modelname-staticproperties-instanceproperties)](#can-model-constructor--can-modelmodelname-staticproperties-instanceproperties)</code>
  - <code>[Model([name,] staticProperties, instanceProperties)](#modelname-staticproperties-instanceproperties)</code>
  - <code>[new Model([options])](#new-modeloptions)</code>
    - <code>[Model.bind(eventType, handler)](#modelbindeventtype-handler)</code>
    - <code>[Model.create: function(serialized) -> Promise](#modelcreate-functionserialized---promise)</code>
    - <code>[Model.create: "[METHOD] /path/to/resource"](#modelcreate-method-pathtoresource)</code>
    - <code>[Model.create: {Object}](#modelcreate-object)</code>
    - <code>[Model.findAll( params[, success[, error]] )](#modelfindall-params-success-error-)</code>
    - <code>[Model.findAll: findAllData( params ) -> Promise](#modelfindall-findalldata-params----promise)</code>
    - <code>[Model.findAll: "[METHOD] /path/to/resource"](#modelfindall-method-pathtoresource)</code>
    - <code>[Model.findAll: {Object}](#modelfindall-object)</code>
    - <code>[Model.model(data)](#modelmodeldata)</code>
    - <code>[Model.models(data[, oldList])](#modelmodelsdata-oldlist)</code>
    - <code>[Model.destroy: function(id) -> Promise](#modeldestroy-functionid---promise)</code>
    - <code>[Model.destroy: "[METHOD] /path/to/resource"](#modeldestroy-method-pathtoresource)</code>
    - <code>[Model.findAll( params[, success[, error]] )](#modelfindall-params-success-error-)</code>
    - <code>[Model.findAll: findAllData( params ) -> Promise](#modelfindall-findalldata-params----promise)</code>
    - <code>[Model.findAll: "[METHOD] /path/to/resource"](#modelfindall-method-pathtoresource)</code>
    - <code>[Model.findAll: {Object}](#modelfindall-object)</code>
    - <code>[Model.findOne( params[, success[, error]] )](#modelfindone-params-success-error-)</code>
    - <code>[Model.findOne: findOneData( params ) -> Promise](#modelfindone-findonedata-params----promise)</code>
    - <code>[Model.findOne: "[METHOD] /path/to/resource"](#modelfindone-method-pathtoresource)</code>
    - <code>[Model.findOne: {Object}](#modelfindone-object)</code>
    - <code>[id String](#id-string)</code>
    - _can-model.isNew_
    - <code>[function(params) -> Promise](#functionparams---promise)</code>
    - <code>[Model.findOne( params[, success[, error]] )](#modelfindone-params-success-error-)</code>
    - <code>[Model.findOne: findOneData( params ) -> Promise](#modelfindone-findonedata-params----promise)</code>
    - <code>[Model.findOne: "[METHOD] /path/to/resource"](#modelfindone-method-pathtoresource)</code>
    - <code>[Model.findOne: {Object}](#modelfindone-object)</code>
    - <code>[findOneData function(params)](#findonedata-functionparams)</code>
    - _can-model.list_
    - <code>[Model.makeFindAll: function(findAllData) -> findAll](#modelmakefindall-functionfindalldata---findall)</code>
    - <code>[Model.makeFindOne: function(findOneData) -> findOne](#modelmakefindone-functionfindonedata---findone)</code>
    - <code>[Model.model(data)](#modelmodeldata)</code>
    - _can-model.model_bind_
    - _can-model.model_destroy_
    - _can-model.model_save_
    - _can-model.model_unbind_
    - <code>[Model.parseModel( data, xhr )](#modelparsemodel-data-xhr-)</code>
    - <code>[parseModel: "PROPERTY"](#parsemodel-property)</code>
    - <code>[Model.parseModels(data, xhr)](#modelparsemodelsdata-xhr)</code>
    - <code>[parseModels: "PROPERTY"](#parsemodels-property)</code>
    - <code>[removeAttr Boolean](#removeattr-boolean)</code>
    - <code>[resource String](#resource-string)</code>
    - <code>[Model.setup(base, fullName, staticProps, protoProps)](#modelsetupbase-fullname-staticprops-protoprops)</code>
    - <code>[store Object](#store-object)</code>
    - <code>[Model.unbind(eventType, handler)](#modelunbindeventtype-handler)</code>
    - <code>[Model.update: "[METHOD] /path/to/resource"](#modelupdate-method-pathtoresource)</code>
    - <code>[Model.update: function(id, serialized) -> Promise](#modelupdate-functionid-serialized---promise)</code>

## API


## <code>__can-model__ constructor => [can-model](#modelname-staticproperties-instanceproperties)</code>



### <code>Model([name,] staticProperties, instanceProperties)</code>

Create a Model constructor. (See [can-construct] for more details on this syntax.)

1. __name__ <code>{String}</code>:
  If given, this will be the globally-available name of the constructor function.
1. __staticProperties__ <code>{Object}</code>:
  The static properties of the class. See below for properties with
  special meanings to `Model`.
1. __instanceProperties__ <code>{Object}</code>:
  The instance properties of instances of the class. These will usually
  be functions.

- __returns__ <code>{function}</code>:
  A Model constructor.
  

### <code>new Model([options])</code>

Creates a new instance of _ModelConstructor_.

1. __options__ <code>{Object}</code>:
  Options to pass to `setup` or `init`.

- __returns__ <code>{[can-model](#modelname-staticproperties-instanceproperties)}</code>:
  A new instance of _ModelConstructor_.
  

#### <code>Model.bind(eventType, handler)</code>


1. __eventType__ <code>{String}</code>:
  The type of event.  It must be
  `"created"`, `"updated"`, `"destroyed"`.
1. __handler__ <code>{function}</code>:
  A callback function
  that gets called with the event and instance that was
  created, destroyed, or updated.

- __returns__ <code>{Model}</code>:
  The model constructor function.
  

#### <code>Model.create: function(serialized) -> Promise</code>


Specify a function to create persistent instances. The function will
typically perform an AJAX request to a service that results in
creating a record in a database.


1. __serialized__ <code>{Object}</code>:
  The [Map::serialize serialized] properties of
  the model to create.

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to an object of attributes
  that will be added to the created model instance.  The object __MUST__ contain
  an [id](#id-string) property so that future calls to [save](#modelsavesuccess-error)
  will call [update](#modelupdate-method-pathtoresource).
  
  

#### <code>Model.create: "[METHOD] /path/to/resource"</code>


Specify a HTTP method and url to create persistent instances.

If you provide a URL, the Model will send a request to that URL using
the method specified (or POST if none is specified) when saving a
new instance on the server. (See below for more details.)


1. __METHOD__ <code>{HttpMethod}</code>:
  An HTTP method. Defaults to `"POST"`.
1. __url__ <code>{STRING}</code>:
  The URL of the service to retrieve JSON data.
  
  

#### <code>Model.create: {Object}</code>


Specify an options object that is used to make a HTTP request to create
persistent instances.


1. __ajaxSettings__ <code>{Object}</code>:
  A settings object that
  specifies the options available to pass to [can-util/dom/ajax/ajax].
  

#### <code>Model.findAll( params[, success[, error]] )</code>


Retrieve multiple resources from a server.


1. __params__ <code>{Object}</code>:
  Values to filter the request or results with.
1. __success__ <code>{function(list)}</code>:
  A callback to call on successful retrieval. The callback receives
  a Model.List of the retrieved resources.
1. __error__ <code>{function(xhr)}</code>:
  A callback to call when an error occurs. The callback receives the
  XmlHttpRequest object.

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to a [List](#list-modellist) of retrieved models.
  
  

#### <code>Model.findAll: findAllData( params ) -> Promise</code>


Implements `findAll` with a [function](#functionparams---promise). This function
is passed to [makeFindAll](#modelmakefindall-functionfindalldata---findall) to create the external
`findAll` method.

```
findAll: function(params){
 return $.get("/tasks",params)
}
```


1. __findAllData__ <code>{Model.findAllData}</code>:
  A function that accepts parameters
  specifying a list of instance data to retrieve and returns a [Promise]
  that resolves to an array of those instances.
  

#### <code>Model.findAll: "[METHOD] /path/to/resource"</code>


Implements `findAll` with a HTTP method and url to retrieve instance data.

   findAll: "GET /tasks"

If `findAll` is implemented with a string, this gets converted to
a [findAllData function](#functionparams---promise)
which is passed to [makeFindAll](#modelmakefindall-functionfindalldata---findall) to create the external
`findAll` method.


1. __METHOD__ <code>{HttpMethod}</code>:
  An HTTP method. Defaults to `"GET"`.
  
1. __url__ <code>{STRING}</code>:
  The URL of the service to retrieve JSON data.
  

- __returns__ <code>{JSON}</code>:
  The service should return a JSON object like:
  
  ```
  {
   "data": [
     { "id" : 1, "name" : "do the dishes" },
     { "id" : 2, "name" : "mow the lawn" },
     { "id" : 3, "name" : "iron my shirts" }
   ]
  }
  ```
  
  This object is passed to [models](#modelmodelsdata-oldlist) to turn it into instances.
  
  _Note: .findAll can also accept an array, but you
  probably [should not be doing that](http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx)._
  
  

#### <code>Model.findAll: {Object}</code>


Implements `findAll` with a ajax settings object.

```
findAll: {url: "/tasks", dataType: "json"}
```

If `findAll` is implemented with an object, it gets converted to
a [findAllData function](#functionparams---promise)
which is passed to [makeFindAll](#modelmakefindall-functionfindalldata---findall) to create the external
`findAll` method.


1. __ajaxSettings__ <code>{Object}</code>:
  A settings object that
  specifies the options available to pass to [can-util/dom/ajax/ajax].
  

#### <code>Model.model(data)</code>


1. __data__ <code>{Object}</code>:
  The data to convert to a Model instance.

- __returns__ <code>{Model}</code>:
  An instance of Model made with the given data.
  
  

#### <code>Model.models(data[, oldList])</code>


1. __data__ <code>{Array\<Object\>}</code>:
  The raw data from a `[Model.findAll findAll()]` request.
1. __oldList__ <code>{Model.List}</code>:
  If supplied, this List will be updated with the data from
  __data__.

- __returns__ <code>{Model.List}</code>:
  A List of Models made from the raw data.
  
  

#### <code>Model.destroy: function(id) -> Promise</code>


If you provide a function, the Model will expect you to do your own AJAX requests.

1. __id__:
  The ID of the resource to destroy.

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to the destroyed model.
  

#### <code>Model.destroy: "[METHOD] /path/to/resource"</code>


If you provide a URL, the Model will send a request to that URL using
the method specified (or DELETE if none is specified) when deleting an
instance on the server. (See below for more details.)


- __returns__ <code>{Promise}</code>:
  A Promise that resolves to the destroyed model.
  

#### <code>Model.findAll( params[, success[, error]] )</code>


Retrieve multiple resources from a server.


1. __params__ <code>{Object}</code>:
  Values to filter the request or results with.
1. __success__ <code>{function(list)}</code>:
  A callback to call on successful retrieval. The callback receives
  a Model.List of the retrieved resources.
1. __error__ <code>{function(xhr)}</code>:
  A callback to call when an error occurs. The callback receives the
  XmlHttpRequest object.

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to a [List](#list-modellist) of retrieved models.
  
  

#### <code>Model.findAll: findAllData( params ) -> Promise</code>


Implements `findAll` with a [function](#functionparams---promise). This function
is passed to [makeFindAll](#modelmakefindall-functionfindalldata---findall) to create the external
`findAll` method.

```
findAll: function(params){
 return $.get("/tasks",params)
}
```


1. __findAllData__ <code>{Model.findAllData}</code>:
  A function that accepts parameters
  specifying a list of instance data to retrieve and returns a [Promise]
  that resolves to an array of those instances.
  

#### <code>Model.findAll: "[METHOD] /path/to/resource"</code>


Implements `findAll` with a HTTP method and url to retrieve instance data.

   findAll: "GET /tasks"

If `findAll` is implemented with a string, this gets converted to
a [findAllData function](#functionparams---promise)
which is passed to [makeFindAll](#modelmakefindall-functionfindalldata---findall) to create the external
`findAll` method.


1. __METHOD__ <code>{HttpMethod}</code>:
  An HTTP method. Defaults to `"GET"`.
  
1. __url__ <code>{STRING}</code>:
  The URL of the service to retrieve JSON data.
  

- __returns__ <code>{JSON}</code>:
  The service should return a JSON object like:
  
  ```
  {
   "data": [
     { "id" : 1, "name" : "do the dishes" },
     { "id" : 2, "name" : "mow the lawn" },
     { "id" : 3, "name" : "iron my shirts" }
   ]
  }
  ```
  
  This object is passed to [models](#modelmodelsdata-oldlist) to turn it into instances.
  
  _Note: .findAll can also accept an array, but you
  probably [should not be doing that](http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx)._
  
  

#### <code>Model.findAll: {Object}</code>


Implements `findAll` with a ajax settings object.

```
findAll: {url: "/tasks", dataType: "json"}
```

If `findAll` is implemented with an object, it gets converted to
a [findAllData function](#functionparams---promise)
which is passed to [makeFindAll](#modelmakefindall-functionfindalldata---findall) to create the external
`findAll` method.


1. __ajaxSettings__ <code>{Object}</code>:
  A settings object that
  specifies the options available to pass to [can-util/dom/ajax/ajax].
  

#### <code>Model.findOne( params[, success[, error]] )</code>


Retrieve a single instance from the server.


1. __params__ <code>{Object}</code>:
  Values to filter the request or results with.
1. __success__ <code>{function(model)}</code>:
  A callback to call on successful retrieval. The callback receives
  the retrieved resource as a Model.
1. __error__ <code>{function(xhr)}</code>:
  A callback to call when an error occurs. The callback receives the
  XmlHttpRequest object.

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to a [Model] instance of the retrieved model
  

#### <code>Model.findOne: findOneData( params ) -> Promise</code>


Implements `findOne` with a [function](#findonedata-functionparams). This function
is passed to [makeFindOne](#modelmakefindone-functionfindonedata---findone) to create the external
`findOne` method.

```
findOne: function(params){
 return $.get("/task/"+params.id)
}
```


1. __findOneData__ <code>{Model.findOneData}</code>:
  A function that accepts parameters
  specifying an instance to retreive and returns a [Promise]
  that resolves to that instance.
  

#### <code>Model.findOne: "[METHOD] /path/to/resource"</code>


Implements `findOne` with a HTTP method and url to retrieve an instance's data.

```
findOne: "GET /tasks/{id}"
```

If `findOne` is implemented with a string, this gets converted to
a [makeFindOne function](#modelmakefindone-functionfindonedata---findone)
which is passed to [makeFindOne](#modelmakefindone-functionfindonedata---findone) to create the external
`findOne` method.


1. __METHOD__ <code>{HttpMethod}</code>:
  An HTTP method. Defaults to `"GET"`.
  
1. __url__ <code>{STRING}</code>:
  The URL of the service to retrieve JSON data.
  

#### <code>Model.findOne: {Object}</code>


Implements `findOne` with a ajax settings object.

   findOne: {url: "/tasks/{id}", dataType: "json"}

If `findOne` is implemented with an object, it gets converted to
a [makeFindOne function](#modelmakefindone-functionfindonedata---findone)
which is passed to [makeFindOne](#modelmakefindone-functionfindonedata---findone) to create the external
`findOne` method.


1. __ajaxSettings__ <code>{Object}</code>:
  A settings object that
  specifies the options available to pass to [ajax].
  
#### id `{String}`

The name of the id field.  Defaults to `'id'`. Change this if it is something different.



##### <code>String</code>


#### <code>function(params) -> Promise</code>




#### <code>Model.findOne( params[, success[, error]] )</code>


Retrieve a single instance from the server.


1. __params__ <code>{Object}</code>:
  Values to filter the request or results with.
1. __success__ <code>{function(model)}</code>:
  A callback to call on successful retrieval. The callback receives
  the retrieved resource as a Model.
1. __error__ <code>{function(xhr)}</code>:
  A callback to call when an error occurs. The callback receives the
  XmlHttpRequest object.

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to a [Model] instance of the retrieved model
  

#### <code>Model.findOne: findOneData( params ) -> Promise</code>


Implements `findOne` with a [function](#findonedata-functionparams). This function
is passed to [makeFindOne](#modelmakefindone-functionfindonedata---findone) to create the external
`findOne` method.

```
findOne: function(params){
 return $.get("/task/"+params.id)
}
```


1. __findOneData__ <code>{Model.findOneData}</code>:
  A function that accepts parameters
  specifying an instance to retreive and returns a [Promise]
  that resolves to that instance.
  

#### <code>Model.findOne: "[METHOD] /path/to/resource"</code>


Implements `findOne` with a HTTP method and url to retrieve an instance's data.

```
findOne: "GET /tasks/{id}"
```

If `findOne` is implemented with a string, this gets converted to
a [makeFindOne function](#modelmakefindone-functionfindonedata---findone)
which is passed to [makeFindOne](#modelmakefindone-functionfindonedata---findone) to create the external
`findOne` method.


1. __METHOD__ <code>{HttpMethod}</code>:
  An HTTP method. Defaults to `"GET"`.
  
1. __url__ <code>{STRING}</code>:
  The URL of the service to retrieve JSON data.
  

#### <code>Model.findOne: {Object}</code>


Implements `findOne` with a ajax settings object.

   findOne: {url: "/tasks/{id}", dataType: "json"}

If `findOne` is implemented with an object, it gets converted to
a [makeFindOne function](#modelmakefindone-functionfindonedata---findone)
which is passed to [makeFindOne](#modelmakefindone-functionfindonedata---findone) to create the external
`findOne` method.


1. __ajaxSettings__ <code>{Object}</code>:
  A settings object that
  specifies the options available to pass to [ajax].
  
#### findOneData `{function(params)}`





##### <code>function(params)</code>


1. __params__ <code>{Object}</code>:
  

- __returns__ <code>{Promise}</code>:
  A Promise
  

#### <code>Model.makeFindAll: function(findAllData) -> findAll</code>


Returns the external `findAll` method given the implemented [findAllData](#functionparams---promise) function.


1. __findAllData__ <code>{Model.findAllData}</code>:
  
  
  [findAll](#modelfindall-params-success-error-) is implemented with a `String`, ajax settings object, or
  [findAllData](#functionparams---promise) function. If it is implemented as
  a `String` or ajax settings object, those values are used
  to create a [findAllData](#functionparams---promise) function.
  
  The [findAllData](#functionparams---promise) function is passed to `makeFindAll`. `makeFindAll`
  should use `findAllData` internally to get the raw data for the request.
  

- __returns__ <code>{function(params, success, error)}</code>:
  
  
  Returns function that implements the external API of `findAll`.
  

#### <code>Model.makeFindOne: function(findOneData) -> findOne</code>


Returns the external `findOne` method given the implemented [findOneData](#findonedata-functionparams) function.


1. __findOneData__ <code>{Model.findOneData}</code>:
  
  
  [findOne](#modelfindone-params-success-error-) is implemented with a `String`, ajax settings object, or
  [findOneData](#findonedata-functionparams) function. If it is implemented as
  a `String` or ajax settings object, those values are used
  to create a [findOneData](#findonedata-functionparams) function.
  
  The [findOneData](#findonedata-functionparams) function is passed to `makeFindOne`. `makeFindOne`
  should use `findOneData` internally to get the raw data for the request.
  

- __returns__ <code>{function(params, success, error)}</code>:
  
  
  Returns function that implements the external API of `findOne`.
  

#### <code>Model.model(data)</code>


1. __data__ <code>{Object}</code>:
  The data to convert to a Model instance.

- __returns__ <code>{Model}</code>:
  An instance of Model made with the given data.
  
  

#### <code>Model.parseModel( data, xhr )</code>


1. __data__ <code>{Object}</code>:
  The data to convert to a Model instance.
1. __xhr__ <code>{XMLHTTPRequest}</code>:
  The XMLHTTPRequest object used to make the request.

- __returns__ <code>{Object}</code>:
  An object of properties to set at the [can-model::attr attributes]
  of a model instance.
  

#### <code>parseModel: "PROPERTY"</code>


Creates a `parseModel` function that looks for the attributes object in the PROPERTY
property of raw instance data.


#### <code>Model.parseModels(data, xhr)</code>



1. __data__:
  The raw data from a `[findAll()](#modelfindall-params-success-error-)` request.
  
1. __xhr__ <code>{XMLHTTPRequest}</code>:
  The XMLHTTPRequest object used to make the request.
  

- __returns__ <code>{Array|Object}</code>:
  A JavaScript Object or Array that [models](#modelmodelsdata-oldlist)
  can convert into the Model's List.
  

#### <code>parseModels: "PROPERTY"</code>


Creates a `parseModels` function that looks for the array of instance data in the PROPERTY
property of the raw response data of [findAll](#modelfindall-params-success-error-).

#### removeAttr `{Boolean}`

Sets whether model conversion should remove non existing attributes or merge with
the existing attributes. The default is `false`.
For example, if `Task.findOne({ id: 1 })` returns



##### <code>Boolean</code>

#### resource `{String}`

Define a restful resource URL. 



##### <code>String</code>


A string URL to a restful resource. If the resource
is specified as `"resource"` and the model's [id](#id-string) is
`"id"`, resource will implement [can-model](#modelname-staticproperties-instanceproperties)'s ajax methods as follows:

 - [findAll](#modelfindall-params-success-error-) - `"GET resource"`
 - [findOne](#modelfindone-params-success-error-) - `"GET resource/{id}"`
 - [create](#modelcreate-functionserialized---promise) - `"POST resource"`
 - [update](#modelupdate-method-pathtoresource) - `"PUT resource/{id}"`
 - [destroy](#modeldestroy-functionid---promise) - `"DELETE resource/{id}"`

Setting the `resource` property will not overwrite other implemented
ajax methods, however will overwrite inherited ajax methods.


#### <code>Model.setup(base, fullName, staticProps, protoProps)</code>

#### store `{Object}`

A non-leaking global store of Model instances. 



##### <code>Object</code>


#### <code>Model.unbind(eventType, handler)</code>


1. __eventType__ <code>{String}</code>:
  The type of event. It must be
  `"created"`, `"updated"`, `"destroyed"`.
1. __handler__ <code>{function}</code>:
  A callback function
  that was passed to `bind`.

- __returns__ <code>{Model}</code>:
  The model constructor function.
  

#### <code>Model.update: "[METHOD] /path/to/resource"</code>

If you provide a URL, the Model will send a request to that URL using
the method specified (or PUT if none is specified) when updating an
instance on the server. (See below for more details.)

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to the updated model.
  

#### <code>Model.update: function(id, serialized) -> Promise</code>

If you provide a function, the Model will expect you to do your own AJAX requests.

1. __id__:
  The ID of the model to update.
1. __serialized__ <code>{Object}</code>:
  The [can-map::serialize serialized] properties of
  the model to update.

- __returns__ <code>{Promise}</code>:
  A Promise that resolves to the updated model.