docs + fix: Leads module doc, badges onsite doc, license access fix, QR log cleanup
- Add MODULE__AE_Events_Exhibitor_Leads.md — full module reference (auth model, tabs, data model, routes, offline/PWA notes, OSIT admin notes) - Add MODULE__AE_Events_Badges_Onsite.md — onsite printing guide (browser settings, CUPS/Linux setup, Zebra ZC10L section with test results, Epson stub, troubleshooting) - Archive PROJECT__AE_Events_Exhibitor_Leads_v3*.md + Zebra test day doc → history/ - Fix leads license management access: ae_tab__manage.svelte license section now visible to administrator_access OR shared-passcode sign-in (type === 'shared'); matches spec - Add type field to LeadsLocState.auth_exhibit_kv interface (was set at runtime but missing from type) - Silence QR code console noise: entry log gated at log_lvl >= 2, data URL log removed - vite.config.ts: exclude documentation/ and tests/ from Vite HMR file watcher Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
207
documentation/MODULE__AE_Events_Badges_Onsite.md
Normal file
207
documentation/MODULE__AE_Events_Badges_Onsite.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# Aether Events — Onsite Badge Printing
|
||||
|
||||
Notes on setup, process, hardware, and browser behavior for onsite badge printing at events.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Aether badge printing uses the browser's native `window.print()` — no special software or print
|
||||
server needed. The badge render page (`/events/[event_id]/badges/print/[badge_id]`) outputs
|
||||
print-ready HTML/CSS, and the browser sends it directly to the connected printer via CUPS (Linux)
|
||||
or the OS print system (macOS/Windows).
|
||||
|
||||
Chrome (Chromium) is the recommended browser for onsite kiosk stations.
|
||||
Firefox is a solid alternative, especially for Save-to-PDF workflows.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Workflow — Onsite Kiosk
|
||||
|
||||
1. Open the event's badge printing page: `/events/[event_id]/badges`
|
||||
2. Search for the attendee (name, badge ID, or QR scan)
|
||||
3. Open the badge print page — review the rendered badge
|
||||
4. Click **Print Badge** in the controls panel (or use keyboard shortcut)
|
||||
5. In the browser print dialog:
|
||||
- Set Margins to **None** (Chrome) or leave defaults (Firefox)
|
||||
- Confirm paper/card size matches the stock loaded in the printer
|
||||
- Print
|
||||
6. `print_count` increments automatically on each print via the Print Badge button
|
||||
|
||||
For high-volume events, consider the **rapid QR scan** mode in the Leads module or using a
|
||||
dedicated kiosk session where the operator only handles physical card handoff.
|
||||
|
||||
---
|
||||
|
||||
## Browser Settings
|
||||
|
||||
### Chrome / Chromium (Recommended for kiosk use)
|
||||
|
||||
Chrome is recommended for onsite badge printing stations. Key print dialog settings:
|
||||
|
||||
| Setting | Correct value | Notes |
|
||||
|---|---|---|
|
||||
| Margins | **None** or **Minimum** | Default margins add URL/date headers — breaks badge centering |
|
||||
| Paper size | Match card stock (e.g. 3.5" × 5.5") | Zebra driver may override this automatically |
|
||||
| Background graphics | **On** | Required for colored header/footer stripe to print |
|
||||
| Pages | 1 | PVC single-sided — only front should print |
|
||||
|
||||
**Important:** Chrome ignores CSS `@page { size }` for Save to PDF — it defaults to letter/A4.
|
||||
For physical printer output, the printer driver controls paper size. This is expected behavior.
|
||||
|
||||
To lock Chrome settings for a kiosk, set Margins to "None" once and Chrome remembers per-printer.
|
||||
|
||||
### Firefox
|
||||
|
||||
Firefox honors CSS `@page { size }` which makes it ideal for PDF generation.
|
||||
For physical printing, Firefox generally "just works" without margin adjustments.
|
||||
|
||||
| Setting | Notes |
|
||||
|---|---|
|
||||
| Paper size | Can be set in dialog, but CSS `@page { size }` is honored |
|
||||
| Margins | Default is usually fine; remove headers/footers if they appear |
|
||||
| Background graphics | Enable for colored stripes and header images to print |
|
||||
|
||||
### General Notes
|
||||
|
||||
- **Background graphics must be enabled** in any browser — otherwise header images, footer
|
||||
color stripes, and tonal backgrounds will not print.
|
||||
- Private/incognito mode blocks PWA install prompts — use normal browser sessions for kiosk.
|
||||
- For highest reliability, set the kiosk machine to auto-login and open Chrome to the event URL.
|
||||
|
||||
---
|
||||
|
||||
## Linux / CUPS Setup
|
||||
|
||||
For Linux workstations and dedicated kiosk machines running Linux:
|
||||
|
||||
1. Install CUPS if not already present: `sudo pacman -S cups` (Arch) or equivalent
|
||||
2. Start the CUPS service: `sudo systemctl enable --now cups`
|
||||
3. Open the CUPS web UI: `http://localhost:631`
|
||||
4. Add the printer and install the appropriate driver (see per-printer sections below)
|
||||
5. Print a test page from CUPS to confirm card feed and quality
|
||||
6. In Chrome: select the CUPS printer name under Destination in the print dialog
|
||||
|
||||
On macOS and Windows, use the vendor-provided driver installer.
|
||||
|
||||
---
|
||||
|
||||
## Printers
|
||||
|
||||
---
|
||||
|
||||
### Zebra ZC10L — PVC Card Printer
|
||||
|
||||
**Card stock:** 3.5" × 5.5" PVC cards (CR80 extended)
|
||||
**Tested:** 2026-03-17 (rental test day, Arch Linux)
|
||||
**Status:** Working. Confirmed suitable for Axonius NYC (mid-April 2026).
|
||||
|
||||
#### Physical Setup
|
||||
|
||||
- Connect via USB (the ZC10L supports USB and Ethernet)
|
||||
- Load PVC card stock per the Zebra loading instructions — cards face-up, landscape
|
||||
- The ZC10L prints one side (single-sided dye-sub thermal); do not attempt duplex on PVC stock
|
||||
|
||||
#### Linux Driver
|
||||
|
||||
- Download the Zebra ZC10L CUPS driver from zebra.com (ZC Series Linux support)
|
||||
- Install the `.deb` or extract the PPD file and add to CUPS manually
|
||||
- In CUPS (`http://localhost:631`), add the printer and select the ZC10L PPD
|
||||
- Set default paper size to **3.5" × 5.5"** (or CR80 Extended if listed)
|
||||
- Print a blank test page from CUPS before using Chrome
|
||||
|
||||
> **Note:** Driver version tested: *(update here after confirming)*
|
||||
> CUPS printer name used: *(update here after setup)*
|
||||
|
||||
#### Chrome Print Settings (ZC10L)
|
||||
|
||||
| Setting | Value |
|
||||
|---|---|
|
||||
| Destination | Zebra ZC10L (CUPS name) |
|
||||
| Paper size | 3.5 × 5.5 in (or as set in CUPS) |
|
||||
| Margins | **None** |
|
||||
| Background graphics | On |
|
||||
| Pages | 1 (front only) |
|
||||
|
||||
#### CSS Layout
|
||||
|
||||
The ZC10L uses the `badge_3.5x5.5_pvc` layout. The PVC layout CSS is at:
|
||||
`src/routes/events/[event_id]/(badges)/badges/print/badge_layout_zebra_zc10l_pvc.css`
|
||||
|
||||
This layout hides `.badge_back` in `@media print` — only the front face prints.
|
||||
`@page { size: 3.5in 5.5in; margin: 0; }` is set in the CSS.
|
||||
|
||||
#### Known Behaviors / Watch-outs
|
||||
|
||||
- Chrome with **Default** margins: inserts URL/date headers, offsets badge — use **None**
|
||||
- Chrome with **None** or **Minimum** margins: correct output
|
||||
- Firefox: works correctly out of the box with this layout
|
||||
- Physical card alignment: if the badge appears offset on the card, a CSS margin tweak may
|
||||
be needed in the PVC layout file — note the offset and adjust `print_margin_cfg` once that
|
||||
field is wired to the UI
|
||||
- Font sizes: if name/affiliation text appears too small at physical scale, adjust via the
|
||||
font size controls (+ / −) in the print controls panel; note the preferred values for this
|
||||
event's template
|
||||
|
||||
#### Test Results (2026-03-19)
|
||||
|
||||
- Card feeds and prints without jam: ✅
|
||||
- Single-sided PVC confirmed (back does not print): ✅
|
||||
- Chrome margins None/Minimum: correct output ✅
|
||||
- Firefox: correct output ✅
|
||||
- QR code scannable from printed card: ✅
|
||||
- Print tracking (`print_count` increment): ✅
|
||||
- Font sizes / visual quality: tested; specific calibration pending client design direction
|
||||
- Driver version: *(record here)*
|
||||
- Physical offset needed: *(record if any)*
|
||||
|
||||
---
|
||||
|
||||
### Epson — Fan-Fold / Label Printer
|
||||
|
||||
**Status:** Not yet tested. Section to be filled in after testing.
|
||||
|
||||
Common Epson models used for fan-fold name badge stock: TM-T88 series, C3500, LX series.
|
||||
Fan-fold stock is typically 4" × 3" or 4" × 6" paper labels.
|
||||
|
||||
#### CSS Layout
|
||||
|
||||
Fan-fold badges would use a layout sized to the specific label stock.
|
||||
A new CSS layout file will need to be created per stock size if not already present.
|
||||
Naming convention: `badge_layout_epson_[model]_[size].css`
|
||||
|
||||
#### Setup Notes
|
||||
|
||||
*(To be filled in after testing — cover: driver source, CUPS setup, paper size, Chrome settings)*
|
||||
|
||||
#### Known Behaviors
|
||||
|
||||
*(To be filled in after testing)*
|
||||
|
||||
---
|
||||
|
||||
## Print Tracking
|
||||
|
||||
The badge print page tracks print counts per badge:
|
||||
|
||||
- `print_count` — increments on each **Print Badge** button click
|
||||
- `print_first_datetime` — timestamp of first print
|
||||
- An amber "Printed N×" chip appears in the print page header after the first print
|
||||
|
||||
The reprint shortcut (trusted access + edit mode) does **not** increment the count.
|
||||
Only the **Print Badge** button path increments the count. This is intentional — reprints
|
||||
for alignment or quality checks should not inflate the print count.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause | Fix |
|
||||
|---|---|---|
|
||||
| White border around printed badge | Chrome Default margins | Change to None or Minimum |
|
||||
| URL / date printed at top or bottom | Chrome Default margins | Change to None |
|
||||
| Header image / stripe not printing | Background graphics disabled | Enable in print dialog |
|
||||
| Badge appears on wrong-size output | Paper size mismatch | Set correct size in CUPS and/or print dialog |
|
||||
| Card jams | Card stock misloaded | Re-seat cards per printer manual; check stock orientation |
|
||||
| Badge content clipped | Layout overflow | Check font size — use − control to reduce if needed |
|
||||
| Second blank card ejected | Duplex triggered on PVC | Confirm `.badge_back { display: none }` in print CSS for this layout |
|
||||
Reference in New Issue
Block a user