Wiki - 1.9 QZ Print vs QZ Tray

Compatibility

Background

Below you will find the five new functions as they appear in the sample.html that is provided with the QZ Tray software.

Caveats

Below are unavoidable caveats introduced with adding a websocket wrapper. These caveats only exist in the 1.9 branch.

New Functions

Function Mandatory? Purpose
getCertificate() Gets public certificate to display trusted message on load of page
signRequest() Calls a custom server-side signing function. See usage below.
qzSocketError(event) Contains the event fired when the websocket encounters an error
qzSocketClose(event) Contains the event fired when the websocket closes
qzNoConnection() Calls function to fall back on QZ Print (applet version) if QZ Tray is not running

qz-websocket.js

  1. There's a new script, qz-websocket.js used for communication between the JavaScript API and the desktop application.

    <script type="text/javascript" src="js/qz-websocket.js"></script>
  2. The function deployQZ is still used, but has been re-purposed to deploy a WebSocket wrapper object.

  3. To deploy the qz object using WebSockets, call deployQZ directly

    deployQZ();   // sets up the global "qz" object, calls qzReady() when finished
    

    Note: For backward compatibility with mixed environments, we have provided a fallback function deployQZApplet. This is not required for QZ Tray and is offered as a fallback mechanism for customers still using the NPAPI method.

getCertificate

The certificate can be provided through an $.ajax function, or can be pasted directly into the page (this is a public certificate). The certificate is only for the initial load.

  1. AJAX method

    function getCertificate(callback) {
       $.ajax({
          method: 'GET',
          url: 'assets/auth/public-key.txt',
          async: false,
          success: callback // Data returned from ajax call should be the site certificate
    });
  2. Non-AJAX method

    Below is just a small sample of a what the public and intermediate key would look like.

    function getCertificate(callback) {
       callback("-----BEGIN CERTIFICATE-----\n" +
           "MIIFAzCCAuugAwIBAgICEAIwDQYJKoZIhvcNAQEFBQAwgZgxCzAJBgNVBAYTAlVT\n" +

signRequest

  1. This function is responsible for calling a custom script that performs the server-side signing. The signing can be done in a variety of different languages. Several examples are provided with the software in QZ Tray\demo\assets\signing. You can also click here for a growing list of examples including these languages: Ruby, Python, JavaScript, C#, J#, Java, ASP and VB.NET

    function signRequest(toSign, callback) {
       $.ajax({
           method: 'GET',
           url: '/secure/url/for/sign-message.php?request=' + toSign,
           async: false,
           success: callback // Data returned from ajax call should be the signature
    });

qzSocketError

   function qzSocketError(event) {
       document.getElementById("qz-status").style.background = "#F5A9A9";
       console.log('Error:');
       console.log(event);

       alert("Connection had an error:\n"+ event.reason);
   }

qzSocketClose

   function qzSocketClose(event) {
       document.getElementById("qz-status").style.background = "#A0A0A0";
       console.log('Close:');
       console.log(event);

       alert("Connection was closed:\n"+ event.reason);
   }

qzNoConnection

   function qzNoConnection() {
       alert("Unable to connect to QZ, is it running?");

       //run deploy applet After page load
       var content = '';
       var oldWrite = document.write;
       document.write = function(text) {
           content += text;
       };
       deployQZApplet();

       var newElem = document.createElement('del');
       newElem.innerHTML = content;

       document.write = oldWrite;
       document.body.appendChild(newElem);
   }

Multiple Appends

QZ Tray 1.9 uses a WebSocket wrapper to simulate LiveConnect calls. This makes the API similar to QZ Print, however has the unintended side-effect of adding considerable latency to multiple calls to qz.append(...). This caveat only exists in the 1.9 branch. 2.0 uses a data object/array for appending and does not suffer this problem.

Making appends faster for QZ Tray 1.9

# Old QZ Print Syntax
- qz.append("foo\n");
- qz.append("bar\n");

# New QZ Tray Syntax
+ var data = "";
+ data += "foo\n";
+ data += "bar\n";
+ qz.append(data);
Edit this page