Customizing Keyboard Support in the Viewer

The Viewer includes support for some keyboard shortcuts. This topic will walk through how the jQuery.hotkeys plugin (https://github.com/jeresig/jquery.hotkeys) is used to support adding keyboard shortcuts, as well as how easy it is to remove the built-in keyboard support.

The current implementation represents some (but not all) that can be accomplished with keyboard shortcuts. The currently supported keyboard combinations are detailed in the tables below:

Keyboard Key Combinations for Page Navigation

Zoom in / Zoom out

Delete Selected Marks

Modal Dialogs

All the following modal dialogs respond to the ‘esc’ key as if the ‘cancel’ button was pressed:

1. e-signature dialog
2. Image stamp selection dialog
3. Page redaction dialog
4. Download  document dialog
5. Print dialog
6. About box

The viewer.js contains a method, initKeyBindings, that contains the code to handle the keyboard support as described in the above tables. This method is called in the initializeViewer method. In order for the keyboard shortcuts to work, jQuery.hotkeys.min.js file is required. This file must be referenced in The Viewer’s start page( default.aspx for .NET sample, index.php in the PHP sample and index.jsp in JSP sample.

<script src="viewer-assets/js/js/jQuery.hotkeys.js"></script>

If you either have your own implementation of the keyboard support or prefer not use this implementation in the viewer.js, simply comment out the call to initKeyBindings() in the initializeViewer method. Also, you can choose to remove the initKeyBindings method definition completely from your copy of the viewer.js.

As an example, let us walk through a snippet of code in the method initKeyBindings for the ‘pageup’ key support for scrolling one page up.

$('body').on('keydown', null, 'pageup', function () {
    if ($(viewer.viewerNodes.$pageList[0]).is(':visible')) {
            //make sure modals are not up
            if (!$(viewer.viewerNodes.$overlayFade[0]).is(':visible')) {
                   //change to the previous page
                   viewer.viewerControl.changeToPrevPage();
                   return false;
            }
       }
       return true;
});

We can also change the code above to trigger the event on the whole document object.

$(document).on('keydown', null, 'pageup', function () {
   if ($(viewer.viewerNodes.$pageList[0]).is(':visible')) {
        //make sure modals are not up
        if (!$(viewer.viewerNodes.$overlayFade[0]).is(':visible')) {
              //change to the previous page
              viewer.viewerControl.changeToPrevPage();
              return false;
         }
    }
    return true;
});

In the above example, line 1 binds the keydown action of the ‘pageup’ key to the in-line handler. For the Viewer, the node with the selector attribute ‘pageList’ is the parent node. Therefore, the handler code checks to see if this node is visible. Also, since we do not want the page navigation to occur when the modal dialogs are showing, in line 4, we check for the visibility of the modal dialogs.

Because our elements are divs and are not normally focusable, we use a wider net and use ‘body’ as the target node of the key events. When nothing in particular has focus, document.body acts as a target node of key events. You can choose to bind to other elements beside the ‘body’ but you may need to give it a tab index. But be mindful, it may not provide expected results in all the browsers. Most browsers have native keyboard focusable support for the following element types:

1. Input elements
2. Buttons
3. link elements

There are other things to consider too. Most browsers provide the following keyboard event types:

1. ‘keydown’
2. ‘keyup’
3. ‘keypress’

The implementation in the Viewer uses ‘keydown’ key action. In some cases you may want to use ‘keyup’ event. We are not using the ‘keypress’ event at all since it is mainly used for capturing key characters entered in the input elements. Not all browsers are consistent in providing key events for all the keys or key combinations. Some browsers will not allow to override their default behavior for a particular key combinations. You may need to experiment/research a little before choosing key action and key combinations. 

Adding Keyboard Support without using jQuery.hotkeys Plugin

First, set up the Viewer as you would normally.

function initKeyBindings (viewerControl) {
  var handler = function(ev){
    return handleGlobalKeypress(ev, viewerControl); 
  };
   
  $(document).on("keydown", handler);
}

var pluginOptions = {
  documentID: viewingSessionId,
  language: languageItems,
  template: htmlTemplates
};

$(document).ready(function () {
  var viewerControl = $("#viewer1").pccViewer(pluginOptions).viewerControl;
   
  initKeyBindings(viewerControl);
});

Example Code for using pageup and pagedown Keys

function handleGlobalKeypress (ev, viewerControl) {
  //check for keys
   switch (ev.keyCode) {
     case 33: // Page Up
       ev.preventDefault();
       viewerControl.changeToPrevPage();
       return false;
     case 34: //Page Down
       ev.preventDefault();
       viewerControl.changeToNextPage();
       return false;
   }
}