Feature Idea: Theme Management

[adrighem]

Tracked from the original suggestion in #30.

This issue is for discussing and designing support for theme management (themes) in PyPluginStore.

Adding themes would be a significant scope expansion beyond Python plugins, so we need to carefully define:

• How themes are packaged and structured.
• Discovery, installation, and update workflows.
• Integration with the current UI.

Please share use cases, requirements, or design proposals here.

[adrighem]

Architectural Design & Implementation Plan: Parallel Theme Store

To seamlessly add Theme Store Support to PyPluginStore while keeping the codebase cohesive, robust, and clean, we will implement theme management as a direct parallel to our plugin management system.

Since Domoticz themes consist purely of static styles (style.css, custom.css) and images residing in the web directory, they do not require Python dependencies, environment checking, or Domoticz service restarts. They can be hot-cloned/updated instantly!

Here is the technical specification and handoff plan for implementing this feature:

---

1. Data Layer & Metadata (themes.json & themes_local.json)

We will establish a dedicated theme registry modeled directly on our registry.json pattern.

• File Location: themes.json in the root folder (plus support for loading custom/private themes from themes_local.json).
• Registry Schema: Keys represent the lowercase unique theme folders under www/styles/ (e.g., aurora-theme). Values follow the same standard dict format:

  {
    "aurora-theme": {
      "author": "MadPatrick",
      "repository": "domoticz-aurora-theme",
      "description": "A gorgeous modern dark theme inspired by the aurora borealis.",
      "branch": "main",
      "updated_at": "2026-07-04T12:00:00Z"
    }
  }

---

2. Backend Engine Extensions (plugin_core.py)

Developer changes will be written to plugin_core.py and then compiled to plugin.py.

A. Path Resolution (HostRuntime)

Extend the path detection framework to locate the Domoticz style directories:

def themes_dir(self):
    # Resolves to <Domoticz_Root>/www/styles
    return os.path.join(self.domoticz_dir(), "www", "styles")

B. Theme Service & Discovery

Create a lightweight ThemesService or extend the existing RegistryService and UpdateStatusService to scan for themes:

• Scanning: Scan <Domoticz_Root>/www/styles/ for subdirectories. A directory represents an installed theme if it matches a theme registry key, has .git config records pointing to a registry repository, or contains a style.css file.
• Update Verification: Check if local theme directories are Git repositories. Query current commits and fetch remote HEADs using the existing GitInstallUpdateStrategy helper methods (like checking ahead/behind counts) to display update indicators.

C. API Command Router

Extend handleApiCommand with matching actions to support themes through the virtual IPC device bridge:

• list_themes: Scans the style directory, cross-references themes.json, checks update/git states, and writes JSON response back into PPM_API_PAYLOAD.
• install_theme: Clone the Git repository directly into the destination:

  Destination: <Domoticz_Root>/www/styles/<theme_name>
  

• update_theme: Execute a hard-reset pull (git fetch && git reset --hard origin/<branch>) inside the theme's folder.
• remove_theme: Delete the folder from disk using shutil.rmtree() (excluding the built-in default styles folder!).

---

3. Frontend UI Upgrades (pypluginstore.html)

The frontend is built on a modular single-page structure. We will implement tabs, reusing existing inputs and sorting controllers.

A. Tabbed Navigation Bar

We will add a beautiful, responsive tab selection bar at the top of the container (directly below the header, above filters):

<div class="tabs-navigation">
    <button class="tab-button active" id="tab-plugins" data-tab="plugins" type="button">Plugins</button>
    <button class="tab-button" id="tab-themes" data-tab="themes" type="button">Themes</button>
</div>

• CSS Styling: Style the tab bar with subtle borders, active indicator animations, and color schemes matching our existing dark theme (var(--primary), var(--border-color)).

B. Unified Filtering & Search

Re-use the same search box, sorting options, and "Show Installed Only" toggle to filter both datasets dynamically. Clicking a tab updates the state:

let activeTab = 'plugins'; // 'plugins' or 'themes'

• When activeTab === 'themes', search operations will filter themeCache and call a corresponding rendering function.

C. Card Layout and Action Handling

Design a parallel renderThemes template or make renderPlugins polymorphic:

• UI Elements: Theme cards will show Display Name, Author, Repository, Description, and Update Status (e.g., "Installed", "Up to Date", "Update Available").
• Optimized UX Note: Action buttons (Install/Update/Remove) will immediately execute, and the success callback will simply show a success notification (e.g., "Theme successfully updated. Please refresh your browser page to apply.") instead of warning the user about Domoticz restarts (since themes are purely client-side css).

---

4. Implementation Phase Order (For Handoff)

1. Step 1: Add themes_dir to HostRuntime in plugin_core.py.
2. Step 2: Scaffold themes.json with a few popular Domoticz themes as seed data.
3. Step 3: Implement list_themes, install_theme, update_theme, and remove_theme API command handlers in plugin_core.py.
4. Step 4: Integrate CSS tabs and state transition handlers in pypluginstore.html.
5. Step 5: Build out Javascript cache-management and card rendering functions to list, install, and update themes.
6. Step 6: Run generate_plugin.py to compile plugin_core.py into plugin.py and run verification tests.