Skip to content

Getting Started

Jump to bottom
Tres Finocchiaro edited this page Aug 26, 2020 · 37 revisions

Compatibility

  • ✅ 2.1 | ✅ 2.0 | ⛔ 1.9 | ...

Video tutorials:

Background

  • What is QZ Tray? It's a cross-browser, cross-platform plugin for printing (and talking to serial/usb devices). Here's what it looks like.
  • QZ Tray ships with a sample.html page to demonstrate its features.
  • The sample.html is bundled with the desktop software located at
  • QZ Tray, Advanced, Open File Location, demo
  • Need to test HTTPS support? We have a copy of our latest sample.html located at https://demo.qz.io. Warning, this is not backwards compatible with 1.9.
  • This guide assumes you have a physical or virtual printer attached.
  • For raw printing, make sure to follow the Linux, Windows or Mac raw printer setup guide, respectively.

Summary

In this tutorial, we will break down the API into a simplistic, bare-bones example to illustrate what is needed to print from a webpage with QZ Tray.

The Code

  1. In the demo folder of QZ Tray (QZ Tray/demo/js) there are several JavaScript files. Three of these are essential for QZ Tray 2.0.

    File Description Required
    js/qz-tray.js QZ Tray websocket wrapper ✅ Yes

    Note: Optionally, you may npm install qz-tray sha ws

      <script type="text/javascript" src="js/qz-tray.js"></script>
Click to expand additional 2.0 dependencies
File Description Required
js/dependencies/rsvp-3.1.0.min.js ECMAScript 6 Promise lib ✅ Yes, unless overriden.
js/dependencies/sha-256.min.js SHA-256 hashing lib ✅ Yes, unless overriden.
js/qz-tray.js QZ Tray websocket wrapper ✅ Yes

Note: Optionally, you may npm install qz-tray sha ws and optionally q|bluebird|rsvp.

  <head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="js/dependencies/rsvp-3.1.0.min.js"></script>
  <script type="text/javascript" src="js/dependencies/sha-256.min.js"></script>
  <script type="text/javascript" src="js/qz-tray.js"></script>
  </head>

  1. This next portion of the code deploys QZ Tray by calling qz.websocket.connect() to bind to a local websocket instance of the running software.

    Connect

    qz.websocket.connect().then(function() {
   alert("Connected!");
});

    💡 Note: To keep trying the connection after failure:

  2. This next code snippet calls qz.printer.find(..) to find a printer name containing the word "zebra" (e.g. Zebra LP2844, etc) . This can only be called after a successful connection.

    Find Printer

    qz.printers.find("zebra").then(function(found) {
   alert("Printer: " + found);
});
    • You can also list all of the printers attached to the system:
     function findPrinters() {
   qz.printers.find().then(function(data) {
      var list = '';
      for(var i = 0; i < data.length; i++) {
         list += "&nbsp; " + data[i] + "<br/>";
     }
     displayMessage("<strong>Available printers:</strong><br/>" + list);
  }).catch(function(e) { console.error(e); });
}

    ⚠️ Warning: Mac users: Due to discrepancies in printer search behavior, the printer may be listed differently to Java versus the System Preferences. e.g. Zebra LP2844 may list in Java as Zebra_LP2844. See qz-print/131 for more information.

  3. Finally, we send the printer some data using qz.print(...). This can only be called after a successful connection.

    Send Data

    var config = qz.configs.create("Zebra LP2844-Z");               // Exact printer name from OS
var data = ['^XA^FO50,50^ADN,36,20^FDRAW ZPL EXAMPLE^FS^XZ'];   // Raw commands (ZPL provided)

qz.print(config, data).then(function() {
   alert("Sent data to printer");
});

  4. That's it! Now chain them all together.

    Chaining Requests

    qz.websocket.connect().then(function() { 
   return qz.printers.find("zebra");              // Pass the printer name into the next Promise
}).then(function(printer) {
   var config = qz.configs.create(printer);       // Create a default config for the found printer
   var data = ['^XA^FO50,50^ADN,36,20^FDRAW ZPL EXAMPLE^FS^XZ'];   // Raw ZPL
   return qz.print(config, data);
}).catch(function(e) { console.error(e); });

Migration Guide

Function matrix
1.9 2.0
Callback driven, synchronous Promise driven, asynchronous
deployQZ() qz.websocket.connect()
qz.findPrinter(...) qz.printers.find(..)
qz.append(...) No direct equivalent. See Raw Printing example.
qz.appendImage(...) No direct equivalent. See Image Printing example.
qz.appendHTML(...) No direct equivalent. See HTML Printing example.
qz.print() qz.print(config, data)
qz.printPS() qz.print(config, data)
qz.printHTML() qz.print(config, data)
qz.setPaperSize(...) qz.configs.create(..., { units: 'in', size: { width: 8.5, height: 11 } });
qz.setAutoSize(...) qz.configs.create(..., { scaleContent: ... });
qz.setOrientation(...) qz.configs.create(..., { orientation: ... });
qz.setEncoding(...) qz.configs.create("...", { encoding: 'UTF-8' /* etc */ });
qz.findPorts() qz.serial.findPorts()
qz.openPort(...) qz.serial.openPort(...)
qz.closePort(...) qz.serial.closePort(...)
qzReady() qz.websocket.connect().then(function() { ... })
qzDoneFinding() qz.printers.find(...).then(function() { ... })
qzDoneAppending() No direct equivalent, resolves promise at print time.
qzDoneFindingPorts() qz.serial.findPorts().then(function() { ... })
qzDoneOpeningPort() qz.serial.openPort(..., ...).then(function() { ... })

What Next?

Clone this wiki locally