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

    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

    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
    Copy Code
    <script src="viewer-assets/js/js/jQuery.hotkeys.js"></script>
    

     

    Do not obtain the file from CDN. 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.

    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.

    Example
    Copy Code
    $('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.

    Example
    Copy Code
    $(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. 

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