Files

bdm 38cdebd0c6 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.

2026-09-28 06:24:25 -07:00

25 KiB

Raw Blame History

BDMurphy BookShelf Template - Technical Specification v2.2.10

WordPress Theme: BDMurphy BookShelf
Plugin 1: BD-BookShelfHelper (not yet implemented)
Plugin 2: BD-BookShelf (not yet implemented)

Version: 2.2.10 | June 2026
Status: Theme fully implemented. Plugins pending development.

Project Overview
Theme - Global Layout
Theme - Pages
Design System
Goodreads Widget (Theme-Built)
Plugin: BD-BookShelfHelper (Planned)
Plugin: BD-SimpleEmail (Planned)
Implementation Standards
Current Build Status

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. (Planned)
Plugin: BD SimpleEmail: Subscriber management and AI-assisted newsletter delivery (Planned)

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	Illustrated timeline banner (1538x250px), full-width on all pages
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 complies with 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 (1538x250px) displayed at 100% viewport width on all pages
Default asset: assets/images/banner.jpg
Site logo via add_theme_support('custom-logo')
Default logo asset: assets/images/Icon_Quill_BDMurphy_Black_WhtBG.jpg
Admin bar offset handled via body.admin-bar rules

Registered via register_nav_menus(['primary' => 'Primary Menu', 'footer' => 'Footer Menu'])
Default menu items: Home, Books, Blogs, Reviews, About
Sticky behavior with gold top border on scroll
Hamburger menu on mobile (<768px)
Custom link fallback when no menu assigned

2.3 Footer

Three-zone layout: social icons, donate/utility links, footer links
Footer links displayed as vertical list (not jumbled)
Two widget areas: "Footer Left" and "Footer Right"
Sign-up prompt with link to /signup/ page (configurable show/hide)
Copyright notice with dynamic year

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
Heading font	`get_theme_mod('heading_font', 'Playfair Display')`	Customizer > Typography
Body font	`get_theme_mod('body_font', 'Lato')`	Customizer > Typography
Author name	`get_theme_mod('author_name', 'B.D. Murphy')`	Customizer > Author Book Settings
Goodreads ID	`get_theme_mod('goodreads_author_id', '30469651')`	Customizer > Author Book Settings
Amazon Author ID	`get_theme_mod('amazon_author_id', '30469651')`	Customizer > Author Book Settings
Show Newsletter Signup	`get_theme_mod('show_newsletter_signup', true)`	Customizer > Display Options
Show Sign Up Link	`get_theme_mod('show_signup_link', true)`	Customizer > Display Options
Social Sharing	`get_theme_mod('share_facebook', true)` etc.	Customizer > Social Sharing

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)

Banner at 100% screen width
Navigation menu line (Home, Books, Blogs, Reviews, About)
Two-column layout: 66% content, 34% sidebar
Content via WordPress block editor
Sidebar contains Goodreads Books widget (fetches from Goodreads API)

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 Books Page (/books-2/)

Template: page-books.php. Grid layout of book covers matching authorbdmurphy.com style.

Default behavior (no plugin): Shows default example books with covers from uploaded images:

Pandemic Hacker
Pandemic Hacker 2
The Last Dwarf
Deal Hunter
Nanite Evolution
Sidney and Watson: Time Detectives

With BD BookHelper plugin: Shows books from the book custom post type.

No sidebar on Books page (correct behavior per specification).

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")

3.5 Reviews Page (/reviews/)

Template: page-reviews.php. Two-column layout with review cards and Goodreads sidebar widget.

3.6 About Page (/about/)

Template: page-about.php. Two-column layout:

Left column: Author bio content, awards section (if plugin active), donate buttons, signup prompt
Right column (sidebar):
- Author photo (thumbnail size, circular crop)
- Newsletter signup card (configurable show/hide)
- Goodreads Books widget (below author photo, shows on all pages except Books)

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

