| ------ |
| JavaScript Reference - tapestry.form |
| ------ |
| Jesse Kuhnert |
| ------ |
| 26 July 2006 |
| ------ |
| |
| tapestry.form |
| |
| The form package defines the core functionality used in tapestry to interact with forms, as well as kicking |
| off the {{{../usersguide/clientside-validation.html}client side validation}} process when forms are submitted. |
| |
| All forms registered with the core tapestry client side form manager will by default have event listeners |
| bound to them that will invoke any registered validation profiles when the form is submitted. <(by listening |
| to the form "onsubmit" event defined by all browser forms)> |
| |
| The source for <<<tapestry.form>>> can be found {{{http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-framework/src/js/tapestry/form.js?view=markup}here}}. |
| |
| * tapestry.form.registerForm(form) |
| |
| Registers a reference to a form that will be managed by tapestry. If the form passed in has already |
| been registered the call will be ignored. The majority of the form functions in this package require that |
| this one first be called or a client side exception will be thrown.(Via dojo, so browser logging will make |
| it look pretty.) |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form to register or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| |
| ** Example usage |
| |
| This example takes an existing form and registers it. |
| |
| +---------------------------- |
| <form id="myform" action="/app" > |
| <fieldset> |
| <label for="firstName">First Name</label> |
| <input type="text" id="firstName" name="firstName" /> |
| </fieldset> |
| </form> |
| |
| <script type="text/javascript"> |
| dojo.require("tapestry.form"); |
| |
| // could also be tapestry.form.registerForm(dojo.byId("myform")) |
| tapestry.form.registerForm("myform"); |
| </script> |
| +---------------------------- |
| |
| * tapestry.form.registerProfile(form, profile) |
| |
| Registers a form validation/translation profile. There can potentially be more than |
| one profile registered with a form. <(such as when you want to register additional validation |
| logic to an existing form without overriding the default tapestry validation profile)> |
| |
| 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)> |
| |
| If no form has previosly been registered via <<<tapestry.form.registerForm(form)>>> matching the specified |
| <<<form>>> an exception will be raised. |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form to register the profile for, or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| profile | JSON | yes | | The JSON object structure representing the logic that should be used to validate this form. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| |
| ** Dojo validation profiles |
| |
| The new tapestry client side validation API relies completely on the logic provided by the |
| <<<dojo.validate.check(form, profile)>>> function. This section will probably be undergoing more extensive |
| documentation at some point, but for now the jsdoc comments in dojo are pasted in below. <(tapestry profile |
| specifics are covered in the javascript {{{form-validation.html}Validation}} section)>. |
| |
| <<See also:>> <<<dojo.validate.common>>> {{{http://archive.dojotoolkit.org/nightly/src/validate/common.js}source}} |
| |
| <<Dojo Documentation>> <(pulled from dojo.validate.common)>: |
| |
| *** Procedural API Description |
| |
| The main aim is to make input validation expressible in a simple format. You define profiles |
| which declare the required and optional fields and any constraints they might have. The results |
| are provided as an object that makes it easy to handle missing and invalid input. |
| |
| <<Usage:>> |
| |
| +------------------------------------------------------ |
| var results = dojo.validate.check(form, profile); |
| +------------------------------------------------------ |
| |
| <<Profile Object:>> |
| |
| +-------------------------------------------------------------------------------------------- |
| var profile = { |
| // filters change the field value and are applied before validation. |
| trim: ["tx1", "tx2"], |
| uppercase: ["tx9"], |
| lowercase: ["tx5", "tx6", "tx7"], |
| ucfirst: ["tx10"], |
| digit: ["tx11"], |
| |
| // required input fields that are blank will be reported missing. |
| // required radio button groups and drop-down lists with no selection will be reported missing. |
| // checkbox groups and selectboxes can be required to have more than one value selected. |
| // List required fields by name and use this notation to require more than one value: {checkboxgroup: 2}, {selectboxname: 3}. |
| required: ["tx7", "tx8", "pw1", "ta1", "rb1", "rb2", "cb3", "s1", {"doubledip":2}, {"tripledip":3}], |
| |
| // dependant/conditional fields are required if the target field is present and not blank. |
| // At present only textbox, password, and textarea fields are supported. |
| dependancies: { |
| cc_exp: "cc_no", |
| cc_type: "cc_no", |
| }, |
| |
| // Fields can be validated using any boolean valued function. |
| // Use arrays to specify parameters in addition to the field value. |
| constraints: { |
| field_name1: myValidationFunction, |
| field_name2: dojo.validate.isInteger, |
| field_name3: [myValidationFunction, additional parameters], |
| field_name4: [dojo.validate.isValidDate, "YYYY.MM.DD"], |
| field_name5: [dojo.validate.isEmailAddress, false, true], |
| }, |
| |
| // Confirm is a sort of conditional validation. |
| // It associates each field in its property list with another field whose value should be equal. |
| // If the values are not equal, the field in the property list is reported as Invalid. Unless the target field is blank. |
| confirm: { |
| email_confirm: "email", |
| pw2: "pw1", |
| } |
| }; |
| +-------------------------------------------------------------------------------------------- |
| |
| <<Results Object:>> |
| |
| +------------------------------------------------------------------------------------------ |
| isSuccessful(): Returns true if there were no invalid or missing fields, else it returns false. |
| hasMissing(): Returns true if the results contain any missing fields. |
| getMissing(): Returns a list of required fields that have values missing. |
| isMissing(field): Returns true if the field is required and the value is missing. |
| hasInvalid(): Returns true if the results contain fields with invalid data. |
| getInvalid(): Returns a list of fields that have invalid values. |
| isInvalid(field): Returns true if the field has an invalid value. |
| +------------------------------------------------------------------------------------------ |
| |
| * tapestry.form.clearProfiles(form) |
| |
| 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/changing form fields is accounted for. |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form, or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| |
| * tapestry.form.setFormValidating(form, validate) |
| |
| If a form registered matching the specified <<<form>>> exists a local property will be set |
| that causes validation to be turned on/off depending on the argument. |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form, or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| validate | boolean | yes | | If true, turns form client side validation on (the default) - false turns validation off. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| |
| * tapestry.form.submit(form, submitName) |
| |
| Submits the form specified, optionally setting the submitname hidden input field to the value |
| of <<<submitName>>> to let the {{{../components/form/form.html}Form}} component on the server know |
| which button caused the submission. (For the case of submit button listeners). |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form, or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| submitName | String | no | | Optional submit name string to use when submitting. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| |
| ** Example |
| |
| +------------------------- |
| <script type="text/javascript"> |
| dojo.require("tapestry.form"); |
| |
| tapestry.form.submit(dojo.byId("myform")); |
| </script> |
| +------------------------- |
| |
| * tapestry.form.cancel(form, submitName) |
| |
| Submits the form specified, and also sets the hidden form input field controlled by tapestry that |
| specifies the <<<submitmode>>> used so that if you have registered a <<<cancel listener>>> on your |
| {{{../components/form/form.html}Form}} component it will be called by this invocation. |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form, or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| submitName | String | no | | Optional submit name string to use when submitting. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| |
| * tapestry.form.refresh(form, submitName) |
| |
| Submits the form specified, and also sets the hidden form input field controlled by tapestry that |
| specifies the <<<submitmode>>> used so that if you have registered a <<<refresh listener>>> on your |
| {{{../components/form/form.html}Form}} component it will be called by this invocation. |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form, or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| submitName | String | no | | Optional submit name string to use when submitting. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| |
| * tapestry.form.submitAsync(form, content, submitName, validate) |
| |
| Similar to the {{{core.html}tapestry.bind}} function call, in that it submits the request asynchronously and |
| expects a valid tapestry xml content response. This is the core function used by Tapestry when submitting |
| forms asynchronously. The same load/error handling functions are called as in {{{core.html}tapestry.bind}}. |
| |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| Parameter | Type | Required | Default | Description |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| form | String element id / HTMLForm node | yes | | The element id of the form, or the form html element itself. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| content | json | no | | A properties map of optional extra content to send. This will be sent <in addition> to the content encapsulated by your form. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| submitName | String | no | | Optional submit name string to use when submitting to bind the request to a specific {{{../components/form/submit.html}Submit}} component. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
| validate | boolean | no | false | Controls whether or not to invoke client side validation. |
| *----------------------*---------------*------------*----------*----------------------------------------------+ |
