api.md

angular-model API documentation

model

function in module ur

Description

Main factory function for angular-model

Usage

model(name[, options]);

Parameters

Param	Type	Details
name	string	Name of the 'class', e.g. 'posts'
options (optional)	object	Config to initialise the model 'class' with. You can supply an object literal to configure your model here.

Returns

ur.model

instance of angular-model for the 'class' identified by 'name'

Example

yourApp.config(function(modelProvider) {
  modelProvider.model('posts', {
    // configuration options
    $instance: {
      // custom instance functions
    },
    $class: {
      // custom class functions
    },
    $collection: {
      // custom collection functions
    }
  });
});

$instance

object in module ur

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

object

Promise from an API request

Example

post.$delete();

$dirty()

Returns boolean - true if a model instance is unmodified, else false. Inverse of $pristine.

Returns

boolean

true if a model instance is modified, else false. Inverse of $pristine.

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

boolean

True if the identifier of this instance exists in the API

Example

if (post.$exists()) { console.log('It exists'); }

$hasRelated(name)

Does an instance have a relation of name name?

Parameters

Param	Type	Details
name	string	Name of the related property to check for

Returns

boolean

true if a $link to name exists on this instance

Example

if (post.$hasRelated('author')) { console.log('Post has an author'); }

$modified()

Returns a map of the properties that have been changed

Returns

object

Map of the fields that have been changed from the $pristine version

Example

console.log(post.$modified());

$pristine()

Returns boolean - false if a model instance is unmodified, else true. Inverse of $dirty.

Returns

boolean

true if a model instance is unmodified, else false. Inverse of $dirty.

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

object

Promise from the API

Example

console.log(post.links());

$reload()

Refresh an instance of a model from the API

Returns

object

Promise from an API request

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

Param	Type	Details
data (optional)	object	Data to save to this model instance. Defaults to the result of this.$modified()

Returns

object

Promise from an API request

Example

var post = model('posts').create({ name: 'some post' });
post.$save();

$class

object in module ur

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

Param	Type	Details
data (optional)	object	Configuration of the request that will be sent to your API
headers (optional)	object	Map of custom headers to send to your API

Returns

object

Promise from an API request

Example

model('posts').all().then(function(posts) {
  console.log(posts.length);
});
=> 4

create(data)

Creates an instance on of the model

Parameters

Param	Type	Details
data (optional)	object	Configuration of the instance that you are creating. Merged with any defaults specified when this model was declared.

Returns

object

angular-model instance

Example

var post = model('Posts').create({});

first(data)

Retrieve a single post instances from the API

Parameters

Param	Type	Details
data (optional)	object	Configuration of the request that will be sent to your API

Returns

object

Promise from an API request

Example

model('posts').first({name: 'some post'}).then(function(post) {
  console.log(post._id);
});
=> 42

$collection

object in module ur

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

Param	Type	Details
object	object	Object to persist data onto
data (optional)	object	Data to persist onto the object

Returns

boolean

true if a $link to name exists on this instance

remove(index)

Find index and delete it from the API, then remove it from the collection

Parameters

Param	Type	Details
index	numberobject	Either the index of the item in the collection to remove, or the object itself, which will be searched for in the collection

Returns

object

Promise from the API

$get

function in module ur

Description

Get the model class factory

Usage

$get($http, $parse, $q);

Parameters

Param	Type	Details
$http	object	https://docs.angularjs.org/api/ng/service/$http
$parse	object	https://docs.angularjs.org/api/ng/service/$parse
$q	object	https://docs.angularjs.org/api/ng/service/$q

Returns

object

The model service

link

directive in module ur.model

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:

<link
       rel="{string}"
       name="{string}"
       href="{string}">
</link>

Parameters

Param	Type	Details
rel	string	Must be equal to "resource".
name	string	The name of the angular-model "class" to use.
href	string	Where should angular-model look for the API for this resource.

Example

<html ng-app="myApp">
<head>
    <title>My Posts Application</title>
    <link rel="resource" name="Posts" href="/api/posts">