Documentation

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(formModified): This method is called when uicForm3 finished initialization. It passes the current modification state of the form a the only parameter. Normally the form will be unmodified but it is possible that you apply the plugin to the form after it has been modified. then the formModified argument would be true.
onFormSubmit(serializedData, dataObject, modifiedDataObject, e): This method is called when the form is going to be submitted. It provides four arguments:

serializedData: the form’s data serialized with jQuery’s serialize method.
dataObject: the form’s data as a javascript object. According to the form elements names this can be an object consisting of a nested object structure.
modifiedDataObject: like dataObject but this one contains only modified data.
e: The event that was fired on a user action or null.
onInitDataLoad(initialData, formModified): This method is called when new initial data is applied to the form. It is not called when individual properties were filled with new initial data. It provides two arguments:

initialData: The new data as it is adapted by the form. This is not necessarily the data that is passed to the form as this data could provide more properties than the form holds within it’s elements. The data uicForm3 is working with is always the data as it is adapted by the form.
formModified: The form’s modification state. This should alway be false as the form is filled with new initial data and this is unmodified per definition.
onInitDataUnload(initialData, formModified): This method is called when current initial data of the form are about to be overwritten. It is not called when current initial data of  individual properties are about to be overwritten. It provides two arguments:

initialData: The data of the form that is about to be overwritten. This is not necessarily the data that has been passed to the form as this data could habe been provided more properties than the form holds within it’s elements. The data uicForm3 is working with is always the data as it is adapted by the form.
formModified: The form’s modification state before overwriting the data.
onDataLoad(currentData, formModified): This method is called when new current data is applied to the form. It is not called when individual properties were filled with new current data. It provides two arguments:

currentData: The new data as it is adapted by the form. This is not necessarily the data that is passed to the form as this data could provide more properties than the form holds within it’s elements. The data uicForm3 is working with is always the data as it is adapted by the form.
formModified: The form’s modification state.
onDataUnload(initialData, formModified): This method is called when current data of the form are about to be overwritten. It is not called when current data of  individual properties are about to be overwritten. It provides two arguments:

currentData: The data of the form that is about to be overwritten. This is not necessarily the data that has been passed to the form as this data could habe been provided more properties than the form holds within it’s elements. The data uicForm3 is working with is always the data as it is adapted by the form.
formModified: The form’s modification state.
onPropertyInitValChange(elements, name, initValue, currentValue, e): This method is called when initial data of a property has changed. It provides five arguments:

elements: This is an array of DOM elements that belong to the property that was filled with new initial data.
name: This is the name pf the property.
initValue: This is the initial value of the property as it is adapted by the property. This is not necessarily the data that is passed to the property as this data could provide more values than the property can hold within it’s elements. For example if you pass an array with four values to a property with three checkboxes assigned to it, the property can hold a maximum of three values (and this only if the three values are corresponding to the values of the value-attribute of the checkboxes).
currentValue: This is the current value of the property. As the current value also changes whenever the initial value is ging to be updated, the content of this argument is the same as the content of the initialValue .
e: The event that was fired on a user action or null.
onPropertyValChange(elements, name, initValue, currentValue, e): This method is called when current data of a property has changed. It provides five arguments:

elements: This is an array of DOM elements that belog to the property that was filled with new initial data.
name: This is the name pf the property.
initValue: This is the initial value of the property.
currentValue: This is the current value of the property. This is not necessarily the data that is passed to the property as this data could provide more values than the property can hold within it’s elements. For example if you pass an array with four values to a property with three checkboxes assigned to it, the property can hold a maximum of three values (and this only if the three values are corresponding to the values of the value-attribute of the checkboxes).
e: The event that was fired on a user action or null.
onPropertyModifiedStateChange(elements, name, initValue, currentValue, modified, e): This method is called whenever the modified state of a property changes. A property is unchanged when it’s current value is equal to its initial value. This method provides six arguments:

elements: This is an array of DOM elements that belog to the property that was filled with new initial data.
name: This is the name pf the property.
initValue: This is the initial value of the property.
currentValue: This is the current value of the property.
modified: This is the modified state of the property.
e: The event that was fired on a user action or null.
onPropertyValidStateChange(elements, name, valid, value || valueObject): This method is called whenever the valid state of a property changes. The valid state of a property has to be declared within the property’s data. uicForm3 does not perform any validation. The validation can be done on the application’s backend or within custom javascript code. See the data interface section for information on how to provide data with valid state declaration. This method provides four arguments.

