horizon/doc/source/contributor/topics/tables.rst

DataTables Topic Guide

Horizon provides the horizon.tables module to provide a convenient, reusable API for building data-driven displays and interfaces. The core components of this API fall into three categories: DataTables, Actions, and Class-based Views.

For a detailed API information check out the ref-datatables.

Tables

The majority of interface in a dashboard-style interface ends up being tabular displays of the various resources the dashboard interacts with. The ~horizon.tables.DataTable class exists so you don't have to reinvent the wheel each time.

Creating your own tables

Creating a table is fairly simple:

1. Create a subclass of ~horizon.tables.DataTable.
2. Define columns on it using ~horizon.tables.Column.
3. Create an inner Meta class to contain the special options for this table.
4. Define any actions for the table, and add them to ~horizon.tables.DataTableOptions.table_actions or ~horizon.tables.DataTableOptions.row_actions.

Examples of this can be found in any of the tables.py modules included in the reference modules under horizon.dashboards.

Connecting a table to a view

Once you've got your table set up the way you like it, the next step is to wire it up to a view. To make this as easy as possible Horizon provides the ~horizon.tables.DataTableView class-based view which can be subclassed to display your table with just a couple lines of code. At its simplest, it looks like this:

from horizon import tables
from .tables import MyTable


class MyTableView(tables.DataTableView):
    table_class = MyTable
    template_name = "my_app/my_table_view.html"

    def get_data(self):
        return my_api.objects.list()

In the template you would just need to include the following to render the table:

{{ table.render }}

That's it! Easy, right?

Actions

Actions comprise any manipulations that might happen on the data in the table or the table itself. For example, this may be the standard object CRUD, linking to related views based on the object's id, filtering the data in the table, or fetching updated data when appropriate.

When actions get run

There are two points in the request-response cycle in which actions can take place; prior to data being loaded into the table, and after the data is loaded. When you're using one of the pre-built class-based views for working with your tables the pseudo-workflow looks like this:

1. The request enters view.
2. The table class is instantiated without data.
3. Any "preemptive" actions are checked to see if they should run.
4. Data is fetched and loaded into the table.
5. All other actions are checked to see if they should run.
6. If none of the actions have caused an early exit from the view, the standard response from the view is returned (usually the rendered table).

The benefit of the multi-step table instantiation is that you can use preemptive actions which don't need access to the entire collection of data to save yourself on processing overhead, API calls, etc.

Basic actions

At their simplest, there are three types of actions: actions which act on the data in the table, actions which link to related resources, and actions that alter which data is displayed. These correspond to ~horizon.tables.Action, ~horizon.tables.LinkAction, and ~horizon.tables.FilterAction.

Writing your own actions generally starts with subclassing one of those action classes and customizing the designated attributes and methods.

Shortcut actions

There are several common tasks for which Horizon provides pre-built shortcut classes. These include ~horizon.tables.BatchAction, and ~horizon.tables.DeleteAction. Each of these abstracts away nearly all of the boilerplate associated with writing these types of actions and provides consistent error handling, logging, and user-facing interaction.

It is worth noting that BatchAction and DeleteAction are extensions of the standard Action class. Some BatchAction or DeleteAction classes may cause some unrecoverable results, like deleted images or unrecoverable instances. It may be helpful to specify specific help_text to explain the concern to the user, such as "Deleted images are not recoverable".

Preemptive actions

Action classes which have their ~horizon.tables.Action.preempt attribute set to True will be evaluated before any data is loaded into the table. As such, you must be careful not to rely on any table methods that require data, such as ~horizon.tables.DataTable.get_object_display or ~horizon.tables.DataTable.get_object_by_id. The advantage of preemptive actions is that you can avoid having to do all the processing, API calls, etc. associated with loading data into the table for actions which don't require access to that information.

Policy checks on actions

The ~horizon.tables.Action.policy_rules attribute, when set, will validate access to the action using the policy rules specified. The attribute is a list of scope/rule pairs. Where the scope is the service type defining the rule and the rule is a rule from the corresponding service policy.json file. The format of horizon.tables.Action.policy_rules looks like:

(("identity", "identity:get_user"),)

Multiple checks can be made for the same action by merely adding more tuples to the list. The policy check will use information stored in the session about the user and the result of ~horizon.tables.Action.get_policy_target (which can be overridden in the derived action class) to determine if the user can execute the action. If the user does not have access to the action, the action is not added to the table.

If ~horizon.tables.Action.policy_rules is not set, no policy checks will be made to determine if the action should be visible and will be displayed solely based on the result of ~horizon.tables.Action.allowed.

For more information on policy based Role Based Access Control see topics-policy.

Table Cell filters (decorators)

DataTable displays lists of objects in rows and object attributes in cell. How should we proceed, if we want to decorate some column, e.g. if we have column memory which returns a number e.g. 1024, and we want to show something like 1024.00 GB inside table?

Decorator pattern

The clear anti-pattern is defining the new attributes on object like ram_float_format_2_gb or to tweak a DataTable in any way for displaying purposes.

The cleanest way is to use filters. Filters are decorators, following GOF Decorator pattern. This way DataTable logic and displayed object logic are correctly separated from presentation logic of the object inside of the various tables. And therefore the filters are reusable in all tables.

Filter function

Horizon DatablesTable takes a tuple of pointers to filter functions or anonymous lambda functions. When displaying a Cell, DataTable takes Column filter functions from left to right, using the returned value of the previous function as a parameter of the following function. Then displaying the returned value of the last filter function.

