Add per-library examples for posprint:// URL encoding.
Document array and local-file usage for PHP, Node, and browser helpers. Co-authored-by: Cursor <cursoragent@cursor.com>
@@ -4,10 +4,10 @@ Small helpers that turn a `.pos` document into a `posprint://` deep link.
4
4
5
5
See [docs/POSPRINT-URL.md](../docs/POSPRINT-URL.md) for the full URL format and size limits.
6
6
7
| Folder | Runtime |
8
|--------|---------|
9
| [`php/`](php/) | PHP (`gzdeflate`) |
10
| [`node/`](node/) | Node.js (`zlib.deflateRawSync`) |
11
| [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) |
7
| Folder | Runtime | Examples |
8
|--------|---------|----------|
9
| [`php/`](php/) | PHP (`gzdeflate`) | [examples.md](php/examples.md) |
10
| [`node/`](node/) | Node.js (`zlib.deflateRawSync`) | [examples.md](node/examples.md) |
11
| [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) | [examples.md](browser/examples.md) |
12
12
13
13
All implementations must stay byte-compatible with Rust `src/protocol_url.rs`.
@@ -4,10 +4,10 @@ Small helpers that turn a `.pos` document into a `posprint://` deep link.4
4
5
See [docs/POSPRINT-URL.md](../docs/POSPRINT-URL.md) for the full URL format and size limits.5
See [docs/POSPRINT-URL.md](../docs/POSPRINT-URL.md) for the full URL format and size limits.6
6
7
| Folder | Runtime |7
| Folder | Runtime | Examples |8
|--------|---------|8
|--------|---------|----------|9
| [`php/`](php/) | PHP (`gzdeflate`) |9
| [`php/`](php/) | PHP (`gzdeflate`) | [examples.md](php/examples.md) |10
| [`node/`](node/) | Node.js (`zlib.deflateRawSync`) |10
| [`node/`](node/) | Node.js (`zlib.deflateRawSync`) | [examples.md](node/examples.md) |11
| [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) |11
| [`browser/`](browser/) | ES module (`CompressionStream('deflate-raw')`) | [examples.md](browser/examples.md) |12
12
13
All implementations must stay byte-compatible with Rust `src/protocol_url.rs`.13
All implementations must stay byte-compatible with Rust `src/protocol_url.rs`.@@ -0,0 +1,85 @@
1
# Browser examples — `posprintUrl()`
2
3
See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5
Browsers cannot read arbitrary paths on disk. “Local file” here means a user-selected `.pos` file via `<input type="file">`, or JSON fetched from your server.
6
7
Requires `CompressionStream('deflate-raw')` (recent Chromium, Firefox, Safari).
8
9
```html
10
<script type="module">
11
import { posprintUrl } from './posprint_url.js';
12
</script>
13
```
14
15
## From an object
16
17
Build the document in JavaScript and open the link:
18
19
```html
20
<button id="print">Print</button>
21
<script type="module">
22
import { posprintUrl } from './posprint_url.js';
23
24
document.getElementById('print').addEventListener('click', async () => {
25
const url = await posprintUrl({
26
version: 1,
27
metadata: {
28
title: 'Barcode demo',
29
page_width_mm: 53,
30
chars_per_line: 32,
31
},
32
body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
33
});
34
window.location.href = url;
35
});
36
</script>
37
```
38
39
Or render a link without navigating immediately:
40
41
```js
42
const url = await posprintUrl({ /* … */ });
43
const a = document.createElement('a');
44
a.href = url;
45
a.textContent = 'Print receipt';
46
document.body.append(a);
47
```
48
49
## From a local `.pos` file (user picks file)
50
51
```html
52
<input type="file" id="pos-file" accept=".pos,application/json" />
53
<a id="print-link" hidden>Print</a>
54
55
<script type="module">
56
import { posprintUrl } from './posprint_url.js';
57
58
document.getElementById('pos-file').addEventListener('change', async (ev) => {
59
const file = ev.target.files?.[0];
60
if (!file) return;
61
62
const json = await file.text();
63
const url = await posprintUrl(json);
64
65
const link = document.getElementById('print-link');
66
link.href = url;
67
link.hidden = false;
68
});
69
</script>
70
```
71
72
## From a file on your server
73
74
If the `.pos` lives on the same site, fetch it and pass the JSON string:
75
76
```js
77
const res = await fetch('/templates/receipt.pos');
78
const json = await res.text();
79
const url = await posprintUrl(json);
80
window.location.href = url;
81
```
82
83
## Length warning
84
85
On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. Prefer short templates and `@image https://…` for logos.
@@ -0,0 +1,85 @@1
# Browser examples — `posprintUrl()`2
3
See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.4
5
Browsers cannot read arbitrary paths on disk. “Local file” here means a user-selected `.pos` file via `<input type="file">`, or JSON fetched from your server.6
7
Requires `CompressionStream('deflate-raw')` (recent Chromium, Firefox, Safari).8
9
```html10
<script type="module">11
import { posprintUrl } from './posprint_url.js';12
</script>13
```14
15
## From an object16
17
Build the document in JavaScript and open the link:18
19
```html20
<button id="print">Print</button>21
<script type="module">22
import { posprintUrl } from './posprint_url.js';23
24
document.getElementById('print').addEventListener('click', async () => {25
const url = await posprintUrl({26
version: 1,27
metadata: {28
title: 'Barcode demo',29
page_width_mm: 53,30
chars_per_line: 32,31
},32
body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',33
});34
window.location.href = url;35
});36
</script>37
```38
39
Or render a link without navigating immediately:40
41
```js42
const url = await posprintUrl({ /* … */ });43
const a = document.createElement('a');44
a.href = url;45
a.textContent = 'Print receipt';46
document.body.append(a);47
```48
49
## From a local `.pos` file (user picks file)50
51
```html52
<input type="file" id="pos-file" accept=".pos,application/json" />53
<a id="print-link" hidden>Print</a>54
55
<script type="module">56
import { posprintUrl } from './posprint_url.js';57
58
document.getElementById('pos-file').addEventListener('change', async (ev) => {59
const file = ev.target.files?.[0];60
if (!file) return;61
62
const json = await file.text();63
const url = await posprintUrl(json);64
65
const link = document.getElementById('print-link');66
link.href = url;67
link.hidden = false;68
});69
</script>70
```71
72
## From a file on your server73
74
If the `.pos` lives on the same site, fetch it and pass the JSON string:75
76
```js77
const res = await fetch('/templates/receipt.pos');78
const json = await res.text();79
const url = await posprintUrl(json);80
window.location.href = url;81
```82
83
## Length warning84
85
On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. Prefer short templates and `@image https://…` for logos.@@ -0,0 +1,67 @@
1
# Node.js examples — `posprintUrl()`
2
3
See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5
```js
6
const { posprintUrl } = require('./posprint_url');
7
// or: import { posprintUrl } from './posprint_url.js'; // with "type": "module"
8
```
9
10
## From an object
11
12
Build the `.pos` document in JavaScript:
13
14
```js
15
const url = posprintUrl({
16
version: 1,
17
metadata: {
18
title: 'Barcode demo',
19
page_width_mm: 53,
20
chars_per_line: 32,
21
},
22
body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',
23
});
24
25
console.log(url);
26
// posprint://print?v=1&d=…
27
```
28
29
Express route example:
30
31
```js
32
app.get('/print-link', (req, res) => {
33
const url = posprintUrl({ /* … */ });
34
res.redirect(url);
35
});
36
```
37
38
## From a local `.pos` file
39
40
Read the file and pass the JSON string:
41
42
```js
43
const fs = require('fs');
44
const path = require('path');
45
46
const filePath = path.join(__dirname, '../../examples/url-demo.pos');
47
let json = fs.readFileSync(filePath, 'utf8');
48
49
// Optional: strip UTF-8 BOM
50
if (json.charCodeAt(0) === 0xfeff) {
51
json = json.slice(1);
52
}
53
54
const url = posprintUrl(json);
55
console.log(url);
56
```
57
58
Or parse and validate first:
59
60
```js
61
const doc = JSON.parse(json);
62
const url = posprintUrl(doc);
63
```
64
65
## Length warning
66
67
On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, use `@image https://…` in the body instead of embedding image data.
@@ -0,0 +1,67 @@1
# Node.js examples — `posprintUrl()`2
3
See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.4
5
```js6
const { posprintUrl } = require('./posprint_url');7
// or: import { posprintUrl } from './posprint_url.js'; // with "type": "module"8
```9
10
## From an object11
12
Build the `.pos` document in JavaScript:13
14
```js15
const url = posprintUrl({16
version: 1,17
metadata: {18
title: 'Barcode demo',19
page_width_mm: 53,20
chars_per_line: 32,21
},22
body: '@barcode RASTER CODE128 ${data}\nHello\n@cut\n',23
});24
25
console.log(url);26
// posprint://print?v=1&d=…27
```28
29
Express route example:30
31
```js32
app.get('/print-link', (req, res) => {33
const url = posprintUrl({ /* … */ });34
res.redirect(url);35
});36
```37
38
## From a local `.pos` file39
40
Read the file and pass the JSON string:41
42
```js43
const fs = require('fs');44
const path = require('path');45
46
const filePath = path.join(__dirname, '../../examples/url-demo.pos');47
let json = fs.readFileSync(filePath, 'utf8');48
49
// Optional: strip UTF-8 BOM50
if (json.charCodeAt(0) === 0xfeff) {51
json = json.slice(1);52
}53
54
const url = posprintUrl(json);55
console.log(url);56
```57
58
Or parse and validate first:59
60
```js61
const doc = JSON.parse(json);62
const url = posprintUrl(doc);63
```64
65
## Length warning66
67
On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, use `@image https://…` in the body instead of embedding image data.@@ -0,0 +1,61 @@
1
# PHP examples — `posprint_url()`
2
3
See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.
4
5
```php
6
require __DIR__ . '/posprint_url.php';
7
```
8
9
## From an array
10
11
Build the `.pos` document in PHP and pass an associative array:
12
13
```php
14
$url = posprint_url([
15
'version' => 1,
16
'metadata' => [
17
'title' => 'Barcode demo',
18
'page_width_mm' => 53.0,
19
'chars_per_line' => 32,
20
],
21
'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",
22
]);
23
24
echo $url, "\n";
25
// posprint://print?v=1&d=…
26
```
27
28
Use in HTML:
29
30
```php
31
<a href="<?= htmlspecialchars($url, ENT_QUOTES, 'UTF-8') ?>">Print receipt</a>
32
```
33
34
## From a local `.pos` file
35
36
Read the file as JSON text and pass the string (same encoding path as an array):
37
38
```php
39
$path = __DIR__ . '/../../examples/url-demo.pos';
40
$json = file_get_contents($path);
41
if ($json === false) {
42
throw new RuntimeException("Could not read {$path}");
43
}
44
45
// Optional: strip UTF-8 BOM if present (Windows editors)
46
$json = preg_replace('/^\xEF\xBB\xBF/', '', $json) ?? $json;
47
48
$url = posprint_url($json);
49
echo $url, "\n";
50
```
51
52
Or decode first to validate, then encode:
53
54
```php
55
$doc = json_decode($json, true, flags: JSON_THROW_ON_ERROR);
56
$url = posprint_url($doc);
57
```
58
59
## Length warning
60
61
On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, keep images as `@image https://…` in the body instead of embedding bytes in JSON.
@@ -0,0 +1,61 @@1
# PHP examples — `posprint_url()`2
3
See [docs/POSPRINT-URL.md](../../docs/POSPRINT-URL.md) for URL format and size limits.4
5
```php6
require __DIR__ . '/posprint_url.php';7
```8
9
## From an array10
11
Build the `.pos` document in PHP and pass an associative array:12
13
```php14
$url = posprint_url([15
'version' => 1,16
'metadata' => [17
'title' => 'Barcode demo',18
'page_width_mm' => 53.0,19
'chars_per_line' => 32,20
],21
'body' => "@barcode RASTER CODE128 \${data}\nHello\n@cut\n",22
]);23
24
echo $url, "\n";25
// posprint://print?v=1&d=…26
```27
28
Use in HTML:29
30
```php31
<a href="<?= htmlspecialchars($url, ENT_QUOTES, 'UTF-8') ?>">Print receipt</a>32
```33
34
## From a local `.pos` file35
36
Read the file as JSON text and pass the string (same encoding path as an array):37
38
```php39
$path = __DIR__ . '/../../examples/url-demo.pos';40
$json = file_get_contents($path);41
if ($json === false) {42
throw new RuntimeException("Could not read {$path}");43
}44
45
// Optional: strip UTF-8 BOM if present (Windows editors)46
$json = preg_replace('/^\xEF\xBB\xBF/', '', $json) ?? $json;47
48
$url = posprint_url($json);49
echo $url, "\n";50
```51
52
Or decode first to validate, then encode:53
54
```php55
$doc = json_decode($json, true, flags: JSON_THROW_ON_ERROR);56
$url = posprint_url($doc);57
```58
59
## Length warning60
61
On Windows, keep the full URL under ~7000 characters so the OS can launch posprint. For large templates, keep images as `@image https://…` in the body instead of embedding bytes in JSON.