pax.form

This PAX library contains methods to manipulate and access forms.

Author

Mikkel Bergmann, http://www.pointful.com

Summary

pax.form	This PAX library contains methods to manipulate and access forms.
Properties
pax.form.ajaxSubmitFieldName	Field name that is added to any form that PAX submits via ajax
pax.form.submitViaIframeFieldName	Field name that is added to any form that PAX submits using the “iframe trick”
Functions
pax.form.useAjaxSubmit	This makes a form submit via ajax, or if there are file uploads, via a hidden iframe
pax.form.submitViaIframe	Submits a form, using a hidden iframe; this allows uploading of files, where as ajax submission doesn’t
getSelectedOptions	Gets the selected option(s) from a select box
setSelected	Sets the selected index for a select box, by text instead of value
setChecked	Sets the selected index for a check box, by value
checkboxDependents	This function relates check boxes to eachother, and warns or forces checking, when a Dependency (parent) is being unchecked, and can optionally uncheck Dependents (child) if a parent is unchecked.

Properties

pax.form.ajaxSubmitFieldName

Field name that is added to any form that PAX submits via ajax

pax.form.submitViaIframeFieldName

Field name that is added to any form that PAX submits using the “iframe trick”

Functions

pax.form.useAjaxSubmit

pax.form.useAjaxSubmit = function( form,
args )

This makes a form submit via ajax, or if there are file uploads, via a hidden iframe

Parameters

form	an ID or DOM element for the form we are submitting
args	An object that contains the following:

callBack - Optional function to run when the submit is complete
url - Optionally specify a different URL to submit the form to
submitButton - the forms associated submit button, note that this must be bound to use ajax

pax.form.submitViaIframe

pax.form.submitViaIframe = function( args,
url )

Submits a form, using a hidden iframe; this allows uploading of files, where as ajax submission doesn’t

Parameters

args	An object that contain the following:

form - an ID or DOM element for the form we are submitting
callBack - Optional function to run when the submit is complete
preserveEncoding - Optional boolean to specify that we don’t want the encoding changed to ‘multipart/form-data’

url	Optionally specify a different URL to submit the form to

getSelectedOptions

pax.form.getSelectedOptions = function( selectBox )

Gets the selected option(s) from a select box

Parameters

selectBox

The select box we’re getting the option(s) from

Example

<select name='fruit' id='fruit'>
    <option value="47">Apples</option>
    <option value="49">Oranges</option>
    <option value="67">Pears</option>
</select>
[:.
    //pax.form.setSelected( pax.$('fruit'), 'Oranges' );
:]

This would

setSelected

pax.form.setSelected = function( selectBox,
text )

Sets the selected index for a select box, by text instead of value

Parameters

selectBox	The select box we’re setting the value for
text	which value to set the select box index for

Example

The select box's selected index should be 49, which has a value of 'Oranges':
<select name='fruit' id='fruit'>
    <option value="47">Apples</option>
    <option value="49">Oranges</option>
    <option value="67">Pears</option>
</select>
[:.
    pax.form.setSelected( pax.$('fruit'), 'Oranges' );
:]

This would set the select box’s selected index value to 49, which has text ‘Oranges’

setChecked

pax.form.setChecked = function( checkBox,
value )

Sets the selected index for a check box, by value

Parameters

checkBox	The check box we’re setting the value for
value	which value to set the check box index for

Example

Assuming you have a check box set like this:

<form name='shoppinglist' id='shoppinglist'>
    <input type='checkbox' name='fruit' value='Apple'>Apple
    <input type='checkbox' name='fruit' value='Orange'>Orange
    <input type='checkbox' name='fruit' value='Pear'>Pear
</form>
[:.
    pax.form.setChecked( document.forms.shoppinglist.fruit, 'Orange' );
:]

This would set the check box’s selected index to 2, which has a value of ‘Orange’

checkboxDependents

pax.form.checkboxDependents = function( formName,
checkBoxMap,
args )

This function relates check boxes to eachother, and warns or forces checking, when a Dependency (parent) is being unchecked, and can optionally uncheck Dependents (child) if a parent is unchecked.

Parameters

formName	Name of the form the fields exist in
checkBoxMap	Dictionary that contains the check boxes
args	An optional object that optionally contain the following:

autoCheck - weather to automatically check dependencies (parent) if a dependent (child) is checked. Default is true
autoUncheck - weather to automatically uncheck dependents (child) if a dependent (parent) is unchecked. Default is false
showHint - weather to show a hint next to a dependent (parent), as it is attempted to be unchecked. Default is true
callBack - function to run when a dependency (parent) checkbox is unchecked, parameter is the field.

Note

After instanciation, each parent field contains two lists as a properties:

childDepend - A list of checkboxes that depend on this field
parentDepend - A list of checkboxes that this field depends on Also, the reason we have autoCheck and autoUncheck is that you may want to just show a warning, in which case you should disable both. Enabling both autoCheck and autoUncheck is not supported.

TODO

Currently you need both name and id to access the fields, it shouldn’t be like that.

