Integrating With Your Code

metafloor edited this page Sep 1, 2017 · 8 revisions

The files included in the repository are ready-to-use in the browser and in Node.js. If you would like to integrate bwipjs into a different environment, it involves the following steps:

  • Load the font-manager library.
  • Load the BWIPP library.
  • Load the bwipjs library.
  • Define the bitmap interface.

There are three built-in font-managers, one for node.js, one for use with browser frameworks such as webpack, react, etc., and another for direct inclusion in the browser.

  • For node.js, the module is node-fonts.js.
  • For browser frameworks, the module is browser-fonts.js.
  • As an included script in the browser, it is lib/xhr-fonts.js and defines the global bwipjs_fonts.

Both browser files use XHR to asynchronously load the font metrics and bitmaps. The font metrics are loaded at start up; the bitmaps are demand-loaded.

The BWIPP and bwipjs libraries are conventional JavaScript files that define two global objects. bwipp.js defines the BWIPP symbol, and bwipjs.js defines the BWIPJS symbol. Both files are CommonJS aware and will assign their global objects to module.exports if available. This allows them to be loaded using require() in node.js, for example.

BWIPJS is a constructor that should be called with the new operator. BWIPP is a factory method and is called as a function returning an instance.

You must define a bitmap graphics interface. See lib/bitmap.js for the one used by the demo to write to a canvas; browser-bitmap.js used by the browser frameworks; and node-bitmap.js for one that creates PNG images using node's zlib module. As of version 1.5, the Bitmap interface is given the size of the image prior to any calls to Bitmap.color() or Bitmap.set(). Your interface no longer needs to track minimum and maximum coordinates and it will never see negative coordinates.

When implementing the Bitmap interface, keep in mind that typical graphics environments (HTML canvas, PHP GD, etc.) set their origin (0,0) to the upper left-hand corner but PostScript uses a page-up orientation with the origin in the lower left-hand corner. Since bwip-js implements a direct mapping to the PostScript graphics primitives, the coordinates your bitmap implementation will see have an origin set in the lower left-hand corner. See the Bitmap implementations for code that converts between the two origin conventions.

Below is the Bitmap prototype you need to implement:

// The bitmap interface.  It's called Bitmap here, but it can be any name
// you wish; your code is the only one that will reference the name.
function Bitmap() {
    // Sets the size of the image, in pixels.
    // ncolors is an estimate (upper bound).  It should never exceed
    // 256 currently but future versions of BWIPP may change that. 
    this.imageinfo = function(width, height, ncolors) {
    // Defines the current color to apply when set() is called. 
    this.color = function(r, g, b) {
	// r,g,b will be integer values between 0 and 255
	// Save as the current color
    // Sets a pixel at coordinates (x,y) using the current color with
    // specified alpha.
    this.set = function(x, y, a) {
        // Update the image using alpha-blending.
	// And invert the y-axis if the graphics format you are using has
	// its origin in the upper-left corner.
    // Called after all pixels have been `set()`.  This is your cue to
    // finish rendering the image.
    this.finalize = function(callback) {
        // Finish rendering and invoke the callback with the expected parameters.

Now we are ready to create a barcode. BWIPP requires two parameters; the barcode text to encode and either an options object or string. The example below uses an options object which is more flexible than using a string of space-separated options values.

The example calls the code128 encoder using the parsefnc option to include the FNC1 character as part of the barcode text, and provides alternate human readable text.

// Initialize a barcode writer object.  This is the interface between
// the low-level BWIPP code, the font-manager, and the Bitmap object.
// The `fontlib` parameter is the font-manager, either the FreeType
// interface or the bitmapped-fonts interface.
// The boolean `monochrome` flag indicates whether to use
// anti-aliased (false) or monochrome (true) font rendering.
var bw = new BWIPJS(fontlib, false /*use anti-aliased fonts*/);

// Add a bitmap instance
bw.bitmap(new Bitmap);

// Set the x,y scaling factors
bw.scale(2, 2);

// Create an options object.  See the bwipjs and BWIPP documentation
// for possible values.
// You can use any plain JavaScript values.  Numbers, bools and strings.
var opts = {

// Call into the BWIPP cross-compiled code.   BWIPP() is a factory
// method that returns a function object.  You can call the
// function object multiple times (and reuse the BWIPJS object as
// well), but you will likely need to create a new Bitmap object
// prior to each call.
try {
    // This call is synchronous and can be CPU intensive.
    // Will throw if a runtime error is encountered
    BWIPP()(bw, 'code128', "^FNC1001234567890", opts);

    // If you are using bitmapped fonts with asynchronous loading (browser),
    // you must allow the font-manager to load any required fonts.
    // Node.js does not use this and calls bw.render() directly.
    bwipjs_fonts.loadfonts(function(err) {
        if (err) {
             // handle the font loading error
        } else {
             // Tell bwip-js to render the image.  This will invoke
             // the interfaces on your Bitmap object.  The callback is passed
             // to Bitmap.finalize().  That interface should call it when done,
             // supplying any expected parameters.
} catch (e) {
    // handle error
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.