rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-10-11 01:26:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(plugin-config): match the config tab, icon and web-action docs to the code

Browse Source 
- PLUGIN_CONFIG_QUICK_START / PLUGIN_CONFIGURATION_TABS /
  PLUGIN_CONFIGURATION_GUIDE: there is no "Reset to Defaults" button (the
  tab has Refresh, Update, Uninstall, Save Configuration); plugin config
  hot-reloads (ConfigService + on_config_change), so no restart; the
  schema is found by the fixed name config_schema.json, not a manifest
  config_schema field; the tab row is "Plugin Manager", not "Plugins";
  forms are server-rendered from /v3/partials/plugin-config/<id>; the
  duration hook is get_display_duration()/display_duration; a class_name
  mismatch raises PluginError; the store requires id, name, class_name and
  display_modes (not version); plugin_system.debug/log_level do not exist
  (use run.py -d / LEDMATRIX_DEBUG). Drop "future" features that shipped.
- PLUGIN_CONFIG_CORE_PROPERTIES: list all of CORE_PLUGIN_PROPERTIES,
  including skin, skin_options and the vegas_* tuning keys.
- PLUGIN_CUSTOM_ICONS: icon is only a Font Awesome class (fallback
  fa-puzzle-piece); emoji/URL icons and getPluginIcon() never existed in
  v3. Note that /api/v3/plugins/installed currently omits icon.
- PLUGIN_WEB_UI_ACTIONS (+ example JSON): success_message, error_message
  and step1_message are never read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-09-22 16:21:58 -04:00
