events.coffee

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

http:#www.apache.org/licenses/LICENSE-2.0

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.

t5/core/events

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 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:

• optional - check for a required field that has no value
• translate - translate a string to another representation, such as Date, or a number
• validate - validate the field against any number of other constraints (such as ranges)

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 return 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:

• set the error property of the memo to true, and trigger the showValidationError event (or otherwise make the validation error visible)
• set the error property of the memo to the message to display; this will indicate a failure, and the showValidationError event will be triggered automatically.
• In addition, return false to 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 value property of the memo is as described for the translate event.

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 value property. 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 component).

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 includes a 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 events: optional, translate, 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, then the clearValidationError event is triggered, to remove any validation errors from previous validation cycles.

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:

• Search for element with attribute data-error-block-for set to the field's id attribute
• If not found, find the enclosing .form-group element
• Search the form group for an element with attribute data-presentation="error"
• Otherwise, it is not found (but may be created dynamically)
• If found, set the data-error-block-for attribute to the field's id (assigning a unique id to the field if not already present)

The rules for creating the help block:

• The element is created as p.help-block with data-error-block-for attribute set to the field's id. The field will be assigned an id if necesary.
• Normally, the block is inserted immediately after the field
• If the field's immediate container has class "input-group", then the block is inserted after the container

Events triggered by the Palette component.

Event triggered when the selection is about to change.

• memo.selectedOptions - array of selected options (e.g., HTMLOptionElement) representing which options will be selected in the Palette, should the change be allowed.
• memo.reorder - if true, then the event represents changing the order of the selections only
• memo.cancel - function to invoke to prevent the change to the Palette from occurring
• memo.defer - like cancel, but returns a no-arguments function that will perform the update at a later date (e.g., after a confirmation panel)

Event triggered after the Palette selection has changed.

• memo.selectedOptions - array of selected options (e.g., HTMLOptionElement)
• memo.reorder - if true, the event represents a change in the order of selections only

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 t5/core/zone module.

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.willUpdate and events.zone.didUpdate events just before and just after changing the element's content.

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 (see t5/core/datefield module).

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.

• memo.url - URL to use for the Ajax request
• memo.parameters - (optional) additional query parameters for the request

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 element.didShow or element.didHide event).