Template: page-signup.php. Email, first name, opt-in checkbox. Shortcode [bdm_signup] available.

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
404: Custom error page with home link

4. Design System

4.1 Color Palette (CSS Custom Properties)

: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)

4.5 Banner Behavior

Full viewport width on all pages using width: 100vw; margin-left: calc(-50vw + 50%)
Max height: 200px with object-fit: cover
Consistent across all page templates

5.1 Overview

The Goodreads widget is built directly into the theme (not dependent on plugins). It fetches books from the author's Goodreads page and displays them in the sidebar.

Widget name: BDM_Goodreads_Books_Widget
Widget title: "GoodReads for {author_name}" (configurable)
Sidebar assignment: home-sidebar (used on all pages except Books)

5.3 Data Sources

BD BookHelper Plugin (if active): Queries book CPT for local book data
Goodreads Fallback (no plugin): Fetches from https://www.goodreads.com/author/list/{author_id}

5.4 Goodreads Integration Details

Author ID: 30469651 (configurable via Customizer)
Fetch method: wp_remote_get() with 10-second timeout
HTML parsing: DOMDocument with XPath queries
Data extracted: Title, cover image, URL, rating
Sort order: By review count descending (most reviews first)
Max books displayed: 6

<div class="goodreads-books-list">
    <div class="goodreads-book-item">
        <div class="goodreads-book-cover">
            <img src="..." alt="Book Title" loading="lazy">
        </div>
        <div class="goodreads-book-details">
            <a href="..." class="goodreads-book-title">Book Title</a>
            <div class="goodreads-book-ratings">
                <span class="rating goodreads">Goodreads: 4.38/5</span>
            </div>
        </div>
    </div>
</div>

5.6 Page Visibility

Page	Widget Shown
Home	Yes
Books	No (correct behavior)
Blogs	Yes
Reviews	Yes
About	Yes (under author photo)
Individual Book	Yes
Individual Review	Yes
Contact	Yes
Signup	Yes
404	No

6. Plugin: BD-BookShelfHelper (Planned)

6.1 Overview

Manages all book-related data, series information, and pen name configuration. Registers "book" custom post type and "series" taxonomy.

6.2 Book Data Entry

6.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 <label> elements properly associated via for attribute
Hints: Helper text below each field provides context, format requirements, and examples
Validation:
- Real-time validation on blur with visual feedback (green checkmark for valid, red border + message for invalid)
- Server-side validation on save with error messages displayed above problematic fields
- Required fields marked with asterisk and validated before submission
- Format validation: ISBN-13 (13 digits), ASIN (10 alphanumeric), dates (YYYY-MM-DD), URLs (valid format)
Organization: Fields grouped into logical sections with collapsible headers:
- Basic Information (title, pen name, publication date)
- Identifiers (ISBN-13, ASIN)
- Series & Order (series selection, volume number)
- Content (blurb, preview excerpt, pull quotes)
- Metadata (genre tags, Amazon search terms)
- Retailer Links (Amazon, Apple, Google, B&N, Kobo)
- Reviews (add/edit reviews)
Multi-language Tabs: Language selector tabs for entering content in each supported language
Auto-save Draft: Automatic saving of work in progress every 60 seconds
Preview: Button to preview how the book will appear on the front-end

Core Fields (language-independent):

Cover image (per language)
Pen name (from configured list)
Publication date, sort order
ISBN-13, ASIN
Series, volume number
Short link slug

Content Fields (per language):

Title, blurb, preview excerpt
Pull quotes (up to 5)
Genre tags (min 3)
Amazon search terms

Reviews (per book):

Comment text, source name, source URL
AI-generated 3-line synopsis
Display order

Supported Languages: EN, FR, ES, DE, IT, PT, RU, JA, ZH (Simplified)

6.3 Series Management

Series name, slug, cover graphic, blurb, display order
Book series assignment with volume number
Conditional nav item rendering

