Core forms-js library
APACHE-2.0 License
Forms JS is a form validation library intended to provide a backbone for other, framework-specific libraries.
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);
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
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.