A valid filter function takes one parameter and returns the decorated value. So e.g. these are valid filter functions :

# Filter function.
def add_unit(v):
  return str(v) + " GB"

# Or filter lambda function.
lambda v: str(v) + " GB"

# This is also a valid definition of course, although for the change of the
# unit parameter, function has to be wrapped by lambda
# (e.g. floatformat function example below).
def add_unit(v, unit="GB"):
  return str(v) + " " + unit

Using filters in DataTable column

DataTable takes tuple of filter functions, so e.g. this is valid decorating of a value with float format and with unit :

ram = tables.Column(
    "ram",
    verbose_name=_('Memory'),
    filters=(lambda v: floatformat(v, 2),
             add_unit))

It always takes tuple, so using only one filter would look like this :

filters=(lambda v: floatformat(v, 2),)

The decorated parameter doesn't have to be only a string or number, it can be anything e.g. list or an object. So decorating of object, that has attributes value and unit would look like this :

ram = tables.Column(
        "ram",
        verbose_name=_('Memory'),
        filters=(lambda x: getattr(x, 'value', '') +
                 " " + getattr(x, 'unit', ''),))

Available filters

There are a load of filters, that can be used, defined in django already: https://github.com/django/django/blob/master/django/template/defaultfilters.py

So it's enough to just import and use them, e.g. :

from django.template import defaultfilters as filters

# code omitted
filters=(filters.yesno, filters.capfirst)


from django.template.defaultfilters import timesince
from django.template.defaultfilters import title

# code omitted
filters=(parse_isotime, timesince)

Inline editing

Table cells can be easily upgraded with in-line editing. With use of django.form.Field, we are able to run validations of the field and correctly parse the data. The updating process is fully encapsulated into table functionality, communication with the server goes through AJAX in JSON format. The javascript wrapper for inline editing allows each table cell that has in-line editing available to:

1. Refresh itself with new data from the server.
2. Display in edit mode.
3. Send changed data to server.
4. Display validation errors.

There are basically 3 things that need to be defined in the table in order to enable in-line editing.

Fetching the row data

Defining an get_data method in a class inherited from tables.Row. This method takes care of fetching the row data. This class has to be then defined in the table Meta class as row_class = UpdateRow.

Example:

class UpdateRow(tables.Row):
    # this method is also used for automatic update of the row
    ajax = True

    def get_data(self, request, project_id):
        # getting all data of all row cells
        project_info = api.keystone.tenant_get(request, project_id,
                                               admin=True)
        return project_info

Updating changed cell data (DEPRECATED)

Define an update_cell method in the class inherited from tables.UpdateAction. This method takes care of saving the data of the table cell. There can be one class for every cell thanks to the cell_name parameter. This class is then defined in tables column as update_action=UpdateCell, so each column can have its own updating method.

Example:

class UpdateCell(tables.UpdateAction):
    def allowed(self, request, project, cell):
        # Determines whether given cell or row will be inline editable
        # for signed in user.
        return api.keystone.keystone_can_edit_project()

    def update_cell(self, request, project_id, cell_name, new_cell_value):
        # in-line update project info
        try:
            project_obj = datum
            # updating changed value by new value
            setattr(project_obj, cell_name, new_cell_value)

            # sending new attributes back to API
            api.keystone.tenant_update(
                request,
                project_id,
                name=project_obj.name,
                description=project_obj.description,
                enabled=project_obj.enabled)

        except Conflict:
            # Validation error for naming conflict, raised when user
            # choose the existing name. We will raise a
            # ValidationError, that will be sent back to the client
            # browser and shown inside of the table cell.
            message = _("This name is already taken.")
            raise ValidationError(message)
        except:
            # Other exception of the API just goes through standard
            # channel
            exceptions.handle(request, ignore=True)
            return False
        return True

Defining a form_field for each Column that we want to be in-line edited.

Form field should be django.form.Field instance, so we can use django validations and parsing of the values sent by POST (in example validation required=True and correct parsing of the checkbox value from the POST data).

Form field can be also django.form.Widget class, if we need to just display the form widget in the table and we don't need Field functionality.

Then connecting UpdateRow and UpdateCell classes to the table.

Example:

class TenantsTable(tables.DataTable):
    # Adding html text input for inline editing, with required validation.
    # HTML form input will have a class attribute tenant-name-input, we
    # can define here any HTML attribute we need.
    name = tables.Column('name', verbose_name=_('Name'),
                         form_field=forms.CharField(required=True),
                         form_field_attributes={'class':'tenant-name-input'},
                         update_action=UpdateCell)

    # Adding html textarea without required validation.
    description = tables.Column(lambda obj: getattr(obj, 'description', None),
                                verbose_name=_('Description'),
                                form_field=forms.CharField(
                                    widget=forms.Textarea(),
                                    required=False),
                                update_action=UpdateCell)

    # Id will not be inline edited.
    id = tables.Column('id', verbose_name=_('Project ID'))

    # Adding html checkbox, that will be shown inside of the table cell with
    # label
    enabled = tables.Column('enabled', verbose_name=_('Enabled'), status=True,
                            form_field=forms.BooleanField(
                                label=_('Enabled'),
                                required=False),
                            update_action=UpdateCell)

    class Meta(object):
        name = "tenants"
        verbose_name = _("Projects")
        # Connection to UpdateRow, so table can fetch row data based on
        # their primary key.
        row_class = UpdateRow