[Tapestry Wiki] Update of "Tapestry5HowToUseForms" by FilipSAdamsen

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Tapestry Wiki" for change notification.

The following page has been changed by FilipSAdamsen:
http://wiki.apache.org/tapestry/Tapestry5HowToUseForms

The comment on the change is:
Added some missing form events. Added a bit on multiple submits with AJAX.

------------------------------------------------------------------------------
- How to use forms in Tapestry 5 [[BR]]
+ How to use forms in Tapestry 5.[[BR]]
  
  Forms are probably the most used way of getting data from an end user.  Tapestry does a lot to hook up actions on your forms to methods in your supporting page/component class.  Keep in mind that page classes are (usually) just POJOs that live in a certain package that mirrors the template location.
  
@@ -10, +10 @@

  
  ==== Form Events ====
  
- 
+  *prepareForRender -> calls onPrepareForRender()
+     Is called before prepare when rendering out the form.
+  *prepareForSubmit -> calls onPrepareForSubmit()
+     Is called before prepare when the form is submitted.
   *prepare -> calls onPrepare()
-     Is called before the form processes data and when the form needs to render itself (just one time).
+     Is called after prepareForRender or prepareForSubmit, that is, once every time the form is rendered or submitted.
   *validate -> calls onValidateForm() 
-     To allow for cross-form validation 
-    (use [http://tapestry.apache.org/tapestry5/tapestry-core/apidocs/org/apache/tapestry/corelib/components/Form.html#recordError(org.apache.tapestry.Field,%20java.lang.String) form.recordError(field,message)])
+     Is called to allow for cross-form validation. Use [http://tapestry.apache.org/tapestry5/tapestry-core/apidocs/org/apache/tapestry/corelib/components/Form.html#recordError(org.apache.tapestry.Field,%20java.lang.String) form.recordError(field,message)]) to record errors.
   *success -> calls onSuccess()
-     After all validation is passed.   
+     Is called after validation if no errors were recorded.
   *failure -> calls onFailure()
-     If there are validation errors.
+     Is called after validation if any errors were recorded.
   *submit -> calls onSubmit()
-     Allways called regardless of success or failure.
+     Is called last, regardless of success or failure.
- 
  
  ==== Context Information ====
  
+ Sometimes you need to store additional data in a form, like the primary key of an entity in a edit page. In such a case, use the context parameter of the form, and retrieve this parameter in one of the prepare events (prepareForRender, prepareForSubmit, prepare).
- Sometimes you need to store additional data in a form (like the primary key of an entity in a edit page)
- in such cases use the context parameter of the form, and retrieve this parameter with the onPrepare event.
- You can also use other event if you like.
  
- for example the template:
+ For example, the template:
  {{{
    <t:form t:id="form" t:context:"id">
-    
-   ...
+     ...
- 
    </t:form>
- 
  }}}
  
- and the page object:
+ And the page class:
  
  {{{
    private long id;
@@ -52, +48 @@

    void onPrepare(long id){
       this.id = id;
    }
- 
  }}}
  
  ==== Dealing with multiple forms ====
  
- It's a good idea to give an id to your forms, either in a component annotation in your code, or in the html template.
+ It's a good idea to give an id to your forms, either in a component annotation in your code, or in the template.
+ 
  Here's how it looks using annotations:
  {{{
-     @Component(id = "foo")
+   @Component(id = "foo")
-     private Form form;
+   private Form form;
  }}}
  
- Here's how it looks using your html template, Tapestry will create a form component because the component declaration and the form tag share the same id (actualy if you rename the form variable to foo you don't need the id parameter of the annotation).
+ Here's how it looks using your template, Tapestry will create a form component because the component declaration and the form tag share the same id. Actually, if you rename the form variable to foo you don't need the id parameter of the annotation.
  
  {{{
    <form t:id="foo">
-     ...stuff...
+     ...
    </form>
  }}}
  
  Now when you have ids for your forms, you probably want a specific method to get called when a particular form is acted on.
- Lets say we have forms with ids "foo" and "bar".
  
- If you have a method called onSubmit() or onSuccess(), etc, they will get called for either form. This happens even if the forms are inside  subcomponents on the page!
+ Lets say we have forms with ids "foo" and "bar". If you have a method called onSubmit() or onSuccess(), and so on, they will get called for either form. This happens even if the forms are inside  subcomponents on the page!
  
+ To make form "foo" call a specific method, add the id of the form to the end of the event like this: onEventFromFoo()
  
- 
- 
- To make form "foo" call a specific method, suffix the on{FormEventName}() with on{FormEventName}FromFoo(), where {FormEventName} is an event from the list given earlier.
- 
- i.e. To catch the submit event of a form with id="Foo", you can do this:
+ That is, to handle the submit event of a form with id="foo", you do this:
  {{{
- onSubmitFromFoo(){
+   onSubmitFromFoo(){
- //do things specific to form Foo
+     // do things specific to form Foo
- }
+   }
  }}}
  
  ==== Dealing with multiple submits ====
@@ -145, +137 @@

       }	
    }
  }}}
+ 
+ ==== Dealing with multiple submits in an AJAX form (zone parameter bound) ====
+ 
+ If you have an AJAX-enabled form:
+ 
+ {{{
+   <t:zone t:id="formzone">
+     <t:form t:id="form" t:zone="formzone">
+       ...
+ 
+       <t:submit t:id="save" value="Save"/>
+       <t:submit t:id="cancel" value="Cancel"/>
+     </t:form>
+   </t:zone>
+ }}}
+ 
+ There is currently a [https://issues.apache.org/jira/browse/TAPESTRY-2324 bug] in Tapestry (or, really, Prototype, one of the JavaScript libraries Tapestry uses) that prevents the correct events from being called.
+ 
+ You'll need to apply one of the patches found [https://issues.apache.org/jira/browse/TAPESTRY-2324 here] to Tapestry to make it work. Also, please vote to have the bug fixed.
+ 
  ==== Forms and Messages Resources (Internationalization) ====
  You can customize the field's label and validation messages used in a form, providing the followings entries in the properties file for the page.
  {{{

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org