Working with PrizmDoc > Developer Guide > Customizing the Viewing Client > Customization Examples > Adding Keyboard Shortcuts |
The Viewing Client 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:
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 Viewing Client’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 |
Number |
Keyboard Key Action Type |
Key Combinations |
Result |
1. |
‘keydown’ |
‘=’ |
zoomin |
2. |
‘keydown’ |
‘-’ |
zoomout |
Number |
Keyboard Key Action Type |
Key Combinations |
Result |
1. |
‘keydown’ |
‘delete’ |
Deletes selected marks |
All the following modal dialogs respond to the ‘esc’ key as if the ‘cancel’ button was pressed:
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. This file must be referenced in the Viewing Client’s start page( default.aspx for .NET sample, index.php in the PHP sample and index.jsp in JSP sample.
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 Viewing Client. |
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 Viewing Client, 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:
There are other things to consider too. Most browsers provide the following keyboard event types:
The implementation in the Viewing Client 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. |
First, set up the Viewing Client 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); }); |
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; } } |