Core Concepts: Dashboards

Dashboards are the top-level containers for your widgets. django-controlcenter supports an unlimited number of dashboards, each with its own URL, title, and collection of widgets.

Defining a Dashboard

A dashboard is a class that inherits from controlcenter.Dashboard. It has two main properties:

• title: A user-friendly title for the dashboard. If not provided, the class name is used.
• widgets: A tuple or list of widget classes and/or groups.

# your_app/dashboards.py

from controlcenter import Dashboard, widgets
from .widgets import NewUsersWidget, SalesChartWidget

class MyDashboard(Dashboard):
    title = 'My Awesome Dashboard'
    widgets = (
        NewUsersWidget,
        SalesChartWidget,
    )

Grouping Widgets

You can group multiple widgets into a single visual block by placing them in a list or tuple within the main widgets tuple. This is useful for logically related widgets that should share a container.

from controlcenter import Dashboard, widgets
from .widgets import OrdersInProgress, FinishedOrders

class OrdersDashboard(Dashboard):
    widgets = (
        # These two widgets will appear in the same block with tabs
        (OrdersInProgress, FinishedOrders),
    )

For more control over the group's appearance, you can use the widgets.Group class.

from controlcenter import Dashboard, widgets
from .widgets import Chart1, Chart2

class MyDashboard(Dashboard):
    widgets = (
        widgets.Group([Chart1, Chart2],
              # Makes the whole block larger
              width=widgets.LARGE,
              # Adds an HTML class attribute to the block
              attrs={'class': 'my_fancy_group'})
    )

The Grid System

The dashboard uses a responsive grid that scales up to 6 columns. The width of each widget or group is determined by its width property. django-controlcenter provides convenient constants for common sizes:

Constant	Value	Column Span at >1000px
widgets.SMALL	1	25% (1/4)
widgets.MEDIUM	2	33.3% (1/3)
widgets.LARGE	3	50% (1/2)
widgets.LARGER	4	66.6% (2/3)
widgets.LARGEST	5	75% (3/4)
widgets.FULL	6	100% (Full Width)

You can set the width on an individual widget or on a Group to control its size in the layout.

Adding Custom Static Files (Media)

Dashboards use Django's Media inner class to include custom CSS and JavaScript files on the page, just like a Django Form or ModelAdmin.

class MyDashboard(Dashboard):
    title = 'Dashboard with Custom Styles'
    widgets = (
        # ... your widgets
    )

    class Media:
        css = {
            'all': ('/css/my_dashboard_styles.css',)
        }
        js = ('/js/my_dashboard_scripts.js',)

Group Options

When you define a widgets.Group manually, you can pass several options:

• attrs: A dictionary of HTML attributes to apply to the group's container div (e.g., {'class': '...', 'id': '...'}).
• width: An integer (preferably one of the size constants) specifying the column width. This overrides the width of individual widgets within the group.
• height: An integer specifying the max-height of the block in pixels. If the content exceeds this height, a scrollbar will appear.