OSIT-AE-App-Svelte/documentation/MODULE__AE_Events_Badge_Templates.md

MODULE: Aether Events — Badge Templates

Module Path: src/routes/events/[event_id]/(badges)/templates/ API Module: src/lib/ae_events/ae_events__event_badge_template.ts Database Table: event_badge_template Last Updated: 2026-03-02

---

Overview

Badge templates define the visual and structural configuration for printing event badges. Each template applies to one category of badge (e.g., general attendees, workshops, exhibitors). An event typically has 1–3 templates.

Key principle: One template per badge stock type/audience. Do not use flags on a single template to drive multiple layouts — create a separate template instead.

Common template sets:

• General Attendees — main conference badge (most attendees)
• Workshops / Pre-conference — alternate header, possibly different badge type list
• Exhibitors — distinct footer stripe colors, exhibitor-specific badge types

Each template uses the same physical badge stock and printer configuration.

---

DB Field Reference

Core Identity

Field	Type	Notes
id	int	Internal PK
id_random	str	External-facing ID (AE Triple ID pattern)
event_id	str	Parent event
name	str	Template display name
description	str	Optional description

Image Assets

Field	Type	Notes
logo_path	str (URL)	Org logo — fallback when no header image
logo_filename	str	Deprecated — redundant with logo_path; do not use
header_path	str (URL)	Front-of-badge header image — primary branding
secondary_header_path	str (URL)	Back-of-badge header image (falls back to header_path)
footer_path	str (URL)	Optional footer image — rarely used
header_row_1	str/HTML	Text fallback line 1 when no header image
header_row_2	str/HTML	Text fallback line 2
footer_title, footer_left, footer_right	str	Legacy Flask-era fields — not used
header_background, footer_background	str	Legacy — not used; do not add to new templates

Network / WiFi

Field	Type	Notes
wireless_ssid	str	WiFi network name — displayed on badge back
wireless_password	str	WiFi password — displayed on badge back

QR Code Behavior

Field	Type	Notes
show_qr_front	bool (0/1)	Show attendee QR code on front of badge
show_qr_back	bool (0/1)	Show attendee QR code (+ ID text) on back of badge

Badge Type List

Field	Type	Notes
badge_type_list	JSON string	List of {code, name} objects for this template

Format:

[
  {"code": "current_member", "name": "Member"},
  {"code": "guest", "name": "Guest"},
  {"code": "staff", "name": "Staff"},
  {"code": "test", "name": "Test"}
]

The badge type footer stripe color is driven by CSS rules targeting the code value as a class on the footer element. Each event/template defines its own list — there is no global default. The component derives this list from the template at render time.

Ticket Definitions

Field	Type	Notes
ticket_list	JSON string	List of {num, code, name} for this template's tickets
ticket_1_text – ticket_8_text	HTML	Ticket block HTML printed on badge back

ticket_list format:

[
  {"num": 1, "code": "foundation_reception", "name": "Foundation Reception"},
  {"num": 2, "code": "volunteer_reception", "name": "Volunteer Reception"}
]

The ticket_N_code field on the badge object references a ticket by its code. The corresponding ticket_N_text on the template provides the HTML rendered on the badge.

Print Layout / Styling

Field	Type	Notes
layout	str	Layout code — see Layout Codes below
style_filename	str	CSS filename for locally-served stylesheets
style_href	str (URL)	Preferred — external URL for custom CSS
script_src	str (URL)	Do not use — Flask-era arbitrary script injection

Access Control

Field	Type	Notes
passcode	str	Shared passcode for template management access
enable	bool	Standard AE enable flag
hide	bool	Standard AE hide flag
priority, sort, group	int/str	Standard AE sort fields
notes	str	Internal notes

New Field (pending backend addition)

Field	Type	Notes
duplex	bool	Planned — when false, back section is hidden from print (@media print)

The duplex field controls whether the back-of-badge section renders during printing. When false (single-sided), badge_back gets print:hidden applied so only the front prints. The back section still displays on screen for configuration reference.

The first event using this system (Axonius, NYC, mid-April 2026) uses single-sided PVC cards on a Zebra ZC10L — duplex will be false for that event's templates.

---

External CSS Approach

Why External

Badge templates may need visual adjustments mid-event (e.g., a color correction, a footer fix) without deploying a new SvelteKit build. Hosting the CSS at an external URL allows changes to take effect on next page load without any deployment.

How It Works

