Documentation

• Options
• Methods
• Property To Form Elements Mapping

Options

The options can be set when applying the uicForm3 plugin to a form or by setting the uicForm3 defaults.
Example of setting defaults:

$.fn.uicForm3.defaults = {
	onFormInit: function() {},
	onPropertyModifiedStateChange: function() {},
	…
};

Example of setting options when applying the plugin:

$('yourFormSelector').uicForm3({
	onFormInit: function() {},
	onPropertyModifiedStateChange: function() {},
	…
});

It is worth a note that if you apply a callback function to an appropriate option property this callback function is not set as the property’s value (as this is common on other plugins and true for the other options on uicForm3) but added to an array. So it works like an addEventListener-Method() and it allows the programmer to define default behaviors on certain events within the default settings and apply special handler for different forms when applying the plugin to a form. Indeed there are also addEventListener() and removeEventListener() methods to add and remove handlers after applying uicForm3.

Currently the following options are available:

• onFormInit()
• onFormSubmit()
• onInitDataLoad()
• onInitDataUnload()
• onDataLoad()
• onDataUnload()
• onPropertyInitValChange()
• onPropertyValChange()
• onPropertyModifiedStateChange()
• onPropertyValidStateChange()
• onFormModifiedStateChange()
• onFormValidStateChange()
• onResetFields()
• onClear()
• onWipe()

Methods

To call a method on uicForm3 please use the following syntax:
General:

$('yourFormSelector').uicForm3('methodname'[,argument1, arguments, …]);

Examples:

$('yourFormSelector').uicForm3('val','firstname','Steve');
$('yourFormSelector').uicForm3('wipe');

• data()
• initData()
• populateData()
• populateRecord()
• populate()
• modifiedData()
• val()
• initVal()
• emptyVal()
• resetFields()
• wipe()
• clear()
• formModified()
• update()
• addEventListener()
• removeEventListener()

data()

initData()

populateData()

populateRecord()

populate()

modifiedData()

val()

initVal()

emptyVal()

resetFields()

wipe()

clear()

formModified()

formValid()

update()

addEventListener()

removeEventListener()

Property To Form Elements Mapping

Mapping form data properties to form elements is done by uicForm3 according to the form elements’ names. Every form element with the same name is mapped to the same property, whereas the elements’ name is either equal to

• the property’s name when dealing with a flat unnamed data object

or

• the property’s path using literal syntax without quotes as string when dealing with a nested data object structure.

Thus the naming of the form elements defines what kind of data is accepted by the form as input respectively what kind of data is produced by the form as output.

Dealing with a flat unnamed data object

This is the classic way of handling forms. If you are requesting it’s values on the server-side – say with php – you have to request every property on it’s own and if you are expecting a complex value you should name the related form fields with a trailing “[]” to tell php that it should create an array and put all the values of the related key-value-pairs into it and then assign the array as the property’s value.
Requesting the form’s data via uicForm3 will result in an unnamed object with as many properties as different form element names. This object contains the same properties as you would request in php one by one.
For uicForm3 to work properly you don’t need to assign trailing “[]” for complex values as uicForm3 detects the value type on its own, but it might be a good idea to use them nevertheless to be compatible with the way php handles these kind of things.

An example probably says more than all my words. So have a look at the following data object and the table with property names and related form element names and refere to the examples to set your hands on this subject.

{
	firstname: "John",
	lastname: "Lennon",
	birthday: "1940-10-09"
	bands: [
		"The Beatles",
		"Plastic Ono Band"
	]
}

Dealing with a nested data object structure

This is a more advanced way of handling forms. If you are requesting it’s values with php you only have to request the root object and get all the submitted data (as long as all data is hold inside the root object’ structure what not necessarily has to be true). The mechanism is similar to the way php handles complex property’s values (arrays) with adding the trailing “[]”. As mentioned before in this case the naming of the form elements has to match the property’s path within the object structure expressed in literal syntax without quotes. In this case the result you get when requesting the root object in php equals the result you get when requesting the form’s data via uicForm3.

So again have a look on the following data object and the table with property paths and relatedform element names and refere to the examples to set your hands on nested data structures.

{
	account: {
		username: 'beatles',
		password: 'submarine',
		users: [{
			firstname:'John',
			lastname:'Lennon'
		},
		{
			firstname:'Paul',
			lastname:'McCartney'
		}]
	}
}