JsForm Documentation

jsForm works as a jQuery plugin and allows basically any type of container to be converted to a jsForm.

jsForm(config)

Constructor with the (optional) config object:

$("#myForm").jsForm({
	/**
	 * enable form control rendering (if jsForm.controls is available) and validation
	 */
	controls: true,
	/**
	 * the object used to fill/collect data
	 */
	data: null,
	/**
	 * the prefix used to annotate theinput fields
	 */
	prefix: "data",
	/**
	 * set to null to discourage the tracking of "changed" fields. 
	 * Disabling this will increase performance, but disabled the "changed" functionality.
	 * his will add the given css class to changed fields.
	 */
	trackChanges: "changed",
	/**
	 * set to false to only validate visible fields. 
	 * This is discouraged especially when you have tabs or similar elements in your form.
	 */
	validateHidden: true,
	/**
	 * skip empty values when getting an object
	 */
	skipEmpty: false,
	/**
	 * an object with callback functions that act as renderer for data fields (class=object).
	 * ie. { infoRender: function(data){return data.id + ": " + data.name} } 
	 */
	renderer: null,
	/**
	 * an object with callback functions that act as pre-processors for data fields (class=object).
	 * ie. { idFilter: function(data){return data.id} } 
	 */
	processors: null,
        /**
	 * dataHandler will be called for each field filled. 
	 */
	dataHandler: null, /*{
		serialize: function(val, field, obj) {
			if(field.hasClass("reverse"))
				return val.reverse();
		},
		deserialize: function(val, field, obj) {
			if(field.hasClass("reverse"))
				return val.reverse();
		}
	    }*/
	/**
	 * optional array of elements that should be connected with the form. This
	 * allows the splitting of the form into different parts of the dom.
	 */
	connect: null,
	/**
	 * The class used when calling preventEditing. This will replace all
	 * inputs with a span with the given field
	*/
	viewClass: "jsfValue"
});

Note: the default prefix is "data" all fields are accessed through html using the prefix and using dot-notation (i.e. prefix.field.value). It is NOT possible to reference into collections use javascript for that.

jsForm("get")

Deserialize the object based on the form and returns the new object. This will analyze any fields matching the given prefix and update the existing data object.

alert(JSON.stringify($("#details").jsForm("get"), null, " "));

jsForm("getData")

Get the data object used as a base for get() - without applying any changes made in the form.

Note that modifying this directly might result into unwanted results when working with some functions that rely on this object.

jsForm("preventEditing", [true|false])

uses form element and replaces them with "spans" that contain the actual content. the original "inputs" are hidden. If the parameter is missing, this funciton will automatically toggle.

jsForm("fill", data)

Fill the form based on a given data object. This will clear all fields before fillung and will call a revalidation of all fields.

Note that a fill will reset the form compleely and also (re-)apply the "changed" functionality.

$("#reload").click(function(){
	// get updated data from the json
	$.getJSON('ajax/test.json', function(data) {
		$("#details").jsForm("fill", data);
	};
});

jsForm("clear")

Calling this will clear the given form. This will not clear the internal object,but just the form fields.

$("#clear").click(function(){
	$("#details").jsForm("clear");
});

jsForm("reset")

Reset the form with the last data, overwriting any changes made by the user.

Note: This will clear and then build up the form again. so any DOM changes made externally might also be reverted!

$("#reset").click(functin(){
	$("#details").jsForm("reset");
});

jsForm("changed")

In order for this to work, the form must have config.trackChanges = true. Each field changed will get the class "changed" and the call of this function will return true.

Only the actual value of the input is being used for comparison - so changes that ar enot represented in the value are not counted (i.e. when you change the "pojo" data).

jsForm("preventEditing" [, {boolean}force])

uses form element and replaces them with "spans" that contain the actual content. The original "inputs" are hidden. The optional force parameter allows to disable directly, otherwise each call will toggle form fields/spans.

jsForm("equals", data[, "idField"])

Compare the current content/object of the jsForm with another object. This will create the object out of the current form and will then do direct compare of all fields.

You can optionally set an "idField" if you want sub-object to be compared only by their id (ie: data.subobj.id). This should be used when working with subobjects that are filled using an autocomplete or a selectbox where the whole object is added to the form, but the fields in them are not changed (foreign key)

$("#check").click(function(){
	$.getJSON('ajax/test.json', function(data) {
		if(!$("#details").jsForm("equals", data)) {
			alert("data is different!");
		} else {
			alert("data is still the same");
		}
	};
});

JsForm Events

.on("filled")

Triggered after the form is finished filling. This is a good place to do some gui post-processing

Field Events

When retrieving/setting data, jsForm will generate events that can be handled to apply special formatting or validation.

.on("fill")

Triggered when the state/value of a field has been changed by jsform

.on("validate")

Before a form field is queried for data, the validate event is thrown to it. Using this you can preprocess the value and/or set the invalid class on the field.

Further Information

• Ajax-Usage see how to transmit the object using ajax
• jQuery Ajax API