FastPluggy Widget System

A clean, extensible widget architecture for FastPluggy with auto-registration and GlobalRegistry integration.

🚀 Features

• ✅ Clean Widget Classes - No decorators, just class attributes
• ✅ Auto-Registration - Widgets register themselves via __init_subclass__
• ✅ GlobalRegistry Integration - Uses FastPluggy's extend_globals()
• ✅ Plugin Support - Easy runtime widget registration
• ✅ Recursion-Safe - Single rendering path with depth protection
• ✅ IDE-Friendly - Full autocomplete and navigation support

📁 Architecture

fastpluggy/core/widgets/
├── base.py                     # AbstractWidget & WidgetRegistry
├── fastpluggy_integration.py   # GlobalRegistry integration
└── categories/                 # Organized widget categories
    ├── layout/                 # GridWidget, ContainerWidget
    ├── display/                # CardWidget, AlertWidget, StatsWidget
    ├── data/                   # TableWidget, ListWidget
    ├── input/                  # FormWidget, ButtonWidget
    └── debug/                  # DebugPanelWidget

🎯 Quick Start

1. Create Widgets

from fastpluggy.core.widgets import AlertWidget, CardWidget, StatsWidget, GridWidget

# Simple alert
alert = AlertWidget(
    message="Welcome to the widget system!",
    alert_type="success"
)

# Stats widgets
stats = [
    StatsWidget(title="Users", value="1,234", icon="users", color="primary"),
    StatsWidget(title="Revenue", value="$45,678", icon="dollar-sign", color="success"),
]

# Responsive grid
grid = GridWidget.create_responsive_grid(stats, cols_md=2)

# Content card
card = CardWidget(
    title="Dashboard",
    content="<p>Your dashboard content here.</p>"
)

2. Render Widgets

from fastpluggy.core.view_builder import ViewBuilder

# Widgets are automatically registered when imported
# Just render them directly
widgets = [alert, grid, card]
view_builder = ViewBuilder()
view_builder.templates = templates

return view_builder.generate(request, widgets, title="My Dashboard")

🔌 Plugin Widgets

Create Plugin Widget

from fastpluggy.core.widgets import AbstractWidget

class MapWidget(AbstractWidget):
    widget_type = "map"
    template_name = "plugins/maps/map.html.j2"
    category = "maps"
    description = "Interactive map widget"
    icon = "map"

    def __init__(self, lat=0, lng=0, **kwargs):
        super().__init__(**kwargs)
        self.lat = lat
        self.lng = lng

    def process(self, **kwargs):
        # Process map data
        pass

Register Plugin

# Register plugin widgets with FastPluggy
FastPluggyWidgets.register_plugin_widgets('maps', [MapWidget])

🛠️ Advanced Usage

Widget Factory

# Create widgets dynamically
create_widget = FastPluggyWidgets.create_widget_factory()

alert = create_widget('alert', message="Dynamic!", alert_type="info")
card = create_widget('card', title="Dynamic Card")

Custom Widget Categories

class AnalyticsWidget(AbstractWidget):
    widget_type = "analytics_chart"
    template_name = "analytics/chart.html.j2"
    category = "analytics"
    # Automatically registered!

Debug Registry

# See all registered widgets
FastPluggyWidgets.print_registry()

# Get specific widgets
widgets = FastPluggyWidgets.get_widget_registry()

🚀 Run Examples

# Basic usage
python examples/widget/basic_usage.py

# Plugin examples
python examples/widget/plugin_example.py

# Visit: http://localhost:8000

📝 Template Structure

Templates automatically resolve via the universal renderer:

{# One line replaces complex routing #}
{{ render_widget(widget, request) }}