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.
552 lines
22 KiB
Plaintext
552 lines
22 KiB
Plaintext
================================================================================
|
|
BD BOOKSHELF PLUGIN SPECIFICATION
|
|
================================================================================
|
|
|
|
Version: 2.2.0
|
|
Location: /wp-content/plugins/bd-bookshelf/
|
|
|
|
================================================================================
|
|
1. OVERVIEW
|
|
================================================================================
|
|
|
|
This plugin serves as a helper for BD Bookshelf. it is a plugin with the same name to show they go together. Make your website the destination to find the best place to buy your book. Enter your ISBN and the system will search book seller websites for your book.
|
|
|
|
The plugin will let the user enter a book by Title and ISBNs. There can be four ISBNs for each book, coorisponding to the form factor: eBook, Paperback, Hard Cover, audio. The system will allow entry and track this information.
|
|
|
|
With the ISBN the system will use known patters to get direct links to popular book selling sites. The user can see the links and edit them.
|
|
The sites are Amazon, Barnes and Noble, Apple, Google, Kobo.
|
|
The plugin will allow the user to create a new link, entering the name and the link manually. The icon for these links will be a general page of a book and quill.
|
|
|
|
The user can enter affiliate codes related to each of the sites and the system will automatically incorporate them into links to that site.
|
|
|
|
The system will use the ISBN/ASIN information to get ratings for the book. It will get the information from Amazon and Goodreads (author information - author ID in theme). The system will scan and do updates every 12 hours with a cron job. The ratings will be shown when the book is displayed with a [rating] short tag - specific to that book.
|
|
|
|
The plugin will create a grid of selling site icons and links when a short code is used on a page. The short codes are specific to format and ISBN. codes: [sell_ebook], [sell_pb], [sell_hc], [sell_audio]
|
|
|
|
The plugin will provide the popup and checks for GDPR compliance
|
|
|
|
The plugin will allow creating and editing SEO metadata for book pages.
|
|
|
|
The plugin will allow creation and management of short codes. A code defined by website/shrtcode that can be redirected, expanded to another site.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
GDPR compliance - get approval for cookies.
|
|
7) SEO metadata
|
|
8) short codes
|
|
|
|
2) User enters book
|
|
Title and ISBN - a book can have eBook, Paperback, Hardcover, Audio.
|
|
2.1) site identifier ASIN/ISBN
|
|
3) System confirms top sites name and link pattern - show site general link search on sites - Need ISBN/ASIN/ident
|
|
3.1 list of sites with pattern to search.
|
|
Amazon
|
|
B&N
|
|
Apple
|
|
Google
|
|
Kobo
|
|
4) Adding affiliate codes for sites
|
|
5)get ratings from site (Amazon/goodreads) - limit updates to every x hours
|
|
|
|
|
|
6) Generate sell buttons/links from a shortcode - links with affiliate codes on page.
|
|
codes: [sell_ebook], [sell_pb], [sell_hc], [sell_audio] When the code is entered the system will generate a grid of the site options to purchase the book.
|
|
6.2)
|
|
|
|
|
|
|
|
|
|
|
|
PlatformPrimary IdentifierBest URL Structure for Programmatic Linking
|
|
Bookshop.org ISBN-13 https://bookshop.org/books/{ISBN13}
|
|
Barnes & Noble (Print)EAN / ISBN-13 https://www.barnesandnoble.com/s/{ISBN13}
|
|
|
|
shortcodes?
|
|
|
|
"Theme Transition Helper" - it provides a bridge
|
|
between WordPress and the BD BookShelf theme by managing book data, generating
|
|
the Amazon-style book display layout, and providing shortcodes for theme use.
|
|
|
|
Purpose:
|
|
- Manage book data (titles, blurbs, covers, ratings) in custom database tables
|
|
- Generate HTML output with specific CSS classes (.bd-book-*) for theme styling
|
|
- Provide REST API endpoints for book data
|
|
- Handle multi-language support with localized content per language
|
|
- Manage retailer links and affiliate tracking
|
|
|
|
================================================================================
|
|
2. FILE STRUCTURE
|
|
================================================================================
|
|
|
|
bd-bookshelfhelper.php Main plugin file - initialization, constants
|
|
inc/class-bookhelper.php Core plugin class - CPTs, taxonomies, shortcodes
|
|
inc/class-admin.php Admin functionality - data entry interface
|
|
inc/class-install.php Database installation, table creation
|
|
assets/css/admin.css Admin interface styling
|
|
assets/js/admin.js Enhanced data entry with auto-save/validation
|
|
uninstall.php Cleanup on plugin deletion
|
|
|
|
================================================================================
|
|
3. CUSTOM POST TYPES
|
|
================================================================================
|
|
|
|
CPT: "book"
|
|
---------------------------------------------------------------------------
|
|
Public: Yes
|
|
Has Archive: Yes (/book)
|
|
Show in Menu: No
|
|
Supports: title, editor, thumbnail, excerpt, custom-fields
|
|
REST API: Yes (show_in_rest = true)
|
|
Menu Icon: dashicons-book-alt
|
|
|
|
Capabilities: Uses native post capability type (edit_posts, etc.)
|
|
|
|
CPT: "bd_shortlink"
|
|
---------------------------------------------------------------------------
|
|
Purpose: Internal short link management
|
|
Public: No
|
|
Show UI: No
|
|
|
|
================================================================================
|
|
4. CUSTOM TAXONOMIES
|
|
================================================================================
|
|
|
|
Taxonomy: "series" (Hierarchical)
|
|
---------------------------------------------------------------------------
|
|
Object Type: book
|
|
Public: Yes
|
|
Show Admin Column: Yes
|
|
REST API: Yes
|
|
Rewrite: /series
|
|
|
|
================================================================================
|
|
5. DATABASE TABLES
|
|
================================================================================
|
|
|
|
TABLE: {prefix}bd_books
|
|
---------------------------------------------------------------------------
|
|
id BIGINT(20) AUTO_INCREMENT PRIMARY KEY
|
|
post_id BIGINT(20) NOT NULL UNIQUE
|
|
pen_name_id BIGINT(20)
|
|
series_id BIGINT(20)
|
|
volume_number INT(11)
|
|
asin VARCHAR(20)
|
|
isbn VARCHAR(20)
|
|
publish_date DATE
|
|
sort_order INT(11) DEFAULT 0
|
|
created_at DATETIME
|
|
|
|
TABLE: {prefix}bd_book_meta
|
|
---------------------------------------------------------------------------
|
|
id BIGINT(20) AUTO_INCREMENT PRIMARY KEY
|
|
book_id BIGINT(20) NOT NULL
|
|
language_code VARCHAR(5) NOT NULL
|
|
title VARCHAR(255)
|
|
blurb TEXT
|
|
preview_excerpt TEXT
|
|
pull_quotes JSON
|
|
UNIQUE KEY (book_id, language_code)
|
|
|
|
TABLE: {prefix}bd_pen_names
|
|
---------------------------------------------------------------------------
|
|
id BIGINT(20) AUTO_INCREMENT PRIMARY KEY
|
|
pen_name VARCHAR(255) NOT NULL
|
|
notes TEXT
|
|
active TINYINT(1) DEFAULT 1
|
|
created_at DATETIME
|
|
|
|
TABLE: {prefix}bd_reviews
|
|
---------------------------------------------------------------------------
|
|
id BIGINT(20) AUTO_INCREMENT PRIMARY KEY
|
|
book_id BIGINT(20) NOT NULL
|
|
comment_text TEXT
|
|
synopsis TEXT
|
|
source_name VARCHAR(255) NOT NULL
|
|
source_url VARCHAR(500)
|
|
display_order INT(11) DEFAULT 0
|
|
|
|
TABLE: {prefix}bd_ratings
|
|
---------------------------------------------------------------------------
|
|
id BIGINT(20) AUTO_INCREMENT PRIMARY KEY
|
|
book_id BIGINT(20) NOT NULL
|
|
source VARCHAR(20) NOT NULL
|
|
rating DECIMAL(3,2)
|
|
review_count INT(11)
|
|
last_updated DATETIME
|
|
UNIQUE KEY (book_id, source)
|
|
|
|
TABLE: {prefix}bd_series
|
|
---------------------------------------------------------------------------
|
|
id BIGINT(20) AUTO_INCREMENT PRIMARY KEY
|
|
name VARCHAR(255) NOT NULL
|
|
slug VARCHAR(100) NOT NULL UNIQUE
|
|
cover_attachment_id BIGINT(20)
|
|
header_attachment_id BIGINT(20)
|
|
blurb TEXT
|
|
display_order INT(11) DEFAULT 0
|
|
created_at DATETIME
|
|
|
|
TABLE: {prefix}bd_review_shortlinks
|
|
---------------------------------------------------------------------------
|
|
id BIGINT(20) AUTO_INCREMENT PRIMARY KEY
|
|
book_id BIGINT(20) 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
|
|
activated_at DATETIME
|
|
|
|
================================================================================
|
|
6. POST META FIELDS FOR BOOKS
|
|
================================================================================
|
|
|
|
Identification:
|
|
pen_name_id int FK to bd_pen_names table
|
|
asin string Amazon Standard Identification Number (10 chars)
|
|
isbn string ISBN-13 (13 digits)
|
|
short_link_slug string Custom short URL slug (e.g., "ph")
|
|
|
|
Series & Order:
|
|
volume_number int Book position in series
|
|
publish_date date Publication date (YYYY-MM-DD)
|
|
sort_order int Manual sort position
|
|
|
|
Ratings:
|
|
amazon_rating string Amazon rating (e.g., "4.5")
|
|
goodreads_rating string Goodreads rating (e.g., "4.2")
|
|
|
|
Localized Content (by language code: en, fr, de, es, it, pt, ru, ja, zh):
|
|
title_{lang} string Book title in language
|
|
blurb_{lang} string Back cover blurb
|
|
preview_excerpt_{lang} string Preview text excerpt
|
|
pull_quote_{lang}_{n} string Pull quote n (1-5)
|
|
genre_tags_{lang} string Genre tags (comma-separated)
|
|
amazon_search_terms_{lang} string Amazon search keywords
|
|
cover_{lang} int Cover image ID for language
|
|
|
|
Retailer Links (format + retailer):
|
|
{format}_url_{retailer}
|
|
|
|
Formats: ebook, paperback, hardback, audiobook
|
|
Retailers: amazon, apple, barnes, kobo, google, bookshop, amazon_uk, waterstones, audible, scribner
|
|
|
|
Examples:
|
|
ebook_url_amazon eBook Amazon link
|
|
paperback_url_barnes B&N paperback link
|
|
hardback_url_amazon Amazon hardback link
|
|
|
|
SEO:
|
|
seo_title string Custom meta title
|
|
seo_description string Meta description
|
|
|
|
Legacy/Migration:
|
|
genre string Primary genre
|
|
pages string Page count
|
|
language string Book language (default: "English")
|
|
publisher string Publisher name
|
|
|
|
================================================================================
|
|
7. SHORTCODES
|
|
================================================================================
|
|
|
|
SHORTCODE: [bd-book]
|
|
---------------------------------------------------------------------------
|
|
Displays a single book by ID or title.
|
|
|
|
Attributes:
|
|
book (string, required) - Book ID (integer) or title
|
|
|
|
Usage:
|
|
[bd-book book="123"]
|
|
[bd-book book="Pandemic Hacker"]
|
|
|
|
Output: Returns render_book_display() HTML or error message with bd-book-error class.
|
|
|
|
SHORTCODE: [bd-books]
|
|
---------------------------------------------------------------------------
|
|
Displays all books in a list.
|
|
|
|
Attributes:
|
|
limit int default: -1 (all) - Number of books to display
|
|
orderby string default: "date" - Sort field (date, title, menu_order, etc.)
|
|
order string default: "DESC" - Sort direction (ASC or DESC)
|
|
|
|
Usage:
|
|
[bd-books limit="10" orderby="date" order="DESC"]
|
|
|
|
Output: Wraps all render_book_display() outputs in <div class="bd-books-list">
|
|
|
|
================================================================================
|
|
8. RENDER_BOOK_DISPLAY() OUTPUT STRUCTURE
|
|
================================================================================
|
|
|
|
This is the CORE HTML OUTPUT that the plugin generates. The theme MUST provide
|
|
CSS styling for these classes to achieve the Amazon Detail layout.
|
|
|
|
```html
|
|
<div class="bd-book-listing">
|
|
<div class="bd-book-entry">
|
|
|
|
<!-- LEFT COLUMN (25%) -->
|
|
<div class="bd-book-cover">
|
|
<a href="[book-url]">
|
|
<img src="[cover-url]" alt="[book-title] Cover">
|
|
</a>
|
|
<div class="bd-book-purchase">
|
|
<div class="bd-book-format-selector">
|
|
<button class="bd-book-format-btn active" data-format="ebook">eBook</button>
|
|
<button class="bd-book-format-btn" data-format="paperback">Paperback</button>
|
|
<button class="bd-book-format-btn" data-format="hardback">Hardback</button>
|
|
</div>
|
|
<div class="bd-book-retailers" data-book-id="[book-id]">
|
|
<!-- Retailer links injected here by display_retailer_links() -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- RIGHT COLUMN (75%) -->
|
|
<div class="bd-book-details">
|
|
<h2 class="bd-book-title">
|
|
<a href="[book-url]">[book-title]</a>
|
|
</h2>
|
|
<p class="bd-book-byline">by [pen-name]</p>
|
|
|
|
<div class="bd-book-ratings">
|
|
<span class="rating-amazon">Amazon: [rating]/5</span>
|
|
<span class="rating-goodreads">Goodreads: [rating]/5</span>
|
|
</div>
|
|
|
|
<hr class="bd-book-separator">
|
|
|
|
<div class="bd-book-blurb">
|
|
[blurb content with wpautop()]
|
|
</div>
|
|
|
|
<div class="bd-book-metadata">
|
|
<span class="metadata-genre">[genre]</span> |
|
|
<span class="metadata-pages">[pages] pages</span> |
|
|
<span class="metadata-language">[language]</span> |
|
|
<span class="metadata-publisher">[publisher]</span>
|
|
</div>
|
|
|
|
<div class="bd-book-categories">
|
|
[category-list]
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
================================================================================
|
|
9. DISPLAY_RETAILER_LINKS() METHOD
|
|
================================================================================
|
|
|
|
Method: public static function display_retailer_links($book_id, $format = 'ebook')
|
|
|
|
Output HTML:
|
|
```html
|
|
<a href="[url]" class="retailer-box retailer-[key]" target="_blank" rel="noopener noreferrer">[name]</a>
|
|
```
|
|
|
|
Supported Retailers:
|
|
Key Name Base URL
|
|
---- ------------- ----------------------------------------------
|
|
amazon Amazon https://www.amazon.com/dp/
|
|
apple Apple Books https://books.apple.com/
|
|
barnes Barnes & Noble https://www.barnesandnoble.com/
|
|
kobo Kobo https://www.kobo.com/
|
|
google Google Play https://play.google.com/store/apps/details?id=
|
|
|
|
Amazon Auto-URL Generation:
|
|
If asin meta is set but no URL, constructs: https://www.amazon.com/dp/{asin}?tag={affiliate}
|
|
|
|
================================================================================
|
|
10. CSS CLASSES GENERATED BY PLUGIN
|
|
================================================================================
|
|
|
|
The following classes are output by the plugin and MUST be styled by the theme:
|
|
|
|
FRONTEND BOOK DISPLAY:
|
|
bd-book-listing Outer wrapper container
|
|
bd-book-entry Flex container with cover + details
|
|
bd-book-cover Left column (25% width)
|
|
bd-book-purchase Purchase section below cover
|
|
bd-book-format-selector Container for format toggle buttons
|
|
bd-book-format-btn Individual format button
|
|
bd-book-format-btn.active Active format state
|
|
bd-book-retailers Container for retailer-box links
|
|
bd-book-details Right column (75% width)
|
|
bd-book-title Title heading (h2)
|
|
bd-book-title a Title link
|
|
bd-book-byline "by [pen-name]" text
|
|
bd-book-ratings Ratings container
|
|
rating-amazon Amazon rating span
|
|
rating-goodreads Goodreads rating span
|
|
bd-book-separator HR element (divider)
|
|
bd-book-blurb Book description/synopsis
|
|
bd-book-metadata Genre, pages, language, publisher row
|
|
metadata-genre Genre span
|
|
metadata-pages Pages span
|
|
metadata-language Language span
|
|
metadata-publisher Publisher span
|
|
bd-book-categories Book categories
|
|
bd-book-error Error message paragraph
|
|
|
|
BOOKS LIST WRAPPER:
|
|
bd-books-list Container wrapping multiple book listings
|
|
|
|
RETAILER LINKS:
|
|
retailer-box Base class for all retailer links
|
|
retailer-amazon Amazon links
|
|
retailer-apple Apple Books links
|
|
retailer-barnes Barnes & Noble links
|
|
retailer-kobo Kobo links
|
|
retailer-google Google Play links
|
|
retailer-unavailable Disabled/unavailable retailer
|
|
|
|
================================================================================
|
|
11. STATIC HELPER METHODS
|
|
================================================================================
|
|
|
|
The following static methods are available for theme use:
|
|
|
|
get_featured_books($limit = 5) Get books ordered by publish_date
|
|
get_cover_url($book_id, $size = 'thumbnail', $lang = 'en') Get cover image URL
|
|
get_book_url($book_id) Get book URL (short link or permalink)
|
|
get_ratings($book_id) Get amazon/goodreads ratings array
|
|
get_retailer_links($book_id, $format = 'ebook') Get retailer purchase links array
|
|
get_localized_title($book_id, $lang = 'en') Get title for language
|
|
get_localized_blurb($book_id, $lang = 'en') Get blurb for language
|
|
get_preview_excerpt($book_id, $lang = 'en') Get preview excerpt
|
|
get_pull_quotes($book_id, $lang = 'en') Get up to 5 pull quotes
|
|
get_reviews($book_id) Get reviews from bd_reviews table
|
|
get_pen_name($book_id) Get author pen name
|
|
get_series_info($book_id) Get series data + volume
|
|
series_count() Count of active series
|
|
get_supported_languages() List supported language codes
|
|
get_awards() Get awards option
|
|
output_seo_tags($book_id) Output meta/OG tags
|
|
generate_schema($book_id) Generate schema.org data
|
|
|
|
================================================================================
|
|
12. MULTI-LANGUAGE SUPPORT
|
|
================================================================================
|
|
|
|
Supported Languages:
|
|
en English
|
|
fr Francais
|
|
de Deutsch
|
|
es Espanol
|
|
it Italiano
|
|
pt Portugues
|
|
ru Russkiy
|
|
ja Japanese
|
|
zh Chinese (Simplified)
|
|
|
|
Implementation:
|
|
- Each language gets its own meta fields (title_en, title_fr, blurb_en, etc.)
|
|
- get_localized_title/blurb methods default to English if requested language not found
|
|
- Data entry interface has language tabs with panels for each language
|
|
|
|
================================================================================
|
|
13. CRON JOBS
|
|
================================================================================
|
|
|
|
Hook: bd_bookshelf_goodreads_refresh
|
|
Schedule: Daily
|
|
Purpose: Refresh data from Goodreads API
|
|
|
|
Hook: bd_bookshelf_amazon_scrape
|
|
Schedule: Every 6 hours
|
|
Purpose: Scrape Amazon for ratings
|
|
|
|
================================================================================
|
|
14. THEME DEPENDENCIES
|
|
================================================================================
|
|
|
|
The plugin is designed to work with the BD BookShelf theme.
|
|
|
|
Integration points:
|
|
1. Nav Menu Filter: Hooks into bdm_nav_menu_items filter to inject Series menu
|
|
2. Book Display: render_book_display() outputs HTML with .bd-book-* classes
|
|
3. Cover Images: Uses theme's standard WordPress featured image system
|
|
4. Short Link Rewrite: Registers /[slug] pattern that works site-wide
|
|
|
|
================================================================================
|
|
15. ADMIN PAGES
|
|
================================================================================
|
|
|
|
Menu: BD BookHelper (main menu icon: dashicons-book-alt)
|
|
|
|
Dashboard bd-bookshelf-dashboard Overview and quick links
|
|
Books edit.php?post_type=book Book list
|
|
Book Data Entry bd-bookshelf-data-entry Enhanced book editor
|
|
Series edit-tags.php?taxonomy=series Series taxonomy management
|
|
Short Links bd-bookshelf-bulk-actions Short link management
|
|
Reviews bd-bookshelf-reviews Review management
|
|
Pen Names bd-bookshelf-pen-names Pen name CRUD
|
|
Settings bd-bookshelf-settings Affiliate codes, Goodreads ID
|
|
Migrate bd-bookshelf-migrate Migration from BD Books
|
|
|
|
================================================================================
|
|
16. REQUIRED THEME CSS (MINIMUM)
|
|
================================================================================
|
|
|
|
The theme MUST provide CSS for the following classes to render the Amazon Detail layout:
|
|
|
|
/* Book Listing Container */
|
|
.bd-book-listing { margin-bottom: 2rem; }
|
|
|
|
/* Entry Flex Container */
|
|
.bd-book-entry { display: flex; gap: 2rem; }
|
|
|
|
/* Cover Column (25%) */
|
|
.bd-book-cover { flex: 0 0 25%; max-width: 25%; }
|
|
.bd-book-cover img { width: 100%; height: auto; box-shadow: 0 4px 8px rgba(0,0,0,0.2); border-radius: 4px; }
|
|
|
|
/* Format Selector */
|
|
.bd-book-format-selector { display: flex; gap: 0.5rem; margin-bottom: 1rem; }
|
|
.bd-book-format-btn { padding: 0.5rem 1rem; border: 1px solid var(--bdm-navy); background: #fff; cursor: pointer; border-radius: 4px; }
|
|
.bd-book-format-btn.active { background: var(--bdm-navy); color: #fff; }
|
|
|
|
/* Retailer Links */
|
|
.bd-book-retailers { display: flex; flex-wrap: wrap; gap: 0.5rem; }
|
|
.retailer-box { display: inline-block; padding: 0.5rem 1rem; background: #FF9900; color: #000; text-decoration: none; border-radius: 4px; font-weight: bold; }
|
|
|
|
/* Details Column (75%) */
|
|
.bd-book-details { flex: 1; }
|
|
.bd-book-title { margin: 0 0 0.5rem 0; font-family: var(--bdm-heading-font); font-size: 1.5rem; }
|
|
.bd-book-byline { color: var(--bdm-mid-grey); margin: 0 0 1rem 0; }
|
|
.bd-book-ratings { margin-bottom: 1rem; }
|
|
.bd-book-separator { border: none; border-top: 1px solid #eee; margin: 1rem 0; }
|
|
.bd-book-blurb { margin-bottom: 1rem; line-height: 1.8; }
|
|
.bd-book-metadata { margin-bottom: 1rem; color: var(--bdm-mid-grey); }
|
|
.bd-book-categories { font-size: 0.85rem; color: var(--bdm-light-grey); }
|
|
|
|
/* Responsive */
|
|
@media (max-width: 768px) {
|
|
.bd-book-entry { flex-direction: column; }
|
|
.bd-book-cover { flex: 0 0 100%; max-width: 100%; }
|
|
}
|
|
|
|
================================================================================
|
|
17. ACTIVATION/DEACTIVATION
|
|
================================================================================
|
|
|
|
Activation creates:
|
|
- All database tables via dbDelta()
|
|
- 'book_manager' role with limited capabilities
|
|
- Default pen name "B.D. Murphy"
|
|
- Scheduled cron events
|
|
- Flushes rewrite rules
|
|
|
|
Deactivation removes:
|
|
- 'book_manager' role
|
|
- Scheduled cron events
|
|
- Flushes rewrite rules
|
|
|
|
================================================================================ |