Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukeed/formee
A tiny (532B) library for handling <form> elements.
https://github.com/lukeed/formee
Last synced: 2 days ago
JSON representation
A tiny (532B) library for handling <form> elements.
- Host: GitHub
- URL: https://github.com/lukeed/formee
- Owner: lukeed
- License: mit
- Created: 2018-12-29T08:40:34.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2019-01-17T22:55:29.000Z (almost 6 years ago)
- Last Synced: 2024-10-01T07:46:25.820Z (about 1 month ago)
- Language: JavaScript
- Homepage: https://codepen.io/lukeed/pen/dwKWVa
- Size: 50.8 KB
- Stars: 441
- Watchers: 6
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
- awesome-list - formee
README
A tiny (532B) library for handling <form> elements
## Features
* Includes `serialize` and `validation` methods
* Compatible with any UI library
* Fully [tree-shakeable](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking)
Additionally, this module is delivered as:
* **ES Module**: [`dist/formee.mjs`](https://unpkg.com/formee/dist/formee.mjs)
* **CommonJS**: [`dist/formee.js`](https://unpkg.com/formee/dist/formee.js)
* **UMD**: [`dist/formee.min.js`](https://unpkg.com/formee)
## Install
```
$ npm install --save formee
```
## Usage
> :wave: [_View a full demo on CodePen_](https://codepen.io/lukeed/pen/dwKWVa)
```html
Register
Register
```
```js
const { validate } = require('formee');
const myForm = document.querySelector('#foo');
const myRules = {
// RegExp rule
email: /.+\@.+\..+/,
// Function, with custom error messages
password(val) {
if (!val) return 'Required';
return val.length >= 8 || 'Must be at least 8 characters';
},
// Function, comparing to other value
confirm(val, data) {
if (!val) return 'Required';
return val === data.password || 'Must match your password';
}
};
myForm.onsubmit = function (ev) {
ev.preventDefault();
let errors = validate(myForm, myRules);
if (myForm.isValid) return alert('Success!');
for (let k in errors) {
// TODO: Render errors manually
// with {insert favorite UI lib here}
console.log(`My rule & element's name: ${k}`);
console.log('> Error message:', errors[k] || 'Required');
console.log('> My form element(s):', myForm.elements[k]);
}
};
```
## API
### formee.serialize(form)
Return: `Object`
Serializes a `` into a data object.
> **Important:** Any inputs that are unnamed, disabled, or are of `type=file|reset|submit|button` will be ignored.
#### form
Type: `HTMLFormElement`
The `` element to evaluate.
### formee.validate(form, rules, toCheck)
Return: `Object`
Validates a `` according to its `rules`.
To check an individual input, you may pass its name as the `toCheck` value.
> **Important:** The `rules` key names must match `form.elements`' names~!
Returns an Object of errors, whose keys are the failing `rules` keys (and the `name=""`s of failing elements) and whose values are your error messages (if provided) else `false`.
Additionally, the `` and _each of its elements_ will receive a new `isValid` property with a `Boolean` value.
For example:
```js
let myForm = document.querySelector('#myform');
let errors = formee.validate(myForm, { ... });
if (!myForm.isValid) {
let i=0, item;
for (; i < myForm.elements; i++) {
item = myForm.elements[i];
console.log(`${item.name} – Am I valid?`, item.isValid);
item.isValid || console.log('>> my error message:', errors[item.name]);
}
}
```
#### form
Type: `HTMLFormElement`
The `` element to validate.
#### rules
Type: `Object`
An object of rules for your form's inputs.
> **Important:** The key names must match a `` element's `name=""` attribute!
The form values will be serialized before reaching your rule(s). (see [`serialize`](#formeeserializeform))
For example, a `select[multiple]` may present its value as `undefined`, a String, or an Array of Strings.
Each rule:
* May be a `RegExp` or a `Function`
* Must return `false` or an error message (`String`) if invalid
* Otherwise, must return `true` if valid
Your `Function`-type rules will receive the corresponding input's value _and_ the entire data object.
```js
validate(form, {
password(val, data) {
if (!val) return 'Required';
if (val.length < 8) return 'Must be at least 8 characters';
if (val !== data.confirmPassword) return 'Please confirm your password!';
return true; // all good homie
}
});
```
#### toCheck
Type: `String`
Default: `undefined`
If set, ***only*** the corresponding form element (with `name={toCheck}`) will be validated.
When unset (default), all form elements will be validated.
> **Important:** The value must match a key within `rules` and a `name=""` attribute for one of ``'s elements.
### formee.bind(form, options)
Return: `HTMLFormElement`
Attaches [`serialize`](#formeeserializeform) and [`validate`](#formeevalidateform-rules-tocheck) methods to the `` element.
Also registers a custom `onsubmit` handler that will:
1) `event.preventDefault` the `"submit"` event
2) Perform [`validate`](#formeevalidateform-rules-tocheck), then
a) If all validation passed, call your `options.onSubmit` function
b) Otherwise, call your `options.onError` function
```js
let myForm = document.querySelector('#myform');
formee.bind(myForm, {
rules: {
// ...
},
onSubmit(ev) {
// validation passed!
console.log(ev.errors); //=> {}
console.log(ev.target === myForm); //=> true
console.log(myForm.isValid, myForm.errors); //=> true {}
},
onError(ev) {
// validation failed!
console.log(ev.errors); //=> { ... }
console.log(ev.target === myForm); //=> true
console.log(myForm.isValid, myForm.errors); //=> false { ... }
}
});
// Now available:
// ---
form.serialize();
form.validate(/* specific item? */);
```
#### form
Type: `HTMLFormElement`
The `` element to evaluate.
#### options.rules
Type: `Object`
Passed directly to `validate` – see [`rules`](#rules).
#### options.onSubmit
Type: `Function`
Required: `true`
The callback to run when validation succeeds fails.
It receives the original `event` – however, a `event.errors` property is added, containing the output from [`validate`](#formeevalidateform-rules-tocheck).
#### options.onError
Type: `Function`
Required: `true`
The callback to run when validation fails.
It receives the original `event` – however, a `event.errors` property is added, containing the output from [`validate`](#formeevalidateform-rules-tocheck).
## License
MIT © [Luke Edwards](https://lukeed.com)