6.4 Pen Name Management

Up to 10 pen names
Active/inactive toggle
Notes field (internal only)
Per-book assignment

6.5 Retailer Purchase Links

Retailer	Formats	URL Pattern
Amazon	Ebook, Paperback, Hardback	`amazon.com/dp/{ASIN}?tag={affiliate_id}`
Apple Books	Ebook	URL with `at=` parameter
Google Play	Ebook	URL with partner code
Barnes & Noble	All	URL with affiliate parameter
Kobo	Ebook	URL with affiliate parameter

6.6 Short Link System

Book Short Links:

Auto-generated from first letter of significant words
Examples: "Pandemic Hacker" → /ph/, "Deal Hunter" → /dh/
Conflict check with incrementing numbers

Review Short Links:

Pattern: {book-slug}r{site-code} (e.g., dhrG = Deal Hunter Goodreads)
Lifecycle: Reserved → Pending → Active

6.7 Goodreads Integration

Daily WP-Cron refresh
Parses widget HTML for book data
Author ID: 30469651

6.8 Amazon Ratings

6-hour WP-Cron scrape
Staleness indicator on failure
Warning: May conflict with Amazon Terms of Service

6.9 SEO Generation

Auto-generated on book save:

Title tag, meta description
Open Graph, Twitter Card tags
schema.org Book structured data

BD BookHelper (top-level menu)
├── All Books
├── Add Book
├── Data Entry         (Enhanced interface per 5.2.1)
├── Series (taxonomy submenu)
├── Pen Names
├── Settings
│   ├── Affiliate Codes
│   ├── Goodreads
│   └── Amazon Scrape
└── Migrate            (Import from BD Books plugin)

6.11 Shortcodes

The plugin will provide WordPress shortcodes for displaying book content:

Shortcode	Description
`[bd-book book="1"]`	Display single book by ID or title
`[bd-books]`	Display all books in a list

6.12 Migration from BD Books Plugin

The plugin includes a migration tool to import books from the original "BD Books" (bd-book-listing) plugin:

Migration Process:

Reads from {$wpdb->prefix}bd_books table
Creates new book CPT entries
Maps author to pen names (creates new if needed)
Imports descriptions as blurbs (English)
Imports cover images (WordPress media or external URLs)
Parses and maps purchase links to retailer fields

7. Plugin: BD-SimpleEmail (Planned)

7.1 Overview

Handles email newsletter creation, subscriber management, and delivery via Gmail SMTP. AI-assisted composition via Gemini API.

7.2 Configuration

Setting	Storage
Gmail address	`wp_options`
App password	Encrypted (openssl_encrypt)
Sender name	`wp_options`
Reply-to	`wp_options`
Gemini API key	Encrypted `wp_options`

7.3 Email Composition Workflow

User opens "New Newsletter"
Enters subject and AI prompt (optional)
Plugin generates HTML via Gemini API
User edits draft
Optional: publish as blog post
Click "Send Newsletter" → sends to all subscribers via Gmail SMTP

7.4 Email Template

Header: Site name/logo
Body: Composed content with affiliate links
Footer (mandatory):

Website URL
One-click unsubscribe (HMAC-signed token)
Full business address (CAN-SPAM)
Unsubscribe text link

7.5 Subscriber Management

Schema:

bd_subscribers (
    id PRIMARY KEY AUTO_INCREMENT,
    email UNIQUE NOT NULL,
    first_name VARCHAR(100),
    status ENUM('subscribed', 'unsubscribed'),
    subscribed_at DATETIME,
    unsubscribed_at DATETIME NULL,
    ip_address VARCHAR(45),
    UNSUBSCRIBE_TOKEN VARCHAR(64) -- pre-generated
)

One-Click Unsubscribe:

HMAC-signed token in every email
Token format: hash_hmac('sha256', email, AUTH_KEY)
Satisfies Gmail/Yahoo delivery requirements

