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}