# BookHelper Menu Structure Specification

## Overview
This specification defines the menu structure for the BD BookHelper plugin in the WordPress admin dashboard. The menu provides access to all book management functionality through a clean, organized interface.

## Menu Structure

### Main Menu Item
- **Title**: BD BookHelper
- **Slug**: bd-bookshelf-dashboard (main page), bd-bookshelf (internal)
- **Icon**: dashicons-book-alt
- **Position**: 30
- **Capability**: edit_posts
- **URL**: /wp-admin/admin.php?page=bd-bookshelf-dashboard

### Submenu Items

#### 1. Dashboard
- **Title**: Dashboard
- **Slug**: bd-bookshelf-dashboard
- **URL**: /wp-admin/admin.php?page=bd-bookshelf-dashboard
- **Callback**: dashboard_page()
- **Purpose**: Overview of book statistics and quick access links
- **Features**:
  - Display count of published and draft books
  - Quick links to all major sections
  - Summary of plugin capabilities

#### 2. Books
- **Title**: Books
- **Slug**: edit.php?post_type=book
- **URL**: /wp-admin/edit.php?post_type=book
- **Type**: Standard WordPress post type listing
- **Purpose**: Listing and management of all books in the system
- **Features**:
  - Display all books with title, author, date, and status columns
  - Bulk actions (edit, delete, view)
  - Search and filter capabilities
  - **Add New Book** button at top and bottom
  - Each book row shows:
    - Title (linked to book detail page)
    - Author/Pen Name
    - Publication Date
    - Status (Published/Draft/Pending)
    - Action links: Edit (Book Helper), View (Book Detail), Trash
  - Bottom action bar with Add New Book button

#### 3. Pen Names
- **Title**: Pen Names
- **Slug**: bd-bookshelf-pen-names
- **URL**: /wp-admin/admin.php?page=bd-bookshelf-pen-names
- **Callback**: pen_names_page()
- **Purpose**: Setup and management of author pen names
- **Features**:
  - List of all pen names with associated books count
  - Add new pen name form:
    - Pen Name (text field)
    - Description/Notes (textarea)
    - Active status (checkbox)
  - Edit/delete existing pen names
  - Explanation: "While John is the author's legal name he may use Ben, Burt, or B.D. Murphy for particular books. Pen names are selectable in the book edit page."

#### 4. Series
- **Title**: Series
- **Slug**: edit-tags.php?taxonomy=series&post_type=book
- **URL**: /wp-admin/edit-tags.php?taxonomy=series&post_type=book
- **Type**: Standard WordPress taxonomy management
- **Purpose**: Create and manage book series
- **Features**:
  - List of all series with name, description, and book count
  - Add new series form:
    - Name (text field)
    - Slug (auto-generated)
    - Description (textarea)
  - Edit series name, slug, and description
  - Ability to assign books to series during book creation/editing
  - Explanation: "Books can be part of a series. Create and manage series for the author. Select books from the book list to add to the series, specifying the number in the series."

#### 5. Short Links
- **Title**: Short Links
- **Slug**: bd-bookshelf-bulk-actions
- **URL**: /wp-admin/admin.php?page=bd-bookshelf-bulk-actions
- **Callback**: bulk_actions_page()
- **Purpose**: Generate and manage short links for books
- **Features**:
  - **Generate Missing Short Links** section:
    - Description: "Generate missing short link slugs for all books."
    - Button: Generate Missing Short Links (primary)
    - Result message showing generated vs. skipped counts
  - **Clear Transient Caches** section:
    - Description: "Clear all transient caches used by the plugin."
    - Button: Clear All Transient Caches (primary)
    - Result message showing number of caches cleared
  - Explanation follows Short_Links_specification.txt for manual shortlink creation

#### 6. Settings
- **Title**: Settings
- **Slug**: bd-bookshelf-settings
- **URL**: /wp-admin/admin.php?page=bd-bookshelf-settings
- **Callback**: settings_page()
- **Purpose**: General settings for the plugin
- **Features**:
  - **Goodreads Integration**:
    - Goodreads Author ID (text field, default: 30469651)
    - Description: "Default: 30469651 (B.D. Murphy)"
  - **Amazon Ratings Warning**:
    - Warning message about Amazon Terms of Service
    - Color: #d63638 (red)
  - **Amazon Author ID**:
    - Amazon Author ID (text field)
    - Description: "Your Amazon author central ID"
  - Save Settings button

#### 7. Migrate
- **Title**: Migrate
- **Slug**: bd-bookshelf-migrate
- **URL**: /wp-admin/admin.php?page=bd-bookshelf-migrate
- **Callback**: migrate_page()
- **Purpose**: Migrate from legacy BD Books plugin and scan for book data
- **Features**:
  - **Migration from BD Books**:
    - Detection of old BD Books table
    - Count of books in old table vs. new system
    - List of books to migrate (title, author, cover availability)
    - Explanation of what gets migrated:
      - Book titles and authors (as pen names)
      - Descriptions become blurbs in English
      - Cover images (WordPress media or external URLs)
      - Purchase links to retailer fields
    - Run Migration button with confirmation
  - **Website Scan** (future enhancement):
    - Scan website for book detail pages
    - Extract book information to complete metadata
    - Check other websites for missing information
  - Status messages for success/error conditions

## Menu Access Logic
- Main menu item (BD BookHelper) opens the Dashboard page by default
- All submenu items are accessible from the main menu dropdown
- Current menu item is highlighted in the admin interface
- Menu respects WordPress capability system (edit_posts required)
- Menu position is set to 30 to appear near the middle of the admin menu

## Implementation Notes
1. The Books submenu uses the standard WordPress post type listing for consistency
2. The Series submenu uses standard WordPress taxonomy management
3. Custom pages (Dashboard, Pen Names, Settings, Bulk Actions, Migrate) use custom callbacks
4. All non-standard pages follow WordPress admin UI patterns:
   - Wrap in `<div class="wrap">`
   - Use `<h1>` for page title
   - Organize content in `<div class="bd-section">` containers
   - Use WordPress button classes for actions
   - Implement proper nonce verification for form submissions
   - Provide descriptive feedback messages
5. The Edit link on the Books list page has been modified to point to the Book Data Entry page instead of the standard WordPress editor
6. The Add Book submenu has been removed as requested - the Add New Book button on the Books list page serves this purpose

## Related Specifications
- Sidebar Widget Specification: sidebar-widget-spec.md
- Book Helper Edit Page Specification: book-helper-edit-page-spec.md
- Short Links Specification: Short_Links_specification.txt
- Book Data Specification: bd-books-spec.md

[End of Specification]