🔌 Plugin Development Guide

public interface IPlugin
{
    // ========================================================================
    // REQUIRED PROPERTIES
    // ========================================================================
    
    // Unique identifier for this plugin (e.g., "BlazorBlueprint.Plugins.MyPlugin")
    // Used internally to identify the plugin in settings and databases
    // Must be unique across all plugins
    string Id { get; }
    
    // Display name shown in PluginManagement UI (e.g., "My Awesome Plugin")
    // This is what users see when browsing available plugins
    string Name { get; }
    
    // Plugin version using semantic versioning (e.g., "1.0.0")
    // Follows Major.Minor.Patch format
    string Version { get; }
    
    // Description of what the plugin does
    // Shown in PluginManagement to help users understand the plugin's purpose
    string Description { get; }
    
    // Plugin author name (e.g., "Your Name" or "Your Company")
    // Shown in PluginManagement for attribution
    string Author { get; }
    
    // Category helps organize plugins in the UI (e.g., "Communication", "Utility")
    // Used for filtering and grouping in PluginManagement
    string Category { get; }
    
    // Whether this plugin requires a premium license
    // Set to true if plugin requires payment or subscription
    bool IsPremium { get; }
    
    // Whether the plugin is currently enabled for the site
    // Managed by PluginManager - don't set this manually
    bool IsEnabled { get; set; }

    // ========================================================================
    // LIFECYCLE METHODS
    // ========================================================================
    
    // Called during application startup to register plugin services
    // Register your services here using dependency injection
    // Example: services.AddScoped<IMyService, MyService>();
    Task RegisterServicesAsync(IServiceCollection services, IConfiguration configuration);
    
    // Called during app configuration (after service registration)
    // Use this to configure middleware, SignalR hubs, etc.
    // Example: app.MapHub<MyHub>("/hubs/myhub");
    Task ConfigureAppAsync(WebApplication app);
    
    // Called after application is fully started
    // Use this for initialization that requires all services to be ready
    // Example: Initialize background workers, cache warmup, etc.
    Task OnApplicationStartupAsync(IServiceProvider serviceProvider, CancellationToken cancellationToken = default);
    
    // ========================================================================
    // INTEGRATION METHODS
    // ========================================================================
    
    // Returns navigation menu items for the main sidebar
    // These links appear in the navigation menu for all users
    // Return empty if plugin doesn't need navigation items
    IEnumerable<PluginNavItem> GetNavigationItems(IServiceProvider? serviceProvider = null);

    // Returns admin pages that appear in PluginManagement
    // These pages are shown as quick action buttons/links
    // Return empty if plugin doesn't have admin pages
    IEnumerable<PluginAdminPage> GetAdminPages();
    
    // Returns routes (pages) your plugin provides
    // Each route maps a URL to a Blazor component
    // Routes are automatically registered when plugin is enabled
    IEnumerable<PluginRoute> GetRoutes();

    // ========================================================================
    // SITE SETUP
    // ========================================================================
    
    // Called when a new site is created
    // Use this to set up default data, create default settings, etc.
    // Returns true if setup succeeded, false otherwise
    // Example: Create default chat groups, initialize AI models, etc.
    Task<bool> SetupNewOrganisationAsync(Organisation organisation, string adminUserId = null, IServiceProvider? serviceProvider = null);
    
    // ========================================================================
    // LAYOUT COMPONENTS
    // ========================================================================
    
    // Returns layout components paired with the slot the host should render them in:
    // Header (sticky-friendly, top of page-content scroll), Footer (below page body),
    // or Floating (outside the layout — for position:fixed overlays like chat bubbles).
    // Return empty if plugin doesn't need layout components
    IEnumerable<LayoutComponentRegistration> GetLayoutComponents(IServiceProvider? serviceProvider = null);
}

# Create new Razor Class Library project
dotnet new razorclasslib -n BlazorBlueprint.Plugins.MyPlugin
cd BlazorBlueprint.Plugins.MyPlugin

# Add project references
dotnet add reference ..\..\Core\BlazorBlueprint.Application\BlazorBlueprint.Application.csproj
dotnet add reference ..\..\Core\BlazorBlueprint.Domain\BlazorBlueprint.Domain.csproj

