Introduction ------------ Boekkat (pronounced "book cat") is a framework that helps you integrate the (non-declawed) CueCat seamlessly into your web applications. Boekkat encompasses many levels of detail so that you can use it simply by writing two or three lines of JavaScript, or use it for more complex applications by writing ten or twelve lines. I have attempted to write Boekkat as elegantly as possible, in a world where I find little elegance in JavaScript programs, and little regard for it in such JavaScript documentation as I've found. The consequence of this elegance is this: Boekkat requires Internet Explorer 5.0 or later, or Netscape 6.0 or later, or any browser from the Mozilla Foundation (incl. Firefox), or Opera 7 or later (i think). More specifically, Boekkat uses exceptions (which don't work on any version-4 browsers), the object-oriented apply function (doesn't work on IE4), the push() method for arrays (doesn't work on IE4), and maybe the instanceof operator. If you try to load the scripts anyway in an old browser you'll get syntax errors and no CueCat handling. If you need version-4 browser support those are the things you must change. Now! Here's how to use Boekkat, simplest scenario first. One form field, catching any barcode ------------------------------------ First, add a bunch of script tags in the header of your html file:: ... Now, any time someone with a CueCat scans a barcode while on your page, the contents of the barcode will go in the barcodeHere field, and the form will be submitted. If you don't want to submit the form, take out the AndSubmit part. One form field, catching only certain types of barcode ------------------------------------------------------ Same as above, but instead of handling "any", handle "ISBN13" or "ISBN10" (that's it at the moment). So keep the same script includes, and the same form, but use this script instead:: Multiple form fields, catching one type each -------------------------------------------- ::
Several notes are in order. First, the order in which you handle barcodes is important. When the user scans a barcode, Boekkat goes through in order, seeing if the barcode conforms to each type. The first one that works, gets the barcode. So if you put "any" first in the script, nothing that you put after it will ever run. Second, the "any" handler is "hot" here. If the user scans an ISBN, she can still fill in other things on the form before it's submitted. But when she scans any other type of barcode, it will be filled in and the form will be submitted. Writing your own custom handlers -------------------------------- Handlers are the functions that actually do stuff with barcode data. Boekkat comes with a couple of handlers, but if you need something else to happen when a barcode gets scanned other than a field getting filled in, you might want to step in and take control. Let's write a handler that just pops up an alert box with the barcode's data.:: That was easy, wasn't it? A handler can be any function that takes one argument, the barcode data. It can do anything with it that you can imagine. Once you write the function, just pass its name to the handle method. Writing your own custom interpreters ------------------------------------ Interpreters are the functions that try to make sense of a barcode as a certain type of data. An interpreter can take into account the symbology of the barcode and its contents in order to determine whether the barcode is valid under the interpretation, and it can alter the data before returning it. Let's say you've made some ID cards. You want to fill in the ID field when someone scans an ID card, yet do something else if they scan the barcode on, say, a soda can. The barcodes on your ID cards are printed using the Code128 symbology, and the codes always start with a capital C.:: Interpreter functions go in the Interpreter.prototype object. The functions receive as their parameter an array containing three things: the serial number of the CueCat, the symbology of the barcode (a three-character code), and the contents of the barcode. They must either return a value of some sort (if the barcode made sense), or throw an InterpreterFailure (if it didn't). Try to make the interpreter as strict as possible. Reject invalid barcodes here and not in the handler. If your interpreting function needs helper functions, you can place those in Interpreter.prototype as well, but make sure they start with an underline character (_). Testing ------- I've written unit tests for at least 80% of the code using ecmaunit, which is included. Ecmaunit uses exceptions and so requires a version-5 browser. You are strongly encouraged to write unit tests for your code, especially if you contribute it back to me. Interpreter ideas ----------------- * UPS tracking number * Book UPC+5 codes (for some paperbacks) * UPC codes