ToasterTable

Introduction to ToasterTable

This is a WIP

ToasterTable is a set of classes in the toastergui module of the Toaster Django application. It is used to present a set of database records in a style and with functionality consistent with the rest of Toaster.

The functionality provided by ToasterTable includes:

• Sorting
• Column hiding/showing
• Filtering
• Paging
• Search

When a ToasterTable is updated, a new set of records matching the filter criteria, search string, sort order and page number is fetched from the back-end using Ajax requests. The ToasterTable is then updated in place from the JSON in the response, using JavaScript to redraw the table rows.

As a developer, you don't need to worry (necessarily) about how this works: you just implement a subclass of ToasterTable, specify a template for rendering it, and supply a URL mapping.

The following sections explain how to use ToasterTable. The filenames in these sections refer to files in the toastergui/ directory.

Note that to be able to follow the example, you will need to set up Toaster for development work. This is described in the Toaster manual.

How to create a ToasterTable

Most of the tables needed for Toaster are already implemented. Many of the key tables in Toaster already use ToasterTable, but some don't. A full list of unconverted tables is in https://bugzilla.yoctoproject.org/show_bug.cgi?id=8363.

This means that you will typically be porting an existing table to ToasterTable, rather than adding a new table from scratch. However, to keep things simple, this section explains how to create a ToasterTable from scratch. Knowing how to do this should make it easier to port an existing table to ToasterTable in future.

To provide a worked example, I'll create a new table which is a variant of the existing "all builds" table, using a reduced number of columns and filters.

Create the table class

A quick overview of where things are and where they go when creating a table:

• widgets.py contains the ToasterTable class. This is the base class for all ToasterTables.
• New tables are added to tables.py.
• A table in tables.py maps to a URL within the Toaster application; the mapping is defined in urls.py.
• Templates for the table are added to templates/.
• If you need custom template tags, these go in templatetags/.

To create a new table, first add the class definition to tables.py:

# import any models you need for the table from orm.models import Build class MiniBuildsTable(ToasterTable): def __init__(self, *args, **kwargs): super(MiniBuildsTable, self).__init__(*args, **kwargs) self.default_orderby = '-completed_on' self.title = 'Mini Builds Table' def setup_queryset(self, *args, **kwargs): self.queryset = Build.objects.all() def setup_columns(self, *args, **kwargs): self.add_column(title='Completed on', help_text='The date and time when the build finished', hideable=False, orderable=True, static_data_name='completed_on', static_data_template='{{data.completed_on | date:"d/m/y H:i"}}')

The key to creating a ToasterTable is to decide which data is going to be shown in the table and define this in the setup_queryset() method. This will typically be a queryset derived from one model in the Toaster application. To see the available models, check the orm/models.py file.

Each row in the table corresponds to a record in the queryset. The setup_queryset() method specifies how to get this queryset for the table: it must set the self.queryset property to the Django queryset containing the data. In the MiniBuildsTable, we show all of the builds by default (using the standard Django model API).

Each column in the ToasterTable corresponds to a field in the queryset. Inside a table row, a cell corresponds to one or more fields from each record in the queryset. A cell can show various aspects of a record: a formatted version of a field's value, an amalgam of multiple fields, a computation based on a group of related records etc. For example, in a row of the MiniBuildsTable, a cell might contain the outcome of the build, the number of tasks which failed during the build, or the time since the build completed.

The setup_columns() method defines which columns should be shown in the table. In this initial version of MiniBuildsTable, only the "completed_on" column is shown. This column has the following properties:

• It cannot be hidden (hideable=False).
• It can be used to order the table (orderable=True).
• static_data_name sets the name of the column so that it can be married up with the sort order specified in the querystring, and with the default_orderby for the ToasterTable (see below).
• static_data_template specifies how to render the value from the record into the HTML for the page. The data.completed_on reference in the template demonstrates how to access

The self.default_orderby member set in __init__() specifies the default column to use for ordering the table. In this case, the completed_on field is used to sort the builds in the table; the "-" specifies reverse order, so the newest build appears at the top of the table. Note that the value for self.default_orderby should match the name of a field in the model, and the name of a column added to the table.

See the [adding more columns] section for full details of the column options available.

Adding the template

This should go into templates/, as this is where Django looks for view templates.

