    001    // Copyright 2008, 2009, 2010, 2011 The Apache Software Foundation
    002    //
    003    // Licensed under the Apache License, Version 2.0 (the "License");
    004    // you may not use this file except in compliance with the License.
    005    // You may obtain a copy of the License at
    006    //
    007    // http://www.apache.org/licenses/LICENSE-2.0
    008    //
    009    // Unless required by applicable law or agreed to in writing, software
    010    // distributed under the License is distributed on an "AS IS" BASIS,
    011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012    // See the License for the specific language governing permissions and
    013    // limitations under the License.
    014
    015    package org.apache.tapestry5;
    016
    017    import org.apache.tapestry5.corelib.components.BeanEditForm;
    018    import org.apache.tapestry5.ioc.util.IdAllocator;
    019    import org.apache.tapestry5.services.ComponentEventRequestParameters;
    020    import org.apache.tapestry5.services.ComponentSource;
    021    import org.apache.tapestry5.services.PageRenderRequestParameters;
    022
    023    /**
    024     * Constant values for common event names fired by Tapestry components.
    025     */
    026    public class EventConstants
    027    {
    028        /**
    029         * Default client event name, "action", used in most situations.
    030         */
    031        public static final String ACTION = "action";
    032
    033        /**
    034         * Event triggered when a page is activated (for rendering). The component event handler will be
    035         * passed the context
    036         * provided by the passivate event.
    037         */
    038        public static final String ACTIVATE = "activate";
    039
    040        /**
    041         * Event triggered when a link for a page is generated. The event handler for the page may
    042         * provide an object, or an
    043         * array of objects, as the context for the page. These values will become part of the page's
    044         * context, and will be
    045         * provided back when the page is activated.
    046         */
    047        public static final String PASSIVATE = "passivate";
    048
    049        /**
    050         * Invoked before {@link #PREPARE} when rendering out the form.
    051         *
    052         * @see org.apache.tapestry5.corelib.components.Form
    053         */
    054        public static final String PREPARE_FOR_RENDER = "prepareForRender";
    055
    056        /**
    057         * Invoked before {@link #PREPARE} when the form is submitted.
    058         *
    059         * @see org.apache.tapestry5.corelib.components.Form
    060         */
    061        public static final String PREPARE_FOR_SUBMIT = "prepareForSubmit";
    062
    063        /**
    064         * Invoked to let the containing component(s) prepare for the form rendering or the form
    065         * submission.
    066         *
    067         * @see org.apache.tapestry5.corelib.components.Form
    068         */
    069        public static final String PREPARE = "prepare";
    070
    071        /**
    072         * Event type for a notification after the form has submitted. This event notification occurs on
    073         * any form submit,
    074         * without respect to "success" or "failure".
    075         *
    076         * @see org.apache.tapestry5.corelib.components.Form
    077         */
    078        public static final String SUBMIT = "submit";
    079
    080        /**
    081         * Event triggered when a client-side form is canceled. This occurs after page activation, and after
    082         * the prepare events for the form, but before any stored {@link ComponentAction}s for the form are triggered.
    083         *
    084         * @see org.apache.tapestry5.corelib.SubmitMode#CANCEL
    085         *
    086         * @since 5.2.0
    087         */
    088        public static final String CANCELED = "canceled";
    089
    090        /**
    091         * Event type for a notification after the form has submitted, when there are no errors in the
    092         * validation tracker.
    093         * This occurs before the {@link #SUBMIT} event.
    094         *
    095         * @see org.apache.tapestry5.corelib.components.Form
    096         */
    097        public static final String SUCCESS = "success";
    098
    099        /**
    100         * Event type for a notification after the form has been submitted, when there are errors in the
    101         * validation tracker.
    102         * This occurs before the {@link #SUBMIT} event.
    103         */
    104        public static final String FAILURE = "failure";
    105
    106        /**
    107         * Event type triggered by the {@link org.apache.tapestry5.corelib.components.Submit} component
    108         * when it is the cause
    109         * of the form submission.
    110         */
    111        public static final String SELECTED = "selected";
    112
    113        /**
    114         * Event triggered by some form-related components to parse a value provided by the client. This
    115         * takes the place of a {@link org.apache.tapestry5.Translator}.
    116         */
    117        public static final String PARSE_CLIENT = "parseClient";
    118
    119        /**
    120         * Event triggered by some form-related components to convert a server-side value to a
    121         * client-side string, as an
    122         * alternative to a {@link org.apache.tapestry5.Translator}.
    123         */
    124        public static final String TO_CLIENT = "toClient";
    125
    126        /**
    127         * Event triggered by form-related components to validate user input. In addition, the Form component
    128         * fires a validate event just before it fires {@link #SUCCESS} or {@link #FAILURE} as a chance
    129         * to perform cross-form validations.
    130         */
    131        public static final String VALIDATE = "validate";
    132
    133        /**
    134         * Event triggered by {@link org.apache.tapestry5.corelib.components.AjaxFormLoop} to inform the
    135         * container about the
    136         * row removed on the client side. The event context is the object that was removed.
    137         */
    138        public static final String REMOVE_ROW = "removeRow";
    139
    140        /**
    141         * Event triggered by {@link org.apache.tapestry5.corelib.components.AjaxFormLoop} to inform the
    142         * container that a new row has been requested. The return value from the event handler must be the newly created
    143         * object, which must
    144         * also be visible in the {@link org.apache.tapestry5.corelib.components.AjaxFormLoop#encoder} parameter.
    145         */
    146        public static final String ADD_ROW = "addRow";
    147
    148        /**
    149         * Event triggered by the {@link org.apache.tapestry5.corelib.components.Loop} component to
    150         * inform its container of
    151         * all the values that were supplied from the client during a form submission. The event handler
    152         * method should have
    153         * a single parameter, of type Object[] or type List, to receive the values.
    154         *
    155         * @since 5.1.0.0
    156         */
    157        public static final String SYNCHRONIZE_VALUES = "synchronizeValues";
    158
    159        /**
    160         * Event triggered by {@link org.apache.tapestry5.corelib.components.ProgressiveDisplay} component to inform its
    161         * container of what context (if any) is available. The event handler may return a renderable
    162         * object or null. If
    163         * null is returned, the component renders its own body as the partial markup response.
    164         *
    165         * @since 5.1.0.1
    166         */
    167        public static final String PROGRESSIVE_DISPLAY = "progressiveDisplay";
    168
    169        /**
    170         * Event triggered by an {@link org.apache.tapestry5.corelib.mixins.Autocomplete} mixin to
    171         * request completions of
    172         * the current input. The context is the partial string provided by the client.
    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    }