Umbra-Bookshelf/docs/sidebar-widget-spec.md

Book Detail Sidebar Widget Specification

Overview

The Book Detail Sidebar Widget displays an author's published books from the local WordPress database, sorted by publication date (newest first), with links to the book's detail page on the website and retailer purchase links.

---

1. Widget Configuration

Theme Settings

The following settings are configured in Appearance > Customize > Theme Settings:

Setting	Key	Description	Default
Author/Pen Name	author_name	The author name to display in widget title	"B.D. Murphy"
Goodreads Author ID	goodreads_author_id	Goodreads author ID (for reference)	"30469651"

---

2. Widget Title

• Format: GoodReads for {author_name}
• Example: GoodReads for B.D. Murphy
• The {author_name} is pulled from theme settings (author_name mod)

---

3. Data Source

Local WordPress Data

• Fetch books from local WordPress book post type
• Books are sorted by publish_date meta field (newest first)
• Fall back to WordPress post date if publish_date is not set
• No external API calls required

---

4. Book Display Format

Each book in the widget displays:

4.1 Cover Image

• Size: 42x60px thumbnail (matching Goodreads standard)
• Source: WordPress featured image or _thumbnail_id meta field
• Display: Small icon to the left of the title
• Fallback: Try medium size, then full size if smaller sizes unavailable

4.2 Book Title

• Text: Book title from WordPress post title
• Link: Links to the book's detail page on this website
• URL Structure: /book/{book-slug}/ (uses short_link_slug meta, or falls back to WordPress permalink)
• Styling: Bold (600), navy color (var(--bdm-navy)), hover effect (var(--bdm-gold))

4.3 Ratings Display

Located below the title:

• Amazon Rating: Amazon: X.X/5 (orange color #ff9900)
• Two spaces between "Amazon:" and "Goodreads:" (i.e., Amazon: 4.5/5 Goodreads: 4.2/5)
• Goodreads Rating: Goodreads: X.X/5 (yellow color #d1d179)
• Data source: amazon_rating and goodreads_rating meta fields
• Only display if ratings are available

4.4 Retailer Links (eBook Only)

Located below the ratings:

• Display: Text-based retailer names inside outline boxes (buttons)
• Always show all 5 retailers regardless of whether URLs are configured
• Retailers: Amazon, Apple Books, Barnes & Noble, Kobo, Google Play
• Gap: 8px between each retailer box
• Behavior:
  • Show retailer name as clickable link if URL is configured in book metadata (ebook_url_amazon, etc.)
  • Show retailer name as grayed-out text (unavailable) if no URL configured
• Order: Amazon, Apple Books, Barnes & Noble, Kobo, Google Play
• Styling: Navy border/outline, navy text, navy background on hover with white text

---

5. Widget HTML Structure

<div class="goodreads-books-widget">
    <h3 class="widget-title">GoodReads for {Author Name}</h3>
    
    <div class="goodreads-books-list">
        <!-- Book Item -->
        <div class="goodreads-book-item">
            <a href="/book/{book-slug}/" class="goodreads-book-cover">
                <img src="{cover-url}" alt="{book-title}" width="42" height="60">
            </a>
            <div class="goodreads-book-details">
                <a href="/book/{book-slug}/" class="goodreads-book-title">{book-title}</a>
                
                <div class="goodreads-book-ratings">
                    <span class="rating amazon">Amazon: {rating}/5</span>
                    <span class="rating goodreads">  Goodreads: {rating}/5</span>
                </div>
                
                <div class="goodreads-book-retailers">
                    <a href="{amazon-url}" class="retailer-box">Amazon</a>
                    <a href="{apple-url}" class="retailer-box">Apple Books</a>
                    <a href="{barnes-url}" class="retailer-box">Barnes & Noble</a>
                    <a href="{kobo-url}" class="retailer-box">Kobo</a>
                    <a href="{google-url}" class="retailer-box">Google Play</a>
                    <!-- Unavailable retailers show as: -->
                    <span class="retailer-box retailer-unavailable">Kobo</span>
                </div>
            </div>
        </div>
        <!-- Repeat for each book -->
    </div>
</div>

---

6. CSS Styling

Widget Container

• Background: white
• Padding: 15px
• Border radius: 8px
• Box shadow: subtle

Book Item

• Display: flex
• Gap: 12px
• Border bottom: 1px solid #eee (except last item)
• Padding: 12px 0
• Align items: flex-start

Book Cover

• Width: 42px
• Height: 60px
• Object fit: cover
• Border radius: 3px
• Flex shrink: 0

Book Details

• Flex: 1
• Min width: 0

Book Title

• Font weight: 600
• Color: var(--bdm-navy)
• Hover: var(--bdm-gold)
• Font size: 0.9rem
• Line height: 1.3
• Margin bottom: 4px

Ratings

• Font size: 0.75rem
• Margin bottom: 6px
• Amazon color: #ff9900
• Goodreads color: #d1d179
• Display: inline-block
• Margin right: 10px

Retailer Links (Outline Boxes)

• Display: flex
• Flex wrap: wrap
• Gap: 8px
• Margin top: 6px
• Font size: 0.7rem
• Padding: 3px 8px
• Border: 1px solid var(--bdm-navy)
• Border radius: 4px
• Color: var(--bdm-navy)
• Hover: background var(--bdm-navy), color white
• Unavailable: color #999, border-color #999, cursor default

---

7. Meta Field References

Book Post Meta Fields Used

Field	Description
publish_date	Publication date (YYYY-MM-DD) for sorting
short_link_slug	Custom slug for book detail URL
cover_image	Custom cover image URL (fallback)
_thumbnail_id	WordPress featured image ID
amazon_rating	Amazon rating (e.g., "4.5")
goodreads_rating	Goodreads rating (e.g., "4.2")
ebook_url_amazon	Amazon eBook link
ebook_url_apple	Apple Books link
ebook_url_barnes	Barnes & Noble link
ebook_url_kobo	Kobo link
ebook_url_google	Google Play link

---

8. Fallback Behavior

• Cover image: Try cover_image meta → _thumbnail_id → medium size → full size
• Book URL: Use short_link_slug meta → WordPress permalink
• Sorting: Use publish_date meta → WordPress post date
• Retailers: Always show all 5, gray out unavailable ones