org.apache.tapestry5.corelib.components

## Class ActionLink

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

- All Implemented Interfaces:
    ClientElement

      @Events(value="action")
      public class ActionLink
      extends AbstractComponentEventLink

  Component that triggers an action on the server with a subsequent full page refresh.

  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.
  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.

  Component Events
  Name | Description
  --- | ---
  action |

  ### Examples

    In this example, we are showing part of a page to view and Account object, with an option to delete the Account.

    ### Account.java

        public class Account
        {
            public long id;

            public String userName;

        }

    ### ViewAccount.tml

        <html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
            <body>
                <h1>View Account #${account.id}</h1>

                <t:beandisplay object="account"/>

                <p>
                  [<t:actionlink t:id="delete" context="account.id">delete</t:actionlink>
                </p>
            </body>
        </html>

    We store the account's id as event context inside the URL. The account's id will be part of the URL and will be accessible when the event request is later triggered.

    ### ViewAccount.java

        public class ViewAccount
        {
            @Persist
            private Account account;

            @InjectPage
            private AccountsSummary accountsSummaryPage;

            @Inject
            private AccountDAO accountDAO;

            public Account getAccount() { return account; }

            Object onActionFromDelete(long accountId)
            {
                accountDAO.delete(accountId);

                accountsSummaryPage.setMessage(String.format("Account #%d has been deleted.", accountId));

                return accountsSummaryPage;
            }
        }

    The ActionLink component triggers an "action" event, which is matched by the onActionFromDelete() method. A real application might have other action links on the page, for (say) creating new accounts or other operations, thus we use the component's id ("delete") to ensure that the method is only invoked under the expected circumstances.

    Notice how the context (from when the link was rendered) now becomes parameters to the event handler method.

    The AccountDAO (data access object) service is responsible for the work, we then set a message on another page (the field for this message should be persistent) and return the page. Tapestry will send a redirect request to the client to display the page.

  ### Notes

    Rarely, you might need to pass more information in the context. For example, perhaps account id is not enought to uniquely identify the Account object in question - hypothetically, you may need to include a company id as well as the account id. You can build an object array to contain both values:

    You can do this in a template using the following syntax:

        <t:actionlink t:id="delete" context="[account.companyId, account.id]">delete ${company.name} / ${account.id}</t:actionlink>

            Object onActionFromDelete(long companyId, long accountId)
            {
                accountDAO.delete(companyId, accountId);

                accountsSummaryPage.setMessage(String.format("Account #%d has been deleted.", accountId));

                return accountsSummaryPage;
            }

    Alternatively, you can provide a getter which returns an object array.

            public Object[] getAccountContext()
            {
                return new Object[] { account.companyId, account.id };
            }

    In the template, this would be referenced as:

                <p>
                  [<t:actionlink t:id="delete" context="accountContext">delete</t:actionlink>
                </p>

    This pattern was more common in early versions of Tapestry; the older versions of the property expression language did not have the ability to create an array on the fly.

- - ### Field Summary

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

      `resources`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ActionLink()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Link` | `createLink(Object[] contextArray)` 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

    - #### ActionLink

          public ActionLink()

  - ### Method Detail

    - #### createLink

          protected Link createLink(Object[] contextArray)

      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:
        `contextArray` - the context as an object array, possibly null

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