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}