Operator Guide (v1.0.0)

Purpose: A one-page, hand-offable guide so any manager can operate, troubleshoot, and extend the Duck MapWordPress plugin.

1) Quick Start (10 minutes)

Pages / Blocks

Map page: add shortcode [td_duckmap].
On that same page, add your “Add Duck Sighting” CTA button with id="td-open-sighting".
Add an Essential Blocks (EB) Modal set to External Trigger = #td-open-sighting.
Inside the modal: [td_duck_sighting_form].

Settings → TerrainDucks Map

Map center (lat/lng), default zoom.
Admin emails (comma-separated).
Toggle: “Email contributor on approval”.
Optional: custom marker icon URL.

QR format

https://YOURDOMAIN.com/duckmap?duck=S431#add-sighting

?duck= pre-fills the Duck ID; #add-sighting auto-opens the modal.

Moderate

WP Admin → Duck Sightings → Approve (row action) or Bulk Approve.
You’ll see a green notice confirming.

2) Minimum Required Plugins (and Recommended)

Required

TerrainDucks Map (this plugin) — provides CPTs, REST API, map, form, emails.
FluentSMTP (or any SMTP plugin) — ensures outgoing emails (pending/approved notifications) actually deliver.

Strongly Recommended

Essential Blocks — for the modal/popup UX (external trigger).
(If you don’t want a modal, you can use a dedicated page instead and skip EB.)
Header & Footer Code Manager or Code Snippets — a safe way to add the tiny auto-open script to /duckmapwithout editing theme files.

Optional / Nice to have

