3. Usage

Usage

Key Capabilities

• Unified browser for both plugins and user patches with persistent filters and paging.
• Offline-friendly cache stored under data/cache/Storefront so existing results remain accessible when you lose connectivity.
• Per-entry README viewer that fetches README.md directly from GitHub and displays it in the plugin.
• Install/update pipeline that handles .koplugin archives, verifies metadata, and copies files to data/plugins or data/patches accordingly.
• Update tracking for installed plugins and numbered patch files, complete with SHA comparisons and refreshable summaries.
• Optional authentication through a GitHub Personal Access Token (PAT) to increase API rate limits.

Navigating the Four Storefront Sections

The UI is built around four dedicated dialogs:

1. Plugins Browser (Storefront · Plugins)

   • Lists repositories tagged as KOReader plugins.
   • Actions per entry: Install / Update / Remove, View README, open detail dialogs with description, stars, last updated timestamp, and repo owner.
   • Toolbar actions: switch to patches tab, refresh cache, adjust filters (search text, owner, minimum stars), change sorting (stars desc/asc, updated, name), and jump into the installed plugins page.
   • Gear icon (⚙️): Access settings including Install plugin from URL to manually install plugins by entering GitHub owner/repo.

2. Patches Browser (Storefront · Patches)

   • Lists repositories tagged as KOReader user patches and enumerates files matching ^[number]-*.lua.
   • Actions per patch: Install patch, retry downloads, or open the repo README for full instructions.
   • Toolbar actions: mirror the plugin tab plus shortcuts to the installed patches page and a "matching patch" banner when reconciling installed files with remote entries.
   • Gear icon (⚙️): Access settings including Install patch from URL to manually install patches by entering GitHub owner/repo.

3. Installed Plugins (Check plugin updates)

   • Summarizes every installed plugin, both linked (matched with a repository) and unlinked.
   • Actions: Check all updates, toggle between "Only outdated" and "Show all plugins," and jump straight back to the Plugins browser.
   • Each row shows the local version, cached remote version/SHA (for linked plugins), last checked timestamp, and provides Update or Reinstall buttons when differences are detected.
   • Per-plugin actions: Disable/Enable, Delete, Match from List or Match with URL (for unlinked plugins), Unlink the repo (for linked plugins).

4. Installed Patches (Check patch updates)

   • Works just like the installed plugins page but focuses on numbered patch files under data/patches.
   • Actions: Check all updates, toggle between "Only outdated" and "Show all patches," and jump straight back to the Patches browser.
   • Each row shows the patch filename, cached remote version/SHA (for linked patches), last checked timestamp, and provides Update or Reinstall buttons when differences are detected.
   • Per-patch actions: Disable/Enable (renames with .disabled suffix), Delete, Match from List or Match with URL (for unlinked patches), Unlink the repo (for linked patches).

Typical Workflow

1. Open KOReader → Tools → Storefront.
2. Pick Plugins or Patches tab. Use the filter dialog to narrow by owner, name, topics, or star threshold.
3. Tap an entry for a quick action menu. Choosing Install downloads the repo ZIP (/zipball/<ref>), extracts it to a temp folder, validates _meta.lua, then copies it to data/plugins/<name>.koplugin.
4. After installation, KOReader prompts for a restart so the new plugin becomes available in the Tools menu.
5. For patches, selecting an item downloads the raw .lua file from the default branch and stores it under data/patches/ while retaining the numbered filename used for KOReader’s patch loader.
6. Return anytime to the Updates dialogs to check for newer commits. The plugin compares cached SHAs with the installed files and highlights items needing attention.
7. Use View README to fetch the upstream documentation and open it in KOReader’s file viewer. Files are cached under data/cache/storefront/readme/owner_repo_README.md for offline rereads.

Cache & Offline Behavior

• Repository metadata is stored in SQLite under data/cache/storefront.db (automatically created).
• The browser always reads from the cache first, keeping scrolling smooth even when the network is slow.
• When cached data is older than 7 days, the banner reminds you to trigger Refresh cache.
• README files, download archives, and installed SHAs are cached so subsequent operations reuse existing data whenever possible.

Non-touch devices (Kindle 4 NT, Kindle Keyboard, …)

The Storefront plugin is fully usable on devices without a touchscreen. The browser and updates dialogs follow KOReader's standard non-touch conventions:

• Up / Down — move focus between list rows; the list scrolls automatically when the focused row would otherwise be off-screen.
• Left / Right — move focus across the title-bar buttons (gear / close) and the pagination row (Previous / Next), or between the top control buttons in the Updates dialog.
• Press (centre key on the 5-way) — activate the focused entry, equivalent to a tap.
• Hold / Long-press (where supported) — open the secondary action of the focused entry, equivalent to a tap-and-hold.
• Page-forward / Page-back keys — flip to the next / previous page in the browser.
• Back — close the dialog. On few-keys devices that do not provide a Back key (e.g. Kindle 4 NT), Left acts as the close shortcut, mirroring KOReader's built-in Menu widget.