Dashboard Views

Dashboard views provide a configurable home screen with KPI cards, charts, lists, and goal widgets. The system supports a Standard dashboard (read-only, defined by modules) and personal dashboards (user-created, fully editable).

Architecture

Standard Dashboard

The Standard dashboard is computed on-the-fly from the view architecture. It is never saved to the database and is always read-only. Each module contributes widgets via view inheritance, so the Standard dashboard automatically reflects all installed modules.

Users see only widgets matching their security groups.

Personal Dashboards

Users can create personal dashboards stored in the DashboardPreference model. Personal dashboards support:

• Drag-and-drop widget repositioning
• Widget resizing
• Adding/removing widgets
• Renaming and deleting dashboards

Each user’s dashboards are private (enforced by a RecordRule).

Defining a Dashboard View

The base dashboard is defined in the core module:

- data_type: UiView
  name: Home Dashboard
  identifier: home_dashboard_view
  type: Dashboard
  model: DashboardPreference
  arch:
  - type: row
    anchor: dashboard_greeting
    content:
    - type: column
      span: 12
      content:
      - type: widget
        widget: Greeting
        groups:
        - core_internal
        properties:
          title: Welcome
          showDate: true
          showIcon: true
  - type: row
    anchor: dashboard_core_kpis
    content:
    - type: column
      span: 3
      content:
      - type: widget
        widget: KPICard
        groups:
        - core_internal
        properties:
          title: Contacts
          model: Contact
          mode: count
          filter: (Q(active=True))
          label: Active Contacts
          icon: Users
          color: blue

Layout System

Dashboard arch uses rows and columns like form views:

Element	Description
row	Horizontal container. Use anchor for stable inheritance targeting.
column	Grid column with span (1-12).
widget	Dashboard widget with widget type, groups, and properties.

Widget Element

- type: widget
  widget: KPICard          # Widget type
  groups:                   # Access control (optional)
  - sales_user_group
  properties:               # Widget-specific configuration
    model: SaleOrder
    mode: count
    filter: (Q(state='Confirmed'))
    label: Sales Orders
    icon: ShoppingCart
    color: blue

Adding Module Widgets via Inheritance

Modules add widgets to the Standard dashboard using view inheritance. Always add an anchor to your rows for other modules to target.

- depends:
  - ../security/security.yaml
  data_type: UiView
  name: Home Dashboard - Sales
  identifier: home_dashboard_sales
  type: Dashboard
  model: DashboardPreference
  inherited_view: home_dashboard_view
  arch:
    operations:
    - action: add
      target:
        anchor: dashboard_core_kpis
      position: after
      value:
        type: row
        anchor: dashboard_sales_kpis
        content:
        - type: column
          span: 3
          content:
          - type: widget
            widget: KPICard
            groups:
            - sales_user_group
            properties:
              title: Quotations
              model: SaleOrder
              mode: count
              filter: (Q(state='Quote') | Q(state='Sent'))
              label: Active Quotes
              icon: FileText
              color: blue

Key points:

• Use inherited_view: home_dashboard_view to extend the Standard dashboard
• Target existing anchors (e.g., dashboard_core_kpis) with position: after
• Always add an anchor to your new rows so other modules can extend after them
• Use security groups on widgets for access control

Widget Types

KPICard

Displays a single aggregated metric with icon, label, and formatted value.

widget: KPICard
properties:
  model: SaleOrder
  mode: count              # count, sum, average, min, max
  measure: total           # Required when mode != count
  filter: (Q(state='Confirmed'))
  label: Sales Orders
  icon: ShoppingCart        # Lucide icon name
  color: blue              # Mantine color
  format: number           # number, currency, percent
  action: sale_order_action  # Navigate to this action on click

Property	Type	Default	Description
model	String	Required	Model to query
mode	String	"count"	Aggregation: count, sum, average, min, max
measure	String	-	Field to aggregate (required when mode is not count)
filter	String	-	Q-expression filter
label	String	"Count"	Display label
icon	String	"ChartBar"	Lucide icon name
color	String	"blue"	Mantine color
format	String	"number"	number, currency, percent
action	String	-	Action identifier to navigate to on click. The KPI’s filter is passed as global_filter.
actionMenu	String	-	Root menu override for the action (auto-resolved from menu data if omitted)

