infra.page

Widget System

Understand how infrapage's three-layer widget architecture works.

Widget System

Widgets are the building blocks of infrapage. Every dashboard page is composed of widgets arranged in a grid. The system is designed to be extensible — each widget type fetches data from a different source and renders it as a card.

Three-Layer Architecture

Every widget in infrapage consists of three layers:

1

Widget Instance (Config)

Stored in MongoDB as part of the page document. Contains the widget's kind, configuration parameters (like a GitHub repo URL or an API endpoint), and grid position (x, y, width, height).

json
{
      "kind": "GitHubRepo",
      "config": {
        "owner": "hauju",
        "repo": "infrapage"
      },
      "w": 1,
      "h": 1,
      "x": 0,
      "y": 0
    }
2

Widget Data (Fetched)

The runtime data fetched from external APIs based on the widget's configuration. For a GitHub repo widget, this would include star count, language, description, and last updated time.

Each widget kind has its own data struct — the `WidgetData` enum dispatches to the correct fetcher.
3

Widget Component (Render)

A Dioxus component that takes the fetched data and renders it as a DaisyUI card. Each widget kind has a dedicated component in src/components/widgets/.

Two-Phase Loading

Public pages use a two-phase approach for optimal performance:

  1. SSR Phase — use_server_future fetches the page metadata from MongoDB. The HTML shell renders immediately with widget skeletons (loading placeholders).
  2. Hydration Phase — Each widget independently calls fetch_widget_data() via use_resource. Widgets render as their data arrives.

Widget Sizes

Widgets support three size presets in the 4-column grid:

Size Grid Columns Description
Normal 1 column Default compact card
Wide 2 columns Extended view with more detail
Large 4 columns Full-width with comprehensive data

Not every widget supports all sizes — each kind defines which sizes are allowed.

Grid Editor

In edit mode, infrapage uses GridStack.js for drag-and-drop widget arrangement:

  • Drag widgets to reposition them
  • Resize using edge handles (east and south)
  • Delete by dragging to the trash zone
  • Double-click to edit widget configuration

The grid layout is saved to MongoDB when you exit edit mode.

Navigation