Fleshed out the resource guide. #28

Author: jmdobry

Gruntfile.js

@@ -207,7 +207,8 @@ module.exports = function (grunt) {
 								index: 1,
 								overview: 2,
 								basic: 3,
-								advanced: 4
+								advanced: 4,
+								lifecycle: 5
 							}
 						},
 						{

guide/overview/overview.doc

@@ -137,13 +137,13 @@ $scope.$watch(function () {
 }, function (lastModifiedTimestamp) {
 	// When this callback is executed, it means that the data store thinks the item changed
 
-	// Retrieve the updated item from the server
+	// Retrieve the updated item from the data store's cache
 	$scope.document = DS.get('document', 45);
 });
 ```
 
-When the app starts up the calls to `lastModified()` and `get()` will both returned undefined, because the item isn't in
-the data store. If we insert `DS.find('document', 45);` right above the `$watch` function, the data store will make an
+When the app starts up, the calls to `lastModified()` and `get()` will both returned undefined, because the item isn't in
+the data store yet. If we insert the statement: `DS.find('document', 45);` right above the `$watch` function, the data store will make an
 AJAX request for that item. When the item returns from the server, the last modified timestamp for that item will change
 from `undefined` to something like `1388809123529`, causing the `get()` call inside the `$watch` callback function to be
 executed, retrieving the item from the data store and putting it on the `$scope`.
@@ -159,12 +159,12 @@ deleted. Example:
 
 This document is in the data store for both users: `{ title: 'How to Cook', id: 45 }`
 
-User #1
+User #1 (asynchronous)
 ```js
 DS.destroy('document', 45).then(function (id) {...}); // sends DELETE request to the server
 ```
 
-User #2 receives notification from the server that document 45 was deleted
+User #2 receives notification from the server that document 45 was deleted and synchronously ejects it from the data store.
 ```js
 DS.eject('document', 45); // synchronously eject document from the store
 ```
@@ -180,7 +180,7 @@ See the [API](/documentation/api/api/index) for more information.
 @description
 
 Angular-data ships with a number of asynchronous methods that facilitate communication between the data store and the
-persistence layer. These methods include the basic CRUD operations and wrappers for the `$http` service.
+persistence layer. These methods cover the basic CRUD operations.
 
 The asynchronous methods return Promises produced by Angular's `$q` service.
 
@@ -196,15 +196,17 @@ DS.find('document', 45).then(function (document) {
 	DS.get('document', 45); // { title: 'How to Cook', id: 45 }
 });
 
-DS.get('document', 45); // undefined
+DS.get('document', 45); // still undefined, because the find operation has not completed yet
 ```
 
 #### Another example
 
 ```js
-DS.get('document', 45); // { title: 'How to Cook', id: 45 }
+var document = DS.get('document', 45); // { title: 'How to Cook', id: 45 }
 
-DS.update('document', 45, { title: 'How NOT to Cook' }).then(function (document) {
+document.title = 'How NOT to cook';
+
+DS.save('document', 45).then(function (document) {
 	document; // { title: 'How NOT to Cook', id: 45 }
 
 	// document 45 in the store has been updated
@@ -214,6 +216,4 @@ DS.update('document', 45, { title: 'How NOT to Cook' }).then(function (document)
 DS.get('document', 45); // { title: 'How to Cook', id: 45 }
 ```
 
-By using the data store's `update()` operation, the data store is able to update the last modified timestamp of the item
-so any code that's `$watch`ing the item can be notified of updates. If you directly modify attributes of items in the
-data store, the data store will not pick up on those updates.
+See the [API](/documentation/api/api/index) for more information.

guide/resource/resource.doc

@@ -5,18 +5,11 @@
 
 # Resource Guide
 
-A _resource_ is the data and meta data associated with a particular RESTful endpoint.
-
-You define _resources_ and register them with the data store. A _resource definition_ tells angular-data
-about a particular _resource_, like what its root endpoint is and which attribute refers to the primary key of the
-resource. A _resource definition_ can also specify validation functions to be executed before create and update
-operations.
-
-See [defineResource(definition)](/documentation/api/api/DS.sync_methods:defineResource) for detailed API information.
+<page-list></page-list>
 
 @doc overview
 @id overview
-@name Resource Guide
+@name Overview
 @description
 
 A _resource_ is the data and meta data associated with a particular RESTful endpoint.
@@ -42,9 +35,9 @@ DS.defineResource('document');
 With this definition the data store assumes the following:
 
 - Resource will be referred to as `"document"`
-- The RESTful endpoint for this resource is `"/document"`
-- The `idAttribute` (attribute that specifies the primary key) is `"id"`
-- This resource does not use any validation
+- The RESTful endpoint for this resource is `DSProvider.defaults.baseUrl + "/document"`
+- The primary key is specified by the `"id"` property (or whatever is specified by `DSProvider.defaults.idAttribute`)
+- This resource has no custom lifecycle hooks (unless `DSProvider.defaults` has some lifecycle hooks defined)
 
 @doc overview
 @id advanced
@@ -58,6 +51,7 @@ DS.defineResource({
 	name: 'document',
 	idAttribute: '_id',
 	endpoint: 'documents',
+	baseUrl: 'https://example.com/api',
 	validate: function (attrs, cb) {
 		if (!angular.isObject(attrs) {
 			cb('Must be an object!');
@@ -71,6 +65,105 @@ DS.defineResource({
 With this definition the data store understands the following:
 
 - Resource will be referred to as `"document"`
-- The RESTful endpoint for this resource is `"/documents"`
-- The `idAttribute` (attribute that specifies the primary key) is `"_id"`
-- Before create/save operations the provided `validate` function must pass
+- The RESTful endpoint for this resource is `"https://example.com/api/documents"`
+- The primary key is specified by the `"_id"` property
+- Before create/save operations, the provided `validate` function is executed (and any lifecycle hooks defined in `DSProvider.defaults`)
+
+See [DS.defineResource](/documentation/api/api/DS.sync_methods:defineResource) for the full resource definition specification.
+
+@doc overview
+@id lifecycle
+@name Model Lifecycle Hooks
+@description
+
+The following asynchronous operations support a model lifecycle:
+
+### DS.create()
+
+- `beforeValidate` - Default: `noop`
+- `validate` - Default: `noop`
+- `afterValidate` - Default: `noop`
+- `beforeCreate` - Default: `noop`
+- `create` - Implementation provided by adapter
+- `afterCreate` - Default: `noop`
+
+### DS.save()
+
+- `beforeValidate` - Default: `noop`
+- `validate` - Default: `noop`
+- `afterValidate` - Default: `noop`
+- `beforeUpdate` - Default: `noop`
+- `save` - Implementation provided by adapter
+- `afterUpdate` - Default: `noop`
+
+### DS.destroy()
+
+- `beforeValidate` - Default: `noop`
+- `validate` - Default: `noop`
+- `afterValidate` - Default: `noop`
+- `beforeDestroy` - Default: `noop`
+- `destroy` - Implementation provided by adapter
+- `afterDestroy` - Default: `noop`
+
+### Define lifecycle hooks
+All lifecycle hooks will be executed according to the following signature:
+```js
+exampleHook(resourceName, attrs, cb) {...}
+```
+
+`resourceName` is the name of the resource that `attrs` belong to, which is a reference to the object on which `create`,
+ `save` or `destroy` was originally called.
+
+`cb` is the callback function to be executed when the lifecycle hook is done. `cb` follows the Node style of callbacks,
+where the first passed argument will be the error, if any, and the second is the result. In the case of these lifecycle
+functions, `attrs` _is_ the result. So, `attrs` is available for inspection and/or modification, and then should be passed
+to `cb`. For example:
+
+```js
+validate(resourceName, attrs, cb) {
+	console.log('hmm, looks good to me!');
+	cb(null, attrs); // no error
+}
+```
+
+```js
+validate(resourceName, attrs, cb) {
+	console.log('something went wrong!');
+	cb('some error'); // error!
+}
+```
+
+The lifecycle will be aborted if `cb` receives an error or an error is thrown.
+
+Finally, model lifecycle hooks can be defined at the global level or per-resource. For example:
+
+```js
+angular.module('myApp', ['angular-data.DS'])
+	.config(function (DSProvider) {
+
+		// Global definition
+		DSProvider.defaults.beforeCreate = function (resourceName, attrs, cb) {
+			console.log('Global beforeCreate');
+			cb(null, attrs);
+		};
+
+	})
+	.run(function (DS) {
+
+		DS.defineResource({
+			name: 'post',
+
+			// Local definition, overrides the global definition
+			beforeCreate = function (resourceName, attrs, cb) {
+				console.log('beforeCreate defined for ' + resourceName);
+				cb(null, attrs);
+			}
+		});
+
+		// Will use the global definition
+		DS.defineResource({
+			name: 'comment'
+		});
+
+	});
+```