tapestry.form

Provides central handling of all client side form related logic.

Summary
tapestry.formProvides central handling of all client side form related logic.
Properties
formsContains a reference to all registered Tapestry forms in the current document.
currentFocusReference to form element/element id of field that should currently recieve focus, if any
Functions
focusFieldIf possible, brings keyboard input focus to the specified field.
registerFormRegisters the form with the local forms property so that there is a central reference of all tapestry forms.
registerProfileRegisters a form validation/translation profile.
clearProfilesClears any previously registered validation profiles on the specified form.
setFormValidatingIf a form registered with the specified formId exists a local property will be set that causes validation to be turned on/off depending on the argument.
submitSubmits the form specified, optionally setting the submitname hidden input field to the value of submitName to let the Form component on server know which button caused the submission.
cancelSubmits the form to the server in “cancel” mode, invoking any cancel listeners registered to the server side equivalent to the form passed in.
refreshSubmits the form to the server in “refresh” mode, invoking any refresh listeners registered to the server side equivalent to the form passed in.
submitAsyncDoes almost the same thing as tapestry.form.submit, but submits the request via XHR to the server asynchronously.

Properties

forms

Contains a reference to all registered Tapestry forms in the current document.

currentFocus

Reference to form element/element id of field that should currently recieve focus, if any

Functions

focusField

focusField:function(field)

If possible, brings keyboard input focus to the specified field.

Parameters

fieldThe field(field id) of the field to focus.

Note

Function deprecated in favor of dojo equivalent, like dojo.html.selectInputText(node).

registerForm

registerForm:function(id,
async,
json)

Registers the form with the local forms property so that there is a central reference of all tapestry forms.

Parameters

idThe form(form id) to register.
asyncBoolean, if true causes form submission to be asynchronous.
jsonBoolean, if true causes form submission to be asyncrhronous with an expected JSON response.

registerProfile

registerProfile:function(id,
profile)

Registers a form validation/translation profile.  There can potentially be more than one profile registered with a form.

The profiles will be consulted at various points in the forms life, which currently only involves running the profile checks before form submission.  (more points to be determined in the future)

See Also

<dojo.validate.check>

Parameters

idThe form(form id) to register profile with.
profileThe object containing all of the validation/value constraints for the form.

clearProfiles

clearProfiles:function(id)

Clears any previously registered validation profiles on the specified form.  Normally called during XHR requests by returned JS response to ensure new validation logic coming in from potentially new form fields is accounted for.

Parameters

idThe form id to clear profiles for.

setFormValidating

setFormValidating:function(formId,
validate)

If a form registered with the specified formId exists a local property will be set that causes validation to be turned on/off depending on the argument.

Parameters

formIdThe id of the form to turn validation on/off for.
validateBoolean for whether or not to validate form, if not specified assumes true.

submit

submit:function(form,
submitName,
parms)

Submits the form specified, optionally setting the submitname hidden input field to the value of submitName to let the Form component on server know which button caused the submission.  (For the case of submit button listeners).

Parameters

formThe form(form id) to submit.
submitNameOptional submit name string to use when submitting.  This is used to associate a form submission with a particular component, like a Submit/LinkSubmit/etc..
parmsOptional extra set of arguments that can control the form submission semantics such as url/async/json/etc.

cancel

cancel:function(form,
submitName,
parms)

Submits the form to the server in “cancel” mode, invoking any cancel listeners registered to the server side equivalent to the form passed in.

Parameters

formThe form(form id) to cancel.
submitNameOptional submit name string to use when submitting.  This is used to associate a form submission with a particular component, like a Submit/LinkSubmit/etc..
parmsOptional object parms passed through to tapestry.form.submit().

refresh

refresh:function(form,
submitName,
parms)

Submits the form to the server in “refresh” mode, invoking any refresh listeners registered to the server side equivalent to the form passed in.

Parameters

formThe form(form id) to refresh.
submitNameOptional submit name string to use when submitting.  This is used to associate a form submission with a particular component, like a Submit/LinkSubmit/etc..
parmsOptional object parms passed through to tapestry.form.submit().

submitAsync

submitAsync:function(form,
content,
submitName,
parms)

Does almost the same thing as tapestry.form.submit, but submits the request via XHR to the server asynchronously.

Parameters

formThe form(form id) to submit.
contentOptional content map, mainly used to pass in browser event parameters to form submission, but can be any typical form/value pair.
submitNameOptional submit name string to use when submitting.
parmsOptional set of extra parms that can override the defautls for this specific form submission, like the url/async/json behaviour of the submission.
focusField:function(field)
If possible, brings keyboard input focus to the specified field.
registerForm:function(id,
async,
json)
Registers the form with the local forms property so that there is a central reference of all tapestry forms.
Contains a reference to all registered Tapestry forms in the current document.
registerProfile:function(id,
profile)
Registers a form validation/translation profile.
clearProfiles:function(id)
Clears any previously registered validation profiles on the specified form.
setFormValidating:function(formId,
validate)
If a form registered with the specified formId exists a local property will be set that causes validation to be turned on/off depending on the argument.
submit:function(form,
submitName,
parms)
Submits the form specified, optionally setting the submitname hidden input field to the value of submitName to let the Form component on server know which button caused the submission.
cancel:function(form,
submitName,
parms)
Submits the form to the server in “cancel” mode, invoking any cancel listeners registered to the server side equivalent to the form passed in.
refresh:function(form,
submitName,
parms)
Submits the form to the server in “refresh” mode, invoking any refresh listeners registered to the server side equivalent to the form passed in.
submitAsync:function(form,
content,
submitName,
parms)
Does almost the same thing as tapestry.form.submit, but submits the request via XHR to the server asynchronously.