diff --git a/PBS/Tech/Projects/pbs-membership-loe1-phase2-save-button.md b/PBS/Tech/Projects/pbs-membership-loe1-phase2-save-button.md new file mode 100644 index 0000000..a6e63f4 --- /dev/null +++ b/PBS/Tech/Projects/pbs-membership-loe1-phase2-save-button.md @@ -0,0 +1,223 @@ + +--- +project: pbs-membership-loe1-phase2-save-button +type: project-plan +status: planned +tags: + - pbs + - wordpress + - wprm + - wpcode + - javascript + - membership + - frontend +created: 2026-04-06 +updated: 2026-04-06 +path: PBS/Tech/Projects/ +--- +# PBS Membership Platform — LOE 1 Phase 2: Save Button on WordPress + +## Context + +This is Phase 2 of LOE 1 (Recipe Saving) in the PBS Membership Platform. +Phase 1 built the backend API and database. Phase 2 builds the user-facing +save button that lives on WordPress recipe pages and calls the Phase 1 API. + +**Related docs:** +- `pbs-membership-loe1-recipe-saving` — Phase 1 backend foundation +--- +## Goal + +Add a save button to WordPress recipe pages that lets Sunnies bookmark +their favorite recipes with a single click. Logged-out visitors see the +button as a signup funnel. + +### Estimated Time: 4-6 hours +--- +## Scope + +### In scope +- JavaScript widget injected via WPCode Lite +- Save button in two locations on recipe pages +- Logged-in and logged-out behaviors +- Visual feedback via Sunnie icon transformation +- Responsive bottom sheet / modal for signup prompt +- Integration with Phase 1 API endpoints + +### Out of scope +- Saved recipes listing page (Phase 3) +- Collections (Phase 4) +- Pinterest button decisions (deferred pending Jenny's input on traffic) +- Star ratings or other WPRM features +--- +## User Experience + +### Logged-in Sunnie +1. Lands on a recipe page +2. Sees heart icon in brand color (two locations) +3. On page load, JS calls `/api/interactions/check` — if already saved, +heart shows as filled Sunnie +4. Clicks heart → calls `POST /api/interactions` → heart animates from +outline to Sunnie +5. Clicks Sunnie → calls `DELETE /api/interactions` → Sunnie animates back +to outline heart + +### Logged-out visitor +1. Lands on a recipe page +2. Sees heart icon (same as logged in) +3. Clicks heart → bottom sheet / modal slides up +4. Modal message: "Join the Sunnies to save your favorite recipes! Build +your personal PBS cookbook — free to join." +5. Options: "Sign Up" (goes to Ultimate Member registration) or "Maybe +Later" (dismisses, returns to recipe) + +**Key principle:** Never hide the save button. It's a passive conversion +funnel on every recipe page. +--- +## Technical Approach + +### Where the code lives + +WPCode Lite snippet — single JavaScript + CSS file injected site-wide on +recipe pages. No plugin dependency, no theme modification. + +### Detecting recipe pages + +The snippet runs on all pages but only activates when it detects WPRM +elements on the page. If no WPRM buttons exist, the script exits quietly. + +### Button injection + +JavaScript targets WPRM's CSS classes to insert the save button into the +existing button groups. TBD which specific selectors during implementation +— depends on current WPRM markup. + +**Locations:** +- **Top of post** — next to Jump to Recipe / Print Recipe +- **Inside recipe card** — next to Print / Pin buttons + +### Login detection + +Client-side check for WordPress logged-in cookie (name includes +`wordpress_logged_in_`). The JS doesn't validate the cookie — that's the +API's job. It only needs to decide: show save action or show signup prompt. + +### API integration + +All API calls go to pbs-hub endpoints from Phase 1: + +- On load: `GET /api/interactions/check?post_id={id}&action=save` +- On save click: `POST /api/interactions` with `{post_id, action: "save"}` +- On unsave click: `DELETE /api/interactions` with `{post_id, action: +"save"}` + +The post ID comes from WordPress page context (`wp_postmeta` or a JS +variable exposed by WordPress). + +### Visual design + +**Button states:** +- Not saved → outlined heart in PBS brand color +- Saved → filled Sunnie icon (PBS already has this asset) +- Hover → subtle scale or bounce +- Transition → 200-300ms animation from heart to Sunnie + +**Animation ideas to experiment with:** +- Heart shrinks → Sunnie blooms in its place +- Petal confetti burst +- Gentle rotation + scale + +Keep animations fast and subtle. Final choice made during implementation +testing. + +### Signup modal / bottom sheet + +Responsive behavior: +- **Desktop** → centered modal dialog +- **Mobile** → bottom sheet sliding up from bottom + +Same HTML/CSS, different positioning based on viewport. Pure CSS media +queries, no framework. + +**Modal content:** +- Sunnie icon +- Headline: "Save your favorites!" +- Body: "Join the Sunnies to build your personal PBS cookbook. Free to +join." +- Primary button: "Sign Up" → Ultimate Member registration URL +- Secondary: "Maybe Later" → dismiss +- Close X in corner +- Tap outside to dismiss + +### Error handling + +- API call fails → brief toast notification: "Couldn't save right now. Try +again?" +- Network offline → same toast +- Auth expired → treat as logged out, show signup modal +- All errors logged to browser console for debugging +--- +## Phase 2 Checklist + +- [ ] Review current WPRM markup on a live recipe page (identify CSS +selectors) +- [ ] Export Sunnie icon as inline SVG for button use +- [ ] Write JavaScript for login detection +- [ ] Write JavaScript for button injection (both locations) +- [ ] Write JavaScript for API integration (check, save, unsave) +- [ ] Build heart-to-Sunnie animation (CSS/SVG) +- [ ] Build signup modal (HTML + CSS) +- [ ] Implement responsive bottom sheet behavior +- [ ] Write error handling and toast notifications +- [ ] Create WPCode Lite snippet with all code +- [ ] Test: logged-in save flow +- [ ] Test: logged-in unsave flow +- [ ] Test: logged-out modal flow +- [ ] Test: API error states +- [ ] Test: mobile responsiveness (Chrome DevTools + real phone) +- [ ] Test: does not break WPRM print or Pinterest buttons +- [ ] Get Jenny's eyes on the final look +--- +## Key Decisions Made + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Plugin vs custom | Custom JavaScript via WPCode Lite | Existing favorites +plugins store data in their own tables, not pbs-hub. Would create two +sources of truth and block the future AI layer. | +| Button locations | Both top of post AND inside recipe card | Catches +users wherever their eye lands. Reinforces the save action. | +| Logged-out visibility | Always show | Button becomes a passive conversion +funnel on every recipe page. Hiding it means logged-out users never +discover the feature. | +| Logged-out behavior | Modal / bottom sheet with signup prompt | Less +disruptive than direct redirect. Lets user make the choice without losing +their place on the recipe. | +| Mobile pattern | Responsive bottom sheet | Feels native on mobile where +most traffic comes from. Same code as desktop modal. | +| Visual feedback | Heart → Sunnie icon transformation | Brand moment on +every save. Reinforces Sunnies identity. Differentiates from generic recipe +sites. | +| Animation length | 200-300ms max | Fast enough to feel snappy on repeat +use. | +| Pinterest button | Deferred | Awaiting Jenny's input on whether Pinterest +drives meaningful traffic. | +--- +## Open Questions + +- **WPRM CSS selectors:** Need to inspect current recipe page markup to +identify exact classes/IDs for button containers +- **Sunnie icon asset:** Confirm Jenny has an SVG-ready version, or need to +convert existing asset +- **Post ID exposure:** How does WordPress currently expose the post ID to +JavaScript on the page? (Likely via `wp_localize_script` or a data +attribute) +- **Brand color hex:** Exact brand color for the heart outline state +- **Pinterest decision:** Revisit with Jenny after checking Pinterest +analytics +--- +*Next Step: Inspect a recipe page's HTML to identify WPRM CSS selectors and +confirm button injection points* + + +...sent from Jenny & Travis \ No newline at end of file