LEDMatrix/docs/archive/NESTED_SCHEMA_IMPLEMENTATION.md

Nested Config Schema Implementation - Complete

Summary

The plugin manager now fully supports nested config schemas, allowing complex plugins to organize their configuration options into logical, collapsible sections in the web interface.

What Was Implemented

1. Core Functionality ✅

Updated Files:

• web_interface/templates/v3/partials/plugins.html

New Features:

• Recursive form generation for nested objects
• Collapsible sections with smooth animations
• Dot notation for form field names (e.g., nfl.display_modes.show_live)
• Automatic conversion between flat form data and nested JSON
• Support for unlimited nesting depth

2. Helper Functions ✅

Added to plugins.html:

• getSchemaPropertyType(schema, path) - Find property type using dot notation
• dotToNested(obj) - Convert flat dot notation to nested objects
• collectBooleanFields(schema, prefix) - Recursively find all boolean fields
• flattenConfig(obj, prefix) - Flatten nested config for form display
• generateFieldHtml(key, prop, value, prefix) - Recursively generate form fields
• toggleNestedSection(sectionId) - Toggle collapse/expand of nested sections

3. UI Enhancements ✅

CSS Styling Added:

• Smooth transitions for expand/collapse
• Visual hierarchy with indentation
• Gray background for nested sections to differentiate from main form
• Hover effects on section headers
• Chevron icons that rotate on toggle
• Responsive design for nested sections

4. Backward Compatibility ✅

Fully Compatible:

• All 18 existing plugins with flat schemas work without changes
• Mixed mode supported (flat and nested properties in same schema)
• No backend API changes required
• Existing configs load and save correctly

5. Documentation ✅

Created Files:

• docs/NESTED_CONFIG_SCHEMAS.md - Complete user guide
• plugin-repos/ledmatrix-football-scoreboard/config_schema_nested_example.json - Example nested schema

Why It Wasn't Supported Before

Simply put: nobody implemented it yet. The original generateFormFromSchema() function only handled flat properties - it had no handler for type: 'object' which indicates nested structures. All existing plugins used flat schemas with prefixed names (e.g., nfl_enabled, nfl_show_live, etc.).

Technical Details

How It Works

1. Schema Definition: Plugin defines nested objects using type: "object" with nested properties
2. Form Generation: generateFieldHtml() recursively creates collapsible sections for nested objects
3. Form Submission: Form data uses dot notation (nfl.enabled) which is converted to nested JSON ({nfl: {enabled: true}})
4. Config Storage: Stored as proper nested JSON objects in config.json

Example Transformation

Flat Schema (Before):

{
  "nfl_enabled": true,
  "nfl_show_live": true,
  "nfl_favorite_teams": ["TB", "DAL"]
}

Nested Schema (After):

{
  "nfl": {
    "enabled": true,
    "show_live": true,
    "favorite_teams": ["TB", "DAL"]
  }
}

Field Name Mapping

Form fields use dot notation internally:

• nfl.enabled → {nfl: {enabled: true}}
• nfl.display_modes.show_live → {nfl: {display_modes: {show_live: true}}}
• ncaa_fb.game_limits.recent_games_to_show → {ncaa_fb: {game_limits: {recent_games_to_show: 5}}}

Benefits

For Plugin Developers

• Better organization - Group related settings logically
• Cleaner code - Access config with natural nesting: config["nfl"]["enabled"]
• Easier maintenance - Related settings are together
• Scalability - Handle 50+ options without overwhelming users

For Users

• Less overwhelming - Collapsible sections hide complexity
• Easier navigation - Find settings quickly in logical groups
• Better understanding - Clear hierarchy shows relationships
• Cleaner UI - Organized sections vs. endless list

Examples

Football Plugin Comparison

Before (Flat - 32 properties): All properties in one long list:

• nfl_enabled
• nfl_favorite_teams
• nfl_show_live
• nfl_show_recent
• nfl_show_upcoming
• ... (27 more)