Example

<form name='pax.form.checkboxDependents.example3'>
    <ul>
        <li><input type='checkbox' name='box1' id='box1'>box1</li>
        <li><input type='checkbox' name='box2' id='box2'>box2</li>
        <li><input type='checkbox' name='box3' id='box3'>box3</li>
    </ul>
</form>
[:.
    var checkBoxMap = {
        'box1': [],
        'box2': [ 'box1' ],
        'box3': [ 'box2' ]
    };
    pax.form.checkboxDependents( 'pax.form.checkboxDependents.example3', checkBoxMap );
:]

This example uses the default behaviour, it auto checks parent checkboxes, and shows a warning.

Example

<form name='pax.form.checkboxDependents.example2'>
    <ul>
        <li><input type='checkbox' name='box1' id='box1'>box1</li>
        <li><input type='checkbox' name='box2' id='box2'>box2</li>
        <li><input type='checkbox' name='box3' id='box3'>box3</li>
    </ul>
</form>
[:.
    var checkBoxMap = {
        'box1': [],
        'box2': [ 'box1' ],
        'box3': [ 'box2' ]
    };
    pax.form.checkboxDependents( 'pax.form.checkboxDependents.example2', checkBoxMap, { autoCheck: false, autoUncheck: true } );
:]

This example auto unchecks the Dependenct (child) boxes. Ie if you uncheck box1, and box2 and box3 are dependents (child), they will be unchecked.

Example

<form name='pax.form.checkboxDependents.example1'>
    <ul>
        <li><input type='checkbox' name='pax.js' id='pax.js' >pax.js</li>
        <li><input type='checkbox' name='pax.load.js' id='pax.load.js' >pax.load.js</li>
        <li><input type='checkbox' name='pax.util.js' id='pax.util.js' >pax.util.js</li>
        <li><input type='checkbox' name='pax.cache.js' id='pax.cache.js' >pax.cache.js</li>
        <li><input type='checkbox' name='pax.cache.template.js' id='pax.cache.template.js' >pax.cache.template.js</li>
        <li><input type='checkbox' name='pax.form.js' id='pax.form.js' >pax.form.js</li>
        <li><input type='checkbox' name='pax.fx.js' id='pax.fx.js' >pax.fx.js</li>
        <li><input type='checkbox' name='pax.validate.js' id='pax.validate.js' >pax.validate.js</li>
        <li><input type='checkbox' name='pax.template.js' id='pax.template.js' >pax.template.js</li>
        <li><input type='checkbox' name='pax.template.modifier.js' id='pax.template.modifier.js' >pax.template.modifier.js</li>
        <li><input type='checkbox' name='pax.widget.js' id='pax.widget.js' >pax.widget.js</li>
        <li><input type='checkbox' name='pax.widget.inputbox.js' id='pax.widget.inputbox.js' >pax.widget.inputbox.js</li>
        <li><input type='checkbox' name='pax.window.js' id='pax.window.js' >pax.window.js</li>
    </ul>
</form>
[:.
    var checkBoxMap = {
        'pax.cache.template.js':    [ 'pax.js', 'pax.cache.js', 'pax.template.js' ],
        'pax.template.js':          [ 'pax.js', 'pax.cache.js', 'pax.cache.template.js', 'pax.template.modifier.js' ],
        'pax.template.modifier.js': [ 'pax.template.js' ],
        'pax.widget.js':            [ 'pax.js', 'pax.util.js' ],
        'pax.validate.js':          [ 'pax.js', 'pax.util.js' ],
        'pax.fx.js':                [ 'pax.js', 'pax.util.js' ]
    };
    pax.form.checkboxDependents( 'pax.form.checkboxDependents.example1', checkBoxMap );
:]

This example auto unchecks the dependent (child) boxes. Ie if you uncheck a box that has Dependents, it will uncheck the Dependents. The example has circular references, ie one or more boxes that depend on eachother.

Example

<form name='pax.form.checkboxDependents.example4'>
    <ul>
        <li><input type='checkbox' name='box1' id='box1'>box1</li>
        <li><input type='checkbox' name='box2' id='box2'>box2</li>
        <li><input type='checkbox' name='box3' id='box3'>box3</li>
    </ul>
</form>
[:.
    var callBack = function( field ) {
        var message = '';
        for( var i = 0; i < field.parentDepend.length; i++ ) {
            message += 'Dependent: ' + field.parentDepend[i];
        }
        message += '<b'+'r>' + field.childDepend;
        pax.box.showOnRight( 'fieldMessage', message, 'hintMessage', field, 5 );
    };

    var checkBoxMap = {
        'box1': [],
        'box2': [ 'box1' ],
        'box3': [ 'box2' ]
    };
    pax.form.checkboxDependents( 'pax.form.checkboxDependents.example4', checkBoxMap, { autoUncheck: true, showHint: false, callBack: callBack } );
:]

This example auto unchecks the dependent (child) boxes. Ie if you uncheck a box that has Dependents, it will uncheck the Dependents. The example has also tuned off the hint box.