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 [email protected]

Create a form file

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

formats supported (with node-validator help!)

• 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.

Form constraints supported

• 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.

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

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

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

Go further

Configuration

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.

Create a new field rule

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

Use your own field rule

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)
    ]
  }, 
  // ...
])

// ...

Create a new field format

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

Use your own field format

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

• TODO: handle array field (list, checkbox)
• Make model strategy and each strategies an external npm package
• Remove external stateless configuration to let form object handle it. It makes more sens to have a stateful configuration, and its easier to understand.
• fix bugs from alpha

v2.0.0-alpha.x

Rewrite the module in order to have a more flexible way to personalized its behaviors with:

• model strategies
• formats/rules strategies.

That means, if something is missing for you in this package, you can create a new model strategy or create a new field format or rule. juste inherit your object with the corresponding strategy object which are exposed at the entry point of the module.

v1.2.x

• Add model persitence

v1.1.3

• Minor fix: readme, error in test...

v1.1.1 & v1.1.2

• Important fix bug: no constraints checked in 1.1.0

v1.1.0

• Add the custom constraint
• Add support for array field value (checkbox, select (multiple)...)
• Add async dependencies

v1.0.0

• 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.