This component is intended to give consistent user interface behaviour which allows easy and efficient form completion without using a mouse.
It achieves this by
- assuring focus starts in the first editable input element on the page
- allow traversing the (useable) form elements using tab or enter
- allow page submit by pressing ctrl-enter
To use it, include the following snippet in your template (probably the layout).
It is recommended to include this is late as possible in your layout to assure the focus is not changed by script code which is executed after this.
To assure the first item on the focus receives focus (as controlled by this component), you need to turn off the tapestry built-in autofocus behaviour.
This can be done by definint your form like this.
The exact behaviour is influenced by the class on the elements.
- defaultSubmit : the first element which can be found with this class is "clicked on" when the user presses ctrl-enter.
- eqTravSkip : any element marked with this class never receives focus (skip)
- eqTravFw : when going forward through the form using tab or enter, and an element with this class is encountered, then the element is "clicked on". This is for example used in the Tabs component to automatically move to the next tab.
- eqTravBw : when going backward through the form using shift-tab, and an element with this class is encountered, then the element is "clicked on". This is for example used in the Tabs component to automatically move to the next tab.
- eqTravMove : when an element is encountered with this class, then searching the next object continues at the object with the id given in the "href" attribute for the element (optionally preceded by a hash).
- eqTravEnter : when a textarea is marked using this class, then enter jumps to a new line in the form.
This key is used to submit the form. It looks for (the first) DOM object with class "defaultSubmit" and invokes that. You probably want to highlight that button.
To assure behaviour is consistent, pressing enter is (normally) considered the same as pressing tab.
When inside a textarea (which is not marked with the class "eqTravEnter"), the user should press shift-enter to go to a new line.
Differences with tab behaviour are
- shift-enter does not move backwards
- when pressing enter on an element marked with the class "defaultButton" then that element is "clicked on".
- when pressing enter in a textarea, focus is still moved to the next element, except when the element is marked using the "eqTravEnter" class.
This moves forward or backward through the page. It only considers visible, enabled links, buttons and form elements, with the extra handling based on the classes as mentioned above.
- 1. FormTraversal
- 1.1. ctrl-enter
- 1.2. enter
- 1.3. tab