Replace DashboardWidgetAdmin with widget_action decorator. (no backward compatibility).

Author: vsdudakov

docs/build.py

@@ -42,6 +42,13 @@ def read_cls_docstring(cls):
 
 def get_versions():
     return [
+        {
+            "version": "0.4.2",
+            "changes": [
+                "Replace DashboardWidgetAdmin with widget_action decorator. (no backward compatibility)",
+                "Fix mobile view.",
+            ],
+        },
         {
             "version": "0.4.1",
             "changes": [
@@ -372,8 +379,6 @@ def get_sections():
 
 
 def get_page_context(page_url):
-    from docs.code.dashboard import djangoorm as dashboard_djangoorm
-    from docs.code.dashboard import tortoise as dashboard_tortoise
     from docs.code.inlines import tortoise as inlines_tortoise
     from docs.code.models import tortoise as models_tortoise
     from docs.code.quick_tutorial import django as quick_tutorial_django
@@ -384,8 +389,17 @@ def get_page_context(page_url):
     from docs.code.quick_tutorial import sqlalchemy as quick_tutorial_sqlalchemy
     from docs.code.quick_tutorial import tortoise as quick_tutorial_tortoise
 
-    from fastadmin import DashboardWidgetAdmin, DashboardWidgetType, InlineModelAdmin, ModelAdmin, WidgetType
+    from fastadmin import InlineModelAdmin, ModelAdmin, WidgetType, widget_action
     from fastadmin.models.base import BaseModelAdmin
+    from fastadmin.models.schemas import (
+        WidgetActionArgumentProps,
+        WidgetActionChartProps,
+        WidgetActionFilter,
+        WidgetActionInputSchema,
+        WidgetActionProps,
+        WidgetActionResponseSchema,
+        WidgetActionType,
+    )
 
     match page_url:
         case "#introduction":
@@ -553,61 +567,63 @@ def get_page_context(page_url):
                 },
             ]
         # widgets
-        case "#registering-widgets":
+        case "#widget-methods-and-attributes":
             return [
                 {
-                    "type": "text-lead",
-                    "content": "Register dashboard widgets",
+                    "type": "text",
+                    "content": (
+                        "Use the @widget_action decorator on ModelAdmin methods to declare "
+                        "dashboard widgets and actions. The decorator attaches metadata used "
+                        "to render chart widgets and action forms on the dashboard."
+                    ),
                 },
+                {"type": "code-python", "content": inspect.getsource(widget_action)},
                 {
-                    "type": "tabs",
-                    "id": "register_dashboard_widgets",
-                    "content": [
-                        {
-                            "name": "Tortoise ORM",
-                            "id": "dashboard_tortoise_orm",
-                            "content": [{"type": "code-python", "content": inspect.getsource(dashboard_tortoise)}],
-                        },
-                        {
-                            "name": "Django ORM",
-                            "id": "dashboard_django_orm",
-                            "content": [{"type": "code-python", "content": inspect.getsource(dashboard_djangoorm)}],
-                        },
-                        {
-                            "name": "SQLAlchemy",
-                            "id": "dashboard_sql_alchemy",
-                            "content": [{"type": "alert-info", "content": "See the Tortoise ORM example above."}],
-                        },
-                        {
-                            "name": "Pony ORM",
-                            "id": "dashboard_pony_orm",
-                            "content": [{"type": "alert-info", "content": "See the Tortoise ORM example above."}],
-                        },
-                    ],
+                    "type": "text",
+                    "content": (
+                        "Widget actions use the following types for configuration "
+                        "(chart props, arguments, filters and payload schema):"
+                    ),
                 },
-            ]
-        case "#widget-methods-and-attributes":
-            return [
                 {
-                    "type": "text",
-                    "content": "The following methods and attributes are available for dashboard widget admins:",
+                    "type": "code-python",
+                    "content": "\n\n".join(
+                        [
+                            inspect.getsource(WidgetActionChartProps),
+                            inspect.getsource(WidgetActionArgumentProps),
+                            inspect.getsource(WidgetActionProps),
+                            inspect.getsource(WidgetActionFilter),
+                            inspect.getsource(WidgetActionInputSchema),
+                            inspect.getsource(WidgetActionResponseSchema),
+                        ]
+                    ),
                 },
-                {"type": "code-python", "content": inspect.getsource(DashboardWidgetAdmin)},
                 {
                     "type": "alert-warning",
-                    "content": f"See <a href='{ANTD_CHARTS_EXAMPLES}' target='_blank'>antd charts</a> for <code>x_field_filter_widget_props</code>.",
+                    "content": (
+                        "If you call @widget_action() without arguments, FastAdmin uses the "
+                        "documented defaults: tab='Default', title='Action', "
+                        "widget_action_type=WidgetActionType.Action and no props or filters."
+                    ),
                 },
             ]
         case "#widget-chart-types":
             return [
                 {
                     "type": "text",
-                    "content": "The FastAdmin dashboard supports the following widget types:",
+                    "content": (
+                        "The FastAdmin dashboard supports the following widget action types for charts and actions:"
+                    ),
                 },
-                {"type": "code-python", "content": inspect.getsource(DashboardWidgetType)},
+                {"type": "code-python", "content": inspect.getsource(WidgetActionType)},
                 {
                     "type": "alert-warning",
-                    "content": f"See <a href='{ANTD_CHARTS_EXAMPLES}' target='_blank'>antd charts</a> for more details (e.g. how they look).",
+                    "content": (
+                        "Chart-* widget actions render charts on the dashboard; the Action "
+                        "type renders a simple action widget. See "
+                        f"<a href='{ANTD_CHARTS_EXAMPLES}' target='_blank'>antd charts</a> "
+                        "for more details (e.g. how they look)."
+                    ),
                 },
             ]
         # models

docs/code/dashboard/__init__.py

@@ -4,7 +4,16 @@
 from tortoise import fields
 from tortoise.models import Model
 
-from fastadmin import TortoiseModelAdmin, WidgetType, action, register
+from fastadmin import TortoiseModelAdmin, WidgetType, action, register, widget_action
+from fastadmin.models.schemas import (
+    WidgetActionArgumentProps,
+    WidgetActionChartProps,
+    WidgetActionFilter,
+    WidgetActionInputSchema,
+    WidgetActionProps,
+    WidgetActionResponseSchema,
+    WidgetActionType,
+)
 
 
 class ModelUser(Model):
@@ -38,7 +47,7 @@ class UserAdmin(TortoiseModelAdmin):
     )
     formfield_overrides = {  # noqa: RUF012
         "username": (WidgetType.SlugInput, {"required": True}),
-        "password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
+        "hash_password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
         "avatar_url": (
             WidgetType.UploadImage,
             {
@@ -52,9 +61,13 @@ class UserAdmin(TortoiseModelAdmin):
         "activate",
         "deactivate",
     )
+    widget_actions = (
+        "users_chart",
+        "users_action",
+    )
 
     async def authenticate(self, username: str, password: str) -> int | None:
-        user = await self.model_cls.filter(phone=username, is_superuser=True).first()
+        user = await self.model_cls.filter(username=username, is_superuser=True).first()
         if not user:
             return None
         if not bcrypt.checkpw(password.encode(), user.hash_password.encode()):
@@ -80,3 +93,68 @@ async def upload_file(self, field_name: str, file_name: str, file_content: bytes
         # save file to media directory or s3/filestorage, then return the file url
         url = f"/media/{file_name}"
         return url
+
+    @widget_action(
+        widget_action_type=WidgetActionType.ChartLine,
+        widget_action_props=WidgetActionChartProps(x_field="x", y_field="y"),
+        widget_action_filters=[
+            WidgetActionFilter(
+                field_name="x",
+                widget_type=WidgetType.DatePicker,
+            ),
+        ],
+        tab="Analytics",
+        title="Users over time",
+        description="Line chart of active users over time",
+        width=24,
+    )
+    async def users_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
+        # In a real project you would aggregate using payload.query filters.
+        return WidgetActionResponseSchema(
+            data=[
+                {
+                    "x": "2026-01-01",
+                    "y": 10,
+                },
+                {
+                    "x": "2026-01-02",
+                    "y": 15,
+                },
+                {
+                    "x": "2026-01-03",
+                    "y": 7,
+                },
+            ],
+        )
+
+    @widget_action(
+        widget_action_type=WidgetActionType.Action,
+        widget_action_props=WidgetActionProps(
+            arguments=[
+                WidgetActionArgumentProps(
+                    name="since",
+                    widget_type=WidgetType.DatePicker,
+                    widget_props={
+                        "required": True,
+                    },
+                ),
+            ],
+        ),
+        tab="Data",
+        title="Export users",
+        description="Return a simple table of users created since a date",
+        width=12,
+    )
+    async def users_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
+        return WidgetActionResponseSchema(
+            data=[
+                {
+                    "id": 1,
+                    "username": "alice",
+                },
+                {
+                    "id": 2,
+                    "username": "bob",
+                },
+            ],
+        )