Default size: 3×3 grid units

Chart

Displays grouped data as bar, area, line, donut, or radar chart.

widget: Chart
properties:
  title: Monthly Revenue
  model: SaleOrder
  chartType: bar           # bar, area, line, donut, radar
  groupBy:
    field: date
    interval: month        # day, week, month, quarter, year (for Date/Datetime fields)
  mode: sum
  measure: total           # Required when mode != count
  filter: (Q(state__in=['Confirmed','Done']))

Property	Type	Default	Description
model	String	Required	Model to query
chartType	String	"bar"	bar, area, line, donut, radar
groupBy	Object	Required	{ field: "field_name", interval: "month" }. The interval key is optional and applies to Date/Datetime fields. Supported: day, week, month, quarter, year.
mode	String	"count"	Aggregation: count, sum, average, min, max
measure	String	-	Field to aggregate (required when mode is not count)
filter	String	-	Q-expression filter
title	String	-	Chart title

Default size: 6×7 grid units (minimum height: 7)

List

Compact table widget for displaying records with formatted columns. Uses the same column spec format and formatting utilities as the CompactList form widget, but fetches its own data independently.

widget: List
properties:
  title: Top Products
  model: Product
  limit: 5
  order_by: total_sold DESC
  columns:
  - field: name
    label: Product
    bold: true
  - field: total_sold
    label: Sold
    format: integer
    align: right
  - field: list_price
    label: Price
    format: currency
    prefix: currency
    color: blue
    bold: true

Property	Type	Default	Description
model	String	Required	Model to query
title	String	-	Table title
columns	Array	Required	Column definitions (see below)
filter	String	-	Q-expression filter
order_by	String/Array	-	Sort order (e.g., "total DESC")
limit	Number	5	Max rows to display

Column Properties:

Property	Type	Default	Description
field	String	Required	Field name to display
label	String	Field name	Column header
format	String	"text"	text, currency, number, integer, percent
precision	Number	Format default	Decimal places
align	String	Auto	left, center, right (numbers default to right)
color	String	-	Mantine color for text
bold	Boolean	false	Bold text
prefix	String	-	Static string or field name from the item data
suffix	String	-	Static string or field name from the item data

Default size: 6×6 grid units (minimum height: 4)

Goal

Displays progress toward a target using a semi-circle progress indicator.

widget: Goal
properties:
  model: SaleOrder
  mode: count
  filter: (Q(state='Done'))
  target: 50
  label: Monthly Sales Target
  color: green

Property	Type	Default	Description
model	String	Required	Model to query
mode	String	"count"	Aggregation: count, sum, average, min, max
measure	String	-	Field to aggregate (required when mode is not count)
filter	String	-	Q-expression filter
target	Number	100	Goal target value
label	String	"Goal"	Display label
color	String	"blue"	Mantine color for filled segment
format	String	"number"	number, currency, percent
precision	Number	0	Decimal places

Default size: 3×6 grid units (minimum height: 5)

Greeting

Built-in welcome widget with date display. Typically spans the full width.

widget: Greeting
properties:
  title: Welcome
  showDate: true
  showIcon: true

DashboardPreference Model

Personal dashboards are stored in the DashboardPreference model:

Field	Type	Description
user	ManyToOne(User)	Owner (auto-set to current user)
dashboard_id	Char	Dashboard identifier (links to the view)
name	Char	Display name (e.g., “My Sales Dashboard”)
sequence	Integer	Sort order in dropdown
layout	JSON	Widget positions for react-grid-layout
widgets	JSON	Widget configurations (type, properties)

A RecordRule ensures users can only access their own dashboard preferences.

Next Steps

• Widgets - Form field widget reference
• View Inheritance - Extending views across modules
• Stats Banner - Stats display for list/kanban views