Framework-agnostic JavaScript scan-events for hardware barcode scanners.

1. Install via npm install onscan.js or bower install onscan-js
2. Include onscan.min.js in your script
3. Add the following initilization script to run on page/view load.

// Enable scan events for the entire document
onScan.attachTo(document);
// Register event listener
document.addEventListener('scan', function(sScancode, iQuantity) {
    alert(iQuantity + 'x ' + sScancode); 
});

Online demo

A similar demo is available within the package: just load index.html from the lib's folder to play around with the settings on your own server.

1. A hardware barcode scanner, that
   • acts as a keyboard (often called keyboard-wedge-mode), or
   • pastes the scanned codes (clipboard-mode)
2. A more-or-less modern browser (IE9+)

onScan.js attempts to distinguish between regular input and scan input by measuring input spead, looking for certain prefix and suffix characters, etc. If a scan is detected, it triggers a custom JavaScript event called scan for the DOM element specified during initialization.

There are lot's of options to fine-tune detection of specific scanner models.

There are also a couple of usefull extras (some requiring specifc hardware):

• Passing a counter along with the scanned code
• Adding a secondary action to the hardware button of built-in scanners, if it is long pressed

// Initialize with options
onScan.attachTo(document, {
    suffixKeyCodes: [13], // enter-key expected at the end of a scan
    reactToPaste: true, // Compatibility to built-in scanners in paste-mode (as opposed to keyboard-mode)
    onScan: function(sCode, iQty) { // Alternative to document.addEventListener('scan')
        console.log('Scanned: ' + iQty + 'x ' + sCode); 
    },
    onKeyDetect: function(iKeyCode){ // output all potentially relevant key events - great for debugging!
        console.log('Pressed: ' + iKeyCode);
    }
});

// Simulate a scan programmatically - e.g. to test event handlers
onScan.simulate(document, '1234567890123');

// Change options on-the-fly
onScan.setOptions(document, {
    singleScanQty: 5 // change the quantity to 5 for every scan
});

// Remove onScan.js from a DOM element completely
onScan.detachFrom(document);

The following options can be set when initializing onScan.js:

You can register regular event listeners on the DOM element, onScan was initialized for:

document
    .addEventListener('scan', function(sScanned, iQty){ ... });
    .addEventListener('scanError', function(oDebug){ ... });
    .addEventListener('scanButtonLongPressed', function(){ ... });

You can also define callback directly in the options, when initializing onScan:

onScan.attachTo(document, {
    onScan: function(sScanned, iQty) { ... },
    onScanError: function(oDebug) { ... },
    onScanButtonLongPress: function() { ... },
    onKeyDetect: function(iKeyCode, oEvent){ ... }
    onKeyProcess: function(sChar, oEvent){ ... }
    onPaste: function(sPasted){ ... }
});

Note: there are more callbacks in the options, than event types. The non-event callbacks are primarily usefull for testing and finding the right configuration for a specific scanner - see playgournd for examples.

By default, onScan.js ignores any key codes other than those matching letters and numbers. The latter are transformed into characters using built-in browser logic. These key codes are converted to characters:

• 48-90 (letters and regular numbers)
• 96-105 (numeric keypad numbers)
• 106-111 (numeric keypad operations)

This should work for the vast majority of cases. However, if you encounter strange extra characters in the codes read or miss some characters (like hypens), you can override the default decoding algorithm by specifying a custom keyCodeMapper like this:

onScan.attachTo(document, {
    onScan: function(sScanned, iQty) { ... },
    keyCodeMapper: function(oEvent) {
		// Look for special keycodes or other event properties specific to
		// your scanner
		if (oEvent.which = 'your_special_key_code') {
			return 'xxx';
		}
		// Fall back to the default decoder in all other cases
		return onScan.decodeKeyEvent(oEvent);
    }
});

Background: Barcode scanners operating in keyboard-mode (as opposed to clipboard-mode) work by simulating pressing keyboard keys. They send key codes and the browser interprets them as input. This works great for letters and numbers. However, many barcode scanners also send additional characters depending on their configuration: e.g. the trailing enter (key code 13), prefix or suffix codes, delimiters, and even their own "virtual" key codes. There are also cases, when key codes are used in a non-standard way. All these cases can be easily treated using a custom keyCodeMapper as shown above.

This library was inspired by the jQuery plugin jQuery ScannerDetection by Julien Maurel.

See HISTORY.md.

onScan.js is an open source project licensed under MIT.