LEDMatrix/docs/archive/PLUGIN_CONFIG_TABS_SUMMARY.md

Plugin Configuration Tabs - Implementation Summary

What Was Changed

Backend (web_interface_v2.py)

Modified /api/plugins/installed endpoint:

• Now loads each plugin's config_schema.json if it exists
• Returns config_schema_data along with plugin information
• Enables frontend to generate configuration forms dynamically

# Added schema loading logic
schema_file = info.get('config_schema')
if schema_file:
    schema_path = Path('plugins') / plugin_id / schema_file
    if schema_path.exists():
        with open(schema_path, 'r', encoding='utf-8') as f:
            info['config_schema_data'] = json.load(f)

Frontend (templates/index_v2.html)

New Functions:

1. generatePluginTabs(plugins) - Creates dynamic tabs for each installed plugin
2. generatePluginConfigForm(plugin) - Generates HTML form from JSON Schema
3. savePluginConfiguration(pluginId) - Saves configuration with type conversion
4. resetPluginConfig(pluginId) - Resets settings to schema defaults

Modified Functions:

1. refreshPlugins() - Now calls generatePluginTabs() to create dynamic tabs
2. configurePlugin(pluginId) - Navigates to plugin's configuration tab

Initialization:

• Plugins are now loaded on page load to generate tabs immediately
• Dynamic tabs use the .plugin-tab-btn and .plugin-tab-content classes for easy cleanup

How It Works

Tab Generation Flow

1. Page loads → DOMContentLoaded
2. refreshPlugins() called
3. Fetches /api/plugins/installed with config_schema_data
4. generatePluginTabs() creates:
   - Tab button: <button class="tab-btn plugin-tab-btn">
   - Tab content: <div class="tab-content plugin-tab-content">
5. generatePluginConfigForm() creates form from schema
6. Current config values populated into form

Form Generation Logic

Based on JSON Schema type:

• boolean → Toggle switch
• number/integer → Number input with min/max
• string → Text input with maxLength
• array → Comma-separated text input
• enum → Dropdown select

Save Process

1. User submits form
2. savePluginConfiguration() processes form data:
   • Converts types per schema (parseInt, parseFloat, split for arrays)
   • Handles boolean checkbox state
3. Each field sent to /api/plugins/config individually
4. Backend updates config.json
5. Success notification shown
6. Plugins refreshed to update display

Benefits

For Users

• Organized UI: Plugin management separate from configuration
• Better UX: Each plugin has its own dedicated space
• Type Safety: Inputs validated based on schema constraints
• Easy Reset: One-click reset to defaults
• Clear Labels: Schema descriptions shown as help text

For Developers

• Automatic: No custom UI code needed
• Declarative: Just define JSON Schema
• Flexible: Supports all common data types
• Validated: Schema constraints enforced automatically

Key Features

1. Dynamic Tab Creation: Tabs appear/disappear as plugins are installed/uninstalled
2. JSON Schema Driven: Forms generated from standard JSON Schema
3. Type Conversion: Automatic conversion between HTML form strings and config types
4. Default Values: Schema defaults used when config value missing
5. Backward Compatible: Plugins without schemas still work normally

File Structure

LEDMatrix/
├── web_interface_v2.py              # Backend API changes
├── templates/
│   └── index_v2.html                # Frontend tab generation
└── docs/
    ├── PLUGIN_CONFIGURATION_TABS.md # Full documentation
    └── PLUGIN_CONFIG_TABS_SUMMARY.md # This file

plugins/
├── hello-world/
│   ├── manifest.json                # References config_schema.json
│   └── config_schema.json           # Defines configuration structure
└── clock-simple/
    ├── manifest.json
    └── config_schema.json

Usage Example

For Users

1. Install a plugin via Plugin Store
2. Navigate to Plugins tab
3. Click "Configure" on plugin card
4. Plugin's configuration tab opens automatically
5. Modify settings and click "Save Configuration"
6. Restart display to apply changes

For Plugin Developers

Create config_schema.json:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "default": true
    },
    "message": {
      "type": "string",
      "default": "Hello!",
      "maxLength": 50
    }
  }
}

Reference in manifest.json:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "icon": "fas fa-star",         // Optional: custom icon
  "config_schema": "config_schema.json"
}

That's it! The configuration tab will be automatically generated.

Tip: Add an icon field to customize your plugin's tab icon. Supports Font Awesome icons, emoji, or custom images. See PLUGIN_CUSTOM_ICONS.md for details.

Testing Checklist

• Backend loads config schemas
• Tabs generated for installed plugins
• Forms render all field types correctly
• Current values populated
• Save updates config.json
• Type conversion works (string → number, string → array)
• Reset to defaults works
• Configure button navigates to tab
• Tabs removed when plugin uninstalled
• Backward compatible with plugins without schemas

Known Limitations

1. Nested Objects: Only supports flat property structures
2. Conditional Fields: No support for JSON Schema conditionals
3. Custom Validation: Only basic schema validation supported
4. Array of Objects: Arrays must be primitive types or simple lists

Future Improvements

1. Support nested object properties
2. Add visual validation feedback
3. Color picker for RGB arrays
4. File upload support for assets
5. Configuration presets/templates
6. Export/import configurations
7. Plugin-specific custom renderers

Migration Notes

• Existing plugins continue to work without changes
• Plugins with config_schema.json automatically get tabs
• No breaking changes to existing APIs
• The Plugins tab still handles management operations
• Raw JSON editor still available as fallback

Related Documentation

• PLUGIN_CONFIGURATION_TABS.md - Full user and developer guide
• Plugin Store Documentation - Plugin system overview
• JSON Schema Draft 07 - Schema specification