commit 38cdebd0c6c18c6c5e594545244523cd9811c4fb Author: bdm Date: Mon Sep 28 06:24:25 2026 -0700 Track Bookshelf WordPress theme, plugins and specs Initial import of the bdmurphy Bookshelf work: the bd-bookshelf theme, bd-bookshelf-plugin, bd-bookshelfhelper and bd-simpleemail plugins, plus the specification documents, mockups and release archives. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..50885e9 --- /dev/null +++ b/.gitignore @@ -0,0 +1,22 @@ +# OS / editor cruft +.DS_Store +Thumbs.db +*.swp +*~ +.idea/ + +# Local environment / secrets +.env +.env.* +*.pem +*.key +!book_retailer_icons/*.png + +# Build / dependency artifacts +node_modules/ +vendor/ +*.min.js +*.min.css + +# Logs +*.log diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100755 index 0000000..ac1b736 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "local.model.provider.serverUrl": "http://192.168.123.14:1234" +} \ No newline at end of file diff --git a/Amazon_View_style_module.md b/Amazon_View_style_module.md new file mode 100755 index 0000000..b75e7d5 --- /dev/null +++ b/Amazon_View_style_module.md @@ -0,0 +1,44 @@ + +Book layout section: + +Similar to an Amazon book detail page. +The language selection will be followed for the page. If there is no translation for a language to show then English will be shown. +On the left is the book cover image, sized appropriatly for the display size. +To the right of the cover image, at the top is the book title, large as a title. +The line below the title will have "by" followed by the author name, or pen name. +The next line will show the Amazon rating, with space and the goodreads rating for the book. +There will be a seperator line below the ratings +Then the back cover blurb will be displayed. +Below the cover image on the left will be buttons linking to retailers to purchase the book. +The top buttons will be the formats available (ebook, paperback, hardback, audio). Below the format selection will be links to the sites with that format. The sites which don't offer that format will be grayed out. +To the right of the button, under the blurb will be additional book information, Genre, length in pages, language selected (with a '+' if other languages are availasble.) and the publisher name. +Below this line there will be the book ASIC listing categories. + + + +SYSTEM INSTRUCTION: Generate book listing components for WordPress using the +"Amazon Detail" layout structure. +LAYOUT RULES: + +1. CONTAINER: Each book must be wrapped in a container that supports a two- +column layout. + +2. LEFT COLUMN (Width 25%): +- TOP: Display the book cover image (Responsive sizing). +- BOTTOM: Display Purchase Section. +- Row 1: Format selectors (Ebook, Paperback, Hardback, Audio). +- Row 2: List of retailers. Apply CSS class "grayed-out" to retailers +that do not support the selected format. +3. RIGHT COLUMN (Width 75%): +- TITLE: Display in Large Bold H1/H2 style. +- BYLINE: "by [Author/Pen Name]" in secondary accent color. +- RATINGS: Show "Amazon: [Stars] | Goodreads: [Score]" on one line. +- SEPARATOR: Horizontal rule line. +- BLURB: Full back cover description text. +- METADATA BLOCK: Below blurb, display "Genre | [Length] Pages | +[Language] (+) | [Publisher]". +- CATEGORIES: Display ASIC listing categories in small muted text at the +very bottom. +4. LANGUAGE LOGIC: Default to selected language. If translation is missing, +fall back to English. + diff --git a/BD-Murphy-Website-Specification-v2.0.md b/BD-Murphy-Website-Specification-v2.0.md new file mode 100644 index 0000000..d2b8d0a --- /dev/null +++ b/BD-Murphy-Website-Specification-v2.0.md @@ -0,0 +1,912 @@ +# BDMurphy BookShelf Template - Technical Specification v2.0 + +**WordPress Theme:** BDMurphy BookShelf +**Plugin 1:** BD-BookShelfHelper +**Plugin 2:** BD-SimpleEmail + +**Version:** 2.0 | April 2026 +**Updated:** Incorporates WordPress Coding Standards, Security Best Practices, Accessibility Requirements, and Testing Standards + +--- + +## Table of Contents + +1. [Project Overview](#1-project-overview) +2. [Theme - Global Layout](#2-theme---global-layout) +3. [Theme - Pages](#3-theme---pages) +4. [Design System](#4-design-system) +5. [Plugin: BD-BookShelfHelper](#5-plugin-bd-bookshelfhelper) +6. [Plugin: BD-SimpleEmail](#6-plugin-bd-simpleemail) +7. [Database Schema](#7-database-schema) +8. [Design Decisions](#8-design-decisions) +9. [Implementation Standards](#9-implementation-standards) +10. [Quality Requirements](#10-quality-requirements) +11. [Deployment Checklist](#11-deployment-checklist) + +--- + +## 1. Project Overview + +### 1.1 Purpose + +This specification defines a custom WordPress theme and two companion plugins for author B.D. Murphy's website. The system allows the author to showcase books, publish blogs, manage reviews, and send newsletters with minimal technical knowledge required after initial setup. + +**Theme Name:** BDMurphy Bookshelf +**Plugin 1:** BD-BookShelfHelper +**Plugin 2:** BD-SimpleEmail + +### 1.2 Deliverables + +- **WordPress Theme:** BDMurphy Bookshelf — custom theme, fully Customizer-driven +- **Plugin: BD BookShelfHelper:** Book data, series, pen names, short links, review links, SEO, and platform integrations. Book data stored and managed in one place accessable everywhere. +- **Plugin: BD SimpleEmail:** Subscriber management and AI-assisted newsletter delivery + +### 1.3 Design Identity + +| Element | Specification | +|---------|--------------| +| Logo | Quill-pen hybrid icon with "B.D. Murphy" in serif text file: "Icon_Quill_BDMurphy_Black_WhtBG.jpg" | +| Banner | 1200x200px illustrated timeline file: "Reading_History_banner_1200x200.jpg" | +| Primary Color | Navy blue (#1B3A6B) | +| Accent Color | Warm gold (#C8A96E) | +| Background | Parchment (#F5F0E8) | +| Heading Font | Playfair Display / Georgia fallback | +| Body Font | Lato / Calibri fallback | + +### 1.4 General Behavior + +All books and blog content displays in reverse chronological order by first-published date unless a manual sort position is assigned. Series content sorts by volume number within the series. UI chrome follows the site language setting; content stays in the language it was authored in. + +### 1.5 WordPress Coding Standards Compliance + +All code MUST comply with [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/): + +- **PHP:** PSR-12 compatible with WordPress conventions +- **JavaScript:** ES5+ with JSHint validation +- **CSS:** WordPress CSS coding standards +- **HTML:** Semantic HTML5, no inline styles except where unavoidable +- **Text Domain:** `bd-murphy` for theme, `bd-bookshelfhelper` and `bd-simpleemail` for plugins + +--- + +## 2. Theme - Global Layout + +### 2.1 Header + +- Banner image (1200x200px) via `add_theme_support('custom-header')` +- Default asset: `Reading_History_banner_1200x200.jpg` +- Site logo via `add_theme_support('custom-logo')` +- Default logo asset: 'Icon_Quill_BDMurphy_Black_WhtBG.jpg' +- Admin bar offset handled via `body.admin-bar` rules + +### 2.2 Navigation Menu + +- Registered via `register_nav_menus(['primary' => 'Primary Menu'])` +- Default items: Home, Blog, Books, Series (conditional), Reviews, About, Contact +- Sticky behavior with gold top border on scroll +- Series menu item conditionally rendered by BD BookHelper + +### 2.3 Footer + +- Three-zone layout: social icons, donate buttons, utility links +- Two widget areas: "Footer Left" and "Footer Right" +- Sign-up prompt with link to /signup/ page + +### 2.4 WordPress Customizer Settings + +| Setting | Function | Location | +|---------|----------|----------| +| Site title | `get_bloginfo('name')` | Settings > General | +| Logo | `the_custom_logo()` | Customizer > Site Identity | +| Banner | `get_header_image()` | Customizer > Header Image | +| Background | Custom background | Customizer > Background | +| Primary color | `get_theme_mod('primary_color', '#1B3A6B')` | Customizer > Colors | +| Accent color | `get_theme_mod('accent_color', '#C8A96E')` | Customizer > Colors | +| Fonts | `get_theme_mod('heading_font', ...)`, etc. | Customizer > Typography | + +### 2.5 Theme Options Admin Screen + +Settings saved via WordPress Settings API in `bdm_theme_options`: + +- Social media URLs (X/Twitter, Facebook, LinkedIn, Instagram) +- Donation URLs (Buy Me a Coffee, PayPal) +- Author photo (media attachment ID) +- Sticky navigation toggle +- Posts per page +- Show read time toggle +- Business information (for CAN-SPAM compliance) + +--- + +## 3. Theme - Pages + +### 3.1 Home Page (front-page.php) +Top will be the banner using 100% of screen. +Line two will be the menu line. Each menu item as shown the menu setup. +Two-column layout: 66% content, 34% sidebar. Content via WordPress block editor. Sidebar contains book shelf widget with the default as custom HTML with the goodreads book list for bdmurphy. +The main page will have a short url from the plugin BookShelf Helper [all-books] + +### 3.2 Blog Page (/blog/) + +Template: `archive.php` or `home.php`. Lists posts with title, date, category, excerpt, featured image. Paginated (10 per page). Social sharing on individual posts. + +### 3.3 All Books Page (/books/) + +Template: `archive-book.php`. Stacked list with cover, title, author, ratings, format toggle, retailer buttons. Each book links to its detail page via short URL. + +### 3.3.1 Shortcode Display + +Books displayed via `[bd-book]` or `[bd-books]` shortcodes: +- Cover image (clickable, links to detail page) +- Title (clickable, links to detail page) +- Author/Pen name +- Blurb excerpt (HTML content, truncated) +- Retailer purchase buttons +- "View details" link to book detail page + +### 3.4 Individual Book Page (single-book.php) + +Full-width template with: +- Language selector tabs (EN, FR, DE, ES, RU, ZH-S, IT, PT, JA) +- Cover image (220x310px) +- Title, pen name, series info +- Ratings, format toggle, retailer links +- Read preview, pull quotes, reviews +- Share button (copies short URL) +- Social sharing buttons + +**Short Link Access:** Books are accessible via short URLs using the slug defined in book metadata. URL pattern: `/{short-slug}` (e.g., `/ph/` for "Pandemic Hacker") + +**Blurb HTML:** Descriptions are stored as HTML, allowing rich formatting (paragraphs, bold, italic, links) in book listings and detail pages. + +### 3.4.1 My Books Submenu + +The "My Books" menu item displays a dropdown submenu with links to each book's detail page: + +``` +My Books (top-level) +├── Book Title 1 +├── Book Title 2 +└── ... +``` + +- Each book appears as a submenu item +- Links point to the book's detail page using short URL +- Books sorted alphabetically by title +- Only published books shown + +### 3.5 Reviews Page (/reviews/) + +Template: `page-reviews.php`. Two-column grid with book cards and review summaries. + +### 3.6 About Page (/about/) + +Template: `page-about.php`. Two-column with author bio, awards, donate buttons, sign-up prompt. + +### 3.7 Series Pages + +- Listing: `archive-series.php` at /series/ +- Individual: `taxonomy-series.php` or `single-series.php` at /series/{slug}/ +- Series nav item hidden when no series exist + +### 3.8 Sign-up Page (/signup/) + +Template: `page-signup.php`. Email, first name, opt-in checkbox. Shortcode `[bdm_signup]` available. + +### 3.9 Social Sharing Buttons + +Platforms: Facebook, X/Twitter, LinkedIn, WhatsApp, Copy Link. Uses Web Share API where available. Book pages share the short URL. + +### 3.10 Utility Pages + +- Privacy Policy: standard WordPress page +- Unsubscribe: single email input + one-click HMAC tokens +- Contact: AJAX form with honeypot spam protection + +--- + +## 4. Design System + +### 4.1 Color Palette (CSS Custom Properties) + +```css +:root { + --bdm-navy: #1B3A6B; + --bdm-slate: #2E6DA4; + --bdm-sky: #4A90D9; + --bdm-gold: #C8A96E; + --bdm-cream: #F5F0E8; + --bdm-parchment: #EDE4D0; + --bdm-body-text: #2C2C2C; + --bdm-mid-grey: #555555; + --bdm-light-grey: #888888; + --bdm-active-green: #2D6A4F; +} +``` + +### 4.2 Typography + +- Headings: Playfair Display, Georgia, serif +- Body: Lato, Calibri, sans-serif +- Google Fonts loaded via `wp_enqueue_style()` with `display=swap` + +### 4.3 Image Sizes + +| Size | Dimensions | Use | +|------|-----------|-----| +| shelf-thumb | 44x62px (crop) | Book shelf widget | +| blog-thumb | 100x68px (crop) | Blog post thumbnails | +| rev-thumb | 52x74px (crop) | Review page covers | +| book-cover | 130x185px (crop) | All books page | +| book-page-cover | 220x310px (crop) | Individual book page | +| series-card | 400x280px (crop) | Series listing | +| series-header | 1200x300px (crop) | Series header | + +### 4.4 Responsive Breakpoints + +| Breakpoint | Layout | +|------------|--------| +| >=1200px | Full two-column, desktop nav | +| 768-1199px | Single column, hamburger menu | +| <768px | Single column, touch-friendly targets (44x44px min) | + +--- + +## 5. Plugin: BD-BookShelfHelper + +### 5.1 Overview + +Manages all book-related data, series information, and pen name configuration. Registers "book" custom post type and "series" taxonomy. + +### 5.2 Book Data Entry + +**5.2.1 Data Entry Interface** + +The plugin provides a dedicated book data entry page with the following UI requirements: + +- **Input Fields:** Each data field has a dedicated input control (text, textarea, select, date picker as appropriate) +- **Labels:** Every field has a visible label using `