LEDMatrix/docs/PLUGIN_CONFIG_QUICK_START.md

Plugin Configuration Tabs - Quick Start Guide

🚀 Quick Start (1 Minute)

For Users

1. Open the web interface: http://your-pi-ip:5000
2. Open the Plugin Manager tab
3. Find a plugin in the Plugin Store section (e.g., "Hello World") and click Install
4. Notice a new tab appears in the second nav row with the plugin's name
5. Click that tab to configure the plugin
6. Modify settings and click Save Configuration. The running display picks the change up by itself; no restart is needed

That's it! Each installed plugin automatically gets its own configuration tab.

🎯 What You Get

Before This Feature

• All plugin settings mixed together in the Plugins tab
• Generic key-value inputs for configuration
• Hard to know what each setting does
• No validation or type safety

After This Feature

• ✅ Each plugin has its own dedicated tab
• ✅ Configuration forms auto-generated from schema
• ✅ Proper input types (toggles, numbers, dropdowns)
• ✅ Help text explaining each setting
• ✅ Input validation (min/max, length, etc.)

📋 Example Walkthrough

Let's configure the "Hello World" plugin:

Step 1: Navigate to Configuration Tab

After installing the plugin, you'll see a new tab:

[Plugin Manager] [Hello World] ← New tab! (second nav row)

Step 2: Configure Settings

The tab shows a form like this:

Hello World Configuration
A simple test plugin that displays a customizable message

✓ Enable or disable this plugin
  [Toggle Switch: ON]

Message
The greeting message to display
  [Hello, World!        ]

Show Time
Show the current time below the message
  [Toggle Switch: ON]

Color
RGB color for the message text [R, G, B]
  [255, 255, 255        ]

Display Duration
How long to display in seconds
  [10                   ]

[Refresh] [Update] [Uninstall] [Save Configuration]

Step 3: Save and Apply

1. Modify any settings
2. Click Save Configuration
3. See the confirmation notification. Plugin settings apply live: the display service reloads config.json when it changes and passes the new settings to the plugin's on_config_change()

🛠️ For Plugin Developers

Minimal Setup

Create config_schema.json in your plugin directory:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "default": true,
      "description": "Enable this plugin"
    },
    "message": {
      "type": "string",
      "default": "Hello!",
      "description": "Message to display"
    }
  }
}

Done! The file name is fixed: the web interface looks for config_schema.json in the plugin's directory; there is no manifest field for it. Every installed plugin gets a tab; the schema is what turns it into a form.

Bonus: an icon field in manifest.json names a Font Awesome class for the tab ("icon": "fas fa-star"). See PLUGIN_CUSTOM_ICONS.md.

🎨 Supported Input Types

Boolean → Toggle Switch

{
  "type": "boolean",
  "default": true
}

Number → Number Input

{
  "type": "integer",
  "default": 60,
  "minimum": 1,
  "maximum": 300
}

String → Text Input

{
  "type": "string",
  "default": "Hello",
  "maxLength": 50
}

Array → Comma-Separated Input

{
  "type": "array",
  "items": {"type": "integer"},
  "default": [255, 0, 0]
}

User enters: 255, 0, 0

Enum → Dropdown

{
  "type": "string",
  "enum": ["small", "medium", "large"],
  "default": "medium"
}

💡 Pro Tips

For Users

1. Navigate Back: Switch to the Plugin Manager tab to see the full list of installed plugins
2. Check Help Text: Each field has a description explaining what it does
3. No Restart Needed: Saved plugin settings apply to the running display

For Developers

1. Add Descriptions: Users see these as help text - be descriptive!
2. Use Constraints: Set min/max to guide users to valid values
3. Sensible Defaults: Make sure defaults work without configuration
4. Test Your Schema: Use a JSON Schema validator before deploying
5. Order Matters: Properties appear in the order you define them

🔧 Troubleshooting

Tab Not Showing

• Check that the plugin is installed and listed under Plugin Manager
• Refresh the page
• Check browser console for errors

Settings Not Saving

• Ensure plugin is properly installed
• Check that all required fields are filled
• Look for validation errors in browser console

Form Looks Wrong

• Check that config_schema.json is in the plugin's directory
• Validate your JSON Schema
• Check that types match your defaults
• Ensure descriptions are strings
• Look for JavaScript errors

📚 Next Steps

• Read the full documentation: PLUGIN_CONFIGURATION_TABS.md
• Check the configuration architecture: PLUGIN_CONFIG_ARCHITECTURE.md
• Browse example plugins in the ledmatrix-plugins repo, especially plugins/hello-world/ and plugins/clock-simple/
• Join the community for help and suggestions

🎉 That's It!

You now have dynamic, type-safe configuration tabs for each plugin. No more manual JSON editing or cluttered interfaces - just clean, organized plugin configuration.

Enjoy! 🚀