docs/api.md
# angular-model API documentation
`model`
=======
<span class="hint">function in module `ur` </span>
Description
-----------
Main factory function for angular-model
Usage
-----
```javascript
model(name[, options]);
```
#### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">name</td>
<td align="left"><a href="">string</a></td>
<td align="left"><div class="ur-model-page ur-model-model-page">
<p>Name of the 'class', e.g. 'posts'</p>
</div></td>
</tr>
<tr class="even">
<td align="left">options
<div>
<em>(optional)</em>
</div></td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="ur-model-page ur-model-model-page">
<p>Config to initialise the model 'class' with. You can supply an object literal to configure your model here.</p>
</div></td>
</tr>
</tbody>
</table>
#### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">ur.model</a></td>
<td align="left"><div class="ur-model-page ur-model-model-page">
<p>instance of angular-model for the 'class' identified by 'name'</p>
</div></td>
</tr>
</tbody>
</table>
Example
-------
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
// configuration options
$instance: {
// custom instance functions
},
$class: {
// custom class functions
},
$collection: {
// custom collection functions
}
});
});
`$instance`
===========
<span class="hint">object in module `ur` </span>
Description
-----------
Methods available on model instances
You can use these when you have created or loaded a model instance, see the example
var post = model('posts').first({_id: 42});
console.log(post.name);
=> "Post with ID 42"
post.name = 'renamed';
post.$save();
You can specify custom instance methods:
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
$instance: {
$logo: function() {
return this.logo || '/logos/default.png';.
}
}
});
});
Methods
-------
### $delete()
Delete an instance from the API
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="-delete-page">
<p>Promise from an API request</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
post.$delete();
### $dirty()
Returns boolean - true if a model instance is unmodified, else false. Inverse of $pristine.
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">boolean</a></td>
<td align="left"><div class="-dirty-page">
<p>true if a model instance is modified, else false. Inverse of $pristine.</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
if (post.$pristine()) { console.log('It is just as it was when we got it from the API'); }
### $exists()
Checks whether an object exists in the API, based on whether it has an identity URL.
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">boolean</a></td>
<td align="left"><div class="-exists-page">
<p>True if the identifier of this instance exists in the API</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
if (post.$exists()) { console.log('It exists'); }
### $hasRelated(name)
Does an instance have a relation of name `name`?
##### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">name</td>
<td align="left"><a href="">string</a></td>
<td align="left"><div class="-hasrelated-page">
<p>Name of the related property to check for</p>
</div></td>
</tr>
</tbody>
</table>
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">boolean</a></td>
<td align="left"><div class="-hasrelated-page">
<p>true if a $link to <code>name</code> exists on this instance</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
if (post.$hasRelated('author')) { console.log('Post has an author'); }
### $modified()
Returns a map of the properties that have been changed
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="-modified-page">
<p>Map of the fields that have been changed from the $pristine version</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
console.log(post.$modified());
### $pristine()
Returns boolean - false if a model instance is unmodified, else true. Inverse of $dirty.
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">boolean</a></td>
<td align="left"><div class="-pristine-page">
<p>true if a model instance is unmodified, else false. Inverse of $dirty.</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
if (post.$dirty()) { console.log('Post has been modified'); }
### $related()
Hydrates the $links property of the instance. $links are used so that an instance can tell the client which objects are related to it. For example, a `post` may have an `author` object related to it.
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="-related-page">
<p>Promise from the API</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
console.log(post.links());
### $reload()
Refresh an instance of a model from the API
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="-reload-page">
<p>Promise from an API request</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
post.$reload();
### $revert()
Reset the model to the state it was originally in when you first got it from the API
#### Example
post.$revert();
### $save(data)
Persist an instance to the API
##### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">data
<div>
<em>(optional)</em>
</div></td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="-save-page">
<p>Data to save to this model instance. Defaults to the result of <code>this.$modified()</code></p>
</div></td>
</tr>
</tbody>
</table>
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="-save-page">
<p>Promise from an API request</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
var post = model('posts').create({ name: 'some post' });
post.$save();
`$class`
========
<span class="hint">object in module `ur` </span>
Description
-----------
Methods available on the model class
Analogous to static methods in the OOP world
You can specify custom class methods:
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
$class: {
types: function() {
return ['announcement', 'article']
}
}
});
});
Methods
-------
### all(data, headers)
Retrieve collection of post instances from the API
##### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">data
<div>
<em>(optional)</em>
</div></td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="all-page">
<p>Configuration of the request that will be sent to your API</p>
</div></td>
</tr>
<tr class="even">
<td align="left">headers
<div>
<em>(optional)</em>
</div></td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="all-page">
<p>Map of custom headers to send to your API</p>
</div></td>
</tr>
</tbody>
</table>
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="all-page">
<p>Promise from an API request</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
model('posts').all().then(function(posts) {
console.log(posts.length);
});
=> 4
### create(data)
Creates an instance on of the model
##### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">data
<div>
<em>(optional)</em>
</div></td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="create-page">
<p>Configuration of the instance that you are creating. Merged with any defaults specified when this model was declared.</p>
</div></td>
</tr>
</tbody>
</table>
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="create-page">
<p>angular-model instance</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
var post = model('Posts').create({});
### first(data)
Retrieve a single post instances from the API
##### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">data
<div>
<em>(optional)</em>
</div></td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="first-page">
<p>Configuration of the request that will be sent to your API</p>
</div></td>
</tr>
</tbody>
</table>
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="first-page">
<p>Promise from an API request</p>
</div></td>
</tr>
</tbody>
</table>
#### Example
model('posts').first({name: 'some post'}).then(function(post) {
console.log(post._id);
});
=> 42
`$collection`
=============
<span class="hint">object in module `ur` </span>
Description
-----------
Methods available on model collections
You can use collection methods to deal with a bunch of instances together. This allows you to have powerful and expressive methods on collections.
You can specify custom collection methods:
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
$collection: {
$hasArchived: function() {
return !angular.isUndefined(_.find(this, { archived: true }));
}
},
});
});
Methods
-------
### add(object, data)
Saves the `object` with `data`
##### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">object</td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="add-page">
<p>Object to persist data onto</p>
</div></td>
</tr>
<tr class="even">
<td align="left">data
<div>
<em>(optional)</em>
</div></td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="add-page">
<p>Data to persist onto the object</p>
</div></td>
</tr>
</tbody>
</table>
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">boolean</a></td>
<td align="left"><div class="add-page">
<p>true if a $link to <code>name</code> exists on this instance</p>
</div></td>
</tr>
</tbody>
</table>
### remove(index)
Find `index` and delete it from the API, then remove it from the collection
##### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">index</td>
<td align="left"><a href="">number</a><a href="">object</a></td>
<td align="left"><div class="remove-page">
<p>Either the index of the item in the collection to remove, or the object itself, which will be searched for in the collection</p>
</div></td>
</tr>
</tbody>
</table>
##### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="remove-page">
<p>Promise from the API</p>
</div></td>
</tr>
</tbody>
</table>
`$get`
======
<span class="hint">function in module `ur` </span>
Description
-----------
Get the model class factory
Usage
-----
```javascript
$get($http, $parse, $q);
```
#### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">$http</td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="ur-model-page ur-model--get-page">
<p><a href="https://docs.angularjs.org/api/ng/service/$http" class="uri">https://docs.angularjs.org/api/ng/service/$http</a></p>
</div></td>
</tr>
<tr class="even">
<td align="left">$parse</td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="ur-model-page ur-model--get-page">
<p><a href="https://docs.angularjs.org/api/ng/service/$parse" class="uri">https://docs.angularjs.org/api/ng/service/$parse</a></p>
</div></td>
</tr>
<tr class="odd">
<td align="left">$q</td>
<td align="left"><a href="">object</a></td>
<td align="left"><div class="ur-model-page ur-model--get-page">
<p><a href="https://docs.angularjs.org/api/ng/service/$q" class="uri">https://docs.angularjs.org/api/ng/service/$q</a></p>
</div></td>
</tr>
</tbody>
</table>
#### Returns
<table>
<colgroup>
<col width="50%" />
<col width="50%" />
</colgroup>
<tbody>
<tr class="odd">
<td align="left"><a href="">object</a></td>
<td align="left"><div class="ur-model-page ur-model--get-page">
<p>The model service</p>
</div></td>
</tr>
</tbody>
</table>
`link`
======
<span class="hint">directive in module `ur.model` </span>
Description
-----------
angular-model will scan your page looking for `<link rel="resources">` tags. It will use these to work out where your API endpoints are for your angular-model classes.
So, if you have a "class" Posts, you would define a link with an href pointing to the API endpoint for Posts. This should be a HATEOS-compliant API endpoint.
Dependencies
------------
`model`
Usage
-----
as element:
```javascript
<link
rel="{string}"
name="{string}"
href="{string}">
</link>
```
#### Parameters
<table>
<colgroup>
<col width="33%" />
<col width="33%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th align="left">Param</th>
<th align="left">Type</th>
<th align="left">Details</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">rel</td>
<td align="left"><a href="">string</a></td>
<td align="left"><div class="ur-model-directive-page ur-model-directive-link-page">
<p>Must be equal to "resource".</p>
</div></td>
</tr>
<tr class="even">
<td align="left">name</td>
<td align="left"><a href="">string</a></td>
<td align="left"><div class="ur-model-directive-page ur-model-directive-link-page">
<p>The name of the angular-model "class" to use.</p>
</div></td>
</tr>
<tr class="odd">
<td align="left">href</td>
<td align="left"><a href="">string</a></td>
<td align="left"><div class="ur-model-directive-page ur-model-directive-link-page">
<p>Where should angular-model look for the API for this resource.</p>
</div></td>
</tr>
</tbody>
</table>
Example
-------
<html ng-app="myApp">
<head>
<title>My Posts Application</title>
<link rel="resource" name="Posts" href="/api/posts">