Keyboard focus

What is the focus?

In user interfaces, the focus usually refers to keyboard focus. A control is said to have focus when it currently receives keyboard input, whether for text entry or for manipulating the control itself (like using cursor keys to open a dropdown). Browsers usually indicate focus with a highlight:

XForms supports focus with a few constructs:

• the <xf:setfocus> action and the the xforms-focus event

• the DOMFocusIn and DOMFocusOut events

This page describes the behaviors associated with focus in the Orbeon Forms XForms engine.

Focusable controls

In Orbeon Forms, the following controls accept focus from the user:

• xf:input

• xf:secret

• xf:select/ xf:select1

• xf:trigger / xf:submit

• xf:textarea

• xf:upload

• XBL controls with the focus mode

Focus can only happen on those controls under the following conditions:

• The control is relevant.

• The control is not read-only.

• The control is not hidden, namely.

  • It is not in a hidden case.

  • It is not in a closed dialog.

The following controls never accept focus:

• xf:output

• grouping controls

  • xf:group

  • xf:switch / xf:case

  • xf:repeat

  • xxf:dialog

  • XBL controls without the focus mode

NOTE: While grouping controls never accept focus directly, XForms actions can be used to set focus to nested controls (see below).

User actions changing the focus

As a user, you can impact the focus in the following ways:

• by clicking inside a control (for example on an input field)

  • this removes focus from the previously focused control if any

  • then sets the focus to the clicked control

• by clicking outside of any controls

  • this removes focus from all controls

• by tabbing between fields, when enabled by the browser

  • this removes focus from the previously focused control

  • then sets the focus to the newly entered control

• by clicking outside of a control but within a repeat iteration

  • if focus was on a control within another repeat iteration, focus is moved to the new iteration's corresponding control

  • otherwise, focus is removed and the iteration becomes the new iteration

XForms actions changing the focus

xf:setfocus

Basic usage

The XForms <xf:setfocus> action allows the form author to change the focus to a particular control. It is similar to the HTML focus() function, with handling of grouping controls as a nice bonus feature.

Here is a basic use of the action:

<xf:input ref="name" id="name-input"/>

<xf:trigger>
    <xf:label>Focus</xf:label>
    <xf:setfocus event="DOMActivate" control="name-input"/>
</xf:trigger>

Grouping controls

You can also use the action on grouping controls, in which case it will set the focus to the first nested control able to accept focus:

<xf:group id="my-group">
    <xf:input ref="name" id="name-input"/>
    <xf:input ref="age" id="age-input"/>
</xf:group>

<xf:trigger>
    <xf:label>Focus</xf:label>
    <xf:setfocus event="DOMActivate" control="my-group"/>
</xf:trigger>

When the grouping control is a switch or a repeat, the focus naturally follows the selected case or the current repeat iteration, respectively. In this example, the focus will be set to the input control in the repeat iteration that matches the current repeat index:

<xf:repeat id="my-repeat" ref="person">
    <xf:input ref="name" id="name-input"/>
    <xf:input ref="age" id="age-input"/>
</xf:repeat>

<xf:trigger>
    <xf:label>Focus</xf:label>
    <xf:setfocus event="DOMActivate" control="my-repeat"/>
</xf:trigger>

Focusing only on xf:input

[DEPRECATED SINCE Orbeon Forms 2016.3. Use includes and excludes instead.]

The input-only extension attribute, when set to true, changes the behavior of the action by allowing focus only on the <xf:input> control. This means that buttons (<xf:trigger>) in particular are excluded.

This is convenient in particular to focus on the first control supporting input under a grouping control:

<xf:setfocus 
    control="my-group" 
    input-only="true"/>

This way, the user can use the keyboard right away, yet the programmer does not have to be specific as to which control must receive focus.

The attribute is an AVT.

Includes and excludes

[SINCE Orbeon Forms 2016.3]

The includes and excludes attribute allow filtering which controls are allowed to receive focus when using <xf:setfocus>.

• includes

  • list of control QNames to include

  • include all controls if missing or blank

• excludes

  • list of control QNames to exclude

  • exclude no controls if missing or blank

These attributes deprecate input-only="true" which is equivalent to includes="xf:input".

This allows focus on all controls except <xf:trigger>:

<xf:setfocus 
    control="my-group" 
    excludes="xf:trigger"/>

This allows focus on <xf:input> and <xf:textarea> only:

<xf:setfocus 
    control="my-group" 
    includes="xf:input xf:textarea"/>

xf:setindex

XForms enforces that, within a repeat, only a control part of the repeat iteration that matches the current repeat index can have focus.

This means that:

1. if the user clicks on a control within a repeat iteration, the focus changes to that control and the current iteration is adjusted

2. if the current repeat iteration changes, and focus was on a control within another iteration, the focus as adjusted

When using the <xf:setindex> action, the following logic takes place if the index changes:

• if the control with focus is within the old iteration, focus is removed from that control

• if possible (based on relevance, read-only, and visibility), focus is set to the corresponding control in the new iteration

xf:toggle and xxf:hide

