| <?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>ImageSubmit</title> |
| </properties> |
| <body> |
| |
| <section name="ImageSubmit"> |
| |
| <p> |
| A component that generates a clickable image that will cause the enclosing form to |
| submit. The <code><input type="image"></code> form element was originally designed |
| for use as a way to select a pixel within an image that was presumable a map; it has been |
| co-opted by web applications as a way to decorate a form submit button using a |
| custom image instead of ordinary clickable buttons. This component is simply an |
| enhanced version of the |
| <a href="submit.html">Submit</a> |
| component that will display an image instead of a text label. |
| </p> |
| |
| <p> |
| <strong> |
| See also: |
| <a href="../../apidocs/org/apache/tapestry/form/ImageSubmit.html"> |
| org.apache.tapestry.form.ImageSubmit |
| </a> |
| , |
| <a href="form.html">Form</a> |
| , |
| <a href="linksubmit.html">LinkSubmit</a> |
| , |
| <a href="submit.html">Submit</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>image</td> |
| <td> |
| <a href="../../apidocs/org/apache/tapestry/IAsset.html"> |
| IAsset |
| </a> |
| </td> |
| <td>yes</td> |
| <td></td> |
| <td>The normal image to display for the button.</td> |
| </tr> |
| |
| <tr> |
| <td>name</td> |
| <td>String</td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Overrides the default mechanism for selecting the form element id; this |
| allows the name attribute of the rendered <code><input></code> tag to be |
| controlled, which is necessary is some browsers to control the tooltip |
| help message for the control. |
| </td> |
| </tr> |
| |
| <tr> |
| <td>disabled</td> |
| <td>boolean</td> |
| <td>no</td> |
| <td>false</td> |
| <td> |
| If set to true, the button will be disabled (will not respond to the |
| mouse); the browser should provide a "greyed out" appearance. |
| </td> |
| </tr> |
| |
| <tr> |
| <td>disabledImage</td> |
| <td> |
| <a href="../../apidocs/org/apache/tapestry/IAsset.html"> |
| IAsset |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| If specified, and if the component is disabled, then this image is used |
| rather than the normal image parameter. This allows an alternate image |
| to be used to indicate to the user that the option is not available. |
| </td> |
| </tr> |
| |
| <tr> |
| <td>point</td> |
| <td>java.awt.Point</td> |
| <td>no</td> |
| <td></td> |
| <td>Set to the coordinates of the clicked point within the image.</td> |
| </tr> |
| |
| <tr> |
| <td>selected</td> |
| <td>Object</td> |
| <td>no</td> |
| <td></td> |
| <td> |
| This parameter is bound to a property that is updated when the submit |
| button is clicked by the user. The property is updated to match the tag |
| parameter. |
| </td> |
| </tr> |
| <tr> |
| <td>tag</td> |
| <td>Object</td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Tag used with the selected parameter to indicate which Submit button on |
| a form was clicked. |
| </td> |
| </tr> |
| |
| <tr> |
| <td>listener</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/IActionListener.html"> |
| IActionListener |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| An optional listener (typically specified as the name of a listener |
| method), notified when the Submit is triggered. |
| |
| <p> |
| When invoking listeners invoked within a <a href="../general/for.html">For</a> loop this |
| listener should be used. |
| </p> |
| |
| <p> |
| This parameter should <strong>not</strong> be used in the majority of cases as the |
| listener is notified before all form data has been captured on the server. Only use |
| this when you know you are going to redirect or do some other cancelling sort of action |
| that isn't likely to alter form state. Use <em>action</em> as your preferred listener |
| method parameter. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td>action</td> |
| <td> |
| <a |
| href="../../apidocs/org/apache/tapestry/IActionListener.html"> |
| IActionListener |
| </a> |
| </td> |
| <td>no</td> |
| <td></td> |
| <td> |
| A listener that is notified if this component is triggered just before |
| the form's listener, after all components enclosed by the Form have had |
| a chance to update their properties. |
| |
| <p> |
| If you are going to notify a listener, this is probably the parameter you want |
| to bind to. |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td>parameters</td> |
| <td>Object</td> |
| <td>no</td> |
| <td></td> |
| <td> |
| Parameter(s) gathered at the time the button is triggered, supplied as |
| listener parameters in the IRequestCycle available to the listener. |
| <p> |
| If the parameter is a Collection, it will be converted to an Object |
| array (to match the IRequestCycle getListenerParameters() |
| signature). |
| </p> |
| <p> |
| Allows deferred listeners (defer = true) access to any rewind state |
| not conveniently placed using tag/selected (e.g. when there are |
| multiple objects to select as might happen with a nested Foreach). |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td>submitType</td> |
| <td>String - [submit,cancel,refresh]</td> |
| <td>yes</td> |
| <td>submit</td> |
| <td> |
| Controls the type of submission that this component invokes. Using javascript |
| this parameter will cause the invocation of the component to be recognized as |
| a cancel/refresh/normal form submission depending on the value given. If you |
| have a <code>cancel="listener"</code> or <code>refresh="listener"</code> |
| parameter set on your <a href="form.html">Form</a> they will be invoked |
| accordingly. |
| </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>removed</strong> |
| </p> |
| |
| <p> |
| Informal parameters: |
| <strong>allowed</strong> |
| </p> |
| |
| <p> |
| Reserved parameters: |
| <em>type, src</em> |
| </p> |
| |
| <span class="warn"> |
| <strong>Warning:</strong> |
| <p> |
| In Tapestry 3.0, the behavior of the ImageSubmit was |
| <em>undeferred</em> |
| , the equivalent of setting the defer parameter to false. The default for the |
| defer parameter in 4.0 is <em>true</em> |
| , which may in rare cases, cause problems when upgrading an applicaton from 3.0 |
| to 4.0. |
| </p> |
| </span> |
| |
| </section> |
| |
| <section name="Examples"> |
| |
| |
| <p>HTML template:</p> |
| |
| <source xml:space="preserve"> |
| <form jwcid="form@Form" success="listener:doSubmit"> |
| <table> |
| <tr> |
| <th>User name:</th> |
| <td><input jwcid="userName@TextField" value="ognl:userName" size="12"/></td> |
| </tr> |
| <tr> |
| <th>Password:</th> |
| <td><input jwcid="password@TextField" value="ognl:password" hidden="true" size="12"/></td> |
| </tr> |
| <tr> |
| <td colspan="2"> |
| <input type="image" src="images/login.png"/> |
| <input type="image" jwcid="help@ImageSubmit" action="listener:doHelp" image="asset:help/> |
| </td> |
| </tr> |
| </table> |
| </form></source> |
| |
| <p>Page specification:</p> |
| <source xml:space="preserve"> |
| |
| . . . |
| |
| <asset name="help" path="images/help.png"/> |
| |
| . . . |
| |
| </source> |
| |
| |
| <p> |
| This is a variation of the example for the |
| <a href="Submit.html">Submit</a> |
| component; it uses images instead of ordinary clickable buttons for the help and |
| login actions. |
| </p> |
| </section> |
| |
| </section> |
| |
| </body> |
| </document> |
