BlueGit

timfa posprint

Files

posprint / docs / POSPRINT-URL.md

POSPRINT-URL.md

POSPRINT-URL.md 3.5 KiB Download Raw

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/.

---

Format

posprint://print?v=1&d=<BASE64URL(raw_deflate(utf8(.pos JSON)))>
PartMeaning
posprint://Custom protocol (registered on install / first run)
printOpen the print-only dialog (same UX as posprint --print)
v=1URL 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" "<url>".

GuidanceSize
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

posprint link receipt.pos

Prints one posprint://… line. Warns if the URL is longer than ~7000 characters.

Libraries

RuntimePath
PHPlib/php/posprint_url.php
Node.jslib/node/posprint_url.js
Browserlib/browser/posprint_url.js

All three use the same encoding: UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding).

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",
]);
// <a href="<?= htmlspecialchars($url) ?>">Print</a>

Node.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

<script type="module">
  import { posprintUrl } from './lib/browser/posprint_url.js';
  const url = await posprintUrl({
    version: 1,
    metadata: { page_width_mm: 53 },
    body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
  });
  location.href = url;
</script>

CompressionStream('deflate-raw') is required (modern Chromium / Firefox / Safari).

---

Protocol registration

PlatformHow
WindowsOn each launch, posprint registers HKCU\Software\Classes\posprint → "<exe>" "%1"
Linux (deb/Arch)Ships posprint-url.desktop with MimeType=x-scheme-handler/posprint

After a Linux package install, if links do not open:

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

@barcode RASTER CODE128 ${data}
Hello from posprint://
@cut

Corresponding minimal .pos 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"
}
Source
1# posprint:// URLs
2
3Magnet-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.
4
5Full reference: create URLs from PHP, Node.js, or browser JavaScript using the helpers in [`lib/`](../lib/).
6
7---
8
9## Format
10
11```
12posprint://print?v=1&d=<BASE64URL(raw_deflate(utf8(.pos JSON)))>
13```
14
15| Part | Meaning |
16|------|---------|
17| `posprint://` | Custom protocol (registered on install / first run) |
18| `print` | Open the print-only dialog (same UX as `posprint --print`) |
19| `v=1` | URL payload version |
20| `d=` | Compressed `.pos` file (JSON with `version`, `metadata`, `body`) |
21
22**Parameters are not in the URL.** The user fills `${Name}` / `$[Name]` in the dialog.
23
24**Images:** keep logos out of the URL. Use `@image https://…` (or `http://…`) in the template body; posprint downloads them when needed.
25
26---
27
28## Size limits
29
30Cross-platform bottleneck is usually the **Windows command line (~8191 characters)** for `"posprint.exe" "<url>"`.
31
32| Guidance | Size |
33|----------|------|
34| Soft warning (`posprint link`) | ~7000 characters URL length |
35| Practical `.pos` JSON | ~3–6 KB uncompressed (often more if it compresses well) |
36
37Prefer short templates + remote `@image https://…` over embedding image bytes in the JSON.
38
39---
40
41## Create a URL
42
43### CLI
44
45```bash
46posprint link receipt.pos
47```
48
49Prints one `posprint://…` line. Warns if the URL is longer than ~7000 characters.
50
51### Libraries
52
53| Runtime | Path |
54|---------|------|
55| PHP | [`lib/php/posprint_url.php`](../lib/php/posprint_url.php) |
56| Node.js | [`lib/node/posprint_url.js`](../lib/node/posprint_url.js) |
57| Browser | [`lib/browser/posprint_url.js`](../lib/browser/posprint_url.js) |
58
59All three use the same encoding: **UTF-8 JSON → raw deflate (RFC 1951) → base64url (no padding)**.
60
61#### PHP
62
63```php
64require 'lib/php/posprint_url.php';
65
66$url = posprint_url([
67 'version' => 1,
68 'metadata' => ['page_width_mm' => 53, 'chars_per_line' => 32],
69 'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
70]);
71// <a href="<?= htmlspecialchars($url) ?>">Print</a>
72```
73
74#### Node.js
75
76```js
77const { posprintUrl } = require('./lib/node/posprint_url');
78
79const url = posprintUrl({
80 version: 1,
81 metadata: { page_width_mm: 53, chars_per_line: 32 },
82 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
83});
84```
85
86#### Browser
87
88```html
89<script type="module">
90 import { posprintUrl } from './lib/browser/posprint_url.js';
91 const url = await posprintUrl({
92 version: 1,
93 metadata: { page_width_mm: 53 },
94 body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
95 });
96 location.href = url;
97</script>
98```
99
100`CompressionStream('deflate-raw')` is required (modern Chromium / Firefox / Safari).
101
102---
103
104## Protocol registration
105
106| Platform | How |
107|----------|-----|
108| **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
109| **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
110
111After a Linux package install, if links do not open:
112
113```bash
114xdg-mime default posprint-url.desktop x-scheme-handler/posprint
115```
116
117Run the GUI once (or any `posprint` launch) on Windows so the registry key exists.
118
119---
120
121## Example template body
122
123```markdown
124@barcode RASTER CODE128 ${data}
125Hello from posprint://
126@cut
127```
128
129Corresponding minimal `.pos` JSON:
130
131```json
132{
133 "version": 1,
134 "metadata": {
135 "title": "URL demo",
136 "page_width_mm": 53,
137 "chars_per_line": 32
138 },
139 "body": "@barcode RASTER CODE128 ${data}\nHello from posprint://\n@cut\n"
140}
141```