The style_href field contains a full URL to a CSS file hosted on the static server (e.g., https://static.oneskyit.com/c/ISHLT/css/badges_custom_ishlt.css).

The print page (print/+page.svelte) or the badge view should conditionally add a <link> element via <svelte:head> when style_href is populated:

<svelte:head>
    {#if $lq__event_badge_template_obj?.style_href}
        <link
            rel="stylesheet"
            href={$lq__event_badge_template_obj.style_href}
        />
    {/if}
</svelte:head>

This is not yet implemented — tracked as a pending Phase 1 item.

CSS Scope

External badge CSS should scope all rules under .badge_front, .badge_back, etc. to avoid bleeding into the rest of the app. The classes used in ae_comp__badge_obj_view.svelte are the canonical hook points:

• .badge_front — entire front card
• .badge_back — entire back card
• .badge_header — front header area
• .badge_body — front content area (name, title, affiliations, location)
• .badge_footer — front footer stripe
• .badge_back_header — back header area
• .badge_back_content — back content area
• .badge_footer_center.<code> — footer text per badge type code (for color stripes)

layout field

The layout field encodes physical badge stock dimensions. Standard codes to use:

Code	Dimensions	CSS file	Description
badge_4x5_fanfold	4" × 5" (101.6 × 127mm)	badge_layout_epson_4x5_fanfold.css	Epson ColorWorks C3500 / ExpoBadge fanfold — preferred for general conference use (ISHLT, demos)
badge_3.5x5.5_pvc	3.5" × 5.5" (88.9 × 139.7mm)	badge_layout_zebra_zc10l_pvc.css	PVC card, Zebra ZC10L — single-sided, set duplex=0
badge_4x6_fanfold	4" × 6" (101.6 × 152.4mm)	(none — Tailwind defaults)	Generic fanfold fallback; dimensions match the hardcoded Tailwind values
badge_4x6_fanfold_tickets	4" × 6" + tear-offs	(pending)	Fanfold with ticket stubs

Layout CSS files live in src/lib/ae_events/badges/css/ and are imported by ae_comp__badge_obj_view.svelte. Rules are scoped under [data-layout="..."] on the wrapper so multiple layouts can coexist in the bundle without conflict.

@page paper size rules are injected per-layout from print/+page.svelte <svelte:head> (attribute selectors cannot scope @page rules, so they're handled dynamically).

---

Template-Derived Features (component behavior)

badge_type_list → badge type select

The badge type dropdown shown when editing a badge is derived from the template's badge_type_list JSON, not a hardcoded list. This was a bug (fixed 2026-03-02). See ae_comp__badge_obj_view.svelte — badge_type_code_li is now $derived.by().

"Info section" flags (exhibitor_info, presenter_info, etc.)

These flags (exhibitor_info, presenter_info, staff_info, vip_info, vote_info) do not exist as DB columns. They appeared as placeholder {#if} blocks in the badge view component from Flask-era development and were never implemented.

The correct approach is one template per badge audience — an Exhibitor template will have exhibitor-specific badge_type_list, header images, and CSS. No flags needed.

The dead {#if $lq__event_badge_template_obj.exhibitor_info} blocks in ae_comp__badge_obj_view.svelte should be removed in a future cleanup pass.

---

Properties Saved to IDB (Dexie)

The properties_to_save array in ae_events__event_badge_template.ts controls what gets cached locally. Current state — fields NOT in properties_to_save that exist in DB and may be needed:

• style_href — needed once external CSS is wired via <svelte:head>
• passcode — not needed client-side
• footer_title, footer_left, footer_right — not needed (legacy)
• header_background, footer_background — not needed (legacy)
• script_src — do not add; this field should not be used
• duplex — add when backend adds the field

---

Standard Template Setup (per event)

1. General Attendees template

• header_path: event-specific conference header image
• secondary_header_path: back-of-badge header (often same or related image)
• wireless_ssid + wireless_password: venue WiFi
• show_qr_back: 1 (back QR is standard for most events)
• show_qr_front: 0 (usually off for front)
• badge_type_list: full list of member/guest/staff/test types
• ticket_list + ticket_N_text: event-specific tickets if applicable
• style_href: client-specific CSS URL
• layout: appropriate layout code
• duplex: 1 (or 0 for single-sided events like Axonius 2026)

2. Workshop / Pre-conference template

• Same as above but with workshop-specific header images
• badge_type_list: reduced list (workshop-relevant types only)
• ticket_list: may be empty []
• duplex: match main template

3. Exhibitor template

• Exhibitor-specific header images
• badge_type_list: exhibitor-only types (ex_all, ex_booth, guest, staff, test)
• ticket_list: [] (exhibitors typically don't have event tickets)
• show_qr_back: may be 0 (exhibitors scan others, they don't need their own QR prominent)
• wireless_ssid + wireless_password: same venue WiFi

---

Related Files

File	Role
ae_events__event_badge_template.ts	API + IDB functions; properties_to_save
db_events.ts	Dexie schema for badge_template table
templates/+page.svelte	Template list + create/edit/delete UI
templates/ae_comp__badge_template_form.svelte	Template create/edit form
[badge_id]/ae_comp__badge_obj_view.svelte	Badge render — consumes template data
[badge_id]/print/+page.svelte	Print page — loads template, hosts <svelte:head> CSS
documentation/MODULE__AE_Events_Badges.md	Badge object reference

---

Pending / TODO

• Wire style_href via <svelte:head> in print page
• Add duplex to properties_to_save once backend field exists
• Add duplex-driven print:hidden to badge_back section in ae_comp__badge_obj_view.svelte
• Make layout field drive actual card dimensions in the badge component (currently hard-coded)
• Remove dead exhibitor_info / presenter_info / staff_info / vip_info / vote_info {#if} blocks from ae_comp__badge_obj_view.svelte
• Improve ae_comp__badge_template_form.svelte to edit all relevant fields (currently minimal)