Widgets: Charts

django-controlcenter uses Chartist.js to render beautiful, responsive SVG charts. A variety of chart widgets are available out of the box.

Core Chart Concepts

All chart widgets inherit from widgets.Chart and share three main data methods:

• labels(): Returns a list of strings for the X-axis labels.
• series(): Returns a list of data series for the Y-axis. For most charts, this is a list of lists (e.g., [[10, 20, 15], [5, 18, 22]]).
• legend(): Returns a list of strings to be displayed as the chart's legend.

These methods, like values(), are cached properties and should be accessed as attributes (e.g., self.labels).

Customizing with the Chartist Inner Class

You can configure the underlying Chartist.js instance by defining an inner class named Chartist on your widget.

from controlcenter import widgets

class MyChart(widgets.LineChart):
    class Chartist:
        # Enable point labels on the line chart
        point_labels = True
        # Pass a dictionary of options to the Chartist.js constructor
        options = {
            'reverseData': True,
            'axisY': {
                'onlyInteger': True,
            }
        }

• klass: The type of chart. Can be widgets.LINE, widgets.BAR, or widgets.PIE.
• scale: The aspect ratio of the chart (e.g., 'octave', 'golden-section'). See the Chartist.js documentation for all available values.
• options: A dictionary of configuration options passed directly to the Chartist.js constructor. This allows for deep customization.
• point_labels: A boolean specific to LineChart and TimeSeriesChart to display labels on data points.

Chart Types

LineChart

A standard line chart. It defaults to 'reverseData': True, which is useful when displaying time-series data ordered from newest to oldest.

TimeSeriesChart

A specialized LineChart for time-series data. Instead of labels, the series method should return data points with x and y keys, where x is a POSIX timestamp.

import datetime

class SalesTimeSeries(widgets.TimeSeriesChart):
    def series(self):
        # series must be a list of lists of dictionaries
        return [
            [
                {'x': (datetime.date(2023, 1, 1)).timestamp(), 'y': 100},
                {'x': (datetime.date(2023, 1, 2)).timestamp(), 'y': 120},
            ]
        ]

You can customize the timestamp formatting via Chartist.timestamp_options:

class MyTimeSeriesChart(widgets.TimeSeriesChart):
    class Chartist:
        timestamp_options = {
            'year': 'numeric',
            'month': 'short',
        }

BarChart and PieChart

Standard bar and pie chart widgets.

Note: For PieChart, the series() method must return a flat list of values, not a list of lists.

Single...Chart Widgets

For the common case of displaying a single data series from one model, SingleLineChart, SingleBarChart, and SinglePieChart widgets are provided. They simplify chart creation significantly.

You only need to define model (or queryset) and values_list.

• values_list: A tuple of two strings: the first for the label (X-axis) and the second for the series value (Y-axis).

from .models import Player

class TopPlayersChart(widgets.SingleBarChart):
    title = 'Top 3 Players by Score'
    model = Player

    # 'username' will be used for labels, 'score' for series values
    values_list = ('username', 'score')

    # The widget automatically handles the query
    queryset = Player.objects.order_by('-score')
    limit_to = 3