From 3ae5b30c372b1af114f9c76f815119b078c18e7f Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Thu, 4 Jun 2026 19:46:59 -0400 Subject: [PATCH] docs(badges): update badges and badge template documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MODULE__AE_Events_Badges: update Search & Filter section — visibility select (3 options, manager-gated), result limit stepper table, badge type filter hardcoding noted as known gap. MODULE__AE_Events_Badge_Templates: add full cfg_json reference section covering all keys (visibility, QR, alignment, header image, appearance, fit_heights, controls_cfg). Update TODO — duplex/form/header cfg done; badge_type_list→search wired as open item. Co-Authored-By: Claude Sonnet 4.6 --- .../MODULE__AE_Events_Badge_Templates.md | 104 +++++++++++++++++- documentation/MODULE__AE_Events_Badges.md | 26 ++++- 2 files changed, 128 insertions(+), 2 deletions(-) diff --git a/documentation/MODULE__AE_Events_Badge_Templates.md b/documentation/MODULE__AE_Events_Badge_Templates.md index 0bb6c1a2..acaf6c30 100644 --- a/documentation/MODULE__AE_Events_Badge_Templates.md +++ b/documentation/MODULE__AE_Events_Badge_Templates.md @@ -194,6 +194,106 @@ wrapper so multiple layouts can coexist in the bundle without conflict. --- +## cfg_json Reference + +All keys are optional. Unknown keys are preserved on save (forward-compatible). Managed via the template form's **Advanced** and **Header & Branding** sections, or directly in phpMyAdmin. + +### Visibility + +| Key | Type | Default | Notes | +| --- | --- | --- | --- | +| `hide_badge_header` | bool | `false` | Hides the entire header section (image + logo/text fallback). Auto-true when `background_image_path` is set, unless explicitly overridden. | +| `hide_badge_footer` | bool | `false` | Hides the badge type footer stripe. | +| `hide_title` | bool | `false` | Suppresses the professional title field on the badge front. | +| `hide_affiliations` | bool | `false` | Suppresses the affiliations field. | +| `hide_location` | bool | `false` | Suppresses the location field. | + +### QR Codes + +These keys override the top-level DB fields (`show_qr_front`, `show_qr_back`) when present. Prefer setting them here rather than the top-level fields. + +| Key | Type | Default | Notes | +| --- | --- | --- | --- | +| `show_qr_front` | bool | `false` | Show attendee QR on badge front. | +| `show_qr_back` | bool | `true` | Show attendee QR (+ ID text) on badge back. | + +### Text Alignment + +Stored under a nested `align` object. + +```json +"align": { "name": "left", "title": "left", "affiliations": "left", "location": "center" } +``` + +| Key | Values | Default | +| --- | --- | --- | +| `align.name` | `left` \| `center` \| `right` \| `justify` | `center` | +| `align.title` | `left` \| `center` \| `right` \| `justify` | `center` | +| `align.affiliations` | `left` \| `center` \| `right` \| `justify` | `center` | +| `align.location` | `left` \| `center` \| `right` \| `justify` | `center` | + +QR alignment stored under `qr_alignment`: + +| Key | Values | Default | +| --- | --- | --- | +| `qr_alignment.front` | `left` \| `center` \| `right` | `center` | +| `qr_alignment.back` | `left` \| `center` \| `right` \| `justify` | `center` | + +### Header Image + +| Key | Type | Default | Notes | +| --- | --- | --- | --- | +| `header_margin_top` | CSS length | `2rem` | Vertical offset of the header image. Negative = shift up. e.g. `"-0.25in"`, `"1rem"`. | +| `header_border_color` | hex color | none | Bottom border drawn below the header div. **Empty = no border.** e.g. `"#FE6111"`. | +| `header_border_width` | CSS length | `2px` | Thickness of the header bottom border. Only applied when `header_border_color` is set. | +| `header_padding_bottom` | CSS length | none | Space between the header image and the bottom border line. e.g. `"1.45in"`. | + +### Appearance + +| Key | Type | Default | Notes | +| --- | --- | --- | --- | +| `body_text_color` | hex color | `#000000` | Inline color applied to all badge body text. | +| `bleed` | CSS length | none | Extends background image past card edges on all sides. Prevents white borders on printers that clip slightly inside the card. e.g. `"0.125in"`, `"3mm"`. | + +### Text Zone Heights (`fit_heights`) + +Per-layout height overrides for the auto-scaling text zones. Set any subset — unset keys fall back to the layout default. Useful when `background_image_path` is set and the designed zones don't align with code defaults. + +```json +"fit_heights": { "grp_name_title": "1.8in", "name": "1.4in" } +``` + +| Key | Notes | +|---|---| +| `grp_name_title` | Height of the name+title container | +| `grp_name_title_flex` | Flex distribution: `around` \| `between` \| `even` \| `center` \| `start` \| `end` | +| `name` | Height of the name text zone | +| `title` | Height of the title text zone | +| `grp_aff_loc` | Height of the affiliations+location container | +| `grp_aff_loc_flex` | Flex distribution (same values as above) | +| `affiliations` | Height of the affiliations text zone | +| `location` | Height of the location text zone | + +### Controls Panel (`controls_cfg`) + +Controls which fields appear in the print controls panel for non-trusted users, and which fields authenticated users may edit. Trusted + Edit Mode always sees and can edit all fields regardless of this config. + +```json +"controls_cfg": { + "shown": ["name", "title", "affiliations"], + "auth_editable": ["title", "affiliations", "location"] +} +``` + +| Key | Type | Default | +| --- | --- | --- | +| `controls_cfg.shown` | `string[]` | `["name", "title", "affiliations", "location"]` | +| `controls_cfg.auth_editable` | `string[]` | `["title", "affiliations", "location", "allow_tracking", "pronouns"]` | + +Valid field keys: `name`, `title`, `affiliations`, `location`, `pronouns`, `allow_tracking`. + +--- + ## Template-Derived Features (component behavior) ### badge_type_list → badge type select @@ -361,6 +461,8 @@ Firefox users can use "Save to PDF" directly — it just works. - [x] Add `duplex` to `properties_to_save` — done. (2026-03-18 verified) - [x] Add `duplex`-driven suppression to `badge_back` section — done in `ae_comp__badge_obj_view.svelte`; `show_badge_back` derived from `duplex` field. - [x] `badge_4x6_fanfold` layout CSS created (`badge_layout_epson_4x6_fanfold.css`), imported in badge component, `@page 4in 6in` wired in print page. (2026-05-15) +- [x] Template form expanded — `layout`, `style_href`, `badge_type_list`, `duplex`, and all `cfg_json` keys now editable via the form. (2026-06-04) +- [x] `cfg_json.header_margin_top`, `header_border_color`, `header_border_width`, `header_padding_bottom` added — header image position and bottom border are fully configurable without a code deploy. (2026-06-04) +- [ ] Wire `badge_type_list` from the template into the badge search filter — currently the search form uses a hardcoded list. See `ae_comp__badge_search.svelte` TODO comment. - [ ] `badge_4x5_fanfold` layout CSS exists but is stale (not used in 2+ years) — review against actual hardware before next use. - [ ] Remove dead `exhibitor_info` / `presenter_info` / `staff_info` / `vip_info` / `vote_info` `{#if}` blocks from `ae_comp__badge_obj_view.svelte` (if they were carried over from v1) -- [ ] Improve `ae_comp__badge_template_form.svelte` to edit all relevant fields (currently minimal) diff --git a/documentation/MODULE__AE_Events_Badges.md b/documentation/MODULE__AE_Events_Badges.md index f81d3003..5deeb0cf 100644 --- a/documentation/MODULE__AE_Events_Badges.md +++ b/documentation/MODULE__AE_Events_Badges.md @@ -71,7 +71,31 @@ Attendees can access their own record via a passcode-gated link (typically `?pas - **Fulltext Search:** Matches against a consolidated `default_qry_str` (Name, email, IDs). - **Multi-Word Logic:** Queries like "Scott Idem" are split and treated as `LIKE %Scott% AND LIKE %Idem%`. - **QR Scan Search:** Scanning an attendee's QR code (from a confirmation email or old badge) immediately jumps to their record. -- **Advanced Filters:** Filter by Badge Type, Printed Status, or Affiliations (Staff only). +- **Advanced Filters (Trusted + Edit Mode):** Badge Type, Printed Status, Affiliations, Sort Order. + +### Visibility Filter (Trusted + Edit Mode) + +Three-option select controlling which records are shown: + +| Option | Who can set it | Effect | +| --- | --- | --- | +| **Default** | Any | Hides hidden and disabled badges | +| **Show Hidden** | Trusted | Shows hidden badges alongside normal ones | +| **Show Disabled + Hidden** | Manager only | Shows all records regardless of enable/hide flags | + +### Result Limit Stepper (Edit Mode) + +Controls the maximum number of results returned. Only visible in edit mode. + +| Access Level | Range | Step | +| --- | --- | --- | +| Below Trusted | Fixed 25 | — | +| Trusted | 25 – 250 | 25 | +| Manager+ | 25 – 2550 | 25 up to 250, then 100 | + +### Badge Type Filter — Known Limitation + +The badge type dropdown in the search form uses a **hardcoded list**, not the template's `badge_type_list`. This means the codes shown in the filter may not match the codes used by the current event's template. This is a known gap — the fix requires passing the template object into the search component. Until resolved, staff can still search by name/email and filter results manually. ---