angular-model
v0.6.0
Published
Simple HATEOS-oriented persistence module for AngularJS.
Downloads
52
Readme
Angular Model
Simple HATEOS-oriented persistence module for AngularJS.
Angular Model is a module that provides a simple way to bind client-side domain logic to JSON-based API resources.
By sticking to hypermedia design principles, Angular Model allows you to implement client applications that are cleanly decoupled from your server architecture.
Basic Usage
In your AngularJS application, include the JavaScript:
// your specific paths may vary
<script src="node_modules/radify/angular-model.js"></script>
In your app configuration, state a dependency on Angular Model:
angular.module('myApp', [
'ur.model'
]);
API documentation
The source code is documented using the ngdoc standard using gulp-ngdocs. A markdown version is browseable at /docs.
To generate documentation in HTML, run:
gulp ngdocs
This will output docs into the build/docs
directory. Then, using a server like ws
, start a local web server:
cd build/docs
npm install -g ws
ws
Then, you should be able to browse to http://localhost:8000 to view the API documentation for angular-model.
Configuration
Here is a quick reference guide to all the configuration settings you can pass to the model() constructor, which is documented in full in the API documentation. Each one is then described in detail later in this document, and in full in the source code in the src
directory.
Setting | Type | Description ------- | ---- | ----------- url | string | API url that this model maps to defaults | object literal | Default values of attributes of instances of this model. Similar to properties in OOP. $instance | object literal | Instance methods available on each instance of this model. $class | object literal | Class methods available on this model. Similar to static methods in OOP. $collection | object literal | Collection
Defaults
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
/**
* @ngdoc object
* @name yourApp.posts.defaults
* @description
* Configure the default attributes for instances of posts.
*
* This is similar to an OOP class, which has attributes with defaults, e.g. "public string foo = 'bar';"
*/
defaults: {
name: '', // The name of the post
published: false, // Whether the post has been released to the general public
body: '', // Body text of this post
logo: null, // The logo to show for this post
author: 'John Doe'// Who wrote the post?
}
});
});
Here is an example of how the defaults get used:
var post = model('posts').create({});
console.log(post.author);
=> John Doe
Creating instances of your model
You can use angular-model ad-hoc to construct object instances:
// From defaults
var post = model('posts').create({});
// Specifying fields
var post = model('posts').create({
name: 'some post',
body: "body of some body, it's just some body, you know?",
author: 'Steve Davis'
});
console.log(post.author);
=> Steve Davis
Instance Methods
angular-model instances have instance methods, similar to objects in the OOP world.
Default instance methods
The following methods are available to every angular-model instance.
Function | Description
------- | -----------
$save | Persist an instance to the API
$delete | Tell the API to delete an instance
$reload | Refresh an instance of a model from the API
$revert | Reset the model to the state it was originally in when you first got it from the API
$exists | Checks whether an object exists in the API, based on whether it has an identity URL.
$dirty | Returns boolean - true if a model instance has been modified, else false. Opposite of $pristine.
$pristine | Returns boolean - true if a model instance has unmodified, else false. Opposite of $dirty.
$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.
$modified | Returns a map of the properties that have been changed
$hasRelated | Does an instance have a relation of name name
?
You can see full details of these methods in the API documentation.
Custom instance methods
angular-model allows you to define instance methods on instances. This is similar to adding methods by extending a base class in the OOP world.
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
// ...
/**
* @ngdoc object
* @name yourApp.posts.$instance
* @description
* Instance methods that are callable on any individual instance of a post
*/
$instance: {
/**
* @ngdoc function
* @name yourApp.posts.$logo
* @description
* If this post instance has a logo, return it, otherwise return a default string
*
* @return string Either the logo for this post, or a default logo
*/
$logo: function() {
return this.logo || '/logos/default.png';.
}
}
});
});
Example:
var post = model('Posts').create({
logo: 'foo.png'
});
console.log(post.$logo());
=> foo.png
Class methods
Default class methods
The following methods are available statically to angular-model:
Function | Description
-------- | -----------
all | Make a request to the API, based on the url
configuration setting
first | Given a query, get the first model instance from the API
create | Create a new instance of the model. Defaults come from the defaults
configuration setting.
You can see full details of these methods in the API documentation.
Custom class methods
angular-model allows you to define class methods on instances. This is similar to static methods in the OOP world.
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
// ...
/**
* @ngdoc object
* @name yourApp.posts.$class
* @description
* Class methods that are callable on the posts class, or any instance thereof. These
* behave similarly to static methods in OOP languages.
*/
$class: {
/**
* @ngdoc function
* @name yourApp.posts.roles
* @description
* Get an array of valid post types.
*
* @return array The valid types that a post can have. Array of strings
*/
types: function() {
return ['announcement', 'article']
}
}
});
});
Example:
console.log(model('Posts').types());
=> ['announcement', 'article']
Collection methods
You can use collection methods as well, so you can deal with a bunch of instances together. This allows you to have powerful and expressive methods on collections.
Default collection methods
The following methods are available statically to angular-model:
Function | Description
-------- | -----------
add | Saves the object
with data
remove | Find index
and delete it from the API, then remove it from the collection
You can see full details of these methods in the API documentation.
Custom collection methods
yourApp.config(function(modelProvider) {
modelProvider.model('posts', {
// ...
/**
* @ngdoc object
* @name yourApp.posts.$collection
* @description
* Methods that apply to a collection of posts together
*/
$collection: {
/**
* @ngdoc function
* @name yourApp.posts.$hasArchived
* @description
* Operates on a collection of posts and determines whether any of them are archived
*
* @requires _ Lodash library is used to search the collection
*
* @return string Either the logo for this post, or a default logo
*/
$hasArchived: function() {
return !angular.isUndefined(_.find(this, { archived: true }));
}
}
});
});
Example:
model('Posts').all().then(function(posts) {
if (posts.$hasArchived()) {
// Some of the posts in the collection are archived
}
});
Running unit tests
Install the test runner with npm:
npm install
You can then run the tests with gulp:
gulp
Tests can be found in the spec
directory of this project.
Related
You may wish to use Angular Scaffold, which is is a collection of convenience wrappers around angular-model collections. Really helpful for building your AngularJS application with angular-model.