From 7a996fbe0cf53440c3782a156794d72fb76eceb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Mon, 6 Jan 2014 19:01:00 +0100 Subject: [PATCH] Describe loopback.ValidationError in API docs. --- docs/api-model.md | 219 +++++++++++++++++++++++++++++----------------- 1 file changed, 139 insertions(+), 80 deletions(-) diff --git a/docs/api-model.md b/docs/api-model.md index 15008a7d..a7128605 100644 --- 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)).