38cdebd0c6
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.
468 lines
35 KiB
Plaintext
Executable File
468 lines
35 KiB
Plaintext
Executable File
BDMurphy BookShelf
|
||
WordPress System
|
||
Technical Specification
|
||
Version 2.0 ? May 2026
|
||
Theme: BDMurphy-Bookshelf · Plugin: BDMurphy-BookShelf · Plugin: BD-BookShelfHelper
|
||
|
||
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 blog posts, manage reviews, and send newsletters with minimal technical knowledge required after initial setup. The theme is built from scratch with no parent framework and follows WordPress coding standards throughout.
|
||
The core design principle is enter once, display everywhere: the author enters book details once in the BD-BookShelfHelper plugin and the system generates all book pages, series pages, and review displays automatically. No individual page creation or editing is required for book content.
|
||
|
||
1.2 Deliverables
|
||
Theme: BDMurphy-Bookshelf Custom WordPress theme. Fully Customizer-driven. Follows WordPress standards and best practices. Provides the visual presentation layer for all pages. Ships with default logo, banner, and sample content.
|
||
Plugin: BDMurphy-BookShelf Manages the home page book shelf sidebar widget, subscriber sign-up, subscriber management, and email newsletter creation and delivery. Includes AI-assisted newsletter composition via the Gemini API.
|
||
Plugin: BD-BookShelfHelper The book data management plugin. Stores all book information (blurbs, genres, reviews, cover images), series, and pen names. Generates book pages, review pages, and series pages from entered data. Manages short links, review links, Goodreads integration, Amazon ratings, and SEO. Full specification: BD-BookShelfHelper-Plugin-Specification-v1_0.docx.
|
||
|
||
Each deliverable package includes: a description, a setup and customization guide, and a display visual for the WordPress plugin or theme directory listing. Each deliverable is a ready-to-upload package installable via the WordPress admin. Deliverables are built one at a time and tested individually before integration testing.
|
||
|
||
1.3 Design Identity
|
||
• Logo: Quill-pen hybrid icon with "B.D. Murphy" in serif text — provided asset ships as default (BD_BookShelf_Logo.png).
|
||
• Banner: 1200×250px illustrated timeline (scrolls from quill to modern ebooks) — ships as default (Reading_through_time.png).
|
||
• Palette: Navy blue (#1B3A6B) primary, warm gold (#C8A96E) accents, parchment (#F5F0E8) background.
|
||
• Typography: Playfair Display / Georgia fallback for headings; Lato / Calibri fallback for body.
|
||
• Mood: Cozy, casual reading — literary but not stiff. Light mode only; no dark mode.
|
||
|
||
1.4 General Behavior
|
||
• All 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 (menus, labels, system text) follows the site language setting; content stays in the language it was authored in.
|
||
• All purchase links support affiliate code injection, applied server-side using per-retailer URL patterns.
|
||
• All short links share one conflict-check pool — no slug can clash with any other WordPress slug.
|
||
• The site represents one author who may publish under multiple pen names. The site header and bio always reflect the author identity; book pages show the pen name the book was published under.
|
||
|
||
2. Theme — Global Layout
|
||
|
||
2.1 Header
|
||
• The author's logo, sized to 250×250px, appears at the top left of every page. BD_BookShelf_Logo.png ships as the default.
|
||
• The banner image, 250px high, appears to the right of the logo and is centered on the page. Reading_through_time.png ships as the default.
|
||
• The logo and banner are the first elements on every page, above the navigation.
|
||
• Both are implemented as WordPress configurable items. The author replaces them via Appearance > Customize > Header Image.
|
||
• The default site title is the website URL. The default tagline (blogdescription) is "Expand your mind."
|
||
• Site title and tagline display as text fallback when no banner image is set.
|
||
• Nothing appears above the banner except the browser chrome and the WordPress admin bar (32px when logged in). Admin bar offset handled via body.admin-bar rules.
|
||
Note: Banner height is locked at 250px maximum in the custom-header declaration.
|
||
|
||
2.2 Navigation Menu
|
||
Registered via register_nav_menus(['primary' => 'Primary Menu']). Assigned in Appearance > Menus.
|
||
Sits directly below the banner with zero gap. Spans 100% viewport width. Background: navy (#1B3A6B). Active item: white text with gold 2px underline.
|
||
|
||
Default Menu Items
|
||
Home · Blog · Books · Reviews · Series · About · Register
|
||
Each item has a pre-built default page installed at theme activation with simple example content.
|
||
|
||
Home General news and blog posts. Two-column layout (see Section 3.1).
|
||
Blog WordPress posts listed in date order, most recent first. Posts tagged as blog posts (not reviews).
|
||
Books All books page. Ships with "Pandemic Hacker" as sample content.
|
||
Reviews Without BD-BookShelfHelper: WordPress posts tagged "reviews". With BD-BookShelfHelper: generated review display page showing review information in multiple languages with pull-quote callouts.
|
||
Series Without BD-BookShelfHelper: standard WordPress page with two sample book entries. With BD-BookShelfHelper: generated series listing from plugin data. The Series nav item is hidden when no series records exist.
|
||
About Standard WordPress page with author biography and details (see Section 3.6).
|
||
Register Sign-up page for newsletter and announcement subscriptions (see Section 3.8). Managed by the BDMurphy-BookShelf plugin.
|
||
|
||
When BD-BookShelfHelper is installed, a language selector dropdown appears right-justified at the far right of the navigation bar. The default language is configured in settings (default: EN).
|
||
When BDMurphy-BookShelf plugin is installed, the Register page provides selection for opt-in / opt-out of categories: Newsletter, New Book Announcements, and Events. Registered users can return to this page to update their preferences.
|
||
|
||
Sticky Behavior
|
||
• Default: sticky — CSS position: sticky; top: 0; z-index: 100. Pins to viewport top as user scrolls past the banner.
|
||
• When sticky and the banner has scrolled out of view, a 2px gold top border appears on the nav bar.
|
||
• body.admin-bar .site-nav { top: 32px } applied when the WordPress admin bar is visible.
|
||
• All in-page anchor targets use scroll-margin-top: 48px to avoid content being hidden behind the sticky nav.
|
||
• A Theme Options toggle (sticky_nav, default: true) allows disabling sticky behavior.
|
||
Note: Sticky nav requires the nav parent element to have defined height, not overflow: hidden.
|
||
|
||
2.3 Footer
|
||
• Three-zone layout: social icons (left), donate buttons (centre), utility links (right).
|
||
• Social links: X/Twitter, Facebook, LinkedIn, Instagram, BlueSky. URLs configured in Appearance > Theme Options > Social Media.
|
||
• "Buy Me a Coffee" and PayPal donate URLs configured in Appearance > Theme Options > Donate Links.
|
||
• Utility links: Contact | About | Privacy Policy | Unsubscribe — registered as footer menu via register_nav_menus(['footer']).
|
||
• Footer also includes a brief sign-up prompt with a link to the /signup/ page.
|
||
• Two registered widget areas: "Footer Left" and "Footer Right" — available in Appearance > Widgets.
|
||
|
||
2.4 WordPress Customizer Settings
|
||
All visual settings are exposed through the WordPress Customizer (Appearance > Customize) using standard WordPress APIs.
|
||
|
||
Setting WordPress mechanism / function Admin location
|
||
Site title get_bloginfo('name') / Settings > General Customizer > Site Identity
|
||
Tagline get_bloginfo('description') Customizer > Site Identity
|
||
Logo upload add_theme_support('custom-logo') / the_custom_logo() Customizer > Site Identity > Logo
|
||
Banner image add_theme_support('custom-header') / get_header_image() Customizer > Header Image
|
||
Page background add_theme_support('custom-background') / default #F5F0E8 Customizer > Background
|
||
Primary color get_theme_mod('primary_color', '#1B3A6B') Customizer > Colors > Primary
|
||
Accent color get_theme_mod('accent_color', '#C8A96E') Customizer > Colors > Accent
|
||
Heading font get_theme_mod('heading_font', 'Playfair Display') Customizer > Typography > Headings
|
||
Body font get_theme_mod('body_font', 'Lato') Customizer > Typography > Body
|
||
Primary navigation register_nav_menus(['primary']) Customizer > Menus
|
||
Footer navigation register_nav_menus(['footer']) Customizer > Menus
|
||
Footer widgets register_sidebar() x 2 Customizer > Widgets > Footer
|
||
|
||
Note: All get_theme_mod() calls include a default value so the theme displays correctly immediately after activation.
|
||
Note: Colors output as CSS custom properties (--bdm-navy, --bdm-gold, --bdm-cream, etc.) via the wp_head hook.
|
||
|
||
2.5 Theme Options Admin Screen
|
||
Settings that do not suit live Customizer preview are in Appearance > Theme Options, saved via the WordPress Settings API.
|
||
|
||
Social: X/Twitter URL URL for X/Twitter profile — displayed as icon in footer.
|
||
Social: Facebook URL URL for Facebook page.
|
||
Social: LinkedIn URL URL for LinkedIn profile.
|
||
Social: Instagram URL URL for Instagram profile.
|
||
Social: BlueSky URL URL for BlueSky profile.
|
||
Donate: Buy Me a Coffee URL Full URL to buymeacoffee.com page.
|
||
Donate: PayPal URL Full PayPal.me or donation URL.
|
||
Donate: Venmo URL Full Venmo donation URL.
|
||
Author photo WordPress media attachment ID — defaults to built-in smiley SVG when empty.
|
||
Sticky navigation Boolean toggle, default: ON.
|
||
Posts per page (blog) Integer, default: 10.
|
||
Language default selection Dropdown: EN, FR, DE, ES. Shown in the language selector when BD-BookShelfHelper is active.
|
||
Show read time on posts Boolean, default: ON. Displays estimated read time on blog posts.
|
||
Business name Legal name — appears in email footer for CAN-SPAM compliance.
|
||
Business address line 1 Street address — required for CAN-SPAM.
|
||
Business address line 2 Suite, unit, PO Box — optional.
|
||
City / State / Postal code Required for CAN-SPAM.
|
||
Country Required for CAN-SPAM.
|
||
Phone number Optional — appears in email footer if provided.
|
||
Note: Business information fields are required by CAN-SPAM law for commercial email. The BDMurphy-BookShelf plugin pulls these values into every outgoing email footer automatically.
|
||
|
||
3. Theme — Pages
|
||
|
||
3.1 Home Page
|
||
Template: front-page.php. Set as static front page via Settings > Reading.
|
||
Two-column layout: left 66%, right 34%.
|
||
|
||
Left Column — News & Blog
|
||
• Content managed via the WordPress block editor on a WordPress Page. No custom meta fields.
|
||
• Editorial, hand-curated. Author news, announcements, featured blog post headings.
|
||
|
||
Right Column — Book Shelf Widget
|
||
• Without the BDMurphy-BookShelf plugin installed: a placeholder widget displays "BDMurphy-BookShelf Plugin recommended."
|
||
• With BDMurphy-BookShelf plugin: custom WordPress widget registered by the plugin, placed in the "Home Sidebar" widget area.
|
||
• Each entry: cover thumbnail (44×62px), Amazon and Goodreads star ratings, retailer icon row.
|
||
• Clicking any cover navigates to that book's individual detail page. If BD-BookShelfHelper is not installed, the link goes to the /books/ page.
|
||
• BD-BookShelfHelper creates the detail page for each book when book data is entered. It displays details based on the reader's selected language.
|
||
• Sorted by publish date newest first unless manual order is set.
|
||
|
||
3.2 Blog Page (/blog/)
|
||
Template: archive.php or home.php. Set as posts page in Settings > Reading.
|
||
• Lists all published blog posts, newest first: title (linked), date, category tag, excerpt (~150 words), featured image thumbnail (100×68px).
|
||
• Paginated — 10 posts per page, configurable via Theme Options.
|
||
• Social sharing buttons at the bottom of each individual blog post (see Section 3.9).
|
||
|
||
3.3 All Books Page (/books/)
|
||
Template: archive-book.php. Stacked list, most recent first. If series exist, a "Browse by series" link appears at the top pointing to /series/.
|
||
• Each entry: cover image (130×185px, left), author pen name, title, ratings, format toggle, retailer buttons, blurb, and review excerpt.
|
||
• Format toggle (Ebook / Paperback / Hardback) filters retailer buttons. Ebook-only retailers (Apple Books, Google Play) disabled when Paperback or Hardback is selected.
|
||
• All retailer links include affiliate codes applied server-side.
|
||
• BD-BookShelfHelper provides an "Update Links" button to scan retailer websites and verify purchase link URLs.
|
||
• If a book belongs to a series, a "Part of [Series Name]" label links to /series/{slug}/.
|
||
|
||
3.4 Individual Book Page
|
||
Template: single-book.php. Canonical URL is the book's short slug (e.g. /ph/). Full-width template — no sidebar.
|
||
|
||
Page Content (Top to Bottom)
|
||
• Language selector tab bar (EN FR DE ES RU ZH-S) — switches title, blurb, and pull quotes to the selected language version.
|
||
• Cover image (220×310px), prominent, left-aligned.
|
||
• Book title and pen name (the name the book was published under).
|
||
• If the book belongs to a series: "Part of the [Series Name] series — Book [volume number]" displayed below the title. The series name links to /series/{slug}/. Styled similarly to Amazon's series display.
|
||
• Amazon and Goodreads star ratings.
|
||
• Format toggle (Ebook / Paperback / Hardback) — dark green active state.
|
||
• Retailer purchase buttons with affiliate codes.
|
||
• "Read preview" section and one-liner pull quotes.
|
||
• Review cards (comment text, source name, optional source link).
|
||
• Back-cover blurb.
|
||
• Share button — copies the book's short URL to clipboard with a toast confirmation. The short URL (e.g. authorbdmurphy.com/ph) is shared, not the full canonical URL.
|
||
• Social sharing buttons at bottom of page (see Section 3.9).
|
||
|
||
3.5 Reviews Page (/reviews/)
|
||
Template: page-reviews.php. Two-column card grid, sorted by book publication date newest first.
|
||
• Each card: book cover thumbnail (52×74px), title, review count, up to 3 review entries.
|
||
• Per review entry: source name (uppercase blue) + 3-line AI-generated synopsis (italic).
|
||
• Clicking a card or "View all reviews" opens the per-book review detail page.
|
||
• Review detail page: cached WordPress page with table of contents (anchor links) and full review text. Anchor targets use scroll-margin-top: 48px for sticky nav clearance.
|
||
• Generated or regenerated when a review is added in BD-BookShelfHelper or the author triggers regeneration.
|
||
|
||
3.6 About Page (/about/)
|
||
Template: page-about.php. Two-column layout.
|
||
|
||
Left Column
|
||
• Author real name and pen name(s) used — listing pen names is optional.
|
||
• Full biography text — entered via the WordPress block editor. One bio for the author (not per pen name).
|
||
• Awards list with gold dot markers.
|
||
• "Buy Me a Coffee" button and PayPal donate button — URLs from Theme Options.
|
||
• Sign-up prompt: a short "Stay updated" section with a link to the /signup/ page.
|
||
|
||
Right Column Sidebar
|
||
• Author photo: defaults to built-in smiley face SVG. Replaced via Appearance > Theme Options > Author Photo.
|
||
• Sign-up card: brief description + "Sign up for updates" button linking to /signup/.
|
||
Note: The About page bio is for the author as a person. Pen names listed here are informational only. Each book page shows the pen name the book was published under.
|
||
|
||
3.7 Series Pages
|
||
Series pages appear only when series are configured in BD-BookShelfHelper. The Series nav item is hidden when no series records exist.
|
||
|
||
Series Listing Page (/series/)
|
||
• Template: archive-series.php.
|
||
• Each series shown as a card: series cover graphic, series name (heading), series blurb/description, book count.
|
||
• Cards sorted by series creation date (most recent first) or manual order set in BD-BookShelfHelper.
|
||
• Clicking a series card navigates to /series/{slug}/.
|
||
|
||
Individual Series Page (/series/{slug}/)
|
||
• Template: taxonomy-series.php.
|
||
• Header: series cover graphic, series name, series blurb.
|
||
• Below: all books in the series displayed in volume number order (Book 1, Book 2, etc.).
|
||
• Each book entry: cover thumbnail, title, pen name, volume number label ("Book 1"), brief blurb excerpt, purchase link buttons.
|
||
• Works correctly when only one book exists in the series.
|
||
• Breadcrumb: Home > Series > [Series Name].
|
||
|
||
3.8 Registration — Sign-Up Page (/signup/)
|
||
Template: page-signup.php. Full-width, no sidebar. Managed by the BDMurphy-BookShelf plugin.
|
||
• Accessed from: About page sign-up prompt, About page sidebar card, footer sign-up link, and any "Subscribe" calls to action on the site.
|
||
• Fields: Email address (required), First name (optional), opt-in confirmation checkbox.
|
||
• Opt-in categories: Newsletter, New Book Announcements, Events.
|
||
• On submission: stores record in the BDMurphy-BookShelf plugin subscriber table with status = "subscribed". Displays a confirmation message.
|
||
• The page includes a brief description of what subscribers receive.
|
||
• Shortcode [bookshelf_signup] available for placing the form in other pages or widget areas.
|
||
• Registered users can return to this page to update their category preferences.
|
||
|
||
3.9 Social Sharing Buttons
|
||
Social sharing buttons appear at the bottom of individual blog posts and individual book pages only. Not shown on list pages (home, /books/, /blog/, /reviews/, /series/).
|
||
|
||
Platforms Facebook, X/Twitter, LinkedIn, WhatsApp, and a "Copy link" button. Additional platforms can be toggled on/off in Appearance > Theme Options > Social Sharing.
|
||
URL on book pages The book's short URL (e.g. authorbdmurphy.com/ph) — not the full canonical URL. Retrieved from the book's stored short slug.
|
||
URL on blog posts The standard WordPress post permalink.
|
||
Implementation Uses the Web Share API where available (modern mobile browsers). Falls back to platform-specific share URLs on desktop. No third-party sharing plugin dependency.
|
||
Share counts Not displayed — avoids third-party API calls and privacy concerns.
|
||
|
||
3.10 Utility Pages
|
||
Privacy policy (/privacy-policy/) Standard static WordPress Page. Template: page.php or page-no-sidebar.php.
|
||
Unsubscribe (/unsubscribe/) Single email input. Sets subscriber status to "unsubscribed" in the BDMurphy-BookShelf plugin. Accepts HMAC-signed one-click unsubscribe tokens from email links. Template: page-unsubscribe.php.
|
||
Contact (/contact/) Template: page-no-sidebar.php. Fields: Name, Email, Subject, Message. AJAX submission. Honeypot field for spam protection.
|
||
|
||
4. Design System
|
||
|
||
4.1 Color Palette
|
||
Navy blue #1B3A6B Primary brand — headers, nav bar, section banners. Customizer-controlled (primary_color).
|
||
Slate blue #2E6DA4 Heading text, links, active states. Fixed, derived from primary_color.
|
||
Sky blue #4A90D9 Hover states, accent highlights. Fixed.
|
||
Warm gold #C8A96E Decorative accents, active nav underline, dividers. Customizer-controlled (accent_color).
|
||
Cream #F5F0E8 Page background. Customizer-controlled via custom-background (default-color: F5F0E8).
|
||
Parchment #EDE4D0 Card and sidebar backgrounds, alternating table rows. Fixed.
|
||
Body text #2C2C2C Primary body copy. Fixed.
|
||
Mid grey #555555 Secondary text, metadata. Fixed.
|
||
Light grey #888888 Placeholder text, disabled states. Fixed.
|
||
Active green #2D6A4F Format toggle active state. Fixed.
|
||
Note: Colors output as CSS custom properties: --bdm-navy, --bdm-gold, --bdm-cream, etc. Light mode only — no dark mode.
|
||
|
||
4.2 Typography
|
||
Heading font Playfair Display, Georgia, serif. Customizer-controlled (heading_font).
|
||
Body font Lato, Calibri, sans-serif. Customizer-controlled (body_font).
|
||
Navigation Lato, Calibri — medium weight, small caps optional. Fixed.
|
||
Pull quotes / blurbs Playfair Display italic. Inherits heading_font.
|
||
Short links / code display Courier New, monospace. Fixed.
|
||
Note: Google Fonts loaded via wp_enqueue_style() with display=swap.
|
||
|
||
4.3 Image Sizes
|
||
shelf-thumb 44×62px Book shelf widget covers on home page right column.
|
||
blog-thumb 100×68px Blog post list featured image thumbnails.
|
||
rev-thumb 52×74px Review page book cover thumbnails.
|
||
book-cover 130×185px All books page cover images.
|
||
book-page-cover 220×310px Individual book page main cover.
|
||
series-card 400×280px Series listing page card graphics.
|
||
series-header 1200×300px Individual series page header graphic.
|
||
Note: All sizes registered via add_image_size() in functions.php. WordPress generates crops automatically on upload.
|
||
|
||
4.4 Responsive Breakpoints
|
||
? 1200px Full two-column layouts, full banner, desktop navigation bar.
|
||
768–1199px Columns stack to single column. Navigation collapses to hamburger menu.
|
||
< 768px Single column, touch-friendly tap targets (minimum 44×44px). Banner scales proportionally.
|
||
Note: Sticky nav functions at all breakpoints. On mobile, hamburger menu opens below the sticky nav bar.
|
||
|
||
5. Plugin: BDMurphy-BookShelf
|
||
|
||
The BD-BookShelfHelper plugin is documented in a separate specification: BD-BookShelfHelper-Plugin-Specification-v1_0.docx. This section covers the BDMurphy-BookShelf plugin.
|
||
|
||
5.1 Overview
|
||
The BDMurphy-BookShelf plugin handles subscriber sign-up and management, email newsletter creation, AI-assisted newsletter composition, and delivery via Gmail SMTP. It also registers the book shelf sidebar widget on the home page right column and the /signup/ registration page.
|
||
|
||
5.2 Plugin Identity
|
||
Plugin name BDMurphy-BookShelf
|
||
WordPress slug bdmurphy-bookshelf
|
||
Dashboard menu label BookShelf
|
||
Text domain bdmurphy-bookshelf
|
||
|
||
5.3 Responsibilities
|
||
• Home page book shelf sidebar widget — registered and rendered in the "Home Sidebar" widget area.
|
||
• Sign-up page (/signup/) — registration form, opt-in category selection, subscriber storage.
|
||
• Subscriber management — subscribed / unsubscribed status, category preferences, audit fields.
|
||
• Email newsletter composition — AI-assisted drafting via Gemini API, HTML editor, template selection.
|
||
• Email delivery — one at a time via Gmail SMTP using an app-specific password.
|
||
• Unsubscribe processing — HMAC-signed one-click tokens and manual /unsubscribe/ form.
|
||
• CAN-SPAM compliance — mandatory footer with business address pulled from Theme Options.
|
||
|
||
5.4 Gmail SMTP Configuration
|
||
Email address Full email address used for sending.
|
||
App-specific password Generated in Google Account > Security. Stored encrypted in wp_options.
|
||
Sender display name Display name, e.g. "B.D. Murphy".
|
||
Reply-to address Can differ from sender address.
|
||
AI API key Gemini API key for AI-assisted newsletter composition. Stored encrypted.
|
||
AI link Used for AI to check and help craft newsletters and emails.
|
||
Business information Pulled automatically from Appearance > Theme Options > Business Information for CAN-SPAM compliance.
|
||
Site URL (boilerplate) Auto-populated from get_bloginfo('url').
|
||
SMTP configuration Configuration screen includes help text and links to Gmail app password setup guide.
|
||
|
||
5.5 Email Newsletter Composition Workflow
|
||
• Author opens BookShelf > New Newsletter.
|
||
• Author enters a prompt summary: topic, books to mention, tone, and announcements.
|
||
• Plugin calls Gemini API with a system instruction to generate a complete newsletter HTML draft.
|
||
• Draft is returned in an HTML email editor. Headers and footers are auto-populated above and below the editor so the author sees the full reader view.
|
||
• Author reviews and edits the draft content.
|
||
• Author checks "Also publish as blog post" — creates a WordPress post with the same content. This checkbox is ON by default.
|
||
• Author clicks "Send Newsletter" — sends one email at a time via Gmail SMTP to all subscribed recipients.
|
||
Note: Sending is always manually triggered. There is no automatic or scheduled send.
|
||
|
||
5.6 Email Template Requirements
|
||
• Email template is selectable in BookShelf settings.
|
||
• Header: site name / author name and logo.
|
||
• Body: composed content with affiliate-coded purchase links.
|
||
• Mandatory footer (not editable per send): website URL, one-click unsubscribe link (HMAC-signed token), full business address from Theme Options (CAN-SPAM requirement).
|
||
|
||
5.7 Subscriber Management
|
||
id Auto-increment primary key.
|
||
email Unique subscriber email address.
|
||
first_name Optional first name.
|
||
status "subscribed" or "unsubscribed" — records are never deleted.
|
||
subscribed_categories Newsletter, Announcements (new books), Events — per-subscriber opt-in flags.
|
||
subscribed_at Timestamp of original opt-in.
|
||
unsubscribed_at Timestamp of unsubscribe (null if still subscribed).
|
||
ip_address IP address at sign-up for audit purposes.
|
||
One-click unsubscribe: HMAC-signed token in every email link. Clicking the link sets status = "unsubscribed" immediately, no form required. Satisfies Gmail and Yahoo delivery requirements. The /unsubscribe/ page also accepts manual email entry as a fallback.
|
||
|
||
5.8 Plugin Settings & Admin Dashboard
|
||
The plugin adds a top-level menu item to the WordPress dashboard called "BookShelf". Submenus provide access to all features.
|
||
|
||
BookShelf > Settings Gmail credentials (email address, app-specific password), sender display name, reply-to address, Gemini API key, email template selection. Business information is pulled from Theme Options and displayed read-only here.
|
||
BookShelf > New Newsletter AI-assisted email composition screen.
|
||
BookShelf > Sent Newsletters Log of previously sent newsletters with subject, sent date, and recipient count.
|
||
BookShelf > Subscribers Subscriber list with status, category preferences, and sign-up date.
|
||
BookShelf > About Plugin version, author credit, Buy Me a Coffee link, PayPal donate link.
|
||
|
||
6. Database Schema (Overview)
|
||
|
||
6.1 BD-BookShelfHelper Tables
|
||
Full detail in the BD-BookShelfHelper Plugin Specification, Section 11.
|
||
bd_books Core book record (id, slug, pen_name_id, series_id, volume_number, asin, isbn, publish_date, sort_order, created_at).
|
||
bd_book_meta Per-language content (book_id, language_code, title, blurb, preview_excerpt, pull_quotes).
|
||
bd_book_covers Cover images per language (book_id, language_code, attachment_id).
|
||
bd_series Series definitions (id, name, slug, cover_attachment_id, header_attachment_id, blurb, display_order, created_at).
|
||
bd_pen_names Pen name list (id, pen_name, notes, active, created_at).
|
||
bd_retailers Retailer definitions (id, name, url_pattern, affiliate_param, formats_supported).
|
||
bd_book_links Purchase links (book_id, retailer_id, format, raw_url, affiliate_url, last_verified).
|
||
bd_reviews Review records (id, book_id, comment_text, synopsis, source_name, source_url, display_order).
|
||
bd_ratings Scraped ratings cache (book_id, source [amazon|goodreads], rating, review_count, last_updated).
|
||
bd_review_shortlinks Review short links (id, book_id, site_code, slug, destination_url, status, created_at, activated_at).
|
||
|
||
6.2 BDMurphy-BookShelf Tables
|
||
bd_subscribers Subscriber list (id, email, first_name, status, subscribed_categories, subscribed_at, unsubscribed_at, ip_address).
|
||
bd_newsletters Sent newsletter log (id, subject, body_html, sent_at, recipient_count).
|
||
|
||
7. Design Decisions — Answered
|
||
|
||
All design decisions have been resolved. This section records each decision and its specification impact for developer reference.
|
||
|
||
Question Answer Spec Impact
|
||
Child theme support? No — customisation via Customizer and Theme Options only. All paths use get_template_directory_uri(). No child theme infrastructure needed.
|
||
Dark mode? No dark mode support. Light mode only confirmed. Parchment palette stands.
|
||
Sign-up form — popup or page? Dedicated page (/signup/) accessed from About menu and footer. Section 3.8. About page and footer include sign-up prompt. Shortcode [bookshelf_signup] also available.
|
||
Visitor-submitted reviews? No — admin-entered only. Reviews come from Amazon, Goodreads, etc. Admin-only entry. No moderation tooling needed.
|
||
Blog post trigger email newsletter? No — future separate AI-driven plugin (blog ? email / social, not a copy). Section 8.4 notes the planned extension and reserves a WordPress action hook.
|
||
Social sharing buttons? Yes — bottom of blog posts and book pages. Section 3.9. Facebook, X/Twitter, LinkedIn, WhatsApp, copy-link. Book pages share the short URL.
|
||
Series page? Yes — full series system with /series/ listing and /series/{slug}/ detail pages. Section 3.7. BD-BookShelfHelper series management. Series nav item conditional on series existing.
|
||
Affiliate IDs? User adds IDs as they sign up. Applied whenever available. Links display without affiliate code until an ID is configured for that retailer.
|
||
CAN-SPAM mailing address? User configures business information (name, address, phone) in Theme Options. Business info fields in Section 2.5. BDMurphy-BookShelf plugin pulls them into every email footer.
|
||
One-click unsubscribe? Yes — HMAC-signed token in email link. Section 5.7. Token-based unsubscribe confirmed as standard.
|
||
Goodreads Author ID? ID: 30469651 (goodreads.com/author/show/30469651.B_D_Murphy) Pre-populated in BD-BookShelfHelper sample data.
|
||
Multiple authors / pen names? One author, one bio. Up to 10 pen names. Each book shows the pen name it was published under. BD-BookShelfHelper pen name management (Plugin Spec Section 4). About page bio is for the author, not per pen name.
|
||
Series sort order? Volume number field controls both display order and the "Book [N]" label. Volume number in bd_books. Sorts books within a series on all series pages.
|
||
Email plugin name? The BD-SimpleEmail plugin is merged into BDMurphy-BookShelf. Email features are part of that plugin. All references to "SimpleEmail" or "BD-SimpleEmail" in this document now refer to the BDMurphy-BookShelf plugin.
|
||
|
||
8. Implementation Notes
|
||
|
||
8.1 WordPress Architecture
|
||
• "book" custom post type registered by BD-BookShelfHelper. The theme queries it but does not register it.
|
||
• "series" registered as a custom taxonomy by BD-BookShelfHelper, attached to the book CPT.
|
||
• Book page short links and review short links registered as WordPress rewrite rules via add_rewrite_rule(). Slugs stored as post meta and in bd_review_shortlinks.
|
||
• Internationalisation: theme uses __() and _e() with text domain "bd-murphy". load_theme_textdomain() in functions.php. .pot generated via WP-CLI i18n make-pot.
|
||
• Scheduled tasks via WP-Cron: Goodreads widget refresh (daily), Amazon rating scrape (every 6 hours), review link activation scan (daily).
|
||
• All CSS and JS enqueued via wp_enqueue_style() and wp_enqueue_script() with correct handles, dependencies, and version strings.
|
||
|
||
8.2 Security
|
||
• Gmail app password and Gemini API key stored encrypted (openssl_encrypt), never plain text.
|
||
• Unsubscribe tokens: HMAC-signed (hash_hmac) — never bare email addresses in URLs.
|
||
• All output escaped with esc_html(), esc_url(), esc_attr(). All input sanitized on save.
|
||
• Affiliate codes applied server-side only.
|
||
• Contact form honeypot field for spam protection.
|
||
|
||
8.3 Sample Data
|
||
• "Pandemic Hacker" by B.D. Murphy — placeholder cover, sample reviews, ratings, blurb.
|
||
• Pre-reserved review short link slugs: phrA, phrG, phrB, phrK, phrP, phrL.
|
||
• All five retailer purchase link placeholders pre-configured for Pandemic Hacker.
|
||
• Three sample blog posts.
|
||
• Goodreads Author ID 30469651 pre-populated in BD-BookShelfHelper settings.
|
||
• Pen name "B.D. Murphy" pre-configured as the default active pen name.
|
||
Note: A "Clear sample data" button in Appearance > Setup Wizard removes all sample content.
|
||
|
||
8.4 Planned Extension — Blog to Social / Email Plugin
|
||
A future AI-driven plugin will take a published blog post and generate distinct email newsletter content and social media posts — not a copy of the blog, but an AI-transformed version appropriate for each channel.
|
||
• Scope: out of scope for the current build. No implementation required now.
|
||
• Hook point reserved: the theme and BD-BookShelfHelper fire do_action('bdm_post_published', $post_id) when a book or blog post is published. The future plugin attaches to this hook without requiring changes to the theme or existing plugins.
|
||
• The BDMurphy-BookShelf plugin (current) handles one-way manual email composition only. The future plugin is separate.
|
||
|
||
8.5 Required Theme Support Declarations
|
||
All required add_theme_support() calls in functions.php:
|
||
|
||
title-tag Lets WordPress manage the <title> element. Not hard-coded in header.php.
|
||
custom-logo array( 'width' => 250, 'height' => 250, 'flex-width' => true, 'flex-height' => true )
|
||
custom-header array( 'default-image' => get_template_directory_uri().'/assets/Reading_through_time.png', 'width' => 1200, 'height' => 250, 'flex-height' => false )
|
||
custom-background array( 'default-color' => 'F5F0E8' )
|
||
post-thumbnails No args. Required for featured images.
|
||
html5 array( 'search-form', 'comment-form', 'comment-list', 'gallery', 'caption', 'script', 'style' )
|
||
automatic-feed-links No args. Adds RSS/Atom links to head.
|
||
wp-block-styles No args. Applies default Gutenberg block styles.
|
||
editor-style add_editor_style('assets/editor-style.css').
|
||
add_image_size shelf-thumb 44×62 (crop), blog-thumb 100×68 (crop), rev-thumb 52×74 (crop), book-cover 130×185 (crop), book-page-cover 220×310 (crop), series-card 400×280 (crop), series-header 1200×300 (crop).
|
||
|
||
8.6 Template File Structure
|
||
style.css Theme header: Theme Name: BDMurphy-Bookshelf, Author, Version, Text Domain: bd-murphy.
|
||
functions.php add_theme_support(), register_nav_menus(), register_sidebar(), wp_enqueue_scripts, Customizer panels, Theme Options, bdm_post_published action hook.
|
||
header.php wp_head(), banner image, sticky nav, body_class().
|
||
footer.php Footer three-zone layout, sign-up prompt, wp_footer().
|
||
front-page.php Home page two-column layout.
|
||
sidebar-home.php Home right column — book shelf widget area.
|
||
archive.php / home.php Blog post list.
|
||
archive-book.php All books page.
|
||
single-book.php Individual book page (series display and social sharing).
|
||
archive-series.php Series listing page (/series/).
|
||
taxonomy-series.php Individual series page (/series/{slug}/).
|
||
page.php Default page template with sidebar.
|
||
page-full-width.php Full width. Template Name: Full Width.
|
||
page-no-sidebar.php Single column. Template Name: No Sidebar.
|
||
page-about.php About page. Template Name: About.
|
||
page-reviews.php Reviews grid. Template Name: Reviews.
|
||
page-unsubscribe.php Unsubscribe form. Template Name: Unsubscribe.
|
||
page-signup.php Sign-up page. Template Name: Sign Up.
|
||
404.php 404 error page.
|
||
search.php Search results.
|
||
|
||
8.7 Required Template Tag Usage
|
||
• body_class() on body tag — plugin hooks and admin bar CSS offset.
|
||
• post_class() on post/book wrapper divs — plugin hooks and state classes.
|
||
• wp_head() immediately before closing </head> — required for all plugins.
|
||
• wp_footer() immediately before closing </body> — required for all plugins.
|
||
• the_custom_logo() for logo output.
|
||
• get_header_image() for banner image output.
|
||
• wp_nav_menu(['theme_location' => 'primary']) for main nav.
|
||
• wp_nav_menu(['theme_location' => 'footer']) for footer links.
|
||
• dynamic_sidebar('home-sidebar') for the book shelf widget area.
|
||
• do_action('bdm_post_published', $post_id) fired on book and blog post publish.
|
||
|
||
End of BDMurphy BookShelf System Specification v2.0
|
||
Note: For the BD-BookShelfHelper plugin full specification, see: BD-BookShelfHelper-Plugin-Specification-v1_0.docx
|