Similarly to <xf:setindex>, XForms enforces that a control within a hidden case or dialog cannot have focus. If a focused control is within a case or dialog and the case is hidden via <xf:toggle> or the dialog closed via <xxf:hide>, focus is removed from that control.

xxf:show

When a dialog is opened with <xxf:show>, and focus was on a control outside the dialog, focus is first removed.

Then, focus is set to the dialog control itself, which means that the first focusable control within the dialog gets focus. This behavior can be overridden, as described further below.

xf:insert and xf:delete

The <xf:insert> and <xf:delete> actions can immediately:

• add or remove iterations

• change the current repeat index, depending on iterations added, removed, or moved

The following logic takes place:

• if the iteration has moved and the focused control is still focusable, keep the focus on that control

• if the iteration has moved and the focused control is no longer focusable, remove the focus

• if the iteration has been removed

  • remove focus from the control

  • try to find the corresponding control matching the current index, as for <xf:setindex>

    • if the control is found and focusable, focus on it

Focus change during refresh

Lots of things can change during refresh:

• controls might become non-relevant

• repeat iterations might be added, removed, or move

• with the XForms 2 @caseref attribute, cases can become hidden

Just after refresh, the focus is adjusted accordingly:

• for repeats, the same logic that applies to the <xf:insert> and <xf:delete> actions takes place

• otherwise, if focus was on a control that has become non-relevant, read-only, or hidden, focus is removed

Overriding the default focus behavior

Overriding focus behavior in dialogs

When a dialog opens, you can explicitly focus on a given control upon receiving the xxforms-dialog-open event. In this example, the form author sets focus on age-input instead of name-input (which would receive focus by default as it is the first control):

<xxf:dialog id="my-dialog">

    <xf:setfocus event="xxforms-dialog-open" control="age-input"/>

    <xf:input ref="name" id="name-input"/>
    <xf:input ref="age" id="age-input"/>

</xxf:dialog>

Overriding focus behavior in XBL components

You can override an XBL component's default focus behavior with an event handler. For example, to run JavaScript upon focus:

<xbl:handler event="xforms-focus" phase="target" defaultAction="cancel">
    <xxf:script id="xf-sf">YAHOO.xbl.fr.Currency.instance(this).setfocus();</xxf:script>
</xbl:handler>

Or, to focus to a specific nested control:

<xbl:handler event="xforms-focus" phase="target" defaultAction="cancel">
    <!-- Override default behavior and focus on search input -->
    <xf:setfocus control="search"/>
</xbl:handler>

In both cases, defaultAction="cancel" ensures that after the overridden behavior has completed, the default algorithm above does not take place.

The DOMFocusIn and DOMFocusOut events

These two events can be used to detect whether a control has lost or gained focus. For example:

<xf:input ref="name" id="name-input">
    <xf:action event="DOMFocusIn">
        ...
    </xf:action>
</xf:input>

When the XForms engine determines that a control must receive focus, it starts a sequence of events, as follows:

• dispatch DOMFocusOut to the control that previously had focus, if any

• dispatch DOMFocusOut to the ancestor grouping controls of the control that previously had focus, if any

• dispatch DOMFocusIn to the ancestor grouping controls of the control that is gaining focus, if any

• dispatch DOMFocusIn to the control that is gaining focus, if any

These two events bubble, so you have to be careful with event listeners. Often, it is a good idea to use the target attribute on event handlers to make sure that focus changes are detected on the expected control:

<xf:group id="my-group">
    <!-- Runs when focus enters the group, but not when focus changes from
         name-input to age-input or back -->
    <xf:action event="DOMFocusIn" target="my-group">
        ...
    </xf:action>

    <xf:input ref="name" id="name-input"/>
    <xf:input ref="age" id="age-input"/>

</xf:group>

The xforms-focus event

The xforms-focus event should usually be considered an internal event used by the xf:setfocus action. However, it is useful to know about this event in two situations:

• to prevent focus from taking place on a control or grouping control

• to override the focus behavior, as in the XBL component example described above

Algorithms for the xf:setfocus action and the xforms-focus event

• refresh models and view if needed

• resolve the target control attribute following Resolving ID References in XForms
• dispatch the xforms-focus event to that control
• the control then searches for the actual control to focus, if any, following the algorithm below

Orbeon Forms implements the following XForms 1.1-compatible behavior when receiving xforms-focus:

• For any control:

  • if the control is non-relevant, read-only, or not visible, processing of the event terminates and the focus is not changed

• If the target control is a core form control (such as <xf:input>):

  • focus is set to that control

• If the target control is one of the following container form control: <xf:group>, <xf:case>, <xxf:dialog>, or an XBL control:

  • children controls are recursively searched and the first descendant control able to receive focus receives focus

  • if there is no such control, processing of the event terminates

• If the target control is the <xf:switch> control:

  • the currently selected child <xf:case> control is recursively searched and the first descendant control able to receive focus receives it

  • If there is no such control, processing of the event terminates

• If the target control is the <xf:repeat> control:

  • the repeat iteration corresponding to the current repeat index is recursively searched and the first descendant control able to receive focus receives it.

  • if there is no such control, or if there is no iteration, processing of the event terminates

NOTE: the xforms-focus event does not bubble.