API Reference & Template Tags

This page provides a reference for the most important classes and a detailed guide to the custom template tags available for advanced widget customization.

Key Classes Quick Reference

• controlcenter.Dashboard: The main container for a dashboard. You subclass this to create a new dashboard page. Key attribute: widgets.
• controlcenter.widgets.Widget: The base class for all widgets. Provides data fetching logic (get_queryset, values).
• controlcenter.widgets.Group: A container to group multiple widgets into a single block with shared properties like width and height.
• controlcenter.widgets.ItemList: A widget for displaying lists of objects in a table. Highly customizable with list_display.
• controlcenter.widgets.charts.*: A collection of widgets for creating charts, including LineChart, BarChart, PieChart, and their Single* variants.

Template Tags

These tags are available within your widget templates to help render data and URLs correctly.

{{ ... | jsonify }}

This filter serializes a Python object (like a list or dictionary) into a JSON string that is safe for embedding in HTML and JavaScript.

• Usage: It's primarily used in chart templates to pass data from Django to the Chartist.js library.

<script type="text/javascript">
    var data = {
      labels: {{ widget.labels|jsonify }},
      series: {{ widget.series|jsonify }}
    };
    new Chartist.Line('#chart_{{ widget.slug }}', data);
</script>

{% change_url widget obj %}

This tag generates the URL to the Django admin change page for a specific object.

• Arguments:
  • widget: The widget instance.
  • obj: The object for which to generate the URL (can be a model instance, dict, etc.).
• Logic: It intelligently determines the object's primary key and model metadata to construct the correct URL. It can handle model instances, dictionaries with a 'pk' or 'id' key, and other object types if the widget has a model defined.

{% change_url widget obj as item_url %}
<a href="{{ item_url }}">Edit {{ obj.name }}</a>

{{ widget|changelist_url }}

This filter generates the URL to the model's admin changelist page, based on the widget's changelist_url attribute.

• Usage: Ideal for the "Show more" link on a widget.

<a class="controlcenter__widget__out" href="{{ widget|changelist_url }}" title="Show more"></a>

{% attrvalue widget obj attrname %}

This tag retrieves and displays a value for a given attribute (attrname) from an object (obj). It follows a specific lookup order.

• Lookup Order:
  1. A method or attribute on the widget class with the name attrname.
  2. A key in obj if it's a dictionary (e.g., from a .values() queryset).
  3. An attribute on obj if it's an object (e.g., a model instance or namedtuple).
• Features:
  • If the found attribute is a callable (method), it's called with the obj as an argument.
  • It respects allow_tags = True on widget methods to prevent HTML escaping.

{# In itemlist.html template #}
{% for attr in widget.list_display %}
    <td>
        {% attrvalue widget obj attr %}
    </td>
{% endfor %}

{{ widget|attrlabel:attrname }}

This filter retrieves the display label (column header) for a given attribute name.

• Lookup Order:
  1. The short_description property of a method on the widget class.
  2. The short_description property of a method on the widget's model class.
  3. The verbose_name of the model field.
  4. Falls back to the attrname itself if no label is found.

{# In itemlist.html template #}
<thead>
    <tr>
        {% for attr in widget.list_display %}
            <th>{{ widget|attrlabel:attr|capfirst }}</th>
        {% endfor %}
    </tr>
</thead>