Skip to content

Substitutions

Tres Finocchiaro edited this page Apr 24, 2024 · 24 revisions

Compatibility

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

Contents

Since QZ Tray 2.2.4, clients have the ability to make advanced client-side overrides to the JSON websocket data. This low-level control for clients is in a direct response to lack of flexibility by website developers.

For resiliency purposes, the JSON substitution is limited to trivial traits of a print job, such as page size, printer name, although this behavior can be altered slightly by adjusting system properties.

Usage

Basic Usage

Basic usage is as follows:

  1. Create a file called substitutions.json

  2. Use the keywords use and for to instruct QZ how to perform JSON substitution replace and search, respectively.

    [
      {
        "use": {
          "config": { "size": { "width": "100", "height": "150" }, "units": "mm" }
        },
        "for": {
          "config": { "size": { "width": "4", "height": "6" } }
        }
      }
    ]
  3. Drag and drop the file into the About dialog (QZ Menu -> About)
    Screenshot 2024-04-24 at 5 24 14 PM

  4. Submit a print job and check the logs to confirm (QZ Menu -> Advanced -> Diagnostics -> View Logs)

    [DEBUG] 2024-04-24T14:26:42,669 @ qz.ws.substitutions.Substitutions:76
        Matched JSON substitution rule: for: {"params":{"options":{"size":{"width":"4","height":"6"}}}}, use: {"params":{"options":{"size":{"width":"100","height":"150"},"units":"mm"}}}
    
  5. The above example substitutes all print commands for the paper size 4x6 (in) to 100x150 (mm).

Printer Substitution

To instruct QZ Tray to send a print job to a different printer, use the "printer": { ... } directive:

[
  {
    "use": {
       "printer": "XPS Document Writer"
    },
    "for": {
       "printer": "PDFwriter"
    }
  }
]
[DEBUG] 2024-04-24T14:26:42,672 @ qz.ws.substitutions.Substitutions:76
    Matched JSON substitution rule: for: {"params":{"printer":{"name":"PDFwriter"}}}, use: {"params":{"printer":{"name":"XPS Document Writer"}}}

Restricted Keywords

  • By default, certain keywords cannot be modified such as "copies": or nested "data": { "data": ... } elements. This is to ensure that the content and quantity being printed matches that intended by the website.
    [WARN] 2024-04-24T14:26:42,672 @ qz.ws.substitutions.Substitutions:132
        Use of { "options": { "copies": ... } } is restricted, removing
    ...
    [WARN] 2024-04-24T14:26:42,672 @ qz.ws.substitutions.Substitutions:148
        Use of { "data": { "data": ... } } is restricted, removing
    

Sanitization

  • Since the QZ Tray API uses keywords such as config, printer, data, these are provided over their raw JSON counterparts (e.g. "params": { "options": { ... }, etc).
  • To make the JSON slightly more human-readable and human-writable, "data": { "options": ... } will be automatically converted to an array before matching as a convenience (e.g. "data": [{ "options": ... }])
Clone this wiki locally