Chart options¶
Django-controlcenter uses Chartist.js to create beautiful, responsive and dpi independent svg charts. Chart
class has three extra cached methods:
labels
- Represents values on x-axis.
series
Represents values on y-axis.
Note
Except for the
SingleBarChart
andSinglePieChart
classes, this method must return a list of lists.legend
Chartist.js doesn’t display series on chart which is really odd. As a workaround you can duplicate values on x-axis and then put labels in legend (and vice versa). Here is an example:
class MyBarChart(widgets.SingleBarChart): def series(self): # Y-axis return [y for x, y in self.values] def labels(self): # Duplicates series on x-axis return self.series def legend(self): # Displays labels in legend return [x for x, y in self.values]
Chartist¶
Chart
may have a special Chartist
class inside itself to configure Chartist.js:
class MyChart(widgets.Chart):
class Chartist:
point_labels = True
options = {
'reverseData': True,
...
}
When you define Chartist
it inherits chart’s parent’s Chartist
properties automatically. The reason why hacky inheritance is used is the options
property.
options
It’s a nested dictionary of options to be passed to Chartist.js constructor. Python dictionaries can’t be inherited properly in a classic way. That’s why when you define
options
in childChartist
class it deep copies and merges parent’s one with it’s own.class MyChart(widgets.Chart): class Chartist: point_labels = True options = { 'reverseData': True, 'foo': { 'bar': True } } class MyNewChart(MyChart): class Chartist: options = { 'fullWidth': True, } # MyNewChart.Chartist copies MyChart.Chartist attributes MyNewChart.chartist.options['reverseData'] # True MyNewChart.chartist.options['foo']['bar'] # True MyNewChart.chartist.options['fullWidth'] # True MyNewChart.chartist.point_labels # True
klass
- Type of the chart. Available values are defined in
widgets
module:LINE
,BAR
andPIE
. Default isLINE
. scale
- Aspect ratio of the chart. By default it’s
octave
. See the full list of available values on official web-site (press ‘Show default settings’). LineChart
- Displays point labels on
LINE
chart.
Note
If you don’t want to use Chartist.js, don’t forget to override Dashboard.Media
to make not load useless static files.
LineChart¶
Line chart with point labels and useful Chartist.js settings. This chart type is usually used to display latest data dynamic sorted by date which comes in backward order from database (because you order entries by date and then slice them). LineChart
passes 'reverseData': True
option to Chartist constructor which reverses series
and labels
.
TimeSeriesChart¶
A variant of LineChart
for time-series data.
This chart does not define labels
. Instead, each series
must consist of pairs of x
and y
values,
where x
is a POSIX timestamp (as returned by datetime.timestamp).
class MyTimeSeriesChart(widgets.TimeSeriesChart):
def series(self):
return [
[{'x': when.timestamp(), 'y': value} for (when, value) in samples],
]
The X-axis timestamp labels will be formatted using Date.toLocaleString.
To customise the timestamp label formatting, specify Date.toLocaleString
’s options
parameter
using the timestamp_options
configuration property.
For example, to only show the year and short month as labels:
class MyTimeSeriesChart(widgets.TimeSeriesChart):
class Chartist:
timestamp_options = {
'year': 'numeric',
'month': 'short',
}
To specify when ticks shown, see the Chartist.FixedScaleAxis documentation. For example:
class MyTimeSeriesChart(widgets.TimeSeriesChart):
class Chartist:
options = {
'axisX': {
# Use 'divisions' for a fixed number of sub-division ticks.
'divisions': 4,
# Alternatively, use 'ticks' to explicitly specify a list of timestamps.
},
}
BarChart¶
Bar type chart.
SingleBarChart, SinglePieChart, SingleLineChart¶
A special classes for charts with a single series. Simply define label and series fields in values_list
then provide model
or queryset
. That’s it.
This widget will render a bar chart of top three players:
class MySingleBarChart(widgets.SingleBarChart):
# label and series
values_list = ('username', 'score')
# Data source
queryset = Player.objects.order_by('-score')
limit_to = 3
Note
SingleLineChart.series
must return a list with a single list.
Chartist colors¶
There are two themes for charts. See Customization.