form-validate

A validation module for nodejs and express. It aims to give a convenient way to validate incoming POST data (which is the most common) and be as flexible as possible. This module is in development - feel free to contribute if you feel like it :)

npm install form-validate
7 downloads in the last week
27 downloads in the last month

node-form-validate

A validation module for nodejs and express. It aims to give a convenient way to validate incoming POST data (which is the most common) and be as flexible as possible. This module is in development - feel free to contribute if you feel like it :)

Installation

npm install form-validate

Setting up form-validate with Express

In order to use the req.Validator object and to access view helpers you have to register the form-validate middleware with express.

var express = require('express'),
              validate = require('form-validate');

// ...Your express initialization logic...


app.use(express.logger('dev'));
app.use(express.bodyParser());
app.use(express.methodOverride());

// ...

var validationConfig = {
    //You can configure certain aspects of the validation module
};
app.use(validate(app, validationConfig));

app.use(app.router);
app.use(express.static(path.join(__dirname, 'public')));

// ... Create http server

Configuration

You can configure the behaviour of the form-validate module by passing options when initializing the middleware:

var options = {
    //You can configure certain aspects of the validation module
};
app.use(validate(app, options));

Options

Options Type Default Description
i18n object
i18n: {
    locales:['en', 'de'],
    defaultLocale: 'en',
    cookie: null,
    directory: ...,
    updateFiles: true,
    indent: "\t",
    extension: '.json'
}
form-validate uses the i18n (https://github.com/mashpie/i18n-node) module to translate the error messages.
You can configure the i18n module using this option.
escapeHTML boolean true If this is true every value will be html escaped when using Validator.getValue()
stripTags boolean true If this is true every value will be stripped from html tags when using Validator.getValue()

Express Usage Example

Using form-validation in an express context is pretty straight-forward:

app.post('/register', function(res, res) {
    /*
     * You call req.Validator.validate for every field you want to validate. You
     * can chain up the validate calls if you want (like in this example).
     * You can optionally pass the field name as the 2nd parameter to
     * place another name in the error message if you want to (for example to translate 
     * fieldnames).
     */
    req.Validator.validate('username', i18n.t('user.displayName'), {
            /*
             * Add as many validators as you want here. To see what 
             * validators are supported have a look in the form-validation/lib/rules/ folder
             */
            length: {
                min: 3,
                max: 256
            },
            /*
             * This validator name must be unique and not already used by form-validation (e.g. length, required etc.)
             */
            isUnique: function(field, fieldName, value, fn){
                /*
                 * This is a custom validation callback. You have to
                 * call fn() with an array containing the error 
                 * message for this custom validation. If the array
                 * is empty, the validation is considered a success.
                 */
                 var errors = [];
                 if(value != 'unique')
                 {
                    errors.push('this field is not unique');
                 }
                 fn(errors); 
            }
        })
        .filter('username', {
            trim: true
        })
        .validate('password', {
            length: {
                min: 4,
                max: 64
            }
        })
        .filter('password', {
            stripTags: false,
            escapeHTML: false
        });

    /*
     * Call the "getErrors" method to start the validation
     */
    req.Validator.getErrors(function(errors){
        /*
         * ... Your further rendering logic. e.g. res.render('view', { errors: errors });
         */
    });
});

Validators

Validators are the core functionality of node-form-validate. Input data can be validated to see if they meet certain criteria. If they dont match, an error message will be generated. They can be added by using req.Validator.validate()

Validator Example Configuration
required required: true
length length: { min: 5, max: 50 }
alpha alpha: true
alphaNumeric alphaNumeric: true
numeric numeric: true
numeric: { allowNegative: true } // also allow negative values
integer integer: true
integer: { allowNegative: true } // also allow negative values
decimal decimal: true
decimal: { allowNegative: true } // also allow negative values
between between: { min: 10, max: 15 }
email email: true
This method of testing is not recommended. You should allow all Email addresses and validate it by sending an email to the given address.

Filters

Filters are applied before the input data is validated. Filters can parse the incoming data and prepare it for validation or database input. They can be added by using req.Validator.filter()

Filter Example Configuration
trim trim: true
toInt toInt: true
toFloat toFloat: true
toBoolean toBoolean: true
hash
i18n: {
hash: {
    algorithm: 'sha1',
    outputEncoding: 'base64' // 'hex', 'binary' or 'base64'
}
                
To get a list of all supported hash algorithms on your installation, see: http://nodejs.org/api/crypto.html#crypto_crypto_gethashes
escapeHTML Explicitly enable HTML escaping (enabled by default):
escapeHTML: true
Disable HTML escaping:
escapeHTML: false
stripTags Explicitly enable stripping of HTML tags (enabled by default):
stripTags: true
Disable stripping of HTML tags:
stripTags: false

Getting all Errors

To get validation errors simply call the asynchronous Validator.getErrors(fn) method and provide a callback which gets called when all validations have been completed. The callback gets provided with an array containing all errors which resulted from the validation process. Example:

app.post('/register', function(res, res) {

    // ... Validation logic ... 

    /*
     * Call the "getErrors" method to start the validation
     */
    req.Validator.getErrors(function(errors){
        /*
         * ... Your further rendering logic. e.g. res.render('view', { errors: errors });
         */
    });
});

View Helpers

Warning: In order to these view helpers to work Validator.getErrors() has to be called before the rendering took place.

The local variable Validator is available in all express views.


/**
 * Returns the sanitized value of <code>fieldName</code> which ran through all
 * filters (if any)
 */
Validator.getValue(fieldName)

/**
 * Returns all errors for this field as an array
 */
Validator.getFieldErrors(fieldName)

/**
 * Returns true if this field has any error. You can use this to give the
 * field a certain class if an error occured
 */
Validator.hasErrors(fieldName)
Jade Usage example

form(action='/login', method='post')
    div(class=Validator.hasError('username') ? 'has-error' : '')
        label(for='username')=Username
        input#username(type='text', name='username', value=Validator.getValue('username'))

    div(class=Validator.hasError('password') ? 'has-error' : '')
        label(for='password')=Password
        input#password(type='text', name='password', value=Validator.getValue('password'))

The MIT License

Copyright (c) 2013 André Eckardt (http://github.com/korve, http://mindpress.de)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

npm loves you