co-authored by Claude Opus 5.5
parent 8dad0fd41c
commit 698807cc62
7 changed files with 141 additions and 453 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PLUGIN_CUSTOM_ICONS.md
+34 -282
View File
@@ -2,17 +2,28 @@
## Overview
Plugins can specify custom icons that appear next to their name in the web interface tabs. This makes your plugin instantly recognizable and adds visual polish to the UI.
A plugin can name an icon for its tab in the web interface's second nav row
(next to **Plugin Manager**) with the `icon` field in `manifest.json`.
## Icon Types Supported
> **Status:** the tab code honors `icon`, but `GET /api/v3/plugins/installed`
> (`web_interface/blueprints/api_v3/plugins.py`) does not currently include
> the manifest's `icon` in its response, so every tab shows the default
> puzzle piece. Setting `icon` is harmless and will take effect once the API
> passes it through again.
The system supports three types of icons:
## Font Awesome classes only
### 1. Font Awesome Icons (Recommended)
`icon` is used verbatim as the CSS class of an `<i>` element
(`iconEl.className = plugin.icon || 'fas fa-puzzle-piece'` in
`web_interface/static/v3/js/app-shell.js` and the same fallback in
`app-early.js`). So it must be a Font Awesome class string. Emoji, image
paths and URLs are not supported: they would end up as a meaningless class
name and render nothing.
The web interface uses Font Awesome 6, giving you access to thousands of icons.
The web interface bundles Font Awesome Free 6
(`web_interface/static/v3/vendor/fontawesome/`), so any free `fas`, `far` or
`fab` icon works.
**Example:**
```json
{
"id": "my-plugin",
@@ -21,292 +32,33 @@ The web interface uses Font Awesome 6, giving you access to thousands of icons.
}
```
**Common Font Awesome Icons:**
- Clock: `fas fa-clock`
Some common choices:
- Clock / calendar: `fas fa-clock`, `fas fa-calendar-alt`
- Weather: `fas fa-cloud-sun`, `fas fa-cloud-rain`
- Calendar: `fas fa-calendar`, `fas fa-calendar-alt`
- Sports: `fas fa-football-ball`, `fas fa-basketball-ball`
- Sports: `fas fa-football-ball`, `fas fa-basketball-ball`, `fas fa-trophy`
- Music: `fas fa-music`, `fas fa-headphones`
- Finance: `fas fa-chart-line`, `fas fa-dollar-sign`
- News: `fas fa-newspaper`, `fas fa-rss`
- Settings: `fas fa-cog`, `fas fa-sliders-h`
- Timer: `fas fa-stopwatch`, `fas fa-hourglass`
- Alert: `fas fa-bell`, `fas fa-exclamation-triangle`
- Heart: `fas fa-heart`, `far fa-heart` (outline)
- Star: `fas fa-star`, `far fa-star` (outline)
- Image: `fas fa-image`, `fas fa-camera`
- Video: `fas fa-video`, `fas fa-film`
- Game: `fas fa-gamepad`, `fas fa-dice`
- Games: `fas fa-gamepad`, `fas fa-dice`
**Browse all icons:** [Font Awesome Icon Gallery](https://fontawesome.com/icons)
Browse the rest in the [Font Awesome gallery](https://fontawesome.com/icons)
(filter to Free, version 6).
### 2. Emoji Icons (Fun & Simple)
## Default
Use any emoji character for a colorful, fun icon.
**Example:**
```json
{
"id": "hello-world",
"name": "Hello World",
"icon": "👋"
}
```
**Popular Emojis:**
- Time: ⏰ 🕐 ⏱️ ⏲️
- Weather: ☀️ ⛅ 🌤️ 🌧️ ⛈️ 🌩️ ❄️
- Sports: ⚽ 🏀 🏈 ⚾ 🎾 🏐
- Music: 🎵 🎶 🎸 🎹 🎤
- Money: 💰 💵 💴 💶 💷
- Calendar: 📅 📆
- News: 📰 📻 📡
- Fun: 🎮 🎲 🎯 🎨 🎭
- Nature: 🌍 🌎 🌏 🌳 🌺 🌸
- Food: 🍕 🍔 🍟 🍦 ☕ 🍰
### 3. Custom Image URLs (Advanced)
Use a custom image file for ultimate branding.
**Example:**
```json
{
"id": "my-plugin",
"name": "My Plugin",
"icon": "/plugins/my-plugin/icon.png"
}
```
**Requirements:**
- Image should be 16x16 to 32x32 pixels
- Supported formats: PNG, SVG, JPG, GIF
- Can be a relative path, absolute path, or external URL
- SVG recommended for best quality at any size
## How to Add an Icon
### Step 1: Choose Your Icon
Decide which type suits your plugin:
- **Font Awesome**: Professional, consistent with UI
- **Emoji**: Fun, colorful, no setup needed
- **Custom Image**: Unique branding, requires image file
### Step 2: Add to manifest.json
Add the `icon` field to your plugin's `manifest.json`:
```json
{
"id": "my-weather-plugin",
"name": "Weather Display",
"version": "1.0.0",
"author": "Your Name",
"description": "Shows weather information",
"icon": "fas fa-cloud-sun", // ← Add this line
"entry_point": "manager.py",
...
}
```
### Step 3: Test Your Plugin
1. Install or update your plugin
2. Open the web interface
3. Look for your plugin's tab
4. The icon should appear next to the plugin name
## Examples
### Weather Plugin
```json
{
"id": "weather-advanced",
"name": "Weather Advanced",
"icon": "fas fa-cloud-sun",
"description": "Advanced weather display with forecasts"
}
```
**Result:** Tab shows: `☁️ Weather Advanced`
### Clock Plugin
```json
{
"id": "digital-clock",
"name": "Digital Clock",
"icon": "⏰",
"description": "A beautiful digital clock"
}
```
**Result:** Tab shows: `⏰ Digital Clock`
### Sports Scores Plugin
```json
{
"id": "sports-scores",
"name": "Sports Scores",
"icon": "fas fa-trophy",
"description": "Live sports scores"
}
```
**Result:** Tab shows: `🏆 Sports Scores`
### Custom Branding
```json
{
"id": "company-dashboard",
"name": "Company Dashboard",
"icon": "/plugins/company-dashboard/logo.svg",
"description": "Company metrics display"
}
```
**Result:** Tab shows: `[logo] Company Dashboard`
## Best Practices
### 1. Choose Meaningful Icons
- Icon should relate to plugin functionality
- Users should understand what the plugin does at a glance
- Avoid generic icons for specific functionality
### 2. Keep It Simple
- Simpler icons work better at small sizes
- Avoid icons with too much detail
- Test how your icon looks at 16x16 pixels
### 3. Match the UI Style
- Font Awesome icons match the interface best
- If using emoji, consider contrast with background
- Custom images should use similar color schemes
### 4. Consider Accessibility
- Icons should be recognizable without color
- Don't rely solely on color to convey meaning
- The plugin name should be descriptive
### 5. Test on Different Displays
- Check icon clarity on various screen sizes
- Ensure emoji render correctly on target devices
- Custom images should have good contrast
## Icon Categories
Here are recommended icons by plugin category:
### Time & Calendar
- `fas fa-clock`, `fas fa-calendar`, `fas fa-hourglass`
- Emoji: ⏰ 📅 ⏱️
### Weather
- `fas fa-cloud-sun`, `fas fa-temperature-high`, `fas fa-wind`
- Emoji: ☀️ 🌧️ ⛈️
### Finance & Stocks
- `fas fa-chart-line`, `fas fa-dollar-sign`, `fas fa-coins`
- Emoji: 💰 📈 💵
### Sports & Games
- `fas fa-football-ball`, `fas fa-trophy`, `fas fa-gamepad`
- Emoji: ⚽ 🏀 🎮
### Entertainment
- `fas fa-music`, `fas fa-film`, `fas fa-tv`
- Emoji: 🎵 🎬 📺
### News & Information
- `fas fa-newspaper`, `fas fa-rss`, `fas fa-info-circle`
- Emoji: 📰 📡 ℹ️
### Utilities
- `fas fa-tools`, `fas fa-cog`, `fas fa-wrench`
- Emoji: 🔧 ⚙️ 🛠️
### Social Media
- `fab fa-twitter`, `fab fa-facebook`, `fab fa-instagram`
- Emoji: 📱 💬 📧
With no `icon` (or an empty one) the tab shows `fas fa-puzzle-piece`.
## Troubleshooting
### Icon Not Showing
1. Check that the `icon` field is correctly spelled in `manifest.json`
2. For Font Awesome icons, verify the class name is correct
3. For custom images, check that the file path is accessible
4. Refresh the plugins in the web interface
5. Check browser console for errors
### Emoji Looks Wrong
- Some emojis render differently on different platforms
- Try a different emoji if one doesn't work well
- Consider using Font Awesome instead for consistency
### Custom Image Not Loading
- Verify the image file exists in the specified path
- Check file permissions (should be readable)
- Try using an absolute path or URL
- Ensure image format is supported (PNG, SVG, JPG, GIF)
- Check image dimensions (16x16 to 32x32 recommended)
### Icon Too Large/Small
- Font Awesome and emoji icons automatically size correctly
- For custom images, adjust the image file dimensions
- SVG images scale best
## Default Behavior
If you don't specify an `icon` field in your manifest:
- The plugin tab will show a default puzzle piece icon: 🧩
- This is the fallback for all plugins without custom icons
## Technical Details
The icon system works as follows:
1. **Frontend reads manifest**: When plugins load, the web interface reads each plugin's `manifest.json`
2. **Icon detection**: The `getPluginIcon()` function determines icon type:
- Contains `fa-` → Font Awesome icon
- 1-4 characters → Emoji
- Starts with `http://`, `https://`, or `/` → Custom image
- Otherwise → Default puzzle piece
3. **Rendering**: Icon HTML is generated and inserted into:
- Tab button in navigation bar
- Configuration page header
## Advanced: Dynamic Icons
Want to change icons programmatically? While not officially supported, you could:
1. Store multiple icon options in your manifest
2. Use JavaScript to swap icons based on plugin state
3. Update the manifest dynamically and refresh plugins
**Example (advanced):**
```json
{
"id": "status-display",
"icon": "fas fa-circle",
"icon_states": {
"active": "fas fa-check-circle",
"error": "fas fa-exclamation-circle",
"warning": "fas fa-exclamation-triangle"
}
}
```
1. Check the class name against the Font Awesome 6 Free gallery; a Pro-only
or misspelled class renders as a blank space.
2. Include the style prefix (`fas`, `far` or `fab`) as well as the icon
class.
3. See the status note above: the icon is currently not passed through by
the API.
## Related Documentation
- [Plugin Configuration Tabs](PLUGIN_CONFIGURATION_TABS.md) - Main plugin tabs documentation
- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md) - How to create plugins
- [Font Awesome Icons](https://fontawesome.com/icons) - Browse all available icons
- [Emoji Reference](https://unicode.org/emoji/charts/full-emoji-list.html) - All emoji options
## Summary
Adding a custom icon to your plugin:
1. **Choose** your icon (Font Awesome, emoji, or custom image)
2. **Add** the `icon` field to `manifest.json`
3. **Test** in the web interface
That's it! Your plugin now has a professional, recognizable icon in the UI. 🎨
- [Plugin Configuration Tabs](PLUGIN_CONFIGURATION_TABS.md)
- [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md)