> {{{../tapestry-annotations/index.html#EventListener}EventListener}} core annotation documentation., {{{http://www.quirksmode.org/js/introevents.html}Quircksmode}}
At its core this new annotation allows you to bind client side events to page/component
{{{../UsersGuide/listenermethods.html}listener}} methods. "Client Side" events can have a lot
of different meanings. It could mean listening to function calls on a Tapestry
{{{../apidocs/org/apache/tapestry/dojo/IWidget.html}supported}} dojo widget,
or it could mean listening to changing field values in a Tapestry {{{../components/Form.html}Form}} component.
* Basic example, listening to DOM events
In this example we want to be notified whenever anyone moves their mouse over a particular
html element on our page.:
+-----------------------------------------------------------
....
Big brother is watching you.
....
+-----------------------------------------------------------
The java page class snippet required to bind to this event:
+-------------------------------------------------------------
....
@EventListener(elements = "myFavoriteDiv", events = "onmouseover")
public void watchText()
{
// do something
}
....
+-------------------------------------------------------------
That's it! If you'd like more contextual information, like what was happening
with the event that initiated the original client-side event just add a
{{{../apidocs/org/apache/tapestry/event/BrowserEvent.html}BrowserEvent}}
parameter to your listener and it will be automatically populated.
+-------------------------------------------------------------
....
@EventListener(elements = "myFavoriteDiv", events = "onmouseover")
public void watchText(BrowserEvent event)
{
// do something
System.out.println("User clicked on x/y coordinates "
+ event.getPageX() + "/" + event.getPageY());
}
....
+-------------------------------------------------------------
* Complex possibilities, binding widget functions to form submissions
Depending on the number of parameters you specify you can achieve some fairly
complicated <(under the covers at least)> logic with very little work.
** Listening to widget functions
In this example we want our {{{../UsersGuide/listenermethods.html}listener}} method to
be called when the {{{../apidocs/org/apache/tapestry/dojo/form/Autocompleter.html}Autocomplete}}
component on our page has selected an entry.
The relevant html:
+-----------------------------------------------------------------------
....
....
+-----------------------------------------------------------------------
The java page class snippet:
+-----------------------------------------------------------------------
....
@Component(bindings = { "model=projectModel", "value=selectedProject",
"displayName=message:choose.project", "filterOnChange=true",
"validators=validators:required"})
public abstract Autocompleter getProjectSelection();
@EventListener(targets = "projectChoose", events = "selectOption")
public void projectSelected()
{
// do something
}
....
+-----------------------------------------------------------------------
** Submitting forms when an event happens, and bypass client validation while you're at it
The last example was good for showing how to listen to widget function events, but what are you
supposed to do with an event that comes from a
{{{../apidocs/org/apache/tapestry/form/IFormComponent.html}IFormComponent}} that
doesn't also submit and update the form value that was changed?
To add automatic submission to our form we only need to modify the definition of our annotation
so that it also submits our form named <<>> before invoking our
{{{../UsersGuide/listenermethods.html}listener}}. <(asynchronously)>
+-----------------------------------------------------------------------
....
@EventListener(targets = "projectChoose", events = "selectOption",
submitForm = "myForm")
public void projectSelected()
{
// do something
}
....
+-----------------------------------------------------------------------
That's it! When your {{{../UsersGuide/listenermethods.html}listener}} is invoked you can be confident
that your <<>> {{{../apidocs/org/apache/tapestry/dojo/form/Autocompleter.html}Autocomplete}}
component has also been updated to reflect the currently selected value.
As an added bonus, form validation is turned off by default with the {{{../tapestry-annotations/index.html#EventListener}EventListener}}
annotation as the majority use case is likely to be one off individual events where invoking
client side validation would be a cumbersome experience for users.
* A note about event names
One common misunderstanding with EventListener is the exact syntax to use when listening to events.
The rules aren't very complicated, but there are two important differences:
* <> : These are events generated by actions people take in the web browser. Such events
might be Mouse,Keyboard,Focus,or any combination within. All are covered in the handy reference at
{{{http://www.quirksmode.org/js/introevents.html}Quircksmode.org}}. These events should almost always be
specified in all lowercase. Event though it is perfectly legal to do something like
<<>>, this is not the same thing that happens when you call
<<>> - which is more or less what Dojo is doing. Just keep
all of your event names in lowercase and you'll be ok.
* <> : Because the Dojo event connection system is so powerful it allows you to bind to more
than just native javascript events, like function calls on javascript functions. The example above referenced
the <<>> function for the Autocompleter widget. It valid/correct to use proper capital case
when referencing actual javascript functions on the client side.