trans-form
v1.1.1
Published
Javascript library that maps html forms to complex objects and vice versa
Downloads
53
Maintainers
Readme
transForm.js
Javascript library for manipulating html forms. It's goal is to easily transform html forms to structured javascript objects and vice versa.
Functions
transForm.serialize()
transForm.deserialize()
transForm.clear()
transForm.submit()
transForm.setDefaults()
Installation
Just add transForm.js
to your HTML page like this
<script src="transForm.js"></script>
Then use the transForm
namespace to use the awesome!
Install with bower
bower install --save trans-form
Add the source to the HTML:
<script src="bower_components/trans-form/dist/transForm.min.js"></script>
Usage
Basic example:
<form id="transform">
<input name="test" value="transform">
</form>
Pass a query string or an HTMLElement
to any of the functions.
The parent element can be any element but .submit()
will only work with <form>
elements.
var obj = transForm.serialize('#transform');
Variable obj
now holds this object:
{ test: 'transform' }
To deserialize this object into the form use the same structure
transForm.deserialize('#transform', obj);
Using the .
delimiter, one can specify an object inside the result object.
Other structures:
<form id="transform">
<input name="person.name" value="Thom Bakker">
<input name="person[job]" value="Programmer">
<input name="person.hobbies[]" type="checkbox" value="Programming" checked>
<input name="person.hobbies[]" type="checkbox" value="Gaming">
<input name="person.address[0].street" value="Inspirationstreet">
<input name="person.address[1].street" value="Objectionlane">
<input name="t.r.a.n.s.f.o.r.m" value="foo">
</form>
Outputs:
{
person: {
name: 'Thom Bakker',
job: 'Programmer',
hobbies: [
'Programming'
],
address: [{
street: 'Inspirationstreet'
},{
street: 'Objectionlane'
}]
},
t:{r:{a:{n:{s:{f:{o:{r:{m: 'foo' }}}}}}}}
}
To ignore an input, select or textarea you can add the ignore data attribute like this:
<input name="ignoreme" data-transform-ignore />
History
This project is inspired by maxatwork/form2js.
transForm is even compatible with the object notation of form2js/js2form.
transForm is a more flexible & faster library build for HTML5.
Functions
transForm.serialize()
Serializes all child inputs from any HTML element to a JavaScript object
Params
- parentElement - Can be a
HTMLElement
or a querySelector string - options - An object containing the serialize options
- nodeCallback - Function that will be executed for every input (param:
input
,entry
). Return the entry{ name, value }
object where thename
is the property string of the resulting object & thevalue
is any value (Ex:{ name: 'text.input', value: true }
results in{ text: { input: true } }
).
Example
<form id="myForm">
<input name="test" value="transform">
</form>
var myFormObject = transForm.serialize('#myForm');
console.log(myFormObject.test); //'transform'
transForm.deserialize()
Deserializes a JavaScript object or a valid JSON string to the child inputs from any HTML element
Params
- parentElement - Can be a
HTMLElement
or a querySelector string - data - The object that needs to be deserialized
- options - An object containing the deserialize options
- nodeCallback - Function that will be executed for every input (params:
input
,value
) return a truthy value (Ex:return true
) to skip deserializing that input, return nothing to apply the default deserialization.
Example
<form id="myForm">
<input name="test">
</form>
transForm.deserialize('#myForm', { test: 'transform' });
transForm.clear()
Clears the value of all child inputs from any HTML element. Selects & Radio's will be defaulted to the first option.
Params
- parentElement - Can be a
HTMLElement
or a querySelector string - options - An object containing the clear options
Example
transForm.clear('#myForm');
transForm.submit()
Submits a form element which triggers the submit
event of the form. You can programmatically trigger the HTML5 validation of the form by passing true
as 2nd param, this creates a button on the fly when there is no submit button inside the form.
Params
- parentElement - Can be a
HTMLElement
or a querySelector string - HTML5Submit - HTML5 validation triggers only on submit button click, if there is no submit button it will create one (destroyed afterwards).
Example
transForm.submit('#myForm', true);
transForm.setDefaults()
Overrides the default options in the transForm
instance.
Params
- defaults - An object containing the default options
Example
//These are the current defaults
transForm.setDefaults({
delimiter: '.', //The delimiter seperates the object keys (serialize, deserialize)
skipDisabled: true, //Skip inputs that are disabled (serialize, deserialize, clear)
skipReadOnly: false, //Skip inputs that are readonly (serialize, deserialize, clear)
skipFalsy: false, //Skip inputs that have falsy values (0, false, null, undefined, '') (serialize)
useIdOnEmptyName: false, //If an input has no name attribute it will fallback to its id attribute (serialize, deserialize)
triggerChange: false, //Fires the change listener for every field when deserializing (even if the value is not changed) (deserialize)
});
TODO's
- Npm for automated
- Distribution
- Unit tests
- Code coverage
- Online examples / docs
Browser support
Supports >=IE9 and latest versions of modern browsers.