Documentation

1 Getting Started
2 Design Overview
3 Page Controller Boot Process
4 Your First App
5 Page Controller
6 Modules
7 Components
8 jqcEmpty
9 jqcLabel
10 jqcButton
11 jqcLayer
12 jqcPanelDeck
13 jqcAccordion
14 jqcProgressBar
15 Data Binding & Remote Data Synchronization
16 jqcDataService
17 jqcDataModel
18 jqcViewModel
19 jqcList
20 jqcTable
21 jqcForm
22 jqcResponsiveLayoutManager
23 jqcTreeList
24 Demos

jqcForm


This document matches version 1.6.0 .

The jqcForm component contains a set of helper functions that make it easier to work with forms. Whether or not you want to use the jqcForm component or not is up to you. You can handle forms in any other way you like. You can also combine other form handling techniques with jqcForm.

Creating a jqcForm Component

jqcForm components are declared and accessed just like any other component. Here is an example:

<form id="myForm" jqc-type="jqcForm">
    <input type="text" id="firstName"> First Name <br/>
    <input type="text" id="lastName">  Last Name <br/>
</form>

<span jqc-module="bootModule"></span>
    
<script>
    function bootModule() {
        var module = {};
        
        module.postRender = function() {
            var myForm = module.jqc.pageController.components.myForm;
        }
        
        return module;
    }
</script>    

This example attaches a jqcForm component to a normal form element. You can now access the form field values via the jqcForm functions.

Getting and Setting Field Values

Forms are often used to edit JavaScript data objects. Because this is such an often occurring use case, the jqcForm component has a set of functions that help you with that.

Getting Field Values

You can get the values of the form fields into a JavaScript object using the getFieldValues() function, like this:

var fieldValues = myForm.getFieldValues();    

A new JavaScript object will be created, the form field values inserted into it, and the object returned. The property names used in the JavaScript object will be the same names as you have used as form field names or IDs (using the name or id HTML attributes).

If you want to insert the field values into an existing JavaScript object, you can pass that object as parameter to the getFieldValues() function, like this:

var dataObject  = { firstName : "", lastName : "" };

var fieldValues = myForm.getFieldValues(dataObject);    

The form field values will then be copied into the dataObject object.

Setting Field Values

You can set the values of form fields using the setFieldValues() function, like this:

var dataObject  = { firstName : "Jakob", lastName : "Jenkov" };

myForm.setFieldValues(dataObject);    

This will set the properties of the JavaScript object into the corresponding form fields. Any properties in the JavaScript object which do not have corresponding form fields will be ignored.

Resetting Field Values

You can clear the form fields using the resetFieldValues() function like this:

myForm.resetFieldValues();

In case you need to set some default values into some of the form fields, use a setFieldValues() function call, passing some default field values in the JavaScript object pass as parameter. Here is an example:

var defaults = { firstName : "First Name ...",
                 lastName  : "Last Name ..." };

myForm.resetFieldValues()
      .setFieldValues(defaults);

Editing Objects

Copying a JavaScript object's properties into form fields, editing them, and copying the form field values back into the original JavaScript object, is a very common use case. Therefore the jqcForm component has some functions supporting this use case.

You can copy the values of a JavaScript object into the form fields using the editObject() function, like this:

    myForm.editObject(dataObject);

The jqcForm component will keep a reference to the object being edited internally. When the user is done editing the form, you can copy all the form field values into the object being edited using the editedObject(), like this:

var edited = myForm.editedObject();

In case you do not want to pollute the original JavaScript object with the edited form field values, you can also create a copy of the original object and insert the form field values into the copy. That is done using the editedObjectCopy() function, like this:

var editedCopy = myForm.editedObjectCopy();

Form Validation

The jqcForm component also contains some functions that help you validate form fields.

First you must set some validation functions (validators) on the jqcForm component. Here is an example:

var validators = {};

validators.fName = function(form, validatorName, validator) {
    return jQuery("#firstName").val().trim() != "";
};

myForm.validators(validators);

This example sets a single validator function that checks if the form field firstName is empty or not.

The validator function is just a normal JavaScript function which takes 3 parameters: The jqcForm object, the property name of the validator (in this case fName), and the validator function itself.

There is no direct relationship between property names of validator functions (e.g. fName) and the names of the form fields they validate (e.g. firstName). You are free to give your validator functions whatever property names you wish.

To validate the form you call the validate() function. This function returns a JavaScript object with a property for each validator. The property names are the same as the validators are using. Each property is a boolean telling if the validator function returned true or false. Here is an example:

// configuring validators
var validators = {};

validators.fName = function(form, validatorName, validator) {
    return jQuery("#firstName").val().trim() != "";
};

myForm.validators(validators);


// performing validation
var validation = myForm.validate();

if(!validation.isValid()) {

    if(!validation.fName) {
      ...
    }

}

The validation object returned from the validate() function contains an isValid() function. This function looks at all the properties of the validation object, and if all properties are true, the isValid() returns true. If a single property is false, then the isValid() function returns false.

Notice how the validation object contains a property named fName. This property contains the true / false value returned by the fName validator function.

Validation Simplicity

As you can see, the validation features are kept at a minimum. This is done because many frameworks which try to make full-automatic validation features often end up over-engineering validation. Simple field validations like if the field is empty, a number, an email address etc. might be easy enough to do with automatic validation. But pretty soon a reasonably advanced application will need something that the validation framework does not support, and then you are stuck.

To avoid getting in your way, the validation functions are kept to a bare minimum, with no automatic field validations, CSS class manipulation etc. All that is up to you to build on top.

In a future version the jqcForm might get support for single field validators, if a model can be implemented that is easy to use, yet fully flexible.

Functions

FunctionDescription
getFieldValues(dataObject) Gets the values of form fields nested inside the form element. Inserts the values into the object passed as parameter, using the form field names / IDs as property names.
setFieldValues(dataObject) Sets the values of form fields nested inside the form element. Inserts the values from the object passed as parameter, using the property names as form field names / IDs.
resetFieldValues() Resets (clears) the values of form fields nested inside the form element.
editObject(dataObject) Sets the values of form fields nested inside the form element. Inserts the values from the object passed as parameter, using the property names as form field names / IDs. Keeps a reference to the edited object, so you can obtain it again using editedObject() or editedObjectCopy().
editedObject() Gets the edited object (set via editObject()) and inserts the form field values into it.
editedObjectCopy() Creates a copy of the edited object (set via editObject()) and inserts the form field values into it.
validators(validators) Sets the validators to be used by this form when validate() is called. The validators parameter is a JavaScript object containing the validators as properties.
validate() Executes the validators set using the validators() function, and returns a JavaScript object with the validation state.