Component events are Tapestry's way of conveying a user's interactions with the web page, such as clicking links and submitting forms, to designated methods in your page and component classes. When a component event is triggered, Tapestry calls the event handler method you've provided, if any, in the containing component's class.

Let's review look at a simple example. Here's a portion of the template for a page (let's call it "Review") that lists documents and lets a user click to edit any one of them.

...

Notice that Review.tml contains an ActionLink component in a loop. When rendered on the pageFor each rendering within the loop, the ActionLink component creates a component event request URL, with the event type set to "action". In this case the , each URL might look like:

    http://localhost:8080/review.edit/3

This URL identifies the page that contains the component ("review"), the Component id of the component within the page ("edit"), and the context value ("3", the "id" property of the document). Additional context values, if any, are appended to the path. (The URL may also contain the event name, unless, as here, it is "action".)

...

• Because of the annotation, it identifies method editDocument() as the method to invoke whenever the component whose ID is "edit" ActionLink component triggers an event.
• Because there is a method parameter, when the link is clicked the context value of the request is converted from a string to an integer and passed in as the method's value parameter.
  
  

In the above example, the editDocument() method will be invoked when any event occurs in in the "edit" component (and has at least one context value).

...

<t:eventlink event="delete" context="document.id">document.name</a>> ${document.name} </t:eventlink>

which is equivalent to:

<a t:type="eventlink" t:id="delete" context="document.id">document.name<> ${document.name} </a>

Note that if you omit the component part of the OnEvent annotation, then you'll receive notifications from all contained components, possibly including nested components (due to event bubbling).

...

This style of event handler methods start with the prefix "on", followed by the name of the event. You may then continue by adding "From" and a capitalized component id (remember that Tapestry is case insensitive about event names and component IDs). So, for example, a method named onActionFromSelectonValidateFromSave() , if it exists, is will be invoked whenever an Action a "Validate" event is triggered by the select componenta component whose component ID is "save".

The previous example may be rewritten as:

...

...

• Null: For no value, or null, the current page (the page containing the component) will render the response.
• Page: For the name of a page, or a page class or page instance, a render request URL will be constructed and sent to the client as a redirect to that page.
• URL: For a java.net.URL, a redirect will be sent to the client. (In Tapestry 5.3.x and earlier, this only works for non-Ajax requests.)
• Zone body: In the case of an Ajax request to update a zone, the component event handler will return the new zone body, typically via an injected component or block.
• HttpError: For an HttpError, an error response is sent to the client.
• Link: For a Link, a redirect is sent to the client.
• Stream: For a StreamResponse, a stream of data is sent to the client
• boolean: true prevents the event from bubbling up further; false lets it bubble up. See Event Bubbling, below.

...

• EventContext
• Object[]
• List<Object>

The latter two should be avoided, they may be removed in a future release. In all of these cases, the EventContext parameter acts as a freebie; it doesn't match against a context value as it represents all context values.

Object onActionFromEdit(EventContext 

Object onActionFromEdit(EventContext context)
{
    if (context.getCount() > 0) {
        this.selectedId = context.get(0);
        // do something with the document here
    } else {
        alertManager.warn("Please select a document.");
        return null;
    }
}

The latter two should be avoided, they may be removed in a future release. In all of these cases, the context parameter acts as a freebie; it doesn't match against a context value as it represents all context values.

Accessing Request Query Parameters

A parameter may be annotated with the @RequestParameter annotation; this allows query parameters (?name1=value1&name2=value2, etc) to be extracted from the request, converted to the correct type, and passed to the method. Again, this doesn't count against the event context valuescontext values.

See the example in the Link Components FAQ.

Method Matching

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.

...

When an event handler method throws an exception (checked or runtime), Tapestry gives the component and its containing page a chance to handle the exception, before continuing on to report the exception. Wiki Markup{float:right|background=#eee|padding=0 1em} *JumpStart Demo:* [Handling A Bad Context|http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/handlingabadcontext/1] {float}

Tapestry triggers a new event, of type "exception", passing the thrown exception as the context. In fact, the exception is wrapped inside a ComponentEventException, from which you may extract the event type and context.

...

If there is no exception event handler, or the exception event handler returns null (or is void), then the exception will be passed to the RequestExceptionHandler service, which (in the default configuration) will render the exception page.

Triggering Events

...

If you want your own component to trigger events, just call the triggerEvent method of ComponentResources from within the your component class.

For example, the following triggers an "updateAll" event. A containing component can then respond to it, if desired, with an "onUpdateAll()" method in its own component class.

...

The third parameter to triggerEvent is a ComponentEventCallback, which you'll only need to implement if you want to get the return value of the handler method. The return value of triggerEvent() says if the event was handled or not.