Widgets and Dashboards -- Your Control Panel

In the previous chapters, you learned about [Modules](06-modules.md) -- full-page applications for w

In the previous chapters, you learned about Modules -- full-page applications for working with your data. Now it is time to learn about Widgets and Dashboards, which give you a bird's-eye view of everything at a glance.

The Phone Home Screen Analogy

Pull out your phone (or picture one in your mind). Your home screen is a page you have arranged yourself. You chose which widgets appear, where they sit, and how big they are. One person's home screen has a weather card, a music player, and a calendar. Another person's has a fitness tracker, a news feed, and a to-do list. Same phone, completely different layouts.

GOD CRM works the same way:

• A Dashboard is your home screen. It is a customizable page inside a Project where you arrange cards.
• A Widget is one of those cards. It shows a quick summary of some piece of information -- a chart, a number, a task list, a calendar, and so on.

You do not write code to build a dashboard. You pick widgets, drop them on the page, resize them, and connect them to your data.

In the four-layer architecture, Widgets are Layer 4 -- the highest layer, sitting on top of everything else.

What Is a Dashboard?

A Dashboard is a customizable overview page that lives inside a Project. Every Project can have its own Dashboard. Key facts:

• One per Project. Each Project gets its own Dashboard.
• Drag and drop. You move widgets around by dragging them.
• Resizable cards. Each widget can be made larger or smaller.
• Live data. Widgets pull data from your tables in real time.
• 12-column grid. The layout uses a responsive 12-column grid system (react-grid-layout), so widgets snap into neat rows and columns.

Think of a Dashboard as your personal command center for a Project. You glance at it and immediately know the state of things -- how many tasks are open, what deadlines are coming up, how revenue is trending.

What Is a Widget?

A Widget is a compact card that displays one piece of information. It is not a full application -- it is a small, focused visualization you can understand at a glance.

The difference between a Module and a Widget is size and purpose:

Some features exist as both a Module and a Widget. For example, the Calendar module is a full-page calendar where you manage events. The Calendar widget is a compact calendar card on your dashboard that shows upcoming events at a glance. Same data, different level of detail.

The 16 Widget Presets

GOD CRM ships with 16 widget types (15 unique plus 1 deprecated alias). Each one is designed for a specific kind of information.

About the Chart widget. The Chart widget supports five chart types, but they are all one widget configured differently -- not five separate widgets:

How Widgets Get Their Data

Widgets do not store their own data. They connect to your Raw Tables (Layer 1) and read from them in real time. When you add a widget to your dashboard, you configure:

1. Which table -- the table the widget reads from.
2. Which columns -- which columns to display or use for calculations.
3. Filters -- conditions to narrow down which rows appear.
4. Sort -- how to order the rows.
5. Limit -- maximum number of rows to show.

Each widget type also has its own specific settings. For example:

Kanban widget -- You choose which column determines the card's stage (like a "status" column), which column shows as the card title, and which columns appear in the card body. You can also set WIP (Work In Progress) limits per lane.

Calendar widget -- You choose which column holds the event date, the event title, and optionally the color.

Chart widget -- You choose the X-axis column, Y-axis column, chart type, and optionally a group-by column.

Metric Card (Number widget) -- You choose an aggregation method (count, sum, average, min, or max) and the widget displays one large number with an optional trend indicator.

Task List widget -- You choose the completion column and whether to show all tasks, only active tasks, or only completed tasks.

Building Your Dashboard -- Three Steps

Step 1: Add widgets. Open your Project's dashboard and click the "Add Widget" button. A palette appears showing all widget types. Click one to add it.

Step 2: Arrange and resize. Drag widgets to move them. Drag the corners to resize them. The 12-column grid keeps everything aligned. Widgets snap into place so your layout stays clean.

Step 3: Configure each widget. Click the settings icon on a widget to open its configuration panel. Choose the data source (table), columns, filters, and visual options. Each widget type has different settings.

That is it. Three steps and you have a custom command center for your project.

Edit Mode vs View Mode

Dashboards have two modes:

• Edit mode -- You can add, remove, move, and resize widgets. The grid shows guides to help you align things.
• View mode -- Widgets are locked in place. You interact with the data (click a chart, check off a task) but cannot accidentally move or delete anything.

Switch between modes with the edit toggle in the dashboard toolbar.

A Dashboard Example

Imagine you run a small online store. Your "E-Commerce" Project has tables for Orders, Products, and Customers. Here is what your dashboard might look like:

+---------------------------+---------------------------+
|                           |                           |
|   Metric Card:            |   Metric Card:            |
|   "Orders Today: 47"     |   "Revenue: $3,290"       |
|                           |                           |
+---------------------------+---------------------------+
|                                                       |
|   Chart (Line):                                       |
|   "Orders per Day This Month"                         |
|   [line graph trending upward]                        |
|                                                       |
+---------------------------+---------------------------+
|                           |                           |
|   Task List:              |   Recent Activity:        |
|   "Pending Shipments"     |   "Latest order changes"  |
|   [ ] Order #1042         |   Order #1041 shipped     |
|   [ ] Order #1043         |   New customer signed up  |
|   [ ] Order #1044         |   Product restocked       |
|                           |                           |
+---------------------------+---------------------------+

Six widgets. One page. A complete picture of your business at a glance. Every number and chart pulls live data from your tables.

Custom Widgets

Beyond the 16 preset types, GOD CRM supports custom widgets where user-provided code runs inside a sandboxed environment (CustomWidgetSandbox). This allows developers to build entirely custom visualizations that go beyond what the presets offer.

Widgets, Modules, and Tables Working Together

Here is how all three relate:

• A Table stores the raw data (rows and columns) -- Layer 1 and Layer 2.
• A Module provides a specialized full-page interface for working with that data -- Layer 3.
• A Widget provides a small summary card of that data on a dashboard -- Layer 4.

All three point to the same underlying data. Change a value in the table, and both the Module view and the Widget update. There is always one source of truth.

Summary

What Is Next?

You now know all the individual pieces: Spaces, Projects, Tables, Agents, Modules, Widgets, and Dashboards. But how do they all fit together in practice?

Read How It All Connects for a complete end-to-end walkthrough.