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 }