Copyright 2012-2014 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
This module defines logical names for all events that Tapestry-controlled elements trigger or listener for. Prototype requires that all custom events have a namespace prefix; jQuery appears to allow it without issue.
Defines events related to the validation and submission of forms. See module
t5/core/forms for further details.
All events are triggered on a specific HTML
<form> element, and top-level handlers take it from there.
Triggered after fields have been validated, when there are no field validation exceptions, to allow for
cross-form validation. Passed a memo object: the handler should set the
error property of the memo
to true to indicate a validation exception occured, and the form submission should be prevented.
Triggered after fields and form have been validated, when there are field or form validation exceptions.
validate (when there are no prior validation exceptions), to allow certain elements
to configure themselves immediately before the form is submitted. This exists primarily for components such
as FormFragment, which will enable or disable a hidden field to match the visibility of the fragment.
There is no event memo.
Events releated to form input fields. Primarily, these events are related to form input validation. Validating a field involves three major steps:
Date, or a number
A field that is blank but not required is considered valid: the translate and validate steps are skipped.
When a validation error occurs, the event handler should present the validation error (see below), but also
false. This will prevent the event from propogating to other event handlers (Tapestry only supports
a single validation exception per field).
Presenting validation error: The event handler has two options for indicating a validation failure at any of the three steps:
errorproperty of the memo to true, and trigger the
showValidationErrorevent (or otherwise make the validation error visible)
errorproperty of the memo to the message to display; this will indicate a failure, and the
showValidationErrorevent will be triggered automatically.
falseto prevent the event bubbling (see note above).
Perform the optionality check. The event memo includes a
value property. If the field is required
but the value is blank, then a validation error should be presented (as described above). The
property of the memo is as described for the
Trigged by the field if there is a field value (a non-empty string, or a non-empty array in the case
of a select element). The event memo includes the field’s value as the
For text fields, the value is the text inside the field. For select elements, it is an array of the values
of selected options. If the element has the attribute
data-value-mode set to ‘options’, then the
value will be the array of all options (selected or not; this is provided for the core/Palette Tapestry
An event handler may update the event, setting the
translated property to an alternate formatting, or
alternate representation (e.g.,
Date, or a number) for the input value. If the input can not be translated,
then a validation error should be presented (as described above).
Triggered by the field if there is a field value, and the
translate event succeeded. The event memo
value' property, and atranslated` property. If any constraints on the field are invalid,
then the event handler should be presented (as described above).
Triggered by the form on all enclosed elements with the
data-validation attribute (indicating they are
interested in participating with user input validation). The default implementation fires a series of
validate. The latter two are always skipped if the input is blank, or if
a preceding event set the memo’s
error property to true. If all events complete without setting an error,
clearValidationError event is triggered, to remove any validation errors from previous
This event is passed a memo object; it should set the memo’s
error property to true if validation failed
for the field.
Clears and hides the element used to display validation error messages. There is no memo for this event. The p.help-block for the field is located (if it exists) and emptied and hidden. The containing .form-group element (if it exists) has its “has-error” class name removed.
Presents a validation error for a field. The event memo should have a
message key; the message to present
(as a string, or even as a detached DOM element). The help block for the field will be located or created,
made visible, and have its content updated to
memo.message. If a containing element has the class “.form-group”,
then the class “has-error” will be added; otherwise, the immediately containing element will have class “has-error”
added. The latter handles the case where, for layout reasons, the error container can not be inside the same
.form-group as the form control (this often happens when constructing horizontal forms).
The rules for locating the help block:
data-error-block-forset to the field’s
data-error-block-forattribute to the field’s
id(assigning a unique id to the field if not already present)
The rules for creating the help block:
data-error-block-forattribute set to the field’s id. The field will be assigned an id if necesary.
Events triggered by the Palette component.
Event triggered when the selection is about to change.
Event triggered after the Palette selection has changed.
Defines a number of event names specific to Tapestry Zones. Zones are Tapestry components that are structured
to correctly support dynamic updates from the server via an Ajax request, and a standard response
(the partial page render reponse). More details are available in the
Invoked on a zone element to force an update to its content. The event memo should contain a
content key (an
Element, or a
t5/core/dom:ElementWrapper, or more typically, a string containing HTML markup). A standard top-level
handler is defined by module
t5/core/zone, and is responsible for the actual update; it triggers the
events.zone.didUpdate events just before and just after changing the element’s
Triggered (by the standard
events.zone.update event handler) just before the content in a Zone will be updated.
Triggered (by the standard
events.zone.update event handle) just after the content in a Zone has updated.
If the zone was not visible, it is made visible after its content is changed, and before this event is triggered.
Some number of other components that also perform Ajax updates of the page also trigger this event.
Certain components bind this event to scan new additions to the page to see if certain structures exist and
create client-side support in the form of controllers and event handlers. DateField is one such example
Triggered on (or within) a zone element, the default handler will peform an Ajax request and, when the response is available,
update the zone (via
events.zone.update). The request should provide a partial page render response. If the
response includes a
content key, its value will be the markup to replace the zone element’s body.
Event names for arbitrary elements. These notifications exist primarily to allow for customizations in how certain behaviors are presented, for example, to add animation when certain elements are hidden or revealed.
Triggered when a hidden element has just been displayed.
Trigered when a visible element has just been hidden.
Event names specific to client-side element associated with the FormFragment component. These events exist to allow client code to cleanly adjust the visibility of the fragment, or remove it.
Requests that the fragment change its visibility. The event memo is an object with a single key, visible, a
boolean. The fragment will show or hide itself if necessary (triggering the
Event to scan inserted DOM content for components to initialize (see t5/core/dom:scanner)
initializeComponents : "t5:initializeComponents"