You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by jk...@apache.org on 2006/07/27 00:50:23 UTC
svn commit: r425891 - in /tapestry/tapestry4/trunk/src/site: apt/ajax/
apt/ajax/EventListener.apt apt/ajax/index.apt site.xml
Author: jkuhnert
Date: Wed Jul 26 15:50:22 2006
New Revision: 425891
URL: http://svn.apache.org/viewvc?rev=425891&view=rev
Log:
Added the start of XHR/DHTML guide.
Added:
tapestry/tapestry4/trunk/src/site/apt/ajax/
tapestry/tapestry4/trunk/src/site/apt/ajax/EventListener.apt
tapestry/tapestry4/trunk/src/site/apt/ajax/index.apt
Modified:
tapestry/tapestry4/trunk/src/site/site.xml
Added: tapestry/tapestry4/trunk/src/site/apt/ajax/EventListener.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/apt/ajax/EventListener.apt?rev=425891&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/apt/ajax/EventListener.apt (added)
+++ tapestry/tapestry4/trunk/src/site/apt/ajax/EventListener.apt Wed Jul 26 15:50:22 2006
@@ -0,0 +1,146 @@
+ ------
+Ajax/DHTML Guide - EventListener
+ ------
+Jesse Kuhnert
+ ------
+26 July 2006
+ ------
+
+EventListener, the swiss army knife of ajax functionality
+
+ The {{{../tapestry-annotations/index.html#EventListener}EventListener}} annotation is probably going to
+ be the most frequently used new feature <(if history from tacos users is any indicator)> in
+ Tapestry 4.1. It offers an awful lot, and is based around the functionality now familiar to many
+ in {{{http://dojotoolkit.org}dojo}}'s {{{http://manual.dojotoolkit.org/WikiHome/DojoDotBook/Book10}event API}}.
+
+ <<See also:>> {{{../tapestry-annotations/index.html#EventListener}EventListener}} core annotation documentation.
+
+ 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
+ {{{../tapestry-framework/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.:
+
++-----------------------------------------------------------
+....
+<body>
+
+ <div id="myFavoriteDiv">Big brother is watching you.</div>
+
+</body>
+....
++-----------------------------------------------------------
+
+ 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
+ {{{../tapestry-framework/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 {{{../tapestry-framework/apidocs/org/apache/tapestry/dojo/form/Autocompleter.html}Autocomplete}}
+ component on our page has selected an entry.
+
+ The relevant html:
+
++-----------------------------------------------------------------------
+....
+
+<form jwcid="myform@Form" clientValidationEnabled="true">
+ <fieldset>
+ Select a project:
+ <span jwcid="projectSelect" />
+ </fieldset>
+</form>
+
+....
++-----------------------------------------------------------------------
+
+ The java page class snippet:
+
++-----------------------------------------------------------------------
+....
+@Component(type = "Autocompleter", id = "projectSelect",
+ 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
+ {{{../tapestry-framework/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 <<<myform>>> 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 <<<projectSelect>>> {{{../tapestry-framework/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.
Added: tapestry/tapestry4/trunk/src/site/apt/ajax/index.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/apt/ajax/index.apt?rev=425891&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/apt/ajax/index.apt (added)
+++ tapestry/tapestry4/trunk/src/site/apt/ajax/index.apt Wed Jul 26 15:50:22 2006
@@ -0,0 +1,13 @@
+ ------
+Ajax/DHTML Guide - Introduction
+ ------
+Jesse Kuhnert
+ ------
+26 July 2006
+ ------
+
+Introduction
+
+ This section of the site is definitely a work in progress, but for now most people will find
+ the {{{EventListener.html}EventListener}} documentation particularly helpful.
+
\ No newline at end of file
Modified: tapestry/tapestry4/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/site.xml?rev=425891&r1=425890&r2=425891&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/site.xml (original)
+++ tapestry/tapestry4/trunk/src/site/site.xml Wed Jul 26 15:50:22 2006
@@ -74,6 +74,11 @@
<item name="Script Template DTD" href="/UsersGuide/script.html" />
</item>
+ <item name="XHR/DHTML Guide" href="/ajax/index.html" collapse="true">
+ <item name="Introduction" href="/ajax/index.html" />
+ <item name="EventListener" href="/ajax/EventListener.html" />
+ </item>
+
<item name="JavaScript Reference" href="/javascript/index.html" collapse="true">
<item name="Introduction" href="/javascript/index.html" />
<item name="Packaging" href="/javascript/packaging.html" />