Widgets
Widgets are the building blocks for plugin admin pages. Build a page by passing a list of
widgets to ViewBuilder.generate().
Building a page
from fastpluggy.core.dependency import get_view_builder
@router.get("/my-page", response_class=HTMLResponse)
def my_page(request: Request, view_builder=Depends(get_view_builder)):
return view_builder.generate(
request,
title = "My Page",
widgets = [TableWidget(...), ButtonListWidget(...)],
)
Data widgets
TableWidget
Sortable data table from a list of dicts.
from fastpluggy.core.widgets import TableWidget
TableWidget(
data = [{"name": "Alice", "role": "admin"}, ...],
title = "Users",
title_icon = "ti ti-users",
fields = ["name", "role"], # explicit column order
headers = {"name": "Full Name"}, # column label overrides
exclude_fields = ["password"],
field_callbacks = {"role": render_role_badge},# callable(value) → HTML string
links = [EditButton(...)], # action buttons per row
sortable = True,
)
TableModelWidget
Same as TableWidget but reads columns and rows from a SQLAlchemy model.
ModelWidget
Displays a Pydantic model's fields in a read-only key/value table.
DebugWidget
Renders arbitrary data as formatted JSON. Useful during development.
TracebackWidget
Displays a Python traceback list (used automatically in the plugin error panel).
Input widgets
FormWidget
Auto-generates a form from a Pydantic model. Submits to the current URL via POST. Checkbox fields handle the absent-means-False HTML behavior correctly.
from fastpluggy.core.widgets import FormWidget
FormWidget(
model = MySettings, # class or instance
data = current_settings, # instance with current values
readonly_fields = ["namespace"],
)
ButtonWidget
A single button. Renders as <a> for URL navigation or <form><button> for POST actions.
from fastpluggy.core.widgets.categories.input.button import ButtonWidget
ButtonWidget(label="Export", url="/my/export", css_class="btn btn-secondary")
FunctionButtonWidget
A button that calls a Python function directly via POST to /execute.
from fastpluggy.core.widgets.categories.input.button import FunctionButtonWidget
FunctionButtonWidget(
call = my_service_function,
label = "Run",
icon = "ti ti-play me-1",
css_class = "btn btn-primary",
param_inputs = {"plugin_name": plugin_name},
condition = some_bool_or_callable,
onclick = "return confirm('Sure?');",
)
param_inputs values support <field_name> placeholders substituted from the row dict
when the button is used inside a TableWidget via links.
AutoLinkWidget
A button that navigates to a named FastAPI route.
from fastpluggy.core.widgets.categories.input.button import AutoLinkWidget
AutoLinkWidget(route_name="my_dashboard", label="Go to Dashboard")
ButtonListWidget
A collection of buttons with flexible layout options.
from fastpluggy.core.widgets.categories.input.button_list import ButtonListWidget
ButtonListWidget(
buttons = [FunctionButtonWidget(...), AutoLinkWidget(...)],
title = "Actions",
layout = "horizontal", # "horizontal" | "vertical"
style = "list", # "list" (spaced) | "group" (Bootstrap btn-group)
button_size = "md", # "sm" | "md" | "lg"
)
Display widgets
CustomTemplateWidget
Include any Jinja2 template with custom context. The widget variable in the template
holds the widget instance (context keys are also set as attributes on it).
from fastpluggy.core.widgets.categories.display.custom import CustomTemplateWidget
CustomTemplateWidget(
template_name = "my_plugin/my_card.html.j2",
context = {"data": my_data},
)
Layout widgets
TabbedWidget
Wraps other widgets in a Bootstrap tab interface. None values are filtered out,
so conditional tabs are safe to pass directly.