org.apache.tapestry5.corelib.components

## Class EventLink

- java.lang.Object
- - org.apache.tapestry5.corelib.base.AbstractLink
  - - org.apache.tapestry5.corelib.base.AbstractComponentEventLink
    - - org.apache.tapestry5.corelib.components.EventLink

- All Implemented Interfaces:
    ClientElement

      public class EventLink
      extends AbstractComponentEventLink

  A close relative of `ActionLink` except in two ways. First, the event that it triggers is explicitly controlled, rather than always "action". Second, the event is triggered in its container. This allows slightly shorter URLs but also allows multiple components within the same container to generate identical URLs for common actions.

  Component Parameters
  Name | Type | Flags | Default | Default Prefix
  --- | --- | --- | --- | ---
  anchor | String |  |  | literal
  An anchor value to append to the generated URL (the hash separator will be added automatically).
  async | boolean | Since 5.4 |  | prop
  When true, the the link will trigger an asynchronous request (via XmlHttpRequest); the event handler method can make use of the org.apache.tapestry5.services.ajax.AjaxResponseRenderer in order to force content updates to the client. This is used as an alternative to placing the link inside a org.apache.tapestry5.corelib.components.Zone and binding the `zone` parameter.
  context | Object |  |  | prop
  The context for the link (optional parameter). This list of values will be converted into strings and included in the URI. The strings will be coerced back to whatever their values are and made available to event handler methods.
  disabled | boolean |  | false | prop
  If true, then then no link element is rendered (and no informal parameters as well). The body is, however, still rendered.
  event | String |  |  | literal
  The name of the event to be triggered in the parent component. Defaults to the id of the component. An org.apache.tapestry5.corelib.components.ActionLink triggers an "action" event on itself, and EventLink component triggers any arbitrary event on its container.
  parameters | java.util.Map | Not Null, Since 5.3 |  | prop
  If specified, the parameters are added to the link as query parameters in key=value fashion. Values will be coerced to string using value encoder; keys should be Strings.
  zone | String |  |  | literal
  Binding the zone parameter turns the link into a an Ajax control that causes the related zone to be updated.

  ### Examples

    This example is from Tapestry itself, from the GridColumns component that displays the columns titles across to the top of a Grid. We've simplified the example somewhat to focus in on the use of the EventLink component.

    ### GridColumns.tml

        <thead xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
            <tr>
                <th t:type="Loop" source="columnNames" value="columnName">
                    <a t:id="sort">${columnModel.label}</a>
                    <a t:id="sort2">
                        <img src="${icon}" id="${columnModel.id}:sort" class="t-sort-icon" alt="${iconLabel}"/>
                    </a>
                </th>
            </tr>
        </thead>

    ### GridColumns.java (partial)

        public class GridColumns
        {
            . . .

            @Component(parameters = {"event=sort", "context=columnModel.id"})
            private EventLink sort, sort2;

            void onSort(String columnId)
            {
                if (columnId.equals(sortColumnId))
                {
                    sortAscending = !sortAscending;
                }
                else
                {
                    sortColumnId = columnId;
                    sortAscending = true;
                }
            }

        }

    The advantage of the EventLink component is that instead of having two identical event handler methods, onActionFromSort() and onActionFromSort2(), we have a single event handler method, onSort(), that covers events triggered by either component. In addition, the URLs for the two components will be identical, whereas if using ActionLink components, the URLs would be slightly different, to reflect to two different component ids.

    This example also shows the advantages of defining the component in the Java class, using the @Component annotation, rather than in the template (as we do in most examples). We can simply define two fields with the same configuration.

  ### Notes

    The event parameter is often omitted; it defaults to the component's id ... you will often specify the component id, or a specific event name, but not both.

- - ### Field Summary

    - ### Fields inherited from class org.apache.tapestry5.corelib.base.AbstractLink

      `resources`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EventLink()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Link` | `createLink(java.lang.Object[] eventContext)` Invoked to create the Link that will become the href attribute of the output.

    - ### Methods inherited from class org.apache.tapestry5.corelib.base.AbstractLink

      `addParameters, getClientId, getLink, isDisabled, writeLink`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### EventLink

          public EventLink()

  - ### Method Detail

    - #### createLink

          protected Link createLink(java.lang.Object[] eventContext)

      Description copied from class: `AbstractComponentEventLink`
      Invoked to create the Link that will become the href attribute of the output.
      Specified by:
        `createLink` in class `AbstractComponentEventLink`
      Parameters:
        `eventContext` - the context as an object array, possibly null

${project.version} - Copyright © 2003-2015 The Apache Software Foundation.