# posprint:// URLs Magnet-style deep links that open **posprint’s print dialog** with an embedded `.pos` document. Useful from websites where posprint is installed on the client, not on the server. Full reference: create URLs from PHP, Node.js, or browser JavaScript using the helpers in [`lib/`](../lib/). --- ## Format ``` posprint://print?v=1&d= ``` | Part | Meaning | |------|---------| | `posprint://` | Custom protocol (registered on install / first run) | | `print` | Open the print-only dialog (same UX as `posprint --print`) | | `v=1` | URL payload version | | `d=` | Compressed `.pos` file (JSON with `version`, `metadata`, `body`) | **Parameters are not in the URL.** The user fills `${Name}` / `$[Name]` in the dialog. **Images:** keep logos out of the URL. Use `@image https://…` (or `http://…`) in the template body; posprint downloads them when needed. --- ## Size limits Cross-platform bottleneck is usually the **Windows command line (~8191 characters)** for `"posprint.exe" ""`. | Guidance | Size | |----------|------| | Soft warning (`posprint link`) | ~7000 characters URL length | | Practical `.pos` JSON | ~3–6 KB uncompressed (often more if it compresses well) | Prefer short templates + remote `@image https://…` over embedding image bytes in the JSON. --- ## Create a URL ### CLI ```bash posprint link receipt.pos ``` Prints one `posprint://…` line. Warns if the URL is longer than ~7000 characters. ### Libraries | Runtime | Path | |---------|------| | PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) | | Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) | | Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) | All three use the same encoding: **UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding)**. #### PHP ```php require 'lib/php/posprint_url.php'; $url = posprint_url([ 'version' => 1, 'metadata' => ['page_width_mm' => 53, 'chars_per_line' => 32], 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n", ]); // Print ``` #### Node.js ```js const { posprintUrl } = require('./lib/node/posprint_url'); const url = posprintUrl({ version: 1, metadata: { page_width_mm: 53, chars_per_line: 32 }, body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n', }); ``` #### Browser ```html ``` `CompressionStream('deflate-raw')` is required (modern Chromium / Firefox / Safari). --- ## Protocol registration | Platform | How | |----------|-----| | **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"" "%1"` | | **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` | After a Linux package install, if links do not open: ```bash xdg-mime default posprint-url.desktop x-scheme-handler/posprint ``` Run the GUI once (or any `posprint` launch) on Windows so the registry key exists. --- ## Example template body ```markdown @barcode RASTER CODE128 ${data} Hello from posprint:// @cut ``` Corresponding minimal `.pos` JSON: ```json { "version": 1, "metadata": { "title": "URL demo", "page_width_mm": 53, "chars_per_line": 32 }, "body": "@barcode RASTER CODE128 ${data}\nHello from posprint://\n@cut\n" } ```