انتقل إلى المحتوى
تجربة مجانية 14 يومًا، بلا بطاقة9 لغات176 نوع عمل · 50 تطبيقًا
AR· USD
جرّب عرضًا حيًاابدأ التجربة المجانية

هذه الصفحة غير متاحة بلغة العربية بعد، لذا تُعرض بالإنجليزية.

Dashboard widgets from a plugin

Declare a widget in module.json, render plain data in register(), and let the dashboard draw, validate and sanitise it.

  • about 8 min

A plugin widget joins the dashboard catalogue as plugin:<pluginId>:<widgetId> and takes part in Customise (show / hide / order / size), the shared default layout and the “New” badges exactly like built-in widgets. It is shown only while the plugin is enabled and the user holds one of its perms.

module.json → widgets
"widgets": [
  {
    "id": "upcoming",
    "title": "Upcoming site visits",
    "description": "The next planned site visits with customer and day.",
    "group": "Operations",
    "size": "sm",
    "perm": ["sitevisits.view"],
    "visible": true
  }
]

Rules: id matches ^[a-z][\w-]{0,40}$ and is unique in the plugin; description has at least 12 characters; group is one of Overview, Sales, Money, Operations, People, Website, System (default System); size is sm, md or lg (default sm); at most 12 widgets per plugin.

register() → widgets
widgets: {
  // ctx = { pluginId, log, userId, may, now, size }
  upcoming: async (ctx) => {
    const rows = await prisma.siteVisit.findMany({ where: { status: "PLANNED", plannedAt: { gte: ctx.now } }, orderBy: { plannedAt: "asc" }, take: 5 });
    return {
      kind: "list",
      href: "/admin/site-visits",
      linkLabel: "All visits",
      empty: "No visits planned.",
      items: rows.map((r) => ({ title: r.customerName, subtitle: r.slot, meta: r.plannedAt.toISOString().slice(0, 10), href: "/admin/site-visits?id=" + r.id })),
    };
  },
},
Widgets return data, not JSX. The dashboard draws it with the generic card (src/components/admin/dashboard/widgets/plugin.tsx), validates it with zod and shows links only when the user may open them. Each widget streams in its own Suspense boundary, so a slow widget delays only itself — but keep the query cheap: it runs on every dashboard load.

Written from: docs/PLUGIN-DEVELOPER-GUIDE.md, src/lib/plugins/types.ts, src/lib/plugins/widgets.ts, src/components/admin/dashboard/widgets/plugin.tsx