formdb
A simple HTML form data API with zero dependencies.
What is this?
Have you ever wanted to treat an HTML form as a data store? Well, I have, and everything else that I came across had big dependencies like jQuery. formdb provides a simple API for getting and setting data in a plain old HTML form using plain old DOM JavaScript.
An Example
Name: Age: young old prefer not to say Skills: JavaScript Python Ruby
Note: formdb only pays attention to form inputs with a name
attribute. All of your inputs should have name attributes anyway. :trollface:
Form objects
Form objects created with the formdb.Form()
constructor can get and set data in their respective HTML form.
formdb.Form(selector)
Create a new Form object bound to the HTML form identified by CSS selector
. This works with or without the new
keyword:
var form = formdb;// orvar form = selector;
form.get(key)
Get the value of one or more fields with the name attribute equal to key
. The returned value may differ depending on the type of the inputs:
checkbox
inputs (<input type="checkbox" name>
):- if there's only one checked, the value will be the input's value iff it is checked (
true
if it has no value) - if there are more than one checkbox checked, the value will be an array of the the checked inputs' values
- if there's only one checked, the value will be the input's value iff it is checked (
radio
inputs (<input type="radio" name>
):- like checkboxes, the value will be undefined if the input is not checked; otherwise, the value will be the inputs value or
true
if it has none
- like checkboxes, the value will be undefined if the input is not checked; otherwise, the value will be the inputs value or
select-one
inputs (<select name>
):- Because select inputs without the
multiple
attribute cannot be unset, the value will always be the value of the input's selected option.
- Because select inputs without the
select-multiple
inputs (<select multiple name>
):- Multi-select inputs will always be expressed as an array of option values. If no options are selected, the value will be an empty array.
- all other inputs are assumed to have a
value
property which is returned as-is.
form.set(key, value)
Set the value of one or more fields with the name attribute equal to key
. The rules for form.get() apply here, with one notable exception:
checkbox
inputs (<input type="checkbox" name>
):- If there are multiple checkboxes with the same name and only one is checked, the return value will be a string literal (the value of the checked box).
form.getData()
Returns an object with key/value pairs for each of the uniquely named inputs in the form.
form.setData(data)
Sets input values for each key in the object data
according to the rules described in form.set().
form.on(event, callback)
Listen for events on the form. These ones are handled specially:
change
: this adds achange
listener to the underlying form element and callscallback(data, e)
with the form'sdata
.change:{key}
: this adds achange
listener to the underlying form that callscallback(value, e)
with the changed input'svalue
if its name is equal tokey
.
form.off(event, callback)
Remove a listener added with form.on(). You'll need to keep a reference to your callback function in order to remove it:
var { /* ... */ };form;form;
Contributing
Wanna help make this better? Awesome! Here's how:
- Fork this repo
- Run
npm install --dev
to install the development dependencies - Run
npm test
to run the tests - Issue a pull request
- Profit?