umbragit/Bookshelf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
38cdebd0c6c18c6c5e594545244523cd9811c4fb
Bookshelf/BD-Murphy-Website-Specification-v2.0.md
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

29 KiB
Raw Blame History

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
  2. Theme - Global Layout
  3. Theme - Pages
  4. Design System
  5. Plugin: BD-BookShelfHelper
  6. Plugin: BD-SimpleEmail
  7. Database Schema
  8. Design Decisions
  9. Implementation Standards
  10. Quality Requirements
  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:

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

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

5.3 Series Management

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

5.4 Pen Name Management

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

5.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

5.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

5.7 Goodreads Integration

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

5.8 Amazon Ratings

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

5.9 SEO Generation

Auto-generated on book save:

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

5.10 Admin Menu Structure

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)

5.11 Shortcodes

The plugin provides 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

Usage:

// Single book by ID
[bd-book book="42"]

// Single book by title
[bd-book book="Pandemic Hacker"]

// All books
[bd-books]

// Limit number of books
[bd-books limit="5"]

5.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:

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

Migrated Fields:

BD Books Field BookHelper Target
title Post title
author Pen name (lookup or create)
description blurb_{lang} meta
cover_image_id Featured image (WordPress media)
cover_image_url Downloaded and imported as attachment
purchase_links Retailer URL metas (Amazon, Apple, B&N, Kobo, Google)

Admin Access: BD BookHelper → Migrate

6. Plugin: BD-SimpleEmail

6.1 Overview

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

6.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

6.3 Email Composition Workflow

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

6.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

6.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

6.6 Admin Menu Structure

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

7. Database Schema

7.1 BD BookHelper Tables

-- Core book record
CREATE TABLE {$wpdb->prefix}bd_books (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    post_id BIGINT NOT NULL,
    pen_name_id BIGINT,
    series_id BIGINT,
    volume_number INT,
    asin VARCHAR(20),
    isbn VARCHAR(20),
    publish_date DATE,
    sort_order INT DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY post_id (post_id)
);

-- Per-language content
CREATE TABLE {$wpdb->prefix}bd_book_meta (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    language_code VARCHAR(5) NOT NULL,
    title VARCHAR(255),
    blurb TEXT,
    preview_excerpt TEXT,
    pull_quotes JSON,
    UNIQUE KEY book_language (book_id, language_code)
);

