Widget System

Modular, extensible widget framework for customizable group dashboards

Overview

The OMOBL Widget System provides a powerful, flexible framework for creating rich, interactive group dashboards. Widgets are reusable components that can be configured, positioned, and customized per group.

Security: The widget system uses a secure registry pattern to prevent arbitrary code execution. Only pre-approved widgets from the registry can be loaded.

Architecture

Core Components

Widget Registry

lib/widgets/registry.tsx

Central registry mapping widget keys to React components. Ensures type safety and prevents arbitrary code execution.

Widget Definition

Database model

Metadata about widgets including name, category, config schema, default size, and permissions.

Group Widget Config

Database model

Per-group widget instances with position, settings, enabled/required status, and display order.

WidgetGrid Component

components/widgets/WidgetGrid.tsx

Renders widgets in a responsive grid layout, handles loading states, and manages widget lifecycle.

System Widgets

OMOBL SSO includes 6 built-in system widgets available to all groups:

Community Metrics

Real-time community analytics

Analytics

Overview metrics showing member growth, engagement, app adoption, and builder activity.

Key: community-metrics

Scope: Group

Realtime: Yes

Projects

Subgroup and project management

Content

Grid view of all projects (subgroups) with member counts, apps, and energy levels.

Key: project-grid

Scope: Group

Realtime: No

Activity Feed

Live community activity stream

Social

Real-time feed of community activity including member joins, app usage, and milestones.

Key: activity-feed

Scope: Group

Realtime: Yes

Onboarding Workflows

Member onboarding journeys

Productivity

List of active onboarding workflows for new members and admins with progress tracking.

Key: onboarding-workflows

Scope: Group

Permissions: Group Admin

Calendar

Event management and scheduling

Productivity

Integrated calendar with Google Calendar and Outlook sync, event management, and scheduling.

Key: calendar

Scope: Group, User

Providers: Google Calendar, Outlook, Custom

Messenger

Real-time messaging powered by Stream Chat

Communication

Group messaging, bulletin boards, and direct messages with real-time delivery.

Key: messenger

Scope: Group, User

Realtime: Yes (Stream Chat WebSocket)

Creating a Widget

1. Create Widget Component

// components/widgets/MyWidget.tsx
import { WidgetComponentProps } from "@/types/widgets";

export function MyWidget({
  widgetId,
  widgetKey,
  groupId,
  userId,
  config,
  data,
  loading,
  error,
  onRefresh,
}: WidgetComponentProps) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>My Widget</CardTitle>
      </CardHeader>
      <CardContent>
        {/* Widget content */}
      </CardContent>
    </Card>
  );
}

2. Register in Widget Registry

// lib/widgets/registry.tsx
import { MyWidget } from "@/components/widgets/MyWidget";

export const WIDGET_REGISTRY = {
  // ... existing widgets
  "my-widget": {
    component: MyWidget,
    displayName: "My Widget",
    category: "PRODUCTIVITY",
    isSystemWidget: true,
  },
};

3. Create Widget Definition

// prisma/seed-my-widget.ts
await prisma.widgetDefinition.create({
  data: {
    widgetKey: "my-widget",
    name: "My Widget",
    description: "Description of my widget",
    category: "PRODUCTIVITY",
    icon: "Wrench",
    componentType: "react",
    dataEndpoint: "/api/groups/[id]/my-widget",
    configSchema: {
      type: "object",
      properties: {
        setting1: { type: "string", default: "value" }
      }
    },
    defaultSize: { w: 6, h: 4 },
    scopes: ["group"],
    isSystemWidget: true,
    isActive: true,
  },
});

Widget Configuration

Widgets support flexible configuration via JSON schemas:

Calendar Widget Config

{
  "view": "month",           // month | week | agenda | list
  "showUpcoming": true,       // Show upcoming events
  "maxUpcomingEvents": 5,     // Max events to show
  "connectionId": "conn_123"  // Calendar connection ID
}