// Import necessary namespaces
using BlazorBlueprint.Application.Plugins;        // PluginBase class
using BlazorBlueprint.Application.Interfaces;     // IPlugin interface
using BlazorBlueprint.Domain.Constants;          // ApplicationRoleConstants for authorization
using Microsoft.Extensions.DependencyInjection;    // IServiceCollection for DI
using Microsoft.Extensions.Configuration;        // IConfiguration for settings

namespace BlazorBlueprint.Plugins.MyPlugin;

/// <summary>
/// Main plugin class - inherits from PluginBase for convenience
/// PluginBase provides helper methods and default implementations
/// </summary>
public class MyPlugin : PluginBase
{
    // ========================================================================
    // REQUIRED PROPERTIES - These must be overridden
    // ========================================================================
    
    /// <summary>
    /// Unique identifier for this plugin.
    /// Convention: "BlazorBlueprint.Plugins.{PluginName}"
    /// This ID must be unique across all plugins.
    /// </summary>
    public override string Id => "BlazorBlueprint.Plugins.MyPlugin";
    
    /// <summary>
    /// Display name shown in PluginManagement UI.
    /// This is what users see in the plugin list.
    /// </summary>
    public override string Name => "My Plugin";
    
    /// <summary>
    /// Plugin version using semantic versioning (Major.Minor.Patch).
    /// Update this when you release new versions.
    /// </summary>
    public override string Version => "1.0.0";
    
    /// <summary>
    /// Description of what the plugin does.
    /// Shown in PluginManagement to help users understand the plugin.
    /// </summary>
    public override string Description => "A sample plugin that demonstrates basic functionality";
    
    /// <summary>
    /// Plugin author name.
    /// Your name or organization name.
    /// </summary>
    public override string Author => "Your Name";
    
    // ========================================================================
    // OPTIONAL PROPERTIES - These have default implementations in PluginBase
    // ========================================================================
    
    /// <summary>
    /// Category helps organize plugins in the UI.
    /// Examples: "Communication", "E-commerce", "Social", "Utility"
    /// </summary>
    public override string Category => "Utility";
    
    /// <summary>
    /// Whether this is a premium/paid plugin.
    /// Set to true if the plugin requires a license or subscription.
    /// </summary>
    public override bool IsPremium => false;

    // ========================================================================
    // REGISTER SERVICES (REQUIRED METHOD)
    // ========================================================================
    
    /// <summary>
    /// Registers services your plugin needs in dependency injection.
    /// This is called when the application starts up.
    /// Services registered here can be injected into your pages and components.
    /// </summary>
    public override async Task RegisterServicesAsync(IServiceCollection services, IConfiguration configuration)
    {
        // Register your plugin's services here
        // AddScoped means a new instance is created for each HTTP request
        // Other options: AddSingleton (one instance for entire app), AddTransient (new instance every time)
        services.AddScoped<IMyService, MyService>();
        
        // You can also register:
        // - Background services: services.AddHostedService<MyBackgroundService>();
        // - Options/configuration: services.Configure<MyOptions>(options => { ... });
        // - Repositories, other services, etc.
        
        await Task.CompletedTask; // Required for async method
    }

    // ========================================================================
    // REGISTER ROUTES (REQUIRED METHOD)
    // ========================================================================
    
    /// <summary>
    /// Defines the routes (pages) your plugin provides.
    /// Each route maps a URL to a Blazor component/page.
    /// Routes are automatically registered when the plugin is enabled.
    /// </summary>
    public override IEnumerable<PluginRoute> GetRoutes()
    {
        // 1. Main plugin landing page (the "app dashboard")
        // This is where users go when they click the plugin tile in /apps
        // or the Apps link in the user-dropdown.
        // Plugin's main entry — renders under MainLayout with the host's
        // PluginSectionNav sidebar (replaces the platform NavMenu while inside the
        // plugin). Settings + admin-only pages live under /admin/plugin/{pluginname}/*.
        yield return new PluginRoute
        {
            Route = "/plugin/myplugin",                             // Canonical dashboard URL
            ComponentType = typeof(Web.Pages.Admin.Index),        // The Razor component to render
            RequiresAuthentication = true,                        // Must be logged in
            RequiredRole = ApplicationRoleConstants.ORGANISATIONADMIN    // Must have ORGANISATIONADMIN role
        };

        // 2. Public route - accessible to everyone
        // This page appears in the main navigation menu
        // Route: /plugin/myplugin/mypage
        // CreatePublicRoute is a helper method from PluginBase
        // It automatically constructs the route: /plugin/{pluginname}/mypage
        yield return CreatePublicRoute("mypage", typeof(Web.Pages.MyPage));

        // 3. Admin route - settings page
        // Only ORGANISATIONADMIN users can access this
        // Route: /admin/plugin/myplugin/settings — renders under AdminLayout
        // because it has a "deeper" path segment after the plugin name.
        // CreateAdminRoute is a helper that constructs: /admin/plugin/{pluginname}/settings
        yield return CreateAdminRoute("settings", typeof(Web.Pages.Admin.Settings), ApplicationRoleConstants.ORGANISATIONADMIN);
    }