-- Series definitions
CREATE TABLE {$wpdb->prefix}bd_series (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    slug VARCHAR(100) NOT NULL UNIQUE,
    cover_attachment_id BIGINT,
    header_attachment_id BIGINT,
    blurb TEXT,
    display_order INT DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Pen names
CREATE TABLE {$wpdb->prefix}bd_pen_names (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    pen_name VARCHAR(255) NOT NULL,
    notes TEXT,
    active TINYINT(1) DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Reviews
CREATE TABLE {$wpdb->prefix}bd_reviews (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    comment_text TEXT,
    synopsis TEXT,
    source_name VARCHAR(255) NOT NULL,
    source_url VARCHAR(500),
    display_order INT DEFAULT 0,
    KEY book_id (book_id)
);

-- Ratings cache
CREATE TABLE {$wpdb->prefix}bd_ratings (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    source VARCHAR(20) NOT NULL,
    rating DECIMAL(3,2),
    review_count INT,
    last_updated DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY book_source (book_id, source)
);

-- Review short links
CREATE TABLE {$wpdb->prefix}bd_review_shortlinks (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    site_code VARCHAR(5) NOT NULL,
    slug VARCHAR(20) NOT NULL UNIQUE,
    destination_url VARCHAR(500),
    status VARCHAR(20) DEFAULT 'pending',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    activated_at DATETIME
);

7.2 BD SimpleEmail Tables

-- Subscribers
CREATE TABLE {$wpdb->prefix}bd_subscribers (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    first_name VARCHAR(100),
    status VARCHAR(20) DEFAULT 'subscribed',
    subscribed_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    unsubscribed_at DATETIME,
    ip_address VARCHAR(45),
    unsubscribe_token VARCHAR(64)
);

-- Newsletter log
CREATE TABLE {$wpdb->prefix}bd_newsletters (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    subject VARCHAR(255) NOT NULL,
    body_html TEXT,
    sent_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    recipient_count INT DEFAULT 0
);

8. Design Decisions

Decision Answer Rationale
Child theme support No Customization via Customizer and Theme Options only
Dark mode No Light mode only, parchment palette
Sign-up form Dedicated page (/signup/) Shortcode [bdm_signup] also available
Visitor-submitted reviews No Admin-entered only
Social sharing Yes Web Share API with platform fallback
Series pages Yes Full series system with conditional nav
Affiliate codes Optional System works without, adds when available
One-click unsubscribe Yes HMAC-signed token per subscriber

9. Implementation Standards

9.1 WordPress Architecture

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

9.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

9.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/banner_1200x200_v3.png',
    '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);

9.4 Template File Structure

bd-murphy-author/
├── style.css              (Theme header: Name, Author, Version, Text Domain)
├── functions.php           (add_theme_support, register_nav_menus, etc.)
├── header.php             (wp_head, banner, nav, body_class())
├── footer.php              (Footer zones, wp_footer)
├── front-page.php         (Home page)
├── archive.php             (Blog posts)
├── archive-book.php        (All books)
├── single-book.php         (Individual book)
├── archive-series.php      (Series listing)
├── taxonomy-series.php     (Individual series)
├── page.php                (Default page)
├── page-full-width.php     (Template: Full Width)
├── page-no-sidebar.php     (Template: No Sidebar)
├── page-about.php         (Template: About)
├── page-reviews.php       (Template: Reviews)
├── page-signup.php        (Template: Sign Up)
├── page-unsubscribe.php   (Template: Unsubscribe)
├── page-contact.php       (Contact with AJAX)
├── 404.php
├── search.php
└── inc/
    ├── customizer.php
    ├── theme-options.php
    ├── template-tags.php
    ├── widgets.php
    └── nav-menu.php

9.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

9.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

10. Quality Requirements

10.1 Testing Standards

Unit Tests (Required):

  • All helper functions must have PHPUnit tests
  • Minimum 80% code coverage for utility functions
  • Test data factories for books, series, subscribers

Integration Tests:

  • Plugin activation/deactivation
  • Database table creation
  • Custom post type registration
  • REST API endpoints

E2E Tests (Recommended):

  • Sign-up flow
  • Unsubscribe flow
  • Newsletter send flow
  • Contact form submission

10.2 Accessibility Requirements (WCAG 2.1 AA)

Requirement Implementation
Keyboard navigation All interactive elements focusable
Skip links "Skip to content" link in header
ARIA labels aria-label, aria-expanded, role attributes
Color contrast Minimum 4.5:1 for text
Focus indicators Visible focus styles
Screen reader Semantic HTML, screen reader text
Touch targets Minimum 44x44px on mobile

10.3 Performance Targets

Metric Target
Page load < 2 seconds
Time to first byte < 600ms
Lighthouse Performance > 90
Lighthouse Accessibility > 95

Optimization Requirements:

  • Lazy loading for images (loading="lazy")
  • Minified CSS and JavaScript in production
  • GZIP compression enabled
  • Object caching enabled (Redis/Memcached recommended)
  • Database query optimization with proper indexing

10.4 Security Audit Checklist

  • All user input sanitized
  • All output escaped
  • Nonces verified on all form submissions
  • Capabilities checked on admin actions
  • SQL injection prevention (prepared statements)
  • XSS prevention (escaping)
  • CSRF protection (nonces)
  • Stored secrets encrypted
  • File upload validation
  • Rate limiting on contact form
  • Security headers (X-Content-Type-Options, X-Frame-Options, CSP)

11. Deployment Checklist

11.1 Pre-Deployment

  • All code passes WordPress Coding Standards sniffs
  • Unit tests pass with >80% coverage
  • No debug output in production code
  • Plugin uninstall.php created
  • Plugin README.txt with installation instructions
  • Theme screenshot.png (1200x900px)

11.2 Server Requirements

  • WordPress 6.0+ installed
  • PHP 7.4+ (8.2 recommended)
  • MySQL 5.7+ or MariaDB 10.3+
  • HTTPS enabled with valid certificate
  • Memory limit >= 256M
  • Max execution time >= 60s
  • WP-Cron configured (DISABLE_WP_CRON = false)

11.3 Configuration

  • AUTH_KEY, SECURE_AUTH_KEY, LOGGED_IN_KEY, NONCE_KEY defined
  • WP_DEBUG disabled in production
  • WP_DEBUG_LOG disabled in production
  • SAVEQUERIES disabled in production
  • Object cache (Redis/Memcached) configured
  • CDN configured for static assets (optional)

11.4 Plugin Installation Order

  1. Install and activate BD-BookShelfHelper first
  2. Install and activate BD-SimpleEmail second
  3. Upload and activate BDMurphy Bookshelf theme
  4. Configure Theme Options (Appearance > Theme Options)
  5. Configure BD BookHelper Settings
  6. Configure BD SimpleEmail Settings

11.5 Post-Installation

  • Permalinks flushed (Settings > Permalinks > Save)
  • Sample data installed (if desired)
  • Required pages created (/signup, /unsubscribe, /contact)
  • Navigation menus configured
  • Book shelf widget placed in Home Sidebar
  • Test sign-up flow
  • Test newsletter send
  • Verify social sharing works
  • Test mobile responsiveness
  • Verify accessibility with screen reader

11.6 Ongoing Maintenance

  • WordPress core updates tested before production deployment
  • Plugin updates tested before production deployment
  • Theme updates tested before production deployment
  • Database backups before any update
  • Security audit quarterly
  • Performance audit bi-annually

Appendix A: Disallowed Functions & Patterns

The following are NOT permitted in this project:

Category Disallowed
Database mysql_* functions (use $wpdb)
Filesystem file_get_contents() with URLs, direct file inclusion
Security eval(), exec(), shell_exec(), system()
Output echo without escaping, print without escaping
Deprecated Any function marked deprecated in WordPress 6.0+

Appendix B: Recommended Tools

  • Local Development: Local by Flywheel, Docker, or VVV
  • Code Quality: PHPStan, ESLint, Prettier
  • Testing: PHPUnit, WP_Mock, Codeception
  • Security: WPScan, Sucuri, Wordfence
  • Performance: Query Monitor, New Relic, GTmetrix

Appendix C: Sample Data

On plugin/theme activation, install sample data:

  1. Pen name "B.D. Murphy" as active default
  2. Book "Pandemic Hacker" with placeholder cover
  3. Pre-reserved review short links: phrA, phrG, phrB, phrK, phrP, phrL
  4. Pre-configured retailer links for sample book
  5. Three sample blog posts
  6. Goodreads Author ID: 30469651

"Clear sample data" button in Theme Options removes all sample content.

End of Specification v2.0

For page mockups, see: BD-Murphy-Page-Mockups-v1.2.docx