umbragit/Bookshelf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
38cdebd0c6c18c6c5e594545244523cd9811c4fb
Bookshelf/bd-bookshelf-plugin-questions-0.0.1.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

6.6 KiB
Raw Blame History

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.