Plugin custom configuration system with granular admin override controls

[ChandlerMoeller]

Sorry for the very large PR. Over the next few days I will work to split off different parts into smaller PRs.

Main Feature: Plugin-extensible Custom Configuration System

This PR introduces a flexible configuration system that allows home screen sections to define their own custom settings. Individual sections can now register configuration options that appear in both the admin interface and user settings, enabling fine-tuned control over section behavior.

The system supports several configuration input types:

• Dropdown menus for selecting from predefined options
• Text boxes for free-form text input
• Number boxes for numeric values
• Checkboxes for boolean settings

Each section can define which options are available to administrators versus regular users, providing appropriate access controls. This extensible approach means new sections can easily add their own configuration without requiring changes to the core plugin structure.

Additionally, synthetic options are automatically added to every section. This means all sections, whether built-in or externally registered, automatically inherit core functionality without requiring any additional configuration from the section implementation:

• Custom Display Name - Allows administrators and users to override the default section title
• Section Header Display - Controls whether the section header and route are shown or hidden

Main Feature: Granular Admin Override Controls

Administrators now have fine-grained control over which configuration options users can modify. For each section and each individual setting within that section, admins can decide whether to allow user overrides or enforce server-wide defaults.

The permission system operates through layered controls:

• Section-level toggle enables per-option permission controls for that specific section - when enabled, each individual option can be configured separately rather than applying a blanket allow/deny
• Per-option permissions provide granular control over each configuration option within the section

Options that sections explicitly mark as non-user-overridable do not appear in the admin interface for permission control. These options, whether restricted by the section definition or by admin configuration, are completely hidden from users and remain server-controlled.

User defaults are automatically inherited from admin-configured values. When a user first accesses their settings, all options start with the values set by the administrator. Users can then modify only the options they have permission to change, while locked options remain at the admin-set values across all users.

Secondary Feature: Section Info

Sections can now provide optional metadata to help administrators and users understand their purpose and source. This information appears in the admin interface and provides context for each section.

The Section Info system includes:

• Description - Displayed to both administrators and users, explaining what the section does
• Admin Notes - Additional details visible only to administrators for configuration guidance
• Version Control - Secure source repository information using supported platforms (GitHub, GitLab, Bitbucket)
• Feature Request Tag - Optional tag that generates links to the feature request system at features.iamparadox.dev

Sections cannot specify arbitrary URLs. Instead, they provide platform, username, and repository details, and the system generates proper source control links. If we would prefer, this can be switched to allow arbitrary URLs.

More External Section Plugin Support

This update expands the existing external plugin registration system to support the new custom configuration and section info capabilities. External plugins can now take advantage of the enhanced configuration system without any breaking changes to their existing integration.

New Readiness API

A new /HomeScreen/Ready endpoint allows external plugins to verify that the home screen system is fully initialized before attempting section registration. This endpoint returns HTTP 200 when ready or HTTP 503 when not ready. If used, this should fix a startup race condition causing external plugins to not register. (Resolves: IAmParadox27/jellyfin-plugin-collection-sections#4)

Expanded Configuration Support

External sections can now include custom configuration options when registering sections. The existing registration API accepts additional metadata for configuration options and section info, allowing external plugins to define dropdown menus, text boxes, number boxes, and checkboxes with validation rules. Each option can be marked as user-overridable or admin-only, with advanced options automatically grouped separately.

Collection Sections Plugin Updates

External sections will work as-is without any changes as the new capabilities are optional. The existing Collection Sections plugin PR is for testing and demonstrating how an external plugin can use these new features.
That PR adds section info as well as new configurations for:

• Sort Order - Default, Date Added, Alphabetical, Random, Rating, Release Date, Recently Watched
• Sort Direction - Ascending or Descending
• Watched Items Handling - Show or Hide watched content
• Item Limit - Maximum number of items to display (1-100)
  In addition the synthetic options "Custom Display Name" and "Section Header Display" are automatically added without any changes from the collections plugin.

It also uses the new /HomeScreen/Ready which resolves IAmParadox27/jellyfin-plugin-collection-sections#4

Admin Configuration

• New Debug tab - This is handy for seeing the current plugin and user configurations
• Sections are now sorted by order
• Sections are now expandable and show the section info, section configurations, and per-option user overrides

User Configuration

• Sections are now expandable and show the section info and any configurable (useroverride=true) options.

Other features added

• My List updates
  • Header now links to a user's My List playlist or plalylist library
  • Configurable "Sort By" dropdown. Supports "Playlist Order", "Date Added To Server", "Alphabetical", "Release Date", "Random", "Recently Watched"
  • Configurable "Sort Direction" dropdown. Supports "Ascending", "Descending"
  • Configurable "Watched Items Handling" dropdown. Supports "Show", "Hide". A "Remove" option could be added in the future.
  • Configurable "Experimental: Show Placeholder When Empty" checkbox. Experimental, currently creates a placeholder BaseItemDto which links to the user's playlists. Implementation is not complete. Should I delete this?
  • Configurable "Item Limit" numberbox. Number of items for the home section to load.
• Because You Watched updates
  • Configurable "Enable Rewatching" checkbox. Shows/hides already watched episodes.
• Respect User Homepage Setting: Option to honor existing user homepage preferences (current behavior) instead of overriding them. default=true

TODO

• Merge: Resolve the "Respect User Homepage" settings conflict
• More testing
  • Upgrade testing
  • 10.11 testing
  • New configuration testing
• Delete the MyList test options

[IAmParadox27]

Sorry to prod again - are we any closer with this PR 🙏 super excited by it and kinda waiting for it to be merged before making a start on some other things

[IAmParadox27]

I've done the process to try and resolve the issues and merged it into the experimental branch. There are issues that I'm sure you're aware of, if you're around to take a look it'd be greatly appreciated, otherwise I'll start having a look over the week and trying to resolve some of the issues :)

