The form package defines the core functionality used in tapestry to interact with forms, as well as kicking off the 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 here.
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. |
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>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. |
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 Validation section).
See also: dojo.validate.common source
Dojo Documentation (pulled from dojo.validate.common):
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.
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. |
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. |
Submits the form specified, optionally setting the submitname hidden input field to the value of submitName to let the 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. |
<script type="text/javascript">
dojo.require("tapestry.form");
tapestry.form.submit(dojo.byId("myform"));
</script>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 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. |
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 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. |
Similar to the 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 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 Submit component. | |
| validate | boolean | no | false | Controls whether or not to invoke client side validation. |