Messenger Widget Config

{
  "defaultTab": "channels",  // channels | dms | bulletin
  "showBulletin": true,      // Show bulletin board
  "showDMs": true            // Show direct messages
}

API Reference

GET /api/groups/[id]/widgets

Get all widgets configured for a group

Authentication Required

POST /api/groups/[id]/widgets

Add a widget to a group

Group Admin

PATCH /api/groups/[id]/widgets/[widgetId]

Update widget configuration or position

Group Admin

DELETE /api/groups/[id]/widgets/[widgetId]

Remove a widget from a group

Group Admin

// components/widgets/MyWidget.tsx
import { WidgetComponentProps } from "@/types/widgets";

export function MyWidget({
  widgetId,
  widgetKey,
  groupId,
  userId,
  config,
  data,
  loading,
  error,
  onRefresh,
}: WidgetComponentProps) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>My Widget</CardTitle>
      </CardHeader>
      <CardContent>
        {/* Widget content */}
      </CardContent>
    </Card>
  );
}

2. Register in Widget Registry

// lib/widgets/registry.tsx
import { MyWidget } from "@/components/widgets/MyWidget";

export const WIDGET_REGISTRY = {
  // ... existing widgets
  "my-widget": {
    component: MyWidget,
    displayName: "My Widget",
    category: "PRODUCTIVITY",
    isSystemWidget: true,
  },
};

3. Create Widget Definition

// prisma/seed-my-widget.ts
await prisma.widgetDefinition.create({
  data: {
    widgetKey: "my-widget",
    name: "My Widget",
    description: "Description of my widget",
    category: "PRODUCTIVITY",
    icon: "Wrench",
    componentType: "react",
    dataEndpoint: "/api/groups/[id]/my-widget",
    configSchema: {
      type: "object",
      properties: {
        setting1: { type: "string", default: "value" }
      }
    },
    defaultSize: { w: 6, h: 4 },
    scopes: ["group"],
    isSystemWidget: true,
    isActive: true,
  },
});

Widget Configuration

Widgets support flexible configuration via JSON schemas:

Calendar Widget Config

{
  "view": "month",           // month | week | agenda | list
  "showUpcoming": true,       // Show upcoming events
  "maxUpcomingEvents": 5,     // Max events to show
  "connectionId": "conn_123"  // Calendar connection ID
}

Messenger Widget Config

{
  "defaultTab": "channels",  // channels | dms | bulletin
  "showBulletin": true,      // Show bulletin board
  "showDMs": true            // Show direct messages
}

API Reference

GET /api/groups/[id]/widgets

Get all widgets configured for a group

Authentication Required

POST /api/groups/[id]/widgets

Add a widget to a group

Group Admin

PATCH /api/groups/[id]/widgets/[widgetId]

Update widget configuration or position

Group Admin

DELETE /api/groups/[id]/widgets/[widgetId]

Remove a widget from a group

Group Admin

Widget System

Overview

Architecture

Core Components

System Widgets

Creating a Widget

1. Create Widget Component

2. Register in Widget Registry

3. Create Widget Definition

Widget Configuration

Calendar Widget Config

Messenger Widget Config

API Reference

GET /api/groups/[id]/widgets

POST /api/groups/[id]/widgets

PATCH /api/groups/[id]/widgets/[widgetId]

DELETE /api/groups/[id]/widgets/[widgetId]

See Also

Widget System

Overview

Architecture

Core Components

System Widgets

Creating a Widget

1. Create Widget Component

2. Register in Widget Registry

3. Create Widget Definition

Widget Configuration

Calendar Widget Config

Messenger Widget Config

API Reference

GET /api/groups/[id]/widgets

POST /api/groups/[id]/widgets

PATCH /api/groups/[id]/widgets/[widgetId]

DELETE /api/groups/[id]/widgets/[widgetId]

See Also