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