All Projects → bvaughn → forms-js

bvaughn / forms-js

Licence: Apache-2.0 license
Core forms-js library

Programming Languages

javascript
184084 projects - #8 most used programming language
typescript
32286 projects

forms-js Build Status Join the chat at https://gitter.im/forms-js/forms-js

Forms JS is a form validation library intended to provide a backbone for other, framework-specific libraries.

Overview

To use Forms JS for validation, begin by creating an instance of Form and providing it with validation rules and a form-data object.

var formsjsForm = new formsjs.Form();
formsjsForm.formData = { // Input fields should read/write data to this object.
  username: "bvaughn"    // Default values can be provided.
};
formsjsForm.validationService = { // Maps field-names to validation rules.
  username: {                     // It should mirror the structure of form-data.
    required: true,
    type: "string"
  }
};
formsjsForm.submitFunction = function() {
  // You provide this function.
  // It is responsible for submitting your form data and returning a Promise.
  // This Promise should resolve/reject based on the response you receive after submitting.
};

Next you should wire your form inputs (the view) up with the Form instance so it can validate your data. (Note that Forms JS doesn't provide any view elements, only validation.) Each web component/Angular directive/React component/whatever should register itself like so:

var attributeMetadata = formsjsForm.registerAttribute('username');

// AttributeMetadata defines an errorMessages Array.
// You should bind to it in your view as it is used to show validation errors.
attributeMetadata.errorMessages;

// AttributeMetadata exposes a method named validate().
// You should call it any time your view updates the field's value.
// It will (asynchronously) update the 'errorMessages' property.
attributeMetadata.validate();

You'll also want to override a form-submit event so that Form can require a valid state. If the current form-data is valid it will be submitted using the submitFunction you provided earlier.

var formElement = document.getElementById('yourForm');

// Angular/jQuery style
$(formElement).on("submit", function() {
  formsjsForm.submitIfValid();

  return false;
});

// Plain JavaScript
formElement.addEventListener("submit", function() {
  event.preventDefault();

  formsjsForm.submitIfValid();
}), false);

Installation

Forms JS is available on both Bower and NPM under the name forms-js. You can install the library like so:

bower install forms-js
npm install forms-js

Building from Source

First install the toolchain with NPM:

npm install

Now you can build source like so:

npm run build

And run tests like so:

npm run test:watch

Note that tests are run on built source so be sure to build first.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].