    // ========================================================================
    // NAVIGATION ITEMS (OPTIONAL METHOD)
    // ========================================================================

    /// <summary>
    /// Adds items to the main navigation menu.
    /// These links appear in the sidebar navigation for all users (or based on auth requirements).
    /// This method is optional - omit it if your plugin doesn't need navigation items.
    /// </summary>
    public override IEnumerable<PluginNavItem> GetNavigationItems(IServiceProvider? serviceProvider = null)
    {
        // IMPORTANT: Choose ONE of the following options, not both!
        // If you yield return multiple items with the same title, you'll get duplicates.

        // ===== OPTION 1: Simple navigation item - direct link =====
        // This creates a single menu item that links directly to your page
        yield return CreateNavItem(
            title: "My Plugin",                           // Text shown in menu
            href: "/plugin/myplugin/mypage",              // URL to navigate to
            icon: "Settings",                              // Icon name (FluentUI icon)
            order: 50,                                     // Position in menu (lower = higher up)
            requiresAuth: false                            // Whether user must be logged in
        );
    }

    // ========================================================================
    // ADMIN PAGES (OPTIONAL METHOD)
    // ========================================================================
    
    /// <summary>
    /// Defines admin pages that appear in PluginManagement and your plugin's index page.
    /// These pages are shown as quick action buttons/links.
    /// This method is optional - omit it if your plugin doesn't have admin pages.
    /// </summary>
    public override IEnumerable<PluginAdminPage> GetAdminPages()
    {
        // These admin pages appear in the admin nav's Plugins group.
        // Direct URL: /admin/plugin/myplugin/{pagename} — renders under AdminLayout.
        // Only list genuinely admin / configuration pages here — user-facing dashboard
        // pages live at /plugin/myplugin/* and are reached via the host PluginSectionNav.

        // Settings page - order 100 (appears first)
        yield return CreateAdminPage(
            title: "Settings",                             // Display name
            pageName: "settings",                          // URL segment (becomes /admin/plugin/myplugin/settings)
            icon: "Settings",                              // Icon name for display
            order: 100                                     // Display order (lower = appears first)
        );
    }
}

# Add plugin to solution
dotnet sln add BlazorBlueprint.Plugins.MyPlugin

<ItemGroup>
  <ProjectReference Include="..\..\Plugins\BlazorBlueprint.Plugins.MyPlugin\BlazorBlueprint.Plugins.MyPlugin.csproj" />
</ItemGroup>

<ItemGroup>
  <ProjectReference Include="..\..\Plugins\MyPlugin\MyPlugin.csproj" />
</ItemGroup>

Web/
└── Plugins/
    └── MyPlugin/
        ├── MyPlugin.dll
        ├── MyPlugin.deps.json
        └── [dependencies]

"Plugins": {
  "BlazorBlueprint.Plugins.Cms": {
    "AutoInstall": true,    // run SetupNewOrganisationAsync for every new org created via
                            // initial-setup or /Org/Select. false = the plugin is loaded
                            // and visible in /Admin/PluginManagement, but org admins must
                            // click Install manually per org.

    "Disabled":    false    // emergency kill switch. true = RegisterServicesAsync is
                            // skipped, ConfigureAppAsync never runs, services are not in
                            // DI. Existing orgs' OrganisationPlugins blob is preserved
                            // but functionally inert. Use this to disable a misbehaving
                            // plugin in prod via config + restart, no redeploy required.
  }
}