Magic Shelves

Magic Shelves ✨

Magic Shelves are dynamic, rule-based collections that automatically populate with books matching specific criteria. Unlike standard shelves where you manually add or remove books, Magic Shelves update themselves instantly as your library changes.

Overview

A Magic Shelf is defined by a set of Rules (e.g., "Rating > 4 AND Tag is 'Sci-Fi'"). Any book in your library that matches these rules will automatically appear in the shelf.

Key Features:

• Dynamic Population: No manual management required.
• Complex Logic: Support for AND / OR groups and nested conditions.
• Custom Columns: Full support for filtering by Calibre custom columns.
• Kobo Sync: Sync your dynamic shelves directly to your Kobo eReader.
• High Performance: Intelligent caching ensures your library stays fast.

---

Creating & Editing Shelves

To create a Magic Shelf:

1. Click "Create Magic Shelf" in the sidebar (under the "Magic Shelves ✨" section).
2. Name: Give your shelf a descriptive name.
3. Icon: Choose an emoji icon to represent the shelf in the sidebar.
4. Kobo Sync: Toggle this on if you want this shelf to appear on your synced Kobo device.

The Rule Builder

The heart of a Magic Shelf is the Rule Builder. You can combine multiple conditions to create precise filters.

• Fields: Filter by Title, Author, Series, Tags, Rating, Publisher, Language, Publication Date, Date Added, Read Status, and Custom Columns.
• Operators: Use comparisons like equals, contains, starts with, greater than, is empty, etc.
• Groups: Create groups of rules with AND (all must match) or OR (any can match) logic.

Example Recipes:

• "Top Rated Sci-Fi": Tag contains 'Science Fiction' AND Rating >= 4
• "Unread Stephen King": Author contains 'Stephen King' AND Read Status is 'Unread'
• "Long Books": Custom Column #pages > 500

---

Features in Detail

🪄 Custom Columns Support

Magic Shelves fully integrate with your Calibre library's custom columns. Whether you track "Word Count", "Fanfic Tags", or "Audiobook Duration", these fields will automatically appear in the Rule Builder dropdown.

🔄 Kobo Integration

When Kobo Sync is enabled for a Magic Shelf:

• The shelf appears as a Collection on your Kobo eReader.
• Books matching the rules are automatically synced to the device (if they aren't already there).
• Note: Since Magic Shelves are read-only on the device, removing a book from the collection on the Kobo will not remove it from the Magic Shelf (as it still matches the rules).

⚡ Performance & Caching

To ensure your library remains snappy, Magic Shelves use a two-layer caching system:

1. Sidebar Counts: The book counts shown in the sidebar are cached for 5 minutes.
2. Shelf Contents: The list of books in a shelf is cached for 30 minutes.
   • Refresh: You can force a cache update by clicking the "Refresh" button on the shelf page.
   • Auto-Invalidation: Editing a shelf's rules immediately clears its cache.

---

Stats Tracking 📊

Magic Shelf activity is tracked in the CWA Stats dashboard (User Activity tab).

• Views Tracking: Since you don't "add" books to a Magic Shelf, CWA tracks Views instead.
• Identification: In the activity list, Magic Shelves are marked with a wand icon (🪄).
• Metrics:
  • Regular Shelves: Track Adds (▲) and Removes (▼).
  • Magic Shelves: Track Views (👁️).

---

Troubleshooting

• "Shelf is empty": Check your rules. Ensure you aren't using mutually exclusive conditions (e.g., "Rating > 5" which is impossible). Use the Refresh button to ensure you aren't seeing cached data.
• Kobo Sync: If a shelf isn't appearing, ensure "Kobo Sync" is checked in the shelf settings and that you have synced your device recently.