elements: This is an array of DOM elements that belog to the property that was filled with new initial data.
name: This is the name pf the property.
valid: This is the valid state of the property.
value: This is the property’s value.
valueObject: This is the property’s valueObject. This object hold at least two properties: value and valid whereas value does contain the value for the property and valid does contain the valid state declaration. The object can contain more properties for example errorNumber, errorMessage etc. uicForm3 will not evaluate these additional properties. It only evaluates the value and the valid property. the additional properties can be used in custom code to enhance usability.
onFormModifiedStateChange(modified, e): This method is called whenever the modified state of the form changes. The modified state of the form depends on the modified states of it’s properties. As soon as one property is modified the form is modified itself. Only if all properties are unmodified the form itself is unmodiefied. This method provides two arguments.

modified: This indicates weather the form is modified or not.
e: The event that was fired on a user action or null.
onFormValidStateChange(valid, e): This method is called whenever the valid state of the form changes. The valid state of the form depends on the valid states of it’s properties. As soon as one property is invalid the form is invalid itself. Only if all properties are valid the form itself is valid. As stated in the onPropertyValidStateChange description, the valid state of a property is a declared attribute and won’t be set but read within uicForm3. This method provides two arguments.

valid: This indicates weather the form is valid or not.
e: The event that was fired on a user action or null.
onResetFields(properties): This method is called whenever the form fields are reseted with the resetFields()-method. Resetting the fields means to go back to their initial values. This dismisses all currently applied changes. This method provides one argument.

properties: This is an array of property objects as they were used within uicForm3.
onClear(): This method is called whenever the form is cleared with the clear()-method. Clearing the form means to clear all initial values of the form. After this the form’s initial values are empty and the form is ready to create a new dataset. This method provides no arguments.
onWipe(): This method is called whenever the form is wiped with the wipe()-method. Wiping the form means to clear all current values of the form. After this the form’s current values (that is what is seen in the UI) are empty but the initial values stay untouched. This method provides no arguments.

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()

data(): This method returns the current data of the form as a data object. uicForm3 works on a property base and each property is related to one or more form elements. There are as many properties as different form element names. The number of form elements with the same name as well as some other properties of the form elements determine if a property expects a primitive value (string, number, boolean) or a complex value (array). So for example if you have three checkboxes with name “categories” (i. e. “Sport”, “Music”, “Business”) they do expose one property with the name “categories” which is associated to a complex value. In this case the values the array can contain is limited to the values of the three checkboxes. So providing a value other than “Sport”, “Music”, “Business” would lead into a notification in the console, if debugging mode is on.
data(data): This method fills the form with current data.

data: This can be a flat object or a nested object structure. Each current value of each property of the data object will be populated into the corresponding form elements as long as these form elements are able to hold the specific values. Please refer to “Property To Form Elements Mapping” and “Examples”.

initData()

initData(): This method returns the initial data of the form as a data object. uicForm3 works on a property base and each property is related to one or more form elements. There are as many properties as different form element names. The number of form elements with the same name as well as some other properties of the form elements determine if a property expects a primitive value (string, number, boolean) or a complex value (array). So for example if you have three checkboxes with name “categories” (i. e. “Sport”, “Music”, “Business”) they do expose one property with the name “categories” which is associated to a complex value. In this case the values the array can contain is limited to the values of the three checkboxes. So providing a value other than “Sport”, “Music”, “Business” would lead into a notification in the console, if debugging mode is on.
initData(data): This method fills the form with initial data.

data: This can be a flat object or a nested object structure. Each initial value of each property of the data object will be populated into the corresponding form elements as long as these form elements are able to hold the specific values. Please refer to “Property To Form Elements Mapping” and “Examples”.

populateData()

populateData(data): This method fills the form with current data. It is an alias for the data(data)-Method. Please refer to the description of this method for details.

data: This can be a flat object or a nested object structure. Each current value of each property of the data object will be populated into the corresponding form elements as long as these form elements are able to hold the specific values. Please refer to “Property To Form Elements Mapping” and “Examples”.

populateRecord()

populateRecord(data): This method fills the form with initial data. It is an alias for the initData(data)-Method. Please refer to the description of this method for details.

