Modules in Google Mashup Editor (GME) applications emit events to signal various actions, such as the user clicking a module or an item being saved. You can connect two modules, asking one to listen for events emitted by the other, and take some action when the event occurs. For example, you can connect a list to a map, and when the user clicks an item in the list, the map scrolls to display its selection in the center.
To make one module
handle events from another, you use the gm:handleEvent tag in
the module that is listening for an event. In our list and map example, we want the map to listen for an event emitted by the list when the user clicks a list item. When the map receives the event, we want the map to respond by scrolling to center itself on the selected item. To set this up, we add a gm:handleEvent tag to the gm:map tag, as in the following example:
|
<gm:page title="eventHandlingDemo" >
<table>
<tr>
<td width="300">
<gm:list id="myList" data="http://mapnut.com/calstatepark.xml"/>
</td>
<td width="600" valign="top">
<gm:map id="myMap" data="${myList}" latref="geo:lat" lngref="geo:long" maptypes="true">
<gm:handleEvent src="myList"/>
</gm:map>
</td>
</tr>
</table>
</gm:page>
By default, the gm:list, gm:map, and gm:calendar modules emit a select event
when the user clicks an item in the module.
If the user clicks in a gm:list module outside certain areas (such as checkbox or toggle controls), the list emits a select event. Similarly, when the user clicks a map pin in a gm:map module, the map emits a select event.
When a list is saved, the list and item emit a save event.
When a gm:list, gm:item, or gm:map module is refreshed, the module emits a repaint event after the module has been updated. (Note that repaint replaces the onrefresh event that was available in a previous version of GME. You should remove any uses of onrefresh in your applications and replace them with repaint.)
If you have a gm:search module and the user clicks it, it emits a submit event. You can create a custom event handler to receive and handle this event before the search takes place.
When you use a gm:handleEvent tag, by default it listens for select events. GME gives you the flexibility to specify a different event in your gm:handleEvent tag. To create a custom event handler, you specify the event type you're interested in as the value of the event attribute.
The gm:handleEvent tag includes an optional execute attribute that lets you specify what action to take when the event is received. To specify an execute attribute, include a JavaScript expression as the value of the execute attribute. The module calls the specified JavaScript expression when the event is received. If you don't specify an execute attribute, the module performs a default action; for example, a map module scrolls to display its selected pin on a select event.
All the attributes (src, event, and execute) are optional, but you must include at least one of them for the tag to have any function. Here's a description of the attributes:
src specifies the ID of the module you're listening to. If you don't include this attribute, you're listening to events from the module containing the gm:handleEvent tag.
event specifies the event type as a string.
If you don't include this attribute, you're listening for all events. Here are the event types and descriptions:select event on a list or map.refresh event from any module.cancel event, emitted by the cancel button.submit event emitted when the user clicks the search button in a gm:search. create event emitted by a gm:create.edit event emitted by a gm:editButtons.delete event emitted by a gm:editButtons.saveelement event emitted by a gm:item.save event emitted by a gm:editButtons.execute is a JavaScript expression evaluated when the given event is received. If you don't include this attribute, the event is handled by performing the module's default
action; for example, a map scrolls to its selected pin on select.
If you specify this attribute, the expression is executed. If it returns "true", the default action is performed; if "false", the default action is not performed.
event variableWhen you create a custom event handler, GME provides a variable named event, which gives you direct access to the event being handled. The event variable includes the type property, which is a string containing the event type. For select events, the entry property contains the event's entry object.
In the example below, we replaced the default event handler with a custom handler that pops up a JavaScript alert box:
<gm:page title="eventHandlingDemo" >
<table>
<tr>
<td width="50%">
<gm:list id="myList" data="http://mapnut.com/calstatepark.xml"/>
</td>
<td width="50%" valign="top">
<gm:map id="myMap" data="${myList}" latref="geo:lat" lngref="geo:long" maptypes="true">
<gm:handleEvent src="myList" event="select" execute="alert('Hello');"/>
</gm:map>
</td>
</tr>
</table>
</gm:page>