Fast Navigation

As described, some larger controls or containers already define F6 groups. If a group is defined on root level of a control or element, the group can be removed by using the CustomData mechanism.

Coding Example

oControl.data("sap-ui-fastnavgroup", "false", true/*Write into DOM*/);

XML View Example

<mvc:View
  xmlns:core="sap.ui.core"
  xmlns:mvc="sap.ui.core.mvc"
  xmlns="sap.m">
  <Panel>
    <headerToolbar>
      <Toolbar>
        <Button icon="sap-icon://settings" />
      </Toolbar>
    </headerToolbar>
    <content>
      <Text text="Lorem ipsum dolor st amet..." />
    </content>
    <customData>
      <core:CustomData key="sap-ui-fastnavgroup" value="false" writeToDom="true" />
    </customData>
  </Panel>
</mvc:View>

The same way it is possible to make a control or element to be an F6 group. However, keep in mind that not all elements are represented in the DOM.

Coding Example:

oControl.data("sap-ui-fastnavgroup", "true", true/*Write into DOM*/);

XML View Example

<mvc:View
  xmlns:core="sap.ui.core"
  xmlns:mvc="sap.ui.core.mvc"
  xmlns="sap.m">
  <Panel>
    <headerToolbar>
      <Toolbar>
        <Button icon="sap-icon://settings" />
      </Toolbar>
    </headerToolbar>
    <content>
      <Text text="Lorem ipsum dolor st amet..." />
    </content>
    <customData>
      <core:CustomData key="sap-ui-fastnavgroup" value="true" writeToDom="true" />
    </customData>
  </Panel>
</mvc:View>

Also, DOM elements that are not controlled by SAPUI5 controls can be grouped by setting data-sap-ui-fastnavgroup="true".

Basically, an F6 group is defined via the attribute data-sap-ui-fastnavgroup="true" on a DOM element. Several options exist to implement fast navigation support in controls:

Defining an F6 group on control or element root level:

This is the preferred option and can be used for many use cases. If a control or an element with a DOM representation wants to define an F6 group on its root element, use the CustomData mechanism in the init function of the control or element to set the attribute.

init = function(){
  //...
  this.data("sap-ui-fastnavgroup", "true", true/*Write into DOM*/);
  //...
};

The RenderManager writes the attribute automatically during rendering when the writeControlData or writeElementData is called. The application can also change the custom data if desired.

Defining the F6 Group Within a Control

During rendering of a control, the attribute can also be written to any arbitrary DOM element of the control.

render = function(oRenderManager, oControl){
  //...
  oRenderManager.writeAttribute("data-sap-ui-fastnavgroup", "true");
  //...
};

Custom F6 Handling

It may be necessary that a control has to provide a custom fast navigation handling, for example, if the DOM structure of the control does not allow to define suitable navigation groups with one of the options described above. The following picture shows how the central fast navigation handling (a) outside the control collaborates with the custom handling inside the control.

To implement custom fast navigation handling, start with flagging the control as a custom handling area:

render = function(oRenderManager, oControl){
  //...
  oRenderManager.writeControlData(oControl);
  oRenderManager.writeAttribute("data-sap-ui-customfastnavgroup", "true"); //Attribute must be on the root element of the control.
  //...
};

To implement the custom F6 behavior within the control (d), use the event handlers onsapskipforward (F6) and onsapskipback (Shift+F6). When preventDefault is called on the provided event, the central fast navigation handling ignores the event.

The interesting point is the collaboration (b, c) between the control and the central fast navigation handling.

onsapskipforward = function(oEvent){ //F6
  var oTarget = findNextDomRefToFocus(oEvent.target); //Search for the next DOM element within the control which should be focused.
  if(!oTarget){
    //target is in the last group -> focus should jump to the first group after the control (done by the central handling, preventDefault not called)
  }else{
    oEvent.preventDefault();
    jQuery.sap.focus(oTarget);
  }
};

onsapskipback = function(oEvent){ //Shift+F6
  var oTarget = findPreviousDomRefToFocus(oEvent.target); //Search for the previous DOM element within the control which should be focused.
  if(!oTarget){
    //target is in the first group -> focus should jump to the first group before the control (done by the central handling, preventDefault not called)
  }else{
    oEvent.preventDefault();
    jQuery.sap.focus(oTarget);
  }
};

If the focus resides within the control and jumps out of the control (b) when pressing F6 or Shift+F6, the onsapskipforward and onsapskipback events should not be handled (no preventDefault call).

If the focus resides outside the control and the central fast navigation handling calculates a target to focus within the control, the central handling first calls the event handler onBeforeFastNavigationFocus (if available) on the control (c1, c2) that is flagged as a custom handling area. The provided event has the following attributes:

• target: Specifies the DOM element that the central handling tries to focus within the custom handling area

• source: Specifies the DOM element which is the starting point for the calculation of the next/previous element to focus; this is usually the element that is currently focused

• forward: Specifies whether forward (F6) or backward (Shift+F6) navigation is used

If preventDefault is called on BeforeFastNavigationFocus, setting the focus on the target by the central handling is skipped.

onBeforeFastNavigationFocus = function(oEvent){
  var oTarget;
  if (jQuery.contains(this.getDomRef(), oEvent.source)) {
    //The source is within the custom area (e.g. might happen when the focus is on a popup which is attached to an element within the custom area)
    oTarget = oEvent.forward ? findNextDomRefToFocus(oEvent.source) : findPreviousDomRefToFocus(oEvent.source);
  }else{
    //The source is outside of the custom area
    oTarget = oEvent.forward ? findFirstDomRefToFocus() : findLastDomRefToFocus();
  }
  if(oTarget){
    oEvent.preventDefault();
    jQuery.sap.focus(oTarget);
  }
};