dec732931c
Merge BD Bookshelf (0.1.0), BD BookShelfHelper (2.0.0) and BD SimpleEmail
(2.0.0) into a single plugin released as Umbra Bookshelf 1.0.0, with the
BD Bookshelf theme left as a separate, unrenamed artifact.
Modules
includes/books/ catalogue, ISBN/ASIN, series, retail, ratings, shortcodes,
SEO, GDPR, scrapers, admin, CSV/post import
includes/library/ book post type + series taxonomy, pen names, data entry,
shortlinks, reviews, migrate
includes/email/ subscribers, newsletters, composition, sending
Renamed: plugin headers, text domains (all three -> umbra-bookshelf), classes
(BD_*/BDM_* -> Umbra_*), constants (-> UMBRA_BOOKSHELF_*), asset handles, JS
globals and admin slugs.
Deliberately not renamed -- persisted contract with live installs and with
published post content: table names, option keys, post meta keys, transients,
nonce actions, cron hooks, AJAX actions, shortcodes ([bd-book], [bd-books],
[bdm_signup]), post type `book`, taxonomy `series`, cookies and CSS classes.
BD_BookShelfHelper survives only as a class_alias for the unmodified theme.
Collisions resolved
* class-umbra-theme-compatibility.php declared BD_BookShelfHelper, the same
name as the library module's helper. Latent while the plugins were
separate (only fired when both were active), but an unconditional fatal
once merged. Renamed to Umbra_Theme_Compatibility with a class_alias.
* All three modules called add_menu_page. One top-level menu is now
registered by the bootstrap at admin_menu priority 9.
* BD Bookshelf and BookShelfHelper both claimed bd-bookshelf-settings, leaving
one Settings screen unreachable -> umbra-bookshelf-settings and
umbra-bookshelf-library-settings.
* Catalogue and library both enqueued bd-bookshelf-admin; the second enqueue
was silently discarded -> unique handles per module.
* Umbra_Admin and Umbra_Migration both registered bd_bookshelf_import_csv, so
one handler silently replaced the other. The import page now lives only in
Umbra_Admin (the variant wired to the admin JS); Umbra_Migration keeps only
the preview/run endpoints it uniquely provides.
* Modules were constructed from an init callback, so their own init
registrations raced the hook being dispatched. Now constructed on
plugins_loaded behind a re-entrancy guard.
Also
* Missing assets created: assets/images/default-cover.png (referenced but
never committed, so every cover-less book 404'd) and email/assets/js/
admin.js (enqueued on every email admin page but never committed).
* Library module's strpos($hook, 'bd-bookshelf') asset check matched every
catalogue and email screen once slugs shared the umbra-bookshelf- prefix;
now matched against its own slug list.
* Consolidated uninstall deduplicates the double drop of bd_books/bd_series.
* Specs aligned to the new name; pre-merge specs retained under
spec/archive/ with provenance notes.
* Tests added: tests/verify_structure.py (static) and tests/smoke_runtime.php
(WordPress-stub runtime boot, front-end and admin contexts).
Deferred and recorded in docs/KNOWN-ISSUES.md: the catalogue and library
modules still create bd_books and bd_series with two incompatible schemas
(pre-existing, now unconditional), and Goodreads/Amazon scraping is still
implemented twice on shared cron hooks.
6.6 KiB
BD Bookshelf Plugin - Questions for Review
Please review these questions and provide answers. Each answer will be incorporated into the final specification.
1. Data Architecture
Q1.1: Should books be stored as a Custom Post Type (CPT) (leveraging WordPress's native metadata, SEO plugins, and editor) or as Custom Database Tables (better performance for large catalogs but requires more custom UI)?
A: Use a custom database table - it will be leveraged later with another plugin
Q1.2: How should the plugin connect to the Author ID from the theme? Options:
- (a) Auto-detect from the current logged-in user
- (b) Manual selection per book from a user dropdown
- (c) Inherited from a global plugin setting
A: If the plugin can't read the author ID, goodread id from the theme configuration data it should have a setting menu item to enter "Author IDs"
2. ISBN & Link Generation
Q2.1: Do we have a documented list of the exact URL patterns for each retail site (Amazon, B&N, Apple, Google, Kobo), or should the plugin attempt to "discover" them via API?
A: This will be a seperate search and analysis. The pattern will be provided in a specification update.
Q2.2: For Amazon, should we use the Product Advertising API (requires API keys) or scrape the product page for ratings?
A: Scrape the product page. This does not require the author to have an account for advertising.
Q2.3: Should custom retail sites (the "book and quill" icon sites) support affiliate codes, or only the predefined sites?
A: affiliate codes only for the predefined sites.
3. Rating Synchronization
Q3.1: For Amazon ratings, should the plugin:
- (a) Scrape the product page (no API key needed, but fragile)
- (b) Use the Product Advertising API (requires Amazon affiliate account and API keys)
- (c) Use a third-party service
A: a robust scraping of the website
Q3.2: For Goodreads ratings, should the plugin:
- (a) Scrape the Goodreads page (no API key, but fragile and potentially rate-limited)
- (b) Use the Goodreads API (deprecated, no longer available to new apps)
- (c) Use a third-party service
a: a robust scraping of the website.
Q3.3: What should happen if a rating fetch fails? Options:
- (a) Keep the last known rating indefinitely
- (b) Clear the rating after X failed attempts
- (c) Mark as "unavailable" and stop retrying
A: If the fetch fails keep the last rating received. If there is no previously saved rating show zero.
4. Shortcode Behavior
Q4.1: For the [rating] shortcode, how should it know which book to display if not on a specific book page? Options:
- (a) Require an ID parameter:
[rating id="123"] - (b) Use a title parameter:
[rating title="Pandemic Hacker"] - (c) Only work on book CPT pages (context-aware)
A: a) require the title. The user doesn't need to look up or remember codes
Q4.2: For the [sell_*] shortcodes, should they:
- (a) Only work on book CPT pages (auto-detect the book)
- (b) Require an ID parameter:
[sell_ebook id="123"] - (c) Support both options
A: The destination for a short code can be any website. Even another website. Local site isn't required.
Q4.3: For custom shortcodes, what constitutes an "expansion"? Options:
- (a) Simple 301/302/307 redirect
- (b) Render the target URL as a clickable link
- (c) Fetch and display the remote content (proxy)
A: redirects - including permanent
5. SEO Metadata
Q5.1: Should the SEO module:
- (a) Only manage on-page meta tags (title, description, keywords)
- (b) Also generate structured data (JSON-LD for books)
- (c) Integrate with existing SEO plugins (Yoast, RankMath) via their API
A: The preference is to integrate with other plugins. The minimum is to provide meta data tags. The stretch goal is to have links to other refernences (facebook, etc) to enhance search engine results.
Q5.2: Should the plugin generate a sitemap entry for each book, or rely on existing SEO plugins?
A: don't rely on other plugins.
6. GDPR Compliance
Q6.1: Should the plugin provide default privacy policy text, or just the popup mechanism? A: Provide an example, common from the internet text.
Q6.2: What data does the plugin collect that requires GDPR consent? Options:
- (a) Cookie for affiliate tracking
- (b) Click tracking for shortcodes
- (c) Both
A: a)
Q6.3: Should the consent popup be:
- (a) A simple banner at the bottom of the page
- (b) A modal popup that blocks interaction until accepted
- (c) Configurable by the admin
A: a)
7. Affiliate Codes
Q7.1: Should affiliate codes be:
- (a) Global (same code for all books on a site)
- (b) Per-site (different codes for Amazon vs B&N)
- (c) Per-book (different codes for different books on the same site)
A: Each site could have a different affiliate code - even if they are the same, each site should have an affiliate code entry.
Q7.2: What query parameter name does each site use for affiliate codes? Examples:
- Amazon:
?tag= - B&N:
?ean= - Others: ? A: This will be researched and provided later
8. Custom Shortcode Manager
Q8.1: For the shortcode manager, what is the primary use case? Options:
- (a) URL shortening for marketing (e.g.,
site.com/go/my-promo) - (b) Affiliate link cloaking
- (c) Both
A: a) Book sites do NOT allow links in a book to a competitor. Having a link for a review needs to be to the author site, with a short code that links to the seller review page.
Q8.2: Should custom shortcodes track:
- (a) Total click count only
- (b) Click count with timestamp (analytics)
- (c) Click count with IP/user agent (detailed analytics)
A: c)
9. Display & Theming
Q9.1: For the retail grid display, should the plugin:
- (a) Use its own CSS (bundled with the plugin)
- (b) Inherit styles from the bd-bookshelf theme
- (c) Provide both (own CSS + theme integration)
A: a) use its own CSS to make the appearance optimized
Q9.2: For the rating display, should it show:
- (a) Star icons (★☆)
- (b) Numeric rating (4.5/5)
- (c) Both (configurable)
A: c) both
10. Future Considerations
Q10.1: Is there a planned integration with book distributor APIs (Ingram, Baker & Taylor) for automatic metadata population?
A: more interation will be with another plugin - this is the basic plugin to help authors.
Q10.2: Should the plugin support multiple authors per book?
A: Yes support up to three authors per book
Q10.3: Is there a need for book series management (grouping books into series with ordering)?
A: Book series management is required. The system will allos defining a series - by name. Books will be assigned to a series by the user.