[ChandlerMoeller]

Hi, sorry for my disappearance and not circling back after you merged this into the experimental branch. Life got busy. You were right there were issues, the 2 big ones that got me were the config ui and trying to wrangle the json per-user backend read/writes. Glad to see the per-section settings is landing in v12!

Rather than trying to revive this, I would like to close this draft and contribute some (much smaller) PRs on top of your implementation in v12, if that's welcome.

A few things I had in mind:

1. Splitting data type from UI type - I propose splitting the config types into a data type (string, bool, integer, double) and ui type (checkbox, dropdown, number box, etc). Then the backend can validate by its real type instead of everything being treated as a string. It would also allow updating a fronted ui type from one to another, or even sharing a same backend data type on different configurations, etc.

2. Per-option user overrides - Implemented in this old PR, messy. I would like to do a different approach, with sqlite rather than json. There is already plugin precedent for this in the official playback reporting plugin. Only the per-user values would be stored in the sqlite, admin's xml would be untouched.

If that sounds good, since Jellyfin is moving towards EFCore, would you prefer I match that or keep it slightly simpler with plain Microsoft.Data.sqlite?

3. Adding cutom config resgistration to the external plugin registration - Implemented in this old PR (and in the old collections plugin PR), split it out.

Totally understand if you already have a plan or direction for the custom config system that I'm not aware of, it has been awhile.

[IAmParadox27]

Hi, sorry for my disappearance and not circling back after you merged this into the experimental branch. Life got busy. You were right there were issues, the 2 big ones that got me were the config ui and trying to wrangle the json per-user backend read/writes. Glad to see the per-section settings is landing in v12!

All good! Life happens.

Rather than trying to revive this, I would like to close this draft and contribute some (much smaller) PRs on top of your implementation in v12, if that's welcome.

I think this makes a lot of sense for sure!

1. Splitting data type from UI type - I propose splitting the config types into a data type (string, bool, integer, double) and ui type (checkbox, dropdown, number box, etc). Then the backend can validate by its real type instead of everything being treated as a string. It would also allow updating a fronted ui type from one to another, or even sharing a same backend data type on different configurations, etc.

Yeah this is fine

2. Per-option user overrides - Implemented in this old PR, messy. I would like to do a different approach, with sqlite rather than json. There is already plugin precedent for this in the official playback reporting plugin. Only the per-user values would be stored in the sqlite, admin's xml would be untouched.

If that sounds good, since Jellyfin is moving towards EFCore, would you prefer I match that or keep it slightly simpler with plain Microsoft.Data.sqlite?

As things stand I've not been able to get plugin pages to work on v12 so haven't done anything with user side config yet, its definitely worth supporting and the page itself will remain the same so if you want to adapt this into user configurability etc then feel free.

Yes please to EF Core.

3. Adding cutom config resgistration to the external plugin registration - Implemented in this old PR (and in the old collections plugin PR), split it out.

Yep this makes a lot of sense to do as well

[IAmParadox27]

With all your PRs please base them against the v12 branch rather than main since I won't be merging for a little while