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.
196 lines
6.3 KiB
Markdown
196 lines
6.3 KiB
Markdown
# 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
|
|
|
|
```html
|
|
<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 |