Author: hlship
Date: Mon Apr 19 16:19:09 2010
New Revision: 935653
URL: http://svn.apache.org/viewvc?rev=935653&view=rev
Log:
TAP5-943: Documentation for event handler methods should go into detail about
returns true or false
Modified:
tapestry/tapestry5/trunk/src/site/apt/guide/event.apt
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/ComponentEventCallback.java
Modified: tapestry/tapestry5/trunk/src/site/apt/guide/event.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/guide/event.apt?rev=935653&r1=935652&r2=935653&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/guide/event.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/guide/event.apt Mon Apr 19 16:19:09
2010
@@ -137,6 +137,24 @@ Event Handler Method Return Values
For page navigation events (originating in components such as ActionLink and
Form),
the value returned from an event handler method {{{pagenav.html}determines
how Tapestry will render a response}}.
+ Returning <<true>> from an event handler method will cancel event bubbling;
returning <<false>> is the same are returning null (or void).
+
+Event Bubbling
+
+ The event will bubble up the hierarchy, until it is aborted. The event is
aborted
+ when an event handler method returns a non-null value.
+
+ Returning a boolean value from an event handler method is special.
Returning <<true>> will abort the event
+ with no result; use this when the event is fully handled without a return
value and no further event handlers
+ (in the same component, or in containing components) should be invoked.
+
+ Returning <<false>> is the same as returning null; event processing will
continue to look for
+ more event handlers, in the same component or its parent.
+
+ When an event bubbles up from a component to its container, the origin of
the event is changed
+ to be the component. For example, a Form component inside a BeanEditForm
component may fire a success event. The page containing the BeanEditForm may
listen for that event, but it will be from the BeanEditForm component (which
makes sense, because the id of the Form inside the BeanEditForm is part
+ of the BeanEditForm's implementation, not its public interface).
+
Multiple Method Matches
In some cases, you may have multiple event methods match a single event.
@@ -200,6 +218,11 @@ Event Context
An event handler method will only be invoked
<if the context contains at least as many values as the method has
parameters>. Methods with too many parameters
will be silently skipped.
+
+ Parameters of type EventContext, List, or Object[], or parameters with the
@QueryParameter annotation
+ do not count against the event context count. The first three are used when
the event handler
+ method will adapt to any number of context values; the latter when the
method parameter value
+ doesn't come form the event context, but form a request query parameter.
* Collections
@@ -207,17 +230,6 @@ Event Context
change the method to accept a <single> parameter of type Object[], type
List, or type
{{{../apidocs/org/apache/tapestry5/EventContext.html}EventContext}}.
-Event Bubbling
-
- The event will bubble up the hierarchy, until it is aborted. The event is
aborted
- when an event handler method returns a non-null value.
-
- Returning a boolean value from an event handler method is special.
Returning true will abort the event
- with no result; use this when the event is fully handled without a return
value and no further event handlers
- (in the same component, or in containing components) should be invoked.
-
- Returning false is the same as returning null.
-
Event Method Exceptions
Event methods are allowed to throw any exception (not just runtime
exceptions). If an event method does
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/ComponentEventCallback.java
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/ComponentEventCallback.java?rev=935653&r1=935652&r2=935653&view=diff
==============================================================================
---
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/ComponentEventCallback.java
(original)
+++
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry5/ComponentEventCallback.java
Mon Apr 19 16:19:09 2010
@@ -27,14 +27,14 @@ public interface ComponentEventCallback<
* acceptable, and throw an exception if not. Any thrown exception will be
wrapped to identify the component and
* method from which the value was returned.
* <p/>
- * Boolean values are <em>not</em> passed to the handler. Booleans are
used to indicate that the event has been
+ * Boolean values are <em>not</em> passed to the callback. Booleans are
used to indicate that the event has been
* handled (true, meaning the event is handled and aborted) or that a
further search for handlers should continue
- * (false, meaning the event was not handler, is not aborted, and the
search up the component heirarchy for event
+ * (false, meaning the event was not handled, is not aborted, and the
search up the component hierarchy for event
* handler methods should continue). If a component event method returns
true, then
* {...@link org.apache.tapestry5.runtime.Event#isAborted()} will return
true.
*
* @param result
- * the result value return from the event handler method
+ * the result value returned from the event handler method
* @return true if the event is aborted, false if the event may continue
*/
boolean handleResult(T result);
