    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5;
    014
    015import org.apache.tapestry5.http.Link;
    016import org.apache.tapestry5.ioc.util.IdAllocator;
    017import org.apache.tapestry5.services.ComponentEventRequestParameters;
    018import org.apache.tapestry5.services.ComponentSource;
    019import org.apache.tapestry5.services.PageRenderRequestParameters;
    020
    021/**
    022 * Constant values for common event names fired by Tapestry components.
    023 */
    024public class EventConstants
    025{
    026    /**
    027     * Default client event name, "action", used in most situations.
    028     */
    029    public static final String ACTION = "action";
    030
    031    /**
    032     * Event triggered when a page is activated (for rendering). The component event handler will be
    033     * passed the context
    034     * provided by the passivate event.
    035     */
    036    public static final String ACTIVATE = "activate";
    037
    038    /**
    039     * Event triggered when a link for a page is generated. The event handler for the page may
    040     * provide an object, or an
    041     * array of objects, as the context for the page. These values will become part of the page's
    042     * context, and will be
    043     * provided back when the page is activated.
    044     */
    045    public static final String PASSIVATE = "passivate";
    046
    047    /**
    048     * Invoked before {@link #PREPARE} when rendering out the form.
    049     *
    050     * @see org.apache.tapestry5.corelib.components.Form
    051     */
    052    public static final String PREPARE_FOR_RENDER = "prepareForRender";
    053
    054    /**
    055     * Invoked before {@link #PREPARE} when the form is submitted.
    056     *
    057     * @see org.apache.tapestry5.corelib.components.Form
    058     */
    059    public static final String PREPARE_FOR_SUBMIT = "prepareForSubmit";
    060
    061    /**
    062     * Invoked to let the containing component(s) prepare for the form rendering or the form
    063     * submission.
    064     *
    065     * @see org.apache.tapestry5.corelib.components.Form
    066     */
    067    public static final String PREPARE = "prepare";
    068
    069    /**
    070     * Event type for a notification after the form has submitted. This event notification occurs on
    071     * any form submit,
    072     * without respect to "success" or "failure".
    073     *
    074     * @see org.apache.tapestry5.corelib.components.Form
    075     */
    076    public static final String SUBMIT = "submit";
    077
    078    /**
    079     * Event triggered when a client-side form is canceled. This occurs after page activation, and after
    080     * the prepare events for the form, but before any stored {@link ComponentAction}s for the form are triggered.
    081     *
    082     * @see org.apache.tapestry5.corelib.SubmitMode#CANCEL
    083     *
    084     * @since 5.2.0
    085     */
    086    public static final String CANCELED = "canceled";
    087
    088    /**
    089     * Event type for a notification after the form has submitted, when there are no errors in the
    090     * validation tracker.
    091     * This occurs before the {@link #SUBMIT} event.
    092     *
    093     * @see org.apache.tapestry5.corelib.components.Form
    094     */
    095    public static final String SUCCESS = "success";
    096
    097    /**
    098     * Event type for a notification after the form has been submitted, when there are errors in the
    099     * validation tracker.
    100     * This occurs before the {@link #SUBMIT} event.
    101     */
    102    public static final String FAILURE = "failure";
    103
    104    /**
    105     * Event type triggered by the {@link org.apache.tapestry5.corelib.components.Submit} component
    106     * when it is the cause
    107     * of the form submission.
    108     */
    109    public static final String SELECTED = "selected";
    110
    111    /**
    112     * Event triggered by some form-related components to parse a value provided by the client. This
    113     * takes the place of a {@link org.apache.tapestry5.Translator}.
    114     */
    115    public static final String PARSE_CLIENT = "parseClient";
    116
    117    /**
    118     * Event triggered by some form-related components to convert a server-side value to a
    119     * client-side string, as an
    120     * alternative to a {@link org.apache.tapestry5.Translator}.
    121     */
    122    public static final String TO_CLIENT = "toClient";
    123
    124    /**
    125     * Event triggered by form-related components to validate user input. In addition, the Form component
    126     * fires a validate event just before it fires {@link #SUCCESS} or {@link #FAILURE} as a chance
    127     * to perform cross-form validations.
    128     */
    129    public static final String VALIDATE = "validate";
    130
    131    /**
    132     * Event triggered by {@link org.apache.tapestry5.corelib.components.AjaxFormLoop} to inform the
    133     * container about the
    134     * row removed on the client side. The event context is the object that was removed.
    135     */
    136    public static final String REMOVE_ROW = "removeRow";
    137
    138    /**
    139     * Event triggered by {@link org.apache.tapestry5.corelib.components.AjaxFormLoop} to inform the
    140     * container that a new row has been requested. The return value from the event handler must be the newly created
    141     * object, which must
    142     * also be visible in the {@link org.apache.tapestry5.corelib.components.AjaxFormLoop#encoder} parameter.
    143     */
    144    public static final String ADD_ROW = "addRow";
    145
    146    /**
    147     * Event triggered by the {@link org.apache.tapestry5.corelib.components.Loop} component to
    148     * inform its container of
    149     * all the values that were supplied from the client during a form submission. The event handler
    150     * method should have
    151     * a single parameter, of type Object[] or type List, to receive the values.
    152     *
    153     * @since 5.1.0.0
    154     */
    155    public static final String SYNCHRONIZE_VALUES = "synchronizeValues";
    156
    157    /**
    158     * Event triggered by {@link org.apache.tapestry5.corelib.components.ProgressiveDisplay} component to inform its
    159     * container of what context (if any) is available. The event handler may return a renderable
    160     * object or null. If
    161     * null is returned, the component renders its own body as the partial markup response.
    162     *
    163     * @since 5.1.0.1
    164     */
    165    public static final String PROGRESSIVE_DISPLAY = "progressiveDisplay";
    166
    167    /**
    168     * Event triggered by an {@link org.apache.tapestry5.corelib.mixins.Autocomplete} mixin to
    169     * request completions of
    170     * the current input. The first value in the context is the input string; additional values
    171     * in the context parameter of the {@link org.apache.tapestry5.corelib.mixins.Autocomplete}
    172     * component.
    173     *
    174     * @since 5.1.0.4
    175     */
    176    public static final String PROVIDE_COMPLETIONS = "provideCompletions";
    177
    178    /**
    179     * Event triggered by {@link org.apache.tapestry5.corelib.components.Select} component to inform
    180     * its
    181     * container that Select's value has changed.
    182     *
    183     * @since 5.2.0
    184     */
    185    public static final String VALUE_CHANGED = "valueChanged";
    186
    187    /**
    188     * Event triggered during page render link generation. The first context parameter is the {@link Link} object, the
    189     * second is the {@link PageRenderRequestParameters} from which the Link
    190     * was created. The event is triggered on the actively rendering page.
    191     *
    192     * @since 5.2.0
    193     */
    194    public static final String DECORATE_PAGE_RENDER_LINK = "decoratePageRenderLink";
    195
    196    /**
    197     * Event triggered during component event link generation. The first context parameter is the {@link Link} object,
    198     * the second is the {@link ComponentEventRequestParameters} from which the Link
    199     * was created. The event is triggered on the actively rendering page, not necessarily the page
    200     * containing the component.
    201     *
    202     * @since 5.2.0
    203     */
    204    public static final String DECORATE_COMPONENT_EVENT_LINK = "decorateComponentEventLink";
    205
    206    /**
    207     * Name of a event triggered by the form component on the {@linkplain ComponentSource#getActivePage() active page}
    208     * to allow it to pre-allocate the names of any query parameters that might be used by the page for its own purposes
    209     * and should not be allocated to components. An {@link IdAllocator} is passed as the event context.
    210     *
    211     * @since 5.2.0
    212     */
    213    public static final String PREALLOCATE_FORM_CONTROL_NAMES = "preallocateFormControlNames";
    214
    215    /**
    216     * Event  triggered by the {@link org.apache.tapestry5.corelib.components.Tree}
    217     * component when a leaf node is selected.
    218     *
    219     * @since 5.3
    220     */
    221    public static final String NODE_SELECTED = "nodeSelected";
    222
    223    /**
    224     * Event  triggered by the {@link org.apache.tapestry5.corelib.components.Tree}
    225     * component when a leaf node is unselected.
    226     *
    227     * @since 5.3
    228     */
    229    public static final String NODE_UNSELECTED = "nodeUnselected";
    230
    231    /**
    232     * Event triggered by {@link org.apache.tapestry5.corelib.mixins.ZoneRefresh ZoneRefresh} to refresh the
    233     * {@link org.apache.tapestry5.corelib.components.Zone Zone}
    234     *
    235     * @since 5.3
    236     */
    237    public static final String REFRESH = "refresh";
    238}