data: This can be a flat object or a nested object structure. Each initial value of each property of the data object will be populated into the corresponding form elements as long as these form elements are able to hold the specific values. Please refer to “Property To Form Elements Mapping” and “Examples”.

populate()

populate(data, initial): This method fills the form with initial or current data. It is equal to populateData(data) and data(data) if the argument “initial” is set to false. It is equal to populateRecord(data) and initData(data) if the argument “initial” is set to true. For details refer to the description of “data(data)” and “initData(data)”.

data: This can be a flat object or a nested object structure. Each initial value of each property of the data object will be populated into the corresponding form elements as long as these form elements are able to hold the specific values. Please refer to “Property To Form Elements Mapping” and “Examples”.
initial: Determies weather the data should be passed as initial data (initial set to true) or current data (initial set to false).

modifiedData()

modifiedData(): This method returns the modified data of the form as a data object.

val()

val(key): This method returns the current value of the property with the name [key]. As uicForm3 works on a property base this could contain values from multiple associated form elements.

key: The property’s declarative identifier what is the value of the name attribute of the related form elements.
val(key, val): This method assigns the value [val] to the current value of the property with name [key]. As uicForm3 works on a property base this might set the current values of multiple associated form elements.

key: The property’s declarative identifier what is the value of the name attribute of the related form elements.
val: A primitive or complex value according to the property’s expected value type.

initVal()

initVal(key): This method returns the initial value of the property with the name [key]. As uicForm3 works on a property base this could contain values from multiple associated form elements.

key: The property’s declarative identifier what is the value of the name attribute of the related form elements.
initVal(key, val): This method assigns the value [val] to the initial value of the property with name [key]. As uicForm3 works on a property base this might set the initial values of multiple associated form elements.

key: The property’s declarative identifier what is the value of the name attribute of the related form elements.
val: A primitive or complex value according to the property’s expected value type.

emptyVal()

emptyVal(key): This method gets the empty value of a property. The empty value of a property derives either from the native empty values of the associated html elements (i. e. for a text element it is an empty string) or it is the value that has been set with the emptyVal(key, val)-method.

key: The property’s declarative identifier what is the value of the name attribute of the related form elements.

emptyVal(key, val): This method sets the empty value of a property. Setting the empty value can be useful if you have a property with a single checkbox associated and you want to specify the checkbox’s unchecked value what might be “0” if the checkbox should represent a boolean. It is also useful for date fields as dates should return “null” if not specified (according to mySQL).

key: The property’s declarative identifier what is the value of the name attribute of the related form elements.
val: A primitive or complex value according to the property’s expected value type.

resetFields()

resetFields(): This method resets the form’s properties (and therefore it’s form elements) to their initial value.

wipe()

wipe(): This method sets all form element’s current data to empty strings or sets them as currently unchecked or unselected. This can be used to clear but not delete a recordset or to fill the current dataset with new data.

clear()

clear(): This method sets all form element’s initial data to empty strings or sets them as initially unchecked or unselected. This can be used to prepare a form for obtaining data for a new recordset.

formModified()

formModified(): This returns the modified state of the form.

formValid()

formValid(): This returns the valid state of the form.

update()

update(): This method should be called after DOM-modifications of the form for i. e. when adding or removing form fields. uicForm3 then updates it’s properties and does show the current state of all properties and fields.

addEventListener()

addEventListener(event, method): This method allows to register event listener functions (or add callback methods) to a specifc uicForm3 event. This helps to modularize your code.

event: The uicForm3 event the handler should be registered for (the callback should be added for).
method: The identifier of the method to add or the method itself. It is recommended to work with a reference rather then with an inline method as you can remove the handler later on by calling removeEventListener(event, method) and providing the reference to the method.

removeEventListener()

removeEventListener(event, method): This method returns the initial value of the property with the name [key]. As uicForm3 works on a property base this could contain values from multiple associated form elements.

event: The uicForm3 event the handler should be removed from (the callback should be removed from).
method: The identifier of the method to remove.

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"
	]
}
property name form element name
firstname firstname
lastname firstname
birthday firstname
bands bands or bands[]

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'
		}]
	}
}
property path form element name
account.username account[username]
account.password account[password]
account.users[0].firstname account[users][0][firstname]
account.users[0].lastname account[users][0][lastname]
account.users[1].firstname account[users][1][firstname]
account.users[1].lastname account[users][1][lastname]