Image optimization (e.g., Smush, ShortPixel) — reduces map popup image sizes.
Caching plugin — improve frontend speed; ensure REST (/wp-json/td/v1/*) isn’t blocked.
Security/WAF — allowlist:
- POST /wp-json/td/v1/pin (multipart)
- GET /wp-json/td/v1/pins

No Leaflet plugin needed; the map uses CDN assets bundled via the plugin.

3) What the Plugin Does

Collects user sightings via QR → photo + city + state (+ optional email/caption).
Moderates all new submissions → pending until approved.
Renders approved pins on a clustered Leaflet map.
Sends emails: admins on new pending; contributor on approval (if they provided email).
Enforces nonce, IP rate limiting (5/24h), and file checks (JPG/PNG/WEBP ≤ 5MB).

4) Content Model (CPTs)

Duck (optional catalog) — internal record of physical ducks (e.g., S431).
Duck Sighting (public submission) — title: “S431 @ City, State”; meta includes duck_id (1 letter + 3 digits), city, state, lat, lng, caption, email; thumbnail = submitted photo; status: pending → publish.

5) Frontend Setup Patterns

A) Map + Modal (recommended)

[td_duckmap] on /duckmap
Button id="td-open-sighting"
EB modal (External Trigger: #td-open-sighting)
Inside modal: [td_duck_sighting_form]
Custom HTML block (below) with auto-open script (provided earlier)

B) Dedicated page (alternative)

Page /duckmap/add-sighting/ with [td_duck_sighting_form redirect="/duckmap"]
QR: https://YOURDOMAIN.com/duckmap/add-sighting/?duck=S431

6) Submission Rules (user inputs)

Duck ID: ^[A-Z][0-9]{3}$ (e.g., S431). Auto-uppercase; server-validated.
City, State: required.
Photo: JPG/PNG/WEBP, ≤ 5 MB.
Email: optional (for approval notification).

7) Admin Workflow

Admin notified via email on new pending sighting.
Approve in WP Admin → Duck Sightings (row action or bulk).
If enabled and provided, contributor receives approval email with map link.

8) Settings (Options → TerrainDucks Map)

Map center lat/lng, zoom
Admin emails
Email contributor on approval (toggle)
Optional marker icon URL

9) API & Extensibility

GET /wp-json/td/v1/pins — returns approved pins; ?duck=S431 filter (case-insensitive).
POST /wp-json/td/v1/pin — public nonce header X-TD-Nonce, multipart upload.
Rate limit: 5 submissions per IP / 24h.
Files: JPG/PNG/WEBP up to 5MB.

10) Troubleshooting (60-second checklist)

Form shows “Oops” → Read the precise message.
Network tab → POST /wp-json/td/v1/pin response codes:
- 400 td_missing → required field blank
- 400 td_bad_duck_id → wrong ID format
- 429 td_rate_limited → too many from this IP
- 400 td_file_too_large / td_bad_mime → image issue
- 403 → nonce invalid (avoid overly aggressive caching on form HTML)
No pins → need published (approved) Duck Sightings. Test /wp-json/td/v1/pins directly.
Emails → FluentSMTP logs; verify admin email list in Settings.

11) Operations & Maintenance

Version: shown in Plugins list & admin footer.
Releases: bump TD_MAP_VERSION when updating; keep a changelog.
Backups: standard site backups cover posts + media.
Performance: default cap is 500 pins fetched; can be raised in Part 2.
Legal/consent: form copy says you have rights to display the photo.

12) Long-Form “Explain It” Scripts

A) 60-Second Stakeholder Update
B) 2–3 Minute “What/Why/How” (for a manager or new teammate)
C) 5–7 Minute Deep Dive (for handoff / potential buyer)

A) 60-Second Stakeholder Update

“Duck Map is a WordPress plugin I built to turn our duck drops into measurable engagement. Each duck has a QR that opens our map page with a prefilled Duck ID. People can upload a photo and location; submissions are pending until we approve. Approved pins appear on a clustered map so visitors see real activity—photos, cities, and spread. On the backend we’ve got rate limiting, file safety checks, and email notifications. The setup is simple: one shortcode for the map, a modal with a built-in form, and a QR format like …/duckmap?duck=S431#add-sighting. Operations just review and approve; the rest is automatic.”

B) 2–3 Minute “What/Why/How” (for a manager or new teammate)

“Think of Duck Map as our UGC engine for the duck campaign. What it does: It collects sightings—photo, city, state, optional email—through a simple form that pops over the map. Every new sighting lands in pending, and when we approve, it goes live and the pin is visible on the public map. Why it matters: It creates a visible, living artifact of our reach and gives us authentic content and social proof. It’s also a lightweight funnel: contributors can opt into an email if we want to send rewards or updates later. How it works: The plugin registers two content types: Ducks (optional catalog) and Duck Sightings (submissions). It exposes a tiny REST API, a Leaflet map with clustering, and a clean moderation interface with quick/bulk approve. Security-wise, there’s a nonce, per-IP rate limiting (5/day), and file type/size constraints. From an Ops view, there are only three steps: set map defaults and admin emails in Settings, place two shortcodes, and moderate. For QR production, we standardize Duck IDs to 1 letter + 3 digits (e.g., S431), and the QR targets …/duckmap?duck=S431#add-sighting. If I went offline, any manager could run this by following the operator guide.”

C) 5–7 Minute Deep Dive (for handoff / potential buyer)

“Duck Map is a productized feature inside WordPress that removes dependency on third-party forms or custom stacks. We have two CPTs: a Ducks catalog (optional) and a Duck Sightings queue (the backbone). The public flow is scan → modal form → pending → approve → live pin. The form is native—no FluentForms needed—and performs client and server validation, including enforcing our Duck ID scheme (A-Z plus three digits). We built in a public REST endpoint with a nonce header so it’s safe for anonymous submissions. The map renders with Leaflet + clustering and fetches pins from the approved pool; performance is solid and adjustable. Ops can bulk approve and see admin notices; admins are emailed when new items arrive, and contributors receive an approval email if they left an address. SMTP is handled by FluentSMTP for deliverability. The setup is idiot-proof: [td_duckmap] on the page, an EB modal with [td_duck_sighting_form], and a QR format that pre-fills and auto-opens. From a technical risk perspective, we’ve minimized moving parts: transient-based rate limiting, simple MIME checks, no exotic dependencies. If the site moves hosts, it comes over with the database and uploads like any normal WP site. If someone wanted to extend it, there’s a clean REST layer, shortcodes, a settings page, and versioned code. The result is a repeatable UGC pipeline that feeds marketing, social proof, and regional expansion, without a heavy ops burden.”

13) Glossary

Duck — internal record for a physical duck (optional).
Duck Sighting — user-submitted location/photo unit.
Pending / Publish — moderation states; only publish is visible on the map.
Leaflet — JS library rendering the map and clusters.

14) Appendix

Shortcodes

Map: [td_duckmap]
Form: [td_duck_sighting_form] with optional redirect="/duckmap" or duck="S431" (usually omit duck; URL provides it)

Constraints

Size: 5MB max (Part 4)
Types: jpg, png, webp
Rate limit: 5 submissions / IP / 24h

Safe URLs

QR: https://YOURDOMAIN.com/duckmap?duck=S431#add-sighting
API test: /wp-json/td/v1/pins

Duck Map – TerrainDucks

Operator Guide (v1.0.0)

1) Quick Start (10 minutes)

2) Minimum Required Plugins (and Recommended)

Required

Strongly Recommended

Optional / Nice to have

3) What the Plugin Does

4) Content Model (CPTs)

5) Frontend Setup Patterns

A) Map + Modal (recommended)

B) Dedicated page (alternative)

6) Submission Rules (user inputs)

7) Admin Workflow

8) Settings (Options → TerrainDucks Map)

9) API & Extensibility

10) Troubleshooting (60-second checklist)

11) Operations & Maintenance

12) Long-Form “Explain It” Scripts

A) 60-Second Stakeholder Update

B) 2–3 Minute “What/Why/How” (for a manager or new teammate)

C) 5–7 Minute Deep Dive (for handoff / potential buyer)

A) 60-Second Stakeholder Update

B) 2–3 Minute “What/Why/How” (for a manager or new teammate)

C) 5–7 Minute Deep Dive (for handoff / potential buyer)

13) Glossary

14) Appendix