| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Copyright 2004, 2005 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <document> |
| <properties> |
| <title>Form</title> |
| </properties> |
| <body> |
| |
| |
| <section name="Form"> |
| |
| <p> |
| A Form component must enclose the other form element components (such as |
| <a href="textfield.html">TextField</a> |
| and |
| <a href="checkbox.html">Checkbox</a> |
| ). It manages the rendering of the form as well as processing when the form is |
| submitted (known as "rewinding" the form). In traditional web applications, the |
| developer is responsible for providing a name for each form and each form control |
| element; in Tapestry, the Form component generates its own unique name, and unique |
| names for each enclosed component ... this is necessary to support advanced features |
| such as loops within forms. |
| </p> |
| <p> |
| <strong> |
| See also: |
| <a href="../../apidocs/org/apache/tapestry/form/Form.html"> |
| org.apache.tapestry.form.Form |
| </a> |
| , |
| <a href="../../usersguide/validation.html">Validation</a> |
| </strong> |
| </p> |
| <section name="Parameters"> |
| |
| <table> |
| <tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Required</th> |
| <th>Default</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>method</td> |
| <td>string</td> |
| <td>no</td> |
| <td>post</td> |
| <td>Method used by the form when it is submitted.</td> |
| </tr> |
| <tr> |
| <td>success</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/IActionListener.html"> |
| IActionListener |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Listener invoked when the form is submitted normally (not a cancel or a |
| refresh) and the validation delegate indicates no errors. If the |
| delegate indicates errors, then the listener parameter (if non-null) is |
| used instead. |
| </td> |
| </tr> |
| <tr> |
| <td>cancel</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/IActionListener.html"> |
| IActionListener |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Listener used when a form is cancelled, overriding the default listener. |
| Forms are cancelled by invoking the client-side JavaScript function |
| document.<br/><br/> |
| |
| <code>tapestry.form.cancel(formId || form element, submitName)</code> |
| |
| <br/> |
| A cancelled form <em>does not</em> rewind. If no cancel listener is |
| provided, then the normal listener will be used. |
| |
| <br/><br/> |
| <strong>See also:</strong> <a href="../../javascript/form.html">Form JavaScript API</a> |
| </td> |
| </tr> |
| <tr> |
| <td>refresh</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/IActionListener.html"> |
| IActionListener |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Listener used when a form is refreshed, overriding the default listener. |
| A refreshed form bypasses input field validation on the client side, |
| though validation still occurs on the server side. If no refresh |
| listener is provided, then the normal listener will be used. |
| |
| <br/><br/> |
| <strong>See also:</strong> <a href="../../javascript/form.html">Form JavaScript API</a> |
| </td> |
| </tr> |
| <tr> |
| <td>listener</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/IActionListener.html"> |
| IActionListener |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Default listener to be invoked when the form is submitted. Invoked only |
| if another listener (success, cancel or refresh) is not invoked. |
| </td> |
| </tr> |
| <tr> |
| <td>stateful</td> |
| <td>boolean</td> |
| <td>no</td> |
| <td>true</td> |
| <td> |
| If true (the default), then an active session is required when the form |
| is submitted, if there was an active session when the form was rendered. |
| </td> |
| </tr> |
| <tr> |
| <td>delegate</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/valid/IValidationDelegate.html"> |
| IValidationDelegate |
| </a> |
| </td> |
| <td>no</td> |
| <td>default instance</td> |
| <td> |
| An object that tracks user input and input field errors, and decorates |
| fields and field labels. This is typically overriden to provide an |
| application-specific look and feel. |
| </td> |
| </tr> |
| <tr> |
| <td>clientValidationEnabled</td> |
| <td>boolean</td> |
| <td>no</td> |
| <td>false</td> |
| <td> |
| If true, then client-side validation will be enabled for components that |
| support it (such as |
| <a href="textfield.html">TextField</a> |
| ). |
| <br/><br/> |
| <strong>See also:</strong> <a href="../../usersguide/clientside-validation.html">Client Side Validation</a> |
| </td> |
| </tr> |
| <tr> |
| <td>focus</td> |
| <td>boolean</td> |
| <td>no</td> |
| <td>true</td> |
| <td> |
| If true (the default), the the Form will determine a field to receive |
| input focus, and add JavaScript to move the cursor to that field. |
| Priority is given to fields in error, then required fields, then any |
| non-disabled field. On a page with multiple forms, use this parameter to |
| control which form will take focus. |
| </td> |
| </tr> |
| <tr> |
| <td>scheme</td> |
| <td>String</td> |
| <td>no</td> |
| <td /> |
| <td> |
| The required scheme ("http" or "https", typically) for the URL. This |
| will force the creation of an absolute URL when the current request's |
| scheme does not match the value for this parameter. This is most often |
| used to switch to "https" for secure portions of an application (such as |
| a login page), before switching back to standard "http" for the majority |
| of an application. |
| </td> |
| </tr> |
| <tr> |
| <td>port</td> |
| <td>Integer</td> |
| <td>no</td> |
| <td /> |
| <td> |
| The required port (80, 443, 8080. 8443, typically) for the URL. This |
| will force the creation of an absolute URL when the current request's |
| scheme does not match the value for this parameter. This is most often |
| used in conjunction with scheme to switch to <code>"https:443"/"https:8443"</code> |
| for secure portions of an application (such as a login page), before |
| switching back to standard <code>"http:80"/"http:80"</code> for the majority of an |
| application. |
| </td> |
| </tr> |
| <tr> |
| <td>updateComponents</td> |
| <td>String[],Collection</td> |
| <td>no</td> |
| <td></td> |
| <td> |
| In an asynchronous request, specifies which components should have their content |
| rendered back to the client. These are expected to be unique component ids. |
| |
| <p> |
| See: <a href="../../apidocs/org/apache/tapestry/services/ResponseBuilder.html">ResponseBuilder</a> |
| </p> |
| |
| <br/> |
| <strong>See also:</strong> <a href="../../ajax/index.html">Ajax Features</a> |
| </td> |
| </tr> |
| <tr> |
| <td>json</td> |
| <td>boolean</td> |
| <td>no</td> |
| <td>false</td> |
| <td> |
| Causes the request to be asynchronous and the response to be captured/rendered via |
| the <a href="../../apidocs/org/apache/tapestry/services/impl/JSONResponseBuilder.html">JSONResponseBuilder</a> |
| renderer. |
| |
| <br/><br/> |
| <strong>See also:</strong> <a href="../../ajax/index.html">Ajax Features</a> |
| </td> |
| </tr> |
| <tr> |
| <td>async</td> |
| <td>boolean</td> |
| <td>no</td> |
| <td>false</td> |
| <td> |
| Causes the request to be asynchronous and the response to be captured/rendered via |
| the <a href="../../apidocs/org/apache/tapestry/services/impl/DojoAjaxResponseBuilder.html">DojoAjaxResponseBuilder</a> |
| renderer. |
| |
| <br/><br/> |
| <strong>See also:</strong> <a href="../../ajax/index.html">Ajax Features</a> |
| </td> |
| </tr> |
| </table> |
| <p> |
| Body: |
| <strong>allowed</strong> |
| </p> |
| <p> |
| Informal parameters: |
| <strong>allowed</strong> |
| </p> |
| <p>Reserved parameters: action, enctype, id, name, onreset, onsubmit</p> |
| <p> |
| A note about clientValidationEnabled: This refers to the revamped input |
| validation support that debuts in Tapestry 4.0. |
| </p> |
| </section> |
| |
| </section> |
| |
| </body> |
| </document> |