After (Nested - Same 32 properties): Organized into 2 main sections:

• NFL Settings (collapsed)
  • Display Modes (collapsed)
  • Game Limits (collapsed)
  • Display Options (collapsed)
  • Filtering (collapsed)
• NCAA Football Settings (collapsed)
  • Same nested structure

Baseball Plugin Opportunity

The baseball plugin has over 100 properties! With nested schemas, these could be organized into:

• MLB Settings
  • Display Modes
  • Game Limits
  • Display Options
  • Background Service
• MiLB Settings
  • (same structure)
• NCAA Baseball Settings
  • (same structure)

Migration Guide

For New Plugins

Use nested schemas from the start:

{
  "type": "object",
  "properties": {
    "enabled": {"type": "boolean", "default": true},
    "sport_name": {
      "type": "object",
      "title": "Sport Name Settings",
      "properties": {
        "enabled": {"type": "boolean", "default": true},
        "favorite_teams": {"type": "array", "items": {"type": "string"}, "default": []}
      }
    }
  }
}

For Existing Plugins

You have three options:

1. Keep flat - No changes needed, works perfectly
2. Gradual migration - Nest some sections, keep others flat
3. Full migration - Restructure entire schema (requires updating plugin code to access nested config)

Testing

Backward Compatibility Verified

• ✅ All 18 existing flat schemas work unchanged
• ✅ Form generation works for flat schemas
• ✅ Form submission works for flat schemas
• ✅ Config saving/loading works for flat schemas

New Nested Schema Tested

• ✅ Nested objects generate collapsible sections
• ✅ Multi-level nesting works (object within object)
• ✅ Form fields use correct dot notation
• ✅ Form submission converts to nested JSON correctly
• ✅ Boolean fields handled in nested structures
• ✅ All field types work in nested sections (boolean, number, integer, array, string, enum)

Files Modified

1. web_interface/templates/v3/partials/plugins.html
   • Added helper functions for nested schema handling
   • Updated generateFormFromSchema() to recursively handle nested objects
   • Updated handlePluginConfigSubmit() to convert dot notation to nested JSON
   • Added toggleNestedSection() for UI interaction
   • Added CSS styles for nested sections

Files Created

1. docs/NESTED_CONFIG_SCHEMAS.md

   • Complete user and developer guide
   • Examples and best practices
   • Migration strategies
   • Troubleshooting guide

2. plugin-repos/ledmatrix-football-scoreboard/config_schema_nested_example.json

   • Full working example of nested schema
   • Demonstrates all nesting levels
   • Shows before/after comparison

No Backend Changes Needed

The existing API endpoints work perfectly:

• /api/v3/plugins/schema - Returns schema (flat or nested)
• /api/v3/plugins/config (GET) - Returns config (flat or nested)
• /api/v3/plugins/config (POST) - Saves config (flat or nested)

The backend doesn't care about structure - it just stores/retrieves JSON!

Next Steps

Immediate Use

You can start using nested schemas right now:

1. Create a new plugin with nested schema
2. Or update an existing plugin's config_schema.json to use nesting
3. The web interface will automatically render collapsible sections

Recommended Migrations

Good candidates for nested schemas:

• Baseball plugin (100+ properties → 3-4 main sections)
• Football plugin (32 properties → 2 main sections) [example already created]
• Basketball plugin (similar to football)
• Hockey plugin (similar to football)

Future Enhancements

Potential improvements (not required):

• Remember collapsed/expanded state per user
• Search within nested sections
• Visual indication of which section has changes
• Drag-and-drop to reorder sections

Conclusion

The plugin manager now has full support for nested config schemas with:

• ✅ Automatic UI generation
• ✅ Collapsible sections
• ✅ Full backward compatibility
• ✅ No breaking changes
• ✅ Complete documentation
• ✅ Working examples

Complex plugins can now be much easier to configure and maintain!