Skip to main content

Dashboard metrics and charts

Added in 1.0.1

All dashboard widgets subclass DashboardComponent. Implement as_dto() indirectly by using the concrete base that matches the widget.

Shared fields on every component: slug, label, order (default 100), status (DashboardComponentStatus.ACTIVE by default).

HookRole
check_view(request)classmethod — extra visibility (superusers skip it)
check_use(request)classmethod — extra use permission (superusers skip it)
get_status(request)may return active / disabled / hidden / error
is_visible / is_availablecombine status + checks
as_dto(request)implemented by the concrete base

HIDDEN removes the widget. Non-ACTIVE blocks use. Superusers still see non-hidden widgets and can use them.

Metric​

from django_chassis.components import DashboardMetric
from django_chassis.enums import DashboardMetricResultType


class OpenOrdersMetric(DashboardMetric):
    slug = 'open-orders'
    label = 'Open orders'
    result_type = DashboardMetricResultType.SINGLE_VALUE

    def get_value(self, request):
        return Order.objects.filter(status='open').count()

result_type may be a single value, a table, or stacked items. For tables, set columns and return rows from get_value(). Optional get_fetched_at() / get_next_refresh_at() feed the live payload.

DashboardAnalyticsCacheService can cache expensive analytical values.

Chart​

from decimal import Decimal

from django_chassis.components import DashboardChart
from django_chassis.dto import DashboardChartDataDTO, DashboardChartPointDTO, DashboardChartSeriesDTO
from django_chassis.enums import DashboardChartColor, DashboardChartType


class RevenueChart(DashboardChart):
    slug = 'revenue'
    label = 'Revenue'
    chart_type = DashboardChartType.LINE

    def get_data(self, request) -> DashboardChartDataDTO:
        return DashboardChartDataDTO(
            value='1 500',
            period_label='2026',
            series=(
                DashboardChartSeriesDTO(
                    label='Revenue',
                    color=DashboardChartColor.BLUE,
                    points=(
                        DashboardChartPointDTO(label='2026-01', value=Decimal('1200')),
                        DashboardChartPointDTO(label='2026-02', value=Decimal('1500')),
                    ),
                ),
            ),
        )

Charts render with ApexCharts. A chart block may contain only one chart component.

Alert​

DashboardAlert is a conditionally visible styled message. Use DashboardAlertStyle for tone. Only alert blocks may be global.

Action​

DashboardAction is a routed action with permission/availability checks, optional confirmation, and completion hooks.

  • URL: {admin}/dashboard/actions/{slug}/
  • Implement the action body; raise to hit the exception hook
  • style is a ButtonColor

Toggle action​

DashboardToggleAction is a form-backed true/false action. Each state is a DashboardActionVariantDTO (label, description, style).

Status​

DashboardComponentStatus: active, disabled, hidden, error. hidden removes the widget. Superusers still see non-hidden widgets.

See also​