# Widget Development Guide ## Overview The LEDMatrix Widget Registry system allows plugins to use reusable UI components for configuration forms. This enables: - **Reusable Components**: Use existing widgets (file upload, checkboxes, etc.) without custom code - **Custom Widgets**: Create plugin-specific widgets without modifying the LEDMatrix codebase - **Backwards Compatibility**: Existing plugins continue to work without changes ## Available Core Widgets ### Plugin File Manager Widget (`plugin-file-manager`) Full inline file management UI for plugins that manage files via the `web_ui_actions` system. Renders a card grid, upload zone, create/delete modals, and an entry table editor — entirely inline, no iframe. `plugin_id` is **automatically injected** from template context. File operations call `/api/v3/plugins/action` immediately on user action; no Save Configuration needed. **Schema Configuration:** ```json { "file_manager": { "type": "null", "title": "Data Files", "x-widget": "plugin-file-manager", "x-widget-config": { "actions": { "list": "list-files", "get": "get-file", "save": "save-file", "upload": "upload-file", "delete": "delete-file", "create": "create-file", "toggle": "toggle-category" }, "upload_hint": "JSON files with day numbers 1–365 as keys", "directory_label": "my_data/", "create_fields": [ { "key": "category_name", "label": "Category Name", "placeholder": "e.g., my_words", "pattern": "^[a-z0-9_]+$", "hint": "Lowercase letters, numbers, underscores" }, { "key": "display_name", "label": "Display Name", "placeholder": "e.g., My Words", "hint": "Optional" } ] } } } ``` **`list` is required** — the widget calls it on render to populate the file grid; omitting it leaves the widget stuck in a loading state. All other actions are optional — omit any key to hide its UI element (e.g., no `create` = no New File button, no `toggle` = no enable/disable switch). The edit view auto-detects whether file content is tabular (object-of-objects with uniform keys) and shows a paginated table editor with inline cells. Otherwise falls back to a JSON textarea. **Used by:** of-the-day --- ### Time Picker Widget (`time-picker`) Single time selection using the browser's native time input. Returns a string in `HH:MM` (24-hour) format. Generic — works in any plugin without configuration. **Schema Configuration:** ```json { "target_time": { "type": "string", "x-widget": "time-picker", "default": "00:00", "x-options": { "placeholder": "Select time", "clearable": true } } } ``` **Used by:** countdown --- ### File Upload Single Widget (`file-upload-single`) Single-image upload for string fields. Uploads to the plugin's asset folder (`assets/plugins//uploads/`) and sets the string field value to the returned relative path. Shows a thumbnail preview and a clear button. The `plugin_id` is **automatically injected** from the template context — no need to specify it in the schema. **Schema Configuration:** ```json { "image_path": { "type": "string", "x-widget": "file-upload-single", "x-upload-config": { "allowed_types": ["image/png", "image/jpeg", "image/bmp", "image/gif"], "max_size_mb": 5 } } } ``` Note: Unlike `file-upload` (array-level), this widget is for a single `string` field. It is ideal for per-item images inside `array-table` rows. **Used by:** countdown --- ### File Upload Widget (`file-upload`) Upload and manage image files with drag-and-drop support, preview, delete, and scheduling. **Schema Configuration:** ```json { "type": "array", "x-widget": "file-upload", "x-upload-config": { "plugin_id": "my-plugin", "max_files": 10, "max_size_mb": 5, "allowed_types": ["image/png", "image/jpeg", "image/bmp", "image/gif"] } } ``` **Used by:** static-image, news plugins ### Checkbox Group Widget (`checkbox-group`) Multi-select checkboxes for array fields with enum items. **Schema Configuration:** ```json { "type": "array", "x-widget": "checkbox-group", "items": { "type": "string", "enum": ["option1", "option2", "option3"] }, "x-options": { "labels": { "option1": "Option 1 Label", "option2": "Option 2 Label" } } } ``` **Used by:** odds-ticker, news plugins ### Custom Feeds Widget (`custom-feeds`) Table-based RSS feed editor with logo uploads. **Schema Configuration:** ```json { "type": "array", "x-widget": "custom-feeds", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "logo": { "type": "object" } } }, "maxItems": 50 } ``` **Used by:** news plugin (for custom RSS feeds) ## Using Existing Widgets To use an existing widget in your plugin's `config_schema.json`, simply add the `x-widget` property: ```json { "properties": { "my_images": { "type": "array", "x-widget": "file-upload", "x-upload-config": { "plugin_id": "my-plugin", "max_files": 5 } }, "enabled_leagues": { "type": "array", "x-widget": "checkbox-group", "items": { "type": "string", "enum": ["nfl", "nba", "mlb"] }, "x-options": { "labels": { "nfl": "NFL", "nba": "NBA", "mlb": "MLB" } } } } } ``` The widget will be automatically rendered when the plugin configuration form is loaded. ## Labelling Enum Options (`x-options.labels`) A plain `enum` renders as a dropdown whose option text is the value with underscores replaced and title case applied — `day_first` becomes "Day First". That is fine for values that read as their own label, and wrong for values that do not: `vs` becomes "Vs", and `abbrev` says nothing about the `Sep 19` it actually produces. Supply `x-options.labels` to set the visible text. This is the same convention the `checkbox-group` widget uses: ```json { "date_format": { "type": "string", "enum": ["abbrev", "numeric", "day_first"], "default": "abbrev", "x-options": { "labels": { "abbrev": "Sep 19", "numeric": "9/19", "day_first": "19 Sep" } } } } ``` Labels are **display only** — the stored value is still the enum value, so adding them never changes a saved config. The map may be partial: any value without a label keeps the humanised fallback. Older cores that predate this support ignore `x-options` and render the fallback for every option, so a plugin can ship labels without requiring a core upgrade. Array-table columns (`x-widget: array-table`) accept the same `x-options.labels` on a column definition, but their fallback is the **raw value** rather than the humanised one, because those columns hold values such as ticker symbols where `aapl` → "Aapl" would be wrong. Rows added in the browser use the labels too (`array-table.js`), so a column reads the same before and after a page reload. ## Marking Fields as Advanced (`x-advanced`) Add `"x-advanced": true` to any top-level, non-object property to move it out of the main form and into a single collapsed **Advanced Settings** section at the bottom of the plugin's configuration page: ```json { "properties": { "city": { "type": "string", "title": "City" }, "request_timeout": { "type": "integer", "default": 10, "description": "HTTP timeout in seconds", "x-advanced": true } } } ``` Guidelines: - Use it for fine-tuning knobs most users never touch (timeouts, retry behavior, cache TTLs, styling overrides). Anything a first-time user must set to get the plugin working should stay basic. - Nothing is hidden permanently — the section expands on click, and the settings search finds and auto-expands advanced fields like any others. - The flag is ignored on `object`-type properties (they already render as their own collapsible sections) and is safely ignored by older cores, so adding it never breaks compatibility. ## Hiding Fields From the Form (`x-display: "hidden"`) Add `"x-display": "hidden"` to a property that must stay in the schema but should not appear as a control: a deprecated key kept so existing configs keep validating, or an internal value such as an auto-generated row id. ```json { "properties": { "radar_zoom": { "type": "integer", "default": 6, "title": "Radar Zoom Level (deprecated)", "x-display": "hidden" } } } ``` What the core does with it: - **Not rendered** at any depth: top-level fields, children of an object section, and properties of array-of-object items (never a table column, even if `x-columns` names it, and never in the row editor). A hidden field flagged `x-advanced` is not listed or counted in Advanced Settings, and an object whose children are all hidden draws no empty section. Hidden fields don't show up in the settings search either, since it indexes the rendered form. - **Stored value preserved on save.** Saving the form never changes a hidden value. The unchecked-checkbox rule ignores a hidden boolean. Array rows carry a hidden property's stored value through the form, so the value survives the row being posted back; a new row gets no value (the plugin fills it in). - **The API is unaffected.** A JSON save to `POST /api/v3/plugins/config` can still set a hidden field. Older cores ignore the flag and render the field as a normal control. ## Creating Custom Widgets ### Step 1: Create Widget File Create a JavaScript file in your plugin's `widgets/` directory, named `widgets/[widget-name].js`. The directory is not optional: it is the only place the core will serve a widget from. ```javascript // Ensure LEDMatrixWidgets registry is available if (typeof window.LEDMatrixWidgets === 'undefined') { console.error('LEDMatrixWidgets registry not found'); return; } // Register your widget window.LEDMatrixWidgets.register('my-custom-widget', { name: 'My Custom Widget', version: '1.0.0', /** * Render the widget HTML * @param {HTMLElement} container - Container element to render into * @param {Object} config - Widget configuration from schema * @param {*} value - Current value * @param {Object} options - Additional options (fieldId, pluginId, etc.) */ render: function(container, config, value, options) { const fieldId = options.fieldId || container.id; // Always escape HTML to prevent XSS const escapeHtml = (text) => { const div = document.createElement('div'); div.textContent = text; return div.innerHTML; }; container.innerHTML = `
`; // Attach event listeners const input = container.querySelector('input'); input.addEventListener('change', (e) => { this.handlers.onChange(fieldId, e.target.value); }); }, /** * Get current value from widget */ getValue: function(fieldId) { const input = document.querySelector(`#${fieldId}_input`); return input ? input.value : null; }, /** * Set value programmatically */ setValue: function(fieldId, value) { const input = document.querySelector(`#${fieldId}_input`); if (input) { input.value = value || ''; } }, /** * Event handlers */ handlers: { onChange: function(fieldId, value) { // Trigger form change event const event = new CustomEvent('widget-change', { detail: { fieldId, value }, bubbles: true }); document.dispatchEvent(event); } } }); ``` ### Step 2: Declare the Widget in `manifest.json` The manifest is the allowlist. A widget is served only if the plugin declares it, so shipping a file under `widgets/` does not by itself publish it: ```json { "widgets": [ { "name": "my-custom-widget", "script": "my-custom-widget.js", "description": "What this widget is for" } ] } ``` `name` is what you use in `x-widget` and in the URL. `script` is optional and defaults to `[name].js`; it must be a plain filename directly inside `widgets/` (no paths). Both are validated against `schema/manifest_schema.json`. ### Step 3: Reference Widget in Schema In your plugin's `config_schema.json`: ```json { "properties": { "my_field": { "type": "string", "description": "My custom field", "x-widget": "my-custom-widget", "default": "" } } } ``` ### Step 4: Widget Loading The widget is loaded on demand when the plugin's configuration form renders a field that references it. The system will: 1. Check whether the widget is already registered in the core registry. 2. If not, fetch it from `/static/plugin-widgets/[plugin-id]/[widget-name].js`. That route serves the declared `script` from your plugin's `widgets/` directory, as `text/javascript`. 3. Render it by calling the `render` function your script registered. The fetch uses a dynamic `import()`, so the file must parse as an ES module. A plain IIFE does — modules are strict mode, so avoid sloppy-mode constructs. **If the widget fails to load** (not declared, file missing, script throws, or it never calls `register`), the field falls back to a plain text input holding the current value. This is deliberate: a broken widget costs the user an editor, not their configured value. **Limitation:** the on-demand path applies to `string`-typed fields (the default branch of the config-form renderer). Fields typed `object`, `array`, `boolean`, `integer` or `number`, and fields whose `enum` is set, are dispatched by the server-side template to its own built-in renderers, so a plugin-supplied `x-widget` on one of those is ignored today. ## Widget API Reference ### Widget Definition Object ```javascript { name: string, // Human-readable widget name version: string, // Widget version render: function, // Required: Render function getValue: function, // Optional: Get current value setValue: function, // Optional: Set value programmatically handlers: object // Optional: Event handlers } ``` ### Render Function ```javascript render(container, config, value, options) ``` **Parameters:** - `container` (HTMLElement): Container element to render into - `config` (Object): Widget configuration from schema - `value` (*): Current field value - `options` (Object): Additional options - `fieldId` (string): Field ID - `pluginId` (string): Plugin ID - `fullKey` (string): Full field key path ### Get Value Function ```javascript getValue(fieldId) ``` **Returns:** Current widget value ### Set Value Function ```javascript setValue(fieldId, value) ``` **Parameters:** - `fieldId` (string): Field ID - `value` (*): Value to set ## Examples See [`web_interface/static/v3/js/widgets/example-color-picker.js`](../web_interface/static/v3/js/widgets/example-color-picker.js) for a complete example of a custom color picker widget. ## Best Practices ### Security 1. **Always escape HTML**: Use `escapeHtml()` or `textContent` to prevent XSS 2. **Validate inputs**: Validate user input before processing 3. **Sanitize values**: Clean values before storing ### Performance 1. **Lazy loading**: Load widget scripts only when needed 2. **Event delegation**: Use event delegation for dynamic content 3. **Debounce**: Debounce frequent events (e.g., input changes) ### Accessibility 1. **Labels**: Always associate labels with inputs 2. **ARIA attributes**: Use appropriate ARIA attributes 3. **Keyboard navigation**: Ensure keyboard accessibility ## Troubleshooting ### Widget Not Loading 1. Check browser console for errors 2. Verify widget file path is correct 3. Ensure `LEDMatrixWidgets.register()` is called 4. Check that widget name matches schema `x-widget` value ### Widget Not Rendering 1. Verify `render` function is defined 2. Check container element exists 3. Ensure widget is registered before form loads 4. Check for JavaScript errors in console ### Value Not Saving 1. Ensure widget triggers `widget-change` event 2. Verify form submission includes widget value 3. Check `getValue` function returns correct type 4. Verify field name matches schema property ## Current Implementation Status **Phase 1 Complete:** - ✅ Widget registry system created - ✅ Core widgets extracted to separate files - ✅ Widget handlers available globally (backwards compatible) - ✅ Plugin widget loading system implemented **Current Behavior:** - Core widgets are server-side rendered via Jinja2 templates (existing behavior preserved) - Widget handlers are registered and available globally - Custom widgets can be created, declared in `manifest.json`, and are served and rendered on demand for `string`-typed fields - Plugin widgets on non-string fields are not dispatched yet (see Step 4) **Backwards Compatibility:** - All existing plugins using widgets continue to work without changes - Server-side rendering remains the primary method - Widget registry provides foundation for future enhancements ## See Also - [Widget README](../web_interface/static/v3/js/widgets/README.md) - Complete widget development guide with examples - [Plugin Development Guide](PLUGIN_DEVELOPMENT_GUIDE.md) - General plugin development - [Plugin Configuration Guide](PLUGIN_CONFIGURATION_GUIDE.md) - Configuration setup