118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
# JavaScript Usage
|
|
|
|
This project minimizes JavaScript usage, preferring pure CSS solutions where possible (e.g., `<details>` elements for toggles). JavaScript is used only where necessary for payment integrations, real-time updates, and progressive enhancement.
|
|
|
|
## Philosophy
|
|
|
|
- Prefer pure HTML/CSS over JavaScript
|
|
- Use `<details>` elements for toggles instead of JS
|
|
- External SDKs loaded only when payment method is enabled
|
|
- No build step - vanilla JS only
|
|
- No jQuery - all vanilla JavaScript
|
|
|
|
## Static JavaScript Files
|
|
|
|
Located in `make_post_sell/static/js/`:
|
|
|
|
### qrcode.min.js
|
|
- QRious library for QR code generation
|
|
- Used by: Crypto checkout page
|
|
- Generates payment QR codes for XMR/DOGE addresses
|
|
|
|
### custom.js
|
|
- Markdown preview functionality
|
|
- Functions: `previewAjax()`, `sendPreview()`
|
|
- Uses fetch API for AJAX calls to `/markup-editor-preview`
|
|
|
|
## Inline JavaScript by Template
|
|
|
|
### base.j2
|
|
**Purpose:** Theme switching (dark/light mode)
|
|
|
|
- Runs immediately in `<head>` to prevent flash of wrong theme
|
|
- Priority: localStorage > user preference > shop default
|
|
- Exposes `window.setTheme()` for programmatic use
|
|
|
|
### shop_settings.j2
|
|
**Purpose:** Settings page interactions
|
|
|
|
- Crypto wallets toggle (checkbox + localStorage)
|
|
- Theme preview for shop default theme radio buttons
|
|
- Note: Payment provider toggles use pure CSS `<details>` elements
|
|
|
|
### user_settings.j2
|
|
**Purpose:** User theme preference sync
|
|
|
|
- Syncs theme radio buttons with localStorage
|
|
- Updates localStorage on form submit
|
|
|
|
### cart_checkout.j2
|
|
**Purpose:** Payment processing
|
|
|
|
1. **PayPal SDK** (`paypal.Buttons()`)
|
|
- Loads PayPal SDK from `paypal.com`
|
|
- Creates orders via `POST /paypal/create-order`
|
|
- Handles approval flow and form submission
|
|
- Double-click protection flags
|
|
|
|
2. **Cancel Crypto Quote** (`cancelQuote()`)
|
|
- Cancels pending crypto payment quotes
|
|
- Uses fetch API with CSRF token
|
|
|
|
### crypto_checkout.j2
|
|
**Purpose:** Crypto payment monitoring
|
|
|
|
- QR code generation using QRious library
|
|
- Countdown timer for quote expiry
|
|
- Status polling via fetch API
|
|
- Copy-to-clipboard for address/amount
|
|
- Dynamic UI updates based on payment status
|
|
- Functions: `disableQuoteButtons()`, `removePaymentElements()`, `replaceButtonsWithInvoiceLink()`
|
|
|
|
### snippets/stripe.j2
|
|
**Purpose:** Stripe card form (macro `new_card()`)
|
|
|
|
- Loads Stripe.js SDK
|
|
- Creates Payment Element for card input
|
|
- Handles `stripe.confirmSetup()` flow
|
|
- Uses vanilla JS with `DOMContentLoaded`
|
|
|
|
### snippets/analytics.j2
|
|
**Purpose:** Analytics tracking (optional)
|
|
|
|
- Plausible Analytics (privacy-focused)
|
|
- Google Analytics (gtag.js)
|
|
- Only loaded if shop has configured analytics
|
|
|
|
### snippets/optional-javascript.j2
|
|
**Purpose:** Optional JS loading
|
|
|
|
- Loads custom.js async
|
|
- Used for markdown preview functionality
|
|
|
|
## External SDKs
|
|
|
|
| SDK | URL | Used For |
|
|
|-----|-----|----------|
|
|
| PayPal | `paypal.com/sdk/js` | PayPal button/checkout |
|
|
| Stripe | `js.stripe.com/v3/` | Card payment form |
|
|
| Plausible | Shop-configured domain | Privacy analytics |
|
|
| Google Analytics | `googletagmanager.com` | Google analytics |
|
|
|
|
## CSRF Protection
|
|
|
|
All fetch/AJAX calls include CSRF tokens:
|
|
- Header: `X-CSRF-Token`
|
|
- Value from: `{{ request.session.get_csrf_token() }}` or hidden input
|
|
|
|
## Progressive Enhancement
|
|
|
|
Pages work without JavaScript where possible:
|
|
- Payment provider toggles use `<details>` (pure CSS)
|
|
- Forms submit normally without JS
|
|
- JS enhances UX (copy buttons, QR codes, live previews)
|
|
|
|
## Future Improvements
|
|
|
|
- Convert remaining checkbox toggles to `<details>` elements
|
|
- Consider removing Google Analytics option (privacy)
|