BD SimpleEmail (top-level menu)
├── Subscribers
├── New Newsletter
└── Settings
    └── Gmail Configuration
    └── Gemini API
    └── About

8. Implementation Standards

8.1 WordPress Architecture

Custom Post Types: "book" CPT registered by BD BookHelper (theme queries, doesn't register)
Taxonomies: "series" registered by BD BookHelper, attached to book CPT
Rewrite Rules: Short links via add_rewrite_rule()
Internationalization: Text domains (bd-murphy, bd-bookshelfhelper, bd-simpleemail), load_theme_textdomain() in functions.php
Scheduled Tasks: WP-Cron for Goodreads (daily), Amazon ratings (6 hours), review links (daily)
Asset Loading: All CSS/JS via wp_enqueue_style() and wp_enqueue_script() with handles, dependencies, version strings

8.2 Security Requirements

Requirement	Implementation
Secrets storage	`openssl_encrypt()` with AES-256-CBC, key from AUTH_KEY
Unsubscribe tokens	`hash_hmac('sha256')` with AUTH_KEY
Output escaping	`esc_html()`, `esc_url()`, `esc_attr()`, `wp_kses_post()`
Input sanitization	`sanitize_text_field()`, `sanitize_email()`, `absint()`, etc.
CSRF protection	`wp_verify_nonce()` on all form submissions
Nonce verification	Nonce field + verification on every AJAX and form POST
Affiliate codes	Server-side application only, never in client-side code
Spam protection	Contact form honeypot field

8.3 Required Theme Support Declarations

add_theme_support('title-tag');
add_theme_support('custom-logo', array(
    'width' => 200,
    'height' => 200,
    'flex-width' => true,
    'flex-height' => true,
));
add_theme_support('custom-header', array(
    'default-image' => BDM_URI . '/assets/images/banner.jpg',
    'width' => 1200,
    'height' => 200,
    'flex-height' => false,
));
add_theme_support('custom-background', array(
    'default-color' => 'F5F0E8',
));
add_theme_support('post-thumbnails');
add_theme_support('html5', array(
    'search-form', 'comment-form', 'comment-list',
    'gallery', 'caption', 'script', 'style'
));
add_theme_support('automatic-feed-links');
add_theme_support('wp-block-styles');
add_editor_style('assets/editor-style.css');

add_image_size('shelf-thumb', 44, 62, true);
add_image_size('blog-thumb', 100, 68, true);
add_image_size('rev-thumb', 52, 74, true);
add_image_size('book-cover', 130, 185, true);
add_image_size('book-page-cover', 220, 310, true);
add_image_size('series-card', 400, 280, true);
add_image_size('series-header', 1200, 300, true);

8.4 Template File Structure (Current Build)

bd-murphy-author/
├── style.css              (Theme header: Name, Author, Version 2.2.0, Text Domain)
├── functions.php           (add_theme_support, register_nav_menus, widgets, etc.)
├── header.php             (wp_head, banner, nav, body_class())
├── footer.php             (Footer zones, wp_footer, vertical links)
├── front-page.php         (Home page with sidebar)
├── archive.php            (Blog posts)
├── archive-book.php       (All books - plugin)
├── archive-series.php     (Series listing - plugin)
├── single-book.php        (Individual book - plugin)
├── taxonomy-series.php    (Individual series - plugin)
├── index.php              (Fallback template)
├── page.php               (Default page with sidebar)
├── page-about.php         (About - author photo, newsletter, Goodreads widget)
├── page-books.php         (Books grid - NO sidebar)
├── page-reviews.php       (Reviews with sidebar)
├── page-full-width.php    (Template: Full Width)
├── page-no-sidebar.php    (Template: No Sidebar)
├── page-signup.php        (Template: Sign Up)
├── page-unsubscribe.php   (Template: Unsubscribe)
├── page-contact.php       (Contact with AJAX)
├── 404.php                (Custom error page)
├── search.php             (Search results)
├── screenshot.png         (Theme screenshot)
├── inc/
│   ├── customizer.php     (Customizer settings, Display Options)
│   ├── theme-options.php  (Theme Options admin page)
│   ├── template-tags.php  (Helper functions, author photo thumbnail)
│   ├── widgets.php        (Goodreads Books Widget)
│   ├── nav-menu.php       (Custom menu walkers)
│   ├── short-urls.php     (Short URL rewrite rules)
│   ├── theme-admin.php    (Admin page functions)
│   ├── setup.php          (Theme setup)
│   ├── book-helpers.php   (Book helper functions)
│   ├── book-api.php       (Book API functions)
│   └── ajax-handlers.php  (AJAX handlers)
├── assets/
│   ├── css/
│   │   ├── style.css      (Main stylesheet - 1740+ lines)
│   │   ├── editor-style.css
│   │   └── admin-style.css
│   ├── js/
│   │   ├── navigation.js  (Menu toggle, sticky nav)
│   │   └── social-share.js
│   └── images/
│       ├── banner.jpg
│       └── Icon_Quill_BDMurphy_Black_WhtBG.jpg
└── template-parts/
    └── social-share.php

8.5 Required Template Tag Usage

Tag	Location	Purpose
`body_class()`	`<body>`	Plugin hooks, admin bar offset
`post_class()`	Article wrappers	Plugin hooks, state classes
`wp_head()`	Before `</head>`	Plugin hooks, styles
`wp_footer()`	Before `</body>`	Plugin hooks, scripts
`the_custom_logo()`	Header	Logo output
`get_header_image()`	Header	Banner output
`wp_nav_menu()`	Header, Footer	Navigation menus
`dynamic_sidebar()`	Sidebar areas	Widget areas
`do_action('bdm_post_published', $post_id)`	On publish	Future plugin hook

8.6 Hooks Reference

Actions:

bdm_post_published — Fired on book/blog post publish (future plugin hook)

Filters:

bdm_nav_menu_items — Filter for Series menu conditional
bdm_social_share_url — Filter share URLs
bdm_email_footer_content — Filter email footer

9. Current Build Status

9.1 Theme Implementation: COMPLETE

Feature	Status	Notes
Banner (full-width)	✅ Complete	1538x250px, responsive
Navigation menu	✅ Complete	Home, Books, Blogs, Reviews, About
Sticky nav	✅ Complete	Gold border on scroll
Home page	✅ Complete	Two-column with Goodreads sidebar
Books page	✅ Complete	Grid layout, no sidebar, default examples
About page	✅ Complete	Author photo, newsletter, Goodreads widget
Reviews page	✅ Complete	Two-column with sidebar
Blog page	✅ Complete	Standard archive
Footer	✅ Complete	Three-zone, vertical links
Customizer	✅ Complete	Colors, fonts, display options, Goodreads ID
Goodreads widget	✅ Complete	Fetches from Goodreads, shows on all pages except Books
Social sharing	✅ Complete	Facebook, X, LinkedIn, WhatsApp, Copy Link
Contact form	✅ Complete	AJAX with honeypot
Signup page	✅ Complete	Email signup form
404 page	✅ Complete	Custom error page
Mobile responsive	✅ Complete	Hamburger menu, touch targets
Default images	✅ Complete	Bundled in assets/images/

9.2 Plugin Implementation: NOT STARTED

Plugin	Status
BD-BookShelfHelper	❌ Not implemented
BD-SimpleEmail	❌ Not implemented

9.3 Current Version

Theme Version: 2.2.0
Zip File: /home/bdm/Bookshelf/bd-bookshelf-v2.2.0.zip
Test Site: https://bdmurphy.me (local at /var/www/html/wordpress/)

End of Specification v2.2

25 KiB Raw Blame History