Merge pull request #121 from strongloop/feature/validation-error-apidocs

Describe `loopback.ValidationError` in API docs.
2014-01-13 08:30:59 -08:00 · 2014-01-13 08:30:59 -08:00 · 8040f2dc60
parent c461ac821e 7a996fbe0c
commit 8040f2dc60
1 changed files with 139 additions and 80 deletions
--- a/docs/api-model.md
+++ b/docs/api-model.md
@ -51,86 +51,6 @@ User.attachTo(oracle);
    
 **Note:** until a model is attached to a data source it will **not** have any **attached methods**.

-### Model.validatesFormatOf(property, options)
-
-Require a model to include a property that matches the given format.
-
-```js
-User.validatesFormat('name', {with: /\w+/});
-```
-
-### Model.validatesPresenceOf(properties...)
-
-Require a model to include a property to be considered valid.
-
-```js
-User.validatesPresenceOf('first', 'last', 'age');
-```
-
-### Model.validatesLengthOf(property, options)
-
-Require a property length to be within a specified range.
-
-```js
-User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}});
-```
-
-### Model.validatesInclusionOf(property, options)
-
-Require a value for `property` to be in the specified array.
-
-```js
-User.validatesInclusionOf('gender', {in: ['male', 'female']});
-```
-
-### Model.validatesExclusionOf(property, options)
-
-Require a value for `property` to not exist in the specified array.
-
-```js
-User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']});
-```
-
-### Model.validatesNumericalityOf(property, options)
-
-Require a value for `property` to be a specific type of `Number`.
-
-```js
-User.validatesNumericalityOf('age', {int: true});
-```
-
-### Model.validatesUniquenessOf(property, options)
-
-Ensure the value for `property` is unique in the collection of models.
-
-```js
-User.validatesUniquenessOf('email', {message: 'email is not unique'});
-```
-
-**Note:** not available for all [connectors](#connectors).
-
-Currently supported in these connectors:
-
- - [In Memory](#memory-connector)
- - [Oracle](http://github.com/strongloop/loopback-connector-oracle)
- - [MongoDB](http://github.com/strongloop/loopback-connector-mongodb)
-
-### myModel.isValid()
-
-Validate the model instance.
-
-```js
-user.isValid(function (valid) {
-    if (!valid) {
-        console.log(user.errors);
-        // => hash of errors
-        // => {
-        // =>   username: [errmessage, errmessage, ...],
-        // =>   email: ...
-        // => }    
-    }
-});
-```
 ## Properties

 ### Model.properties
@ -523,6 +443,145 @@ appearing in many groups, you could declare the models this way,
    user.groups.remove(group, callback); // remove the user from the group
 ```
    
+## Validations
+
+### Model.validatesFormatOf(property, options)
+
+Require a model to include a property that matches the given format.
+
+```js
+User.validatesFormat('name', {with: /\w+/});
+```
+
+### Model.validatesPresenceOf(properties...)
+
+Require a model to include a property to be considered valid.
+
+```js
+User.validatesPresenceOf('first', 'last', 'age');
+```
+
+### Model.validatesLengthOf(property, options)
+
+Require a property length to be within a specified range.
+
+```js
+User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}});
+```
+
+### Model.validatesInclusionOf(property, options)
+
+Require a value for `property` to be in the specified array.
+
+```js
+User.validatesInclusionOf('gender', {in: ['male', 'female']});
+```
+
+### Model.validatesExclusionOf(property, options)
+
+Require a value for `property` to not exist in the specified array.
+
+```js
+User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']});
+```
+
+### Model.validatesNumericalityOf(property, options)
+
+Require a value for `property` to be a specific type of `Number`.
+
+```js
+User.validatesNumericalityOf('age', {int: true});
+```
+
+### Model.validatesUniquenessOf(property, options)
+
+Ensure the value for `property` is unique in the collection of models.
+
+```js
+User.validatesUniquenessOf('email', {message: 'email is not unique'});
+```
+
+**Note:** not available for all [connectors](#connectors).
+
+Currently supported in these connectors:
+
+ - [In Memory](#memory-connector)
+ - [Oracle](http://github.com/strongloop/loopback-connector-oracle)
+ - [MongoDB](http://github.com/strongloop/loopback-connector-mongodb)
+
+### myModel.isValid()
+
+Validate the model instance.
+
+```js
+user.isValid(function (valid) {
+    if (!valid) {
+        console.log(user.errors);
+        // => hash of errors
+        // => {
+        // =>   username: [errmessage, errmessage, ...],
+        // =>   email: ...
+        // => }
+    }
+});
+```
+
+### loopback.ValidationError
+
+`ValidationError` is raised when the application attempts to save an invalid
+model instance.
+
+Example:
+
+```js
+{
+  "name": "ValidationError",
+  "status": 422,
+  "message": "The Model instance is not valid. \
+     See `details` property of the error object for more info.",
+  "statusCode": 422,
+  "details": {
+    "context": "user",
+    "codes": {
+      "password": [
+        "presence"
+      ],
+      "email": [
+        "uniqueness"
+      ]
+    },
+    "messages": {
+      "password": [
+        "can't be blank"
+      ],
+      "email": [
+        "Email already exists"
+      ]
+    }
+  },
+}
+```
+
+You might run into situations where you need to raise a validation error
+yourself, for example in a "before" hook or a custom model method.
+
+```js
+MyModel.prototype.preflight = function(changes, callback) {
+  // Update properties, do not save to db
+  for (var key in changes) {
+    model[key] = changes[key];
+  }
+
+  if (model.isValid()) {
+    return callback(null, { success: true });
+  }
+
+  // This line shows how to create a ValidationError
+  err = new ValidationError(model);
+  callback(err);
+}
+```
+
 ## Shared methods

 Any static or instance method can be decorated as `shared`. These methods are exposed over the provided transport (eg. [loopback.rest](#rest)).