Athenian Barcode & QR Code Generator

Developer starting point

This baseline documents barcode and QR generation code. It does not claim a generated production artifact or physical scanner workflow has been exercised.

Shortcode Usage

Default Generator

[athenian_barcode_qr_generator]

Alias Shortcode

[abqg_generator]

Custom Title and Subtitle

[athenian_barcode_qr_generator title="Code Studio" subtitle="Generate QR, barcode, GS1, and label payloads from one interface."]

Start in Barcode Mode

[athenian_barcode_qr_generator default_mode="barcode"]

Supported Shortcode Attributes

| Attribute | Default | Notes | |---|---:|---| | title | Barcode and QR Studio | Display title shown in the shortcode topbar. | | subtitle | Generate production-ready codes with compact controls and Athenian-style UI. | Supporting copy shown below the title. | | default_mode | qr | Accepts qr or barcode. Any other value falls back to QR mode. |

---

Frontend Workflow

1. User places the shortcode on a WordPress page or builder template.
2. Plugin enqueues the registered shortcode CSS and JavaScript assets.
3. The shortcode renders a two-column generator interface with controls and preview.
4. JavaScript boots one ABQGApp instance for each shortcode root.
5. The app loads saved state from localStorage, falling back to default QR/barcode/integration settings.
6. User chooses QR or barcode mode.
7. User enters or builds a payload.
8. Output renders instantly in SVG form.
9. Validation messages and preview dimensions update live.
10. Builder outputs refresh and dispatch the abqg:payloads browser event.
11. User exports the output as an image, PDF, SVG, or JSON config.

---

Technical Architecture

File Structure

athenian-barcode-qr-generator/
├── athenian-barcode-qr-generator.php
├── includes/
│   ├── class-abqg-assets.php
│   └── class-abqg-shortcode.php
├── assets/
│   ├── css/
│   │   └── abqg-shortcode.css
│   ├── js/
│   │   └── abqg-shortcode.js
│   └── vendor/
│       ├── jsbarcode/JsBarcode.all.min.js
│       ├── jspdf/jspdf.umd.min.js
│       └── qrcode/qrcode.min.js
├── docs/
│   ├── abqg-marketing-document.md
│   └── epricetag-integration.md
└── output/playwright/
    ├── visual QA screenshots
    └── shortcode harness files

Main Plugin Bootstrap

The root plugin file defines constants, verifies the PHP version, registers an activation guard, loads the plugin text domain, and initializes the asset and shortcode classes.

Defined constants include:

• ABQG_FILE
• ABQG_PATH
• ABQG_URL
• ABQG_BASENAME
• ABQG_VER
• ABQG_MIN_PHP

PHP Version Guard

The plugin requires PHP 7.4 or newer. If the environment does not meet the requirement, it displays an admin notice and prevents activation.

Classes

| Class | Responsibility | |---|---| | ABQG_Assets | Registers and enqueues CSS/JS assets required by the shortcode generator. | | ABQG_Shortcode | Registers the shortcodes and renders the frontend generator markup. |

---

JavaScript Application Model

The frontend application is implemented as a browser-side ABQGApp class. Each shortcode instance receives its own app instance and its own indexed localStorage key.

Default State Areas

The app maintains three major state sections:

| State Section | Purpose | |---|---| | mode | Current active mode, either qr or barcode. | | qr | QR payload, visual settings, logo data, size, margin, colors, error correction, and preset. | | barcode | Barcode payload, format, dimensions, text settings, colors, PDF417 settings, and preset. | | integration | GS1, Digital Link, label, store, template, product URL, campaign URL, and notes data. |

State Persistence

The generator persists state in window.localStorage. Each shortcode instance uses the localized storage prefix plus an index, which helps avoid collisions when multiple generators appear on the same page.

Logo data is intentionally excluded from persisted state and reset during load/export snapshots to avoid permanently storing uploaded logo data URLs.

---

Rendering Details

QR Rendering

QR generation uses window.QRCode.create() to generate QR modules, then ABQG custom-renders the modules into an SVG. This allows more flexible visual styling than simply outputting a default canvas.

The QR renderer:

• Reads the QR payload and error correction level.
• Calculates module size based on render size and margin.
• Skips finder cells during normal module rendering.
• Renders custom finder marks separately.
• Supports multiple module shapes.
• Adds a background rectangle.
• Optionally adds a center logo with a background patch.
• Stores the latest SVG markup for export.

Linear Barcode Rendering

Linear barcode rendering uses window.JsBarcode() and updates an SVG element in the preview area.

The renderer passes current settings for:

• Format
• Width
• Height
• Margin
• Line color
• Background
• Human-readable text visibility
• Text position
• Font size
• Font family

After rendering, the plugin calculates the SVG bounding box, normalizes the viewBox, stores dimensions, serializes the SVG, and enables export buttons.

PDF417 Rendering