In all cases, you will need to include the toastertable.html template from your template. You will also need to add links for the jQuery UI CSS and JS files. (In an ideal world, this would be in toastertable.html, but for historical reasons, it isn't yet.)

You will also need to define an xhr_table_url variable in your template. This is used to request new data for the table when filters or search terms are applied, or if a new page is requested. ToasterTable will send a request for the table JSON to this URL, then automatically refresh the table display with the new data when it's received.

As an example, here's a minimal template for the Mini Builds page, which would be in templates/minibuilds.html.

{% extends 'base.html' %} {% load static %} {% block extraheadcontent %} <link rel="stylesheet" href="{% static 'css/jquery-ui.min.css' %}" type='text/css'> <link rel="stylesheet" href="{% static 'css/jquery-ui.structure.min.css' %}" type='text/css'> <link rel="stylesheet" href="{% static 'css/jquery-ui.theme.min.css' %}" type='text/css'> <script src="{% static 'js/jquery-ui.min.js' %}"></script> {% endblock %} {% block title %}{{title}}{% endblock %} {% block pagecontent %} <h1 class="page-header top-air">{{title}}</h1> {% url 'minibuilds' as xhr_table_url %} {% include 'toastertable.html' %} {% endblock %}

Depending on which side menus or other wrapping you need around your table, you may need to modify an existing template (particularly if you are porting a table to ToasterTable). Note that this template extends the base.html template, which provides the header/footer for Toaster itself, but doesn't have a side menu. For an example of a more complex page, see builds-toastertable.html.

The important things to remember, though, are in the example template above; in particular, the need to import the jQuery UI assets, set xhr_table_url, and include the toastertable.html template.

Add a URL mapping for the table

To be able to view the Mini Builds page, it needs a mapping in the urls.py file:

urlpatterns = patterns('toastergui.views', // ... other mappings ... url(r'^minibuilds/$', tables.MiniBuildsTable.as_view(template_name='minibuilds.html'), name='minibuilds') )

This is standard Django template mapping code. The only wrinkle is that because a ToasterTable is a Django TemplateView subclass, we call Django's as_view() method on our table to render it, passing the name of the template file.

Now, with Toaster running locally, you should be able to visit

http://localhost:8000/minibuilds/

in a browser and see your Mini Builds table (note that it will be empty unless you've run some builds).

More ToasterTable

The following sections flesh out the options for adding columns to a ToasterTable, adding more data to the page, and using the table filter APIs.

Adding more columns

???

Column options

Adding a column to a table: - Sorting by a column - Hiding/showing a column - Filtering: The Filter API is used to add filtering functionality to particular columns in the table.

Other context data

Data not in each record of the queryset, but which needs to be visible on the page. As an example, the project builds page shows all of the builds for a project; but the project name needs to be shown at the top of the page. In this case, the project is added to the extra context data for the ToasterTable and accessed in the template.

As an example, we could compute the total number of builds Toaster has recorded and show this in the title at the top of the Mini Builds page.

???

Note that if you want this value to update as the table is filtered, you'll need to do it in JavaScript. This is because the page for a ToasterTable isn't re-rendered when its data changes: only the HTML for the table is updated. Any additional updates required on the page have to be done similarly, via JavaScript.

For example, to update the title of the page as the table is filtered, we could add this code to the template:

???

(see example for all builds table)

Computed and derived column values

??? see ProjectsTable in tables.py

Prefer to add methods to models rather than compute values on the fly in the template. This is because these values will very often be useful in other contexts; if they are defined in the view in an ad hoc way, they can't easily be reused.

Filter API

The classes for creating filters are defined in tablefilter.py.

A filter applies to a single column in the table. Any actions on a filter should filter records according to criteria which make sense with respect to that column. For example, you wouldn't add a filter to the "Completed on" column of the "All Builds" table which filters builds according to whether they failed or succeeded; but you could add a filter which filters the builds based on when they finished.

A filter adds an option to the column heading to filter in/out particular records or to remove filtering altogether.

Each filter has one or more actions associated with it. It also gets an action by default which turns off the filter and shows all the records again.

Each action changes the records shown in its associated ToasterTable, by applying a set of criteria to the query used to fetch records (e.g. show records for a single date, for a date range, or matching/not matching some other criteria related to the column).

How to add a filter to a field

Table filters

The TableFilter class acts as a container for a group of TableFilterAction objects.

TableFilterAction is the base class for an action associated with a filter. See the next section for the types of filter action already implemented.

Table filter actions

TableFilterActionToggle TableFilterActionDay TableFilterActionDateRange