express-form-handler

A form handler for the Node.js framework: Express.js

 

- Why?
- Get Started
- Install
- Create a form
- The middleware
- Extend a form
- Go further
- Configuration
- Model Strategy
- Rules & Formats
- Contribute
- Changelog

Why?

Make the form hanlding easier by avoiding repetitive tasks such as fields validation or find the one element to update according to the id route parameter.

Define a form (fields, field format & validation rules, ...), process the form validation with a route middleware then use the req.form object into the next route middleware to check the form validity or get form values.

Extend a form with other forms.

Create your own formats and rules.

Attach a model to a form through a model strategy in order to automate data binding to it. When a :id parameter is present in the req.params object, form-handler will try to find the corresponding document into the database before update it.

Create a custom model strategy corresponding to your ODM / ORM.

Chose the way you want to process the validation: by the defined form's fields format and rules or by the model strategy validate() method.

Get Started

Install via npm

Run npm install --save express-form-handler@2.0.0-beta.5

Create a form file

``js
const formHandler = require('express-form-handler')
const MongooseStrategy = require('express-form-handler-mongoose')
const User = require('./models/user')

let form = formHandler.create([
{
name: 'username',
label: 'Username',
format: formHandler.format.string(),
rules: [
formHandler.rule.required(),
formHandler.rule.minlength(4)
]
},
{
name: 'password',
label: 'Password',
format: formHandler.format.string(),
rules: [
formHandler.rule.required(),
formHandler.rule.minlength(6)
]
},
{
name: 'passwordConfirm',
label: 'Confirm password',
format: formHandler.format.string(),
rules: [
formHandler.rule.required(),
formHandler.rule.equalsto('password')
]
}
])

form.config({
modelStrategy: new MongooseStrategy(User),
validationByModel: false
})

module.exports = exports = form

`

$3

- alpha - check if the string contains only letters (a-zA-Z).
- alphanumeric - check if the string contains only letters and numbers.
- date - check if the string is a date.
- email - check if the string is an email.
- float - check if the string is a float.
- int - check if the string is an integer.
- numeric - check if the string contains only numbers.
- url - check if the string is an URL.

$3

- equalsto - check if the field value match with the given field's label value.
- required - check if the field value exist and is not empty|false|null.
- custom - a custom function that must return a boolean and accept the field value as first argument
- minlength
- maxlength

Use the route middleware

Forms must be submitted by POST, PUT or PATCH method.

`js
const userForm = require('./user-form');

//...

app.post('/registration', userForm.process, function(req, res, next) {
if(!req.form.isValid) {
return next({ error: { status:400 } });
}

//else...
console.log(req.form.username);
console.log(req.form.password);
console.log(req.form.model);
});
`

Extend a form

`js
const formHandler = require('express-form-handler');
const userForm = require('./user-form');

module.exports = formHandler.create([
//...
]).extends(userForm);
`

Go further

Configuration

`js
form.config({
modelStrategy: new MongooseStrategy(User), // Or whatever strategy
validationByModel: false // true if you want to use the validate() method from the model if it has one.
})
`


Model Strategy

You can create your own model strategy by creating an object which extends the main strategy provided by this module: express-form-handler-strategy.

Rules & Formats

You can create your own field rule or field format by creating an object which extends the main rule or format object provided by this module: formHandler.FieldRule - formHandler.FieldFormat.

$3

`js
const Fieldrule = require('express-form-handler').FieldRule

class YourRule extends Fieldrule {
constructor (something) {
this.name = 'myRule' // Optional...
this.something = something
}

check (field) {
if (field.value !== this.something) {
this.error = The field ${field.label} ...
return false
}

return true
}
}
module.exports = exports = YourRule
`

$3

`js
const formHandler = require('express-form-handler');
const YourRule = require('./yourule')

let form = formHandler.create([
{
name: 'username',
label: 'Username',
format: formHandler.format.string(),
rules: [
formHandler.rule.required(),
formHandler.rule.minlength(4),
new YourRule(something)
]
},
// ...
])

// ...

`

$3

`js
const validator = require('validator')
const Fieldformat = require('express-form-handler').FieldFormat

class YourFormat extends FieldFormat {
constructor () {
this.name = 'myFormat' // Optional...
}

check (field) {
if (!validator.isBase64(field.value)) {
this.error = The field ${field.label} ...
return false
}

return true
}
}
module.exports = exports = YourFormat
`

$3

`js
const formHandler = require('express-form-handler');
const YourFormat = require('./yourformat')

let form = formHandler.create([
{
name: 'username',
label: 'Username',
format: new YourFormat(),
rules: [
formHandler.rule.required(),
formHandler.rule.minlength(4)
]
},
// ...
])

// ...

`

Contribute

All PR are welcome !
Feel free to open an issue if you found a bug or if you have an idea that can improve this package (new features, performance issues...).

Changelog

v2.0.0-beta

- Remove the duty to create a new Form instance.
- Add inheritance feature with extend()` method.

v0.3.1

- Fix custom error messages for constraint errors (equals to, required). I forgot to implement that :).
- Add tests for this.

v0.3.0

- Add custom error messages feature.
- Fix i18n error.
- If the i18n error was already used by your project and configured, on showing translated error messages, that overwrite your i18n configuration settings.
- Then, I removed i18n dependency for a simple require-dir on json files.
- Add common.js file to handle some 'magic values' through constants system.