PDF417 rendering uses bwip-js with toSVG(). ABQG passes PDF417-specific options such as:

• bcid: "pdf417"
• Text payload
• Scale
• Columns
• Rows
• Security level
• Compact mode
• Padding width/height
• Background color
• Bar color

The generated SVG is normalized with a data-role="barcode-svg" marker and an accessible label.

---

GS1 and Integration Payloads

ABQG builds standards-oriented payloads from the integration panel.

GS1 Digital Link

Digital Link URLs use the configured GS1 domain and GTIN path:

https://id.example.com/01/{GTIN}

Optional qualifiers are appended as query parameters:

| GS1 AI | Field | |---|---| | 21 | Serial | | 10 | Lot / batch | | 17 | Expiry | | 240 | Additional ID |

GS1 AI Element String

The plugin also builds a human-readable GS1 AI element string, for example:

(01)00012345678905(21)SN-0001(10)LOT-24A(17)270630(240)ATH-CORE-01

E-Pricetag Payload

The e-pricetag payload is a label-centric JSON object that includes:

• Source identifier
• Generated timestamp
• Label UID
• Store key
• Template key
• QR URL
• Barcode value
• Barcode format
• Digital Link URL
• GS1 element string
• GTIN
• Serial
• Lot
• Expiry
• Product URL
• Campaign URL
• Notes

Generic REST Update Payload

The REST payload uses a versioned envelope with an updates[] array. This structure is intended for generic REST connectors, ESL middleware, signage systems, or downstream Athenian integration tools.

---

Browser Event Integration

Every render or builder update dispatches a browser event from the shortcode root:

abqg:payloads

The event bubbles and includes a detail object with:

• digitalLink
• gs1ElementString
• etagPayload
• restPayload
• gtinDigits

Example Listener

document.addEventListener("abqg:payloads", (event) => {
  console.log("Digital Link:", event.detail.digitalLink);
  console.log("E-pricetag payload:", event.detail.etagPayload);
});

This creates a clean integration point for other frontend scripts, e-pricetag sync tools, internal admin utilities, or future Athenian platform modules.

---

E-Pricetag and Shelf-Tag Integration Story

The included docs/epricetag-integration.md outlines how ABQG can feed an athenian-e-pricetag-sync-manager or any middleware that accepts generic REST updates.

Recommended downstream fields include:

• digital_link_url
• gs1_element_string
• barcode_format
• code_profile
• campaign_url
• template_key
• codes
• links

Strategic integration scenarios include:

• UPC/EAN retail labels with GS1 Digital Link QR beside them.
• Smart shelf tags showing consumer-facing QR plus scanner-facing barcode data.
• Product passport flows where the Digital Link becomes the scannable gateway.
• Serialized products using GS1 serial, lot, and expiry fields.
• ESL middleware receiving REST update payloads generated from WordPress.

---

WordPress Integration Points

Hooks Used

| Hook | Usage | |---|---| | register_activation_hook | Enforces minimum PHP version during activation. | | admin_notices | Displays PHP compatibility errors. | | plugins_loaded | Loads text domain, registers assets, and registers shortcodes. | | add_shortcode | Registers public generator shortcodes. | | apply_filters('abqg_bwipjs_url', ...) | Allows the PDF417 script URL to be customized. |

No Server-Side Storage by Default

The current implementation does not create custom database tables, custom post types, admin settings pages, REST endpoints, or server-side generated files. Generation and export are handled in the browser, with state persisted locally through localStorage.

This keeps the plugin lightweight and portable while leaving room for future server-side persistence, WooCommerce product mapping, or e-pricetag sync integration.

---

Implementation Notes

Current Strengths

• Lightweight architecture with no database dependency.
• Shortcode-first deployment model.
• Rich frontend app with isolated per-instance state.
• Strong export coverage for both design and handoff needs.
• Built-in GS1 and integration payload helpers.
• Compatible styling approach for Athenian token systems.
• Browser event integration point for downstream scripts.

Current Limitations

• Most functionality is browser-side; there is no server-side asset library or saved code history.
• PDF417 relies on an external CDN by default unless the URL is filtered to a local copy.
• WooCommerce product binding is not implemented in the current plugin code.
• GS1 logic builds useful payload formats but does not replace formal GS1 validation/certification workflows.
• Generated assets are downloaded locally rather than saved to the WordPress Media Library.
• There is no admin settings page for defaults, presets, or dependency hosting.

Code Review Observations

The plugin is compact and focused, but future cleanup could include:

• Removing a duplicate currentOutputValid assignment in the JavaScript constructor.
• Reviewing the shortcode template markup for minor duplicated/stray closing tags.
• Reviewing the CSS around .abqg-accordion > .abqg-panel__body, where a selector appears duplicated.
• Optionally moving the bwip-js dependency into the bundled vendor directory for fully offline/self-hosted environments.

These notes do not change the core value of the plugin, but they are useful before packaging this as a broader public release.

---