focusable

An attribute which represents the focusable element. When you want to use key navigation, just add this attribute to target element.

 <div focusable></div>

All elements which are specified by this attribute automatically have three additional properties such as depth, group and name. By default, depth value will be 0 and group value will be 'default' and name value will be sequential string like 'focusable-0'.

These properties and their values are also stored in the element's data object through jQuery's .data() API. jQuery's .data() API will be automatically associated with HTML5 data attributes. (So this plug-in depends on jQuery 1.7 above.) So you can change these values like below. (Note that each property has 'focusable' prefix.)

 <div focusable data-focusable-depth="0" data-focusable-group="default" data-focusable-name="focusable-0"></div>

Of course, you can set those values to whatever you want.

 <div focusable data-focusable-depth="1" data-focusable-group="test" data-focusable-name="focus1"></div>

So then, what is 'depth', 'group' and 'name'?

The 'depth' is used when moving focus to another focusable element. The focus will be changed only between the same depth. So if there is no same depth focusable element, the focus will not be changed.

The 'group' separates focusable area semantically. Even if group is not equal to each other, the focus can be changed if each depth is same. Separating groups is useful when you manage each group's previous focusable element history by calling controller's 'setGroup API.

The 'name' is used when setting the next focus to the specific element, or changing focus to another focusable element by calling controller's 'focus' API. Each name should be an unique value.

If you need more information about the controller API, refer to the controller documentation.

This module automatically finds the nearest focusable element from the given direction using 'nearestFocusableFinder'. If you want to set the next focusable element manually, you can do it by using 'next-focus-direction' option. The direction values are 'left', 'right', 'up', 'down'.

 <div focusable data-focusable-name="focus1" data-focusable-next-focus-right="focus2"></div>
 <div focusable data-focusable-name="focus2"></div>

The 'next-focus-direction' option supports to change the group. You can change the group easily by concatenating 'group:' prefix and option value. (You can also change the group by using 'setGroup' API.)

 <div focusable data-focusable-group="test1" data-focusable-next-focus-down="group:test2"></div>
 <div focusable data-focusable-group="test2" data-focusable-next-focus-up="group:test1"></div>

If you do not want to change the focus to the specific direction anymore, set the corresponding 'next-focus-direction' option to null.

 <div focusable data-focusable-next-focus-left="null"></div>

You can set auto focus element by setting 'initial-focus' option to true.

 <div focusable data-focusable-initial-focus="true"></div>

The initial focus should be only one per depth and group. If you set multiple initial focus, the first matched focusable element will become an initial focus.

Every focusable element invokes event when focused, blurred or selected. So you can attach the event handler to receive corresponding events.

 $(document).ready(function() {
     $.caph.focus.init(function(nearestFocusableFinderProvider, controllerProvider) {
         controllerProvider.onFocused(function(event, originalEvent) {
             // your code
         });

         controllerProvider.onBlurred(function(event, originalEvent) {
             // your code
         });

         controllerProvider.onSelected(function(event, originalEvent) {
             // your code
         });
     });
 });

The event handler function can have two arguments such as 'event' and 'originalEvent'. The 'event' parameter is a custom jQuery event object such as 'focused', 'blurred' and 'selected'. So if you want to know where this event comes from, you should refer to the 'originalEvent'. The 'originalEvent' is real DOM jQuery event object such as 'keydown', 'mouseover', 'mouseout' and 'click'.

You can receive the events through attaching event handler to DOM directly.

 $('[focusable]').on('focused blurred selected', function(event) {
     // your code here
 });

Note that you should properly detach the appended event handlers by yourself when DOM is removed.

By default, add 'focused' class to focusable element when focused. If blurred, 'focused' class will be removed. So, if you define the corresponding 'focused' style, will be able to make focus effect without attaching event handlers.

All focusable elements are able to be disabled or enabled. If you want to enable or disable focusable element, change the 'disabled' option.

 <div focusable data-focusable-disabled="true"></div>

If you want to change the status, use controller's APIs. The controller conveniently provides 'enable' and 'disable' APIs for these functionality. See the controller documentation for more API details.

 <div focusable data-focusable-name="test" data-focusable-disabled="true"></div>

 $.caph.focus.controllerProvider.getInstance().enable('test');

When focusable element is disabled, 'disabled' class is added to it. If enabled, 'disabled' class will be removed.

By default, if a focusable element is disabled, it will no longer receive a focus event. But you can get a focus event even if focusable element is disabled, using the controller provider's 'setFocusWhenDisabled' API. See the controller provider documentation for more API details.