PrizmDoc Viewer v13.18 Release - Updated
Developer Guide / Viewer / How to Customize the Viewer / Add Keyboard Shortcuts
In This Topic
    Add Keyboard Shortcuts
    In This Topic

    Introduction

    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

    Number Keyboard Action Key Combinations Result
    1. ‘keydown’ ‘pageup’ Scrolls the document one page up.
    2. ‘keydown’ ‘pagedown’ Scrolls the document one page down.
    3. ‘keydown’ ‘home’ document scrolls to the first page
    4. ‘keydown’ ‘end’ document scrolls to the last page
    5. "keydown" ‘ctrl+g’ puts the cursor in The Viewer’s ‘go to page’ edit box. It allows user to enter the page number to go to.
    6. "keydown" down arrow Scrolls the page down.
    7. ‘keydown’ up arrow Scrolls the current page up.
    8. ‘keydown’ left arrow Scrolls the displayed current page left.
    9. ‘keydown’ right arrow Scrolls the displayed current page right.

    Zoom in / Zoom out

    Number Keyboard Key Action Type Key Combinations Result
    1. ‘keydown’ ‘=’ zoomin
    2. ‘keydown’ ‘-’ zoomout

    Delete Selected Marks

    Number Keyboard Key Action Type Key Combinations Result
    1. ‘keydown’ ‘delete’ Deletes 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
    Number Keyboard Key Action Type Key Combinations Result
    1. ‘keydown’ ‘esc’ Closes the dialog. The result is equivalent to pressing the ‘cancel’ button.

    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.

    Example

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

    Do not obtain the file from CDN because it is broken. The non-minified version can be obtained from GitHub: https://github.com/jeresig/jquery.hotkeys This is a small file and it is recommended that you read all the details about the plugin before using it in your Viewer.

    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.

    The following example shows a snippet of code in the method initKeyBindings for the ‘pageup’ key support for scrolling one page up.

    Example

    $('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;
    });
    
    

    The following example shows how you can change the code above to trigger the event on the whole document object.

    Example

    $(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 you do not want the page navigation to occur when the modal dialogs are showing, in line 4, check for the visibility of the modal dialogs.

    Because the elements are divs and are not normally focusable, 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. 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 the ‘keyup’ event. The ‘keypress’ event is not used 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 before choosing key action and key combinations.

    The method initKeyBindings also contains some commented out code that demonstrates how to provide keyboard support for the buttons in the modal dialogs.

    Adding Keyboard Support without using jQuery.hotkeys Plugin

    First, set up the Viewer as you would normally.

    Example

    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

    This code does not check for modal dialogs but the check can be added as shown in the examples above.

    Example

    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;
       }
    }