tri.table 8.5.1

tri.table is a library to make full featured HTML tables easily

Warning

tri.table is end of life. It has been merged into iommi.

iommi is backwards incompatible but the porting effort should be fairly mild, the biggest changes are that show is now called include, tri.query’s Variable is renamed to Filter and plural is used consistently for containers (so column__foo is columns__foo in iommi).

tri.table

tri.table is a library to make full featured HTML tables easily:

• generates header, rows and cells

• grouping of headers

• filtering

• sorting

• bulk edit

• pagination

• automatic rowspan

• link creation

• customization on multiple levels, all the way down to templates for cells

All these examples and a bigger example using many more features can be found in the examples django project.

Read the full documentation for more.

Contents

• tri.table

  • Simple example

  • Fancy django features

  • Usage

  • Motivation

  • Running tests

  • License

  • Documentation

  • Changelog

    • 8.5.1 (2020-12-04)

    • 8.5.0 (2020-08-21)

    • 8.4.0 (2020-04-24)

    • 8.3.0 (2020-01-09)

    • 8.2.0 (2019-11-21)

    • 8.1.1 (2019-10-23)

    • 8.1.0 (2019-10-15)

    • 8.0.0 (2019-06-14)

    • 7.0.2 (2019-05-06)

    • 7.0.1 (2019-05-03)

    • 7.0.0 (2019-04-12)

    • 6.3.0 (2019-03-15)

    • 6.2.1 (2019-03-05)

    • 6.2.0 (2019-03-04)

    • 6.1.0 (2019-01-29)

    • 6.0.3 (2018-12-06)

    • 6.0.2 (2018-12-06)

    • 6.0.1 (2018-12-04)

    • 6.0.0 (2018-12-03)

    • 5.3.1 (2018-10-10)

    • 5.3.0 (2018-08-19)

    • 5.2.2 (2018-06-29)

    • 5.2.1 (2018-06-18)

    • 5.2.0 (2018-06-15)

    • 5.1.1 (2018-04-09)

    • 5.1.0 (2018-01-08)

    • 5.0.0 (2017-08-22)

    • 4.3.1 (2017-05-31)

    • 4.3.0 (2017-04-25)

    • 4.2.0 (2017-04-21)

    • 4.1.2 (2017-04-19)

    • 4.1.1 (2017-04-10)

    • 4.1.0 (2017-03-22)

    • 4.0.0 (2016-09-15)

    • 3.0.1 (2016-09-06)

    • 3.0.0 (2016-09-02)

    • 2.5.0 (2016-07-14)

    • 2.4.0 (2016-07-13)

    • 2.3.0 (2016-07-12)

    • 2.2.0 (2016-06-23)

    • 2.1.0 (2016-06-16)

    • 2.0.0 (2016-06-02)

    • 1.16.0 (2016-04-25)

    • 1.15.0 (2016-04-21)

    • 1.14.0 (2016-04-19)

    • 1.13.0 (2016-04-08)

    • 1.12.0 (2016-02-29)

    • 1.11.0 (2016-02-04)

    • 1.10.0 (2016-01-28)

    • 1.9.0 (2016-01-19)

Simple example

def readme_example_1(request):
    # Say I have a class...
    class Foo(object):
        def __init__(self, i):
            self.a = i
            self.b = 'foo %s' % (i % 3)
            self.c = (i, 1, 2, 3, 4)

    # and a list of them
    foos = [Foo(i) for i in xrange(4)]

    # I can declare a table:
    class FooTable(Table):
        a = Column.number()  # This is a shortcut that results in the css class "rj" (for right justified) being added to the header and cell
        b = Column()
        c = Column(cell__format=lambda table, column, row, value, **_: value[-1])  # Display the last value of the tuple
        sum_c = Column(cell__value=lambda table, column, row, **_: sum(row.c), sortable=False)  # Calculate a value not present in Foo

    # now to get an HTML table:
    return render_table_to_response(request, FooTable(data=foos), template='base.html')

And this is what you get:

Fancy django features

Say I have some models:

class Foo(models.Model):
    a = models.IntegerField()

    def __unicode__(self):
        return 'Foo: %s' % self.a

class Bar(models.Model):
    b = models.ForeignKey(Foo)
    c = models.CharField(max_length=255)

Now I can display a list of Bars in a table like this:

def readme_example_2(request):
    fill_dummy_data()

    class BarTable(Table):
        select = Column.select()  # Shortcut for creating checkboxes to select rows
        b__a = Column.number(  # Show "a" from "b". This works for plain old objects too.
            query__show=True,  # put this field into the query language
            query__gui__show=True)  # put this field into the simple filtering GUI
        c = Column(
            bulk=True,  # Enable bulk editing for this field
            query_show=True,
            query__gui__show=True)

    return render_table_to_response(request, BarTable(data=Bar.objects.all()), template='base.html', paginate_by=20)

This gives me a view with filtering, sorting, bulk edit and pagination.

All these examples and a bigger example using many more features can be found in the examples django project.

Read the full documentation for more.

Usage

Add tri_form, tri_query, tri_table to INSTALLED_APPS.

Motivation

tri.table grew out of a frustration with how tables were created at TriOptima. We have a /lot/ of tables and the code to produce them included long HTML templates and often the code to extract and massage the data in some trivial way ended up as methods on the model classes or template tags, even though it was only used by one view.

This code was also error prone to change since we often have columns that we show or hide based on the permissions of the user, which meant the thead and tbody had to be in sync. When you have a lot of columns and more and more complex logic for when to show/hide columns this can become harder than it sounds!

We also saw that almost always the names of the columns (aka the headers) could be derived from the name of the field they should display data for, so we opted for defaults to make this case easier.

It was very important for us to have customization available at many levels. Many table libraries have really nice and short code for the default case but when you have to customize some tiny thing you have to rewrite huge swaths of the library’s code. We didn’t want to do that since we made this library in order to refactor out exactly this thing from our existing code base. We ended up with the powerful pattern of being able to supply callables for the points of customization, leading to small tweaks moving into the table definition instead of being scattered in model or template tag code. We also have many levels or customization so that the path from “just display columns x, y and z somehow” to heavy customization is smooth and gradual.

We chose to mimic how django forms and models are declared because we really like that kind of declarative style, but you can also use it in a more functional style if you want. The latter is useful when you want to create a list of the columns to display programmatically for example.

This library has been a big win for us. The time to create a page with a table on it has been drastically reduced without sacrificing any flexibility when we later want to tweak the view.

Running tests

You need tox installed then just make test.

License

BSD

Documentation

https://tritable.readthedocs.org.

Changelog

8.5.1 (2020-12-04)

• Removed broken validation of sort columns. This validation prevented sorting on annotations which was very confusing as it worked in dev.

• NOTE: tri.table is a legacy library and is fully replaced by iommi

8.5.0 (2020-08-21)

• Include tri.struct 4.x as possible requirement

8.4.0 (2020-04-24)

• Fix bulk form missing requests attribute. (Failing on ajax selects)

• Upped dependency tri.declarative to 5.x

8.3.0 (2020-01-09)

• Change python version to 3.7

8.2.0 (2019-11-21)

• Introduced data_retrivial_method, and turned it on by default for foreign_key and many_to_many. This means that by default tables are now efficient instead of requiring you to use prefetch_related or select_related manually.

• Added missing UUIDField factory

• Added missing Column.multi_choice

• page_size wasn’t refinable

8.1.1 (2019-10-23)

• Upped dependency on tri.form due to a bug fix there, and the use of that bug fix in tri.table

• Handle late binding of request member of Table

• Removed deprecated use of @creation_ordered

8.1.0 (2019-10-15)

• Implemented Table.actions as a replacement for render_table`s argument `links.

• Column.multi_choice_queryset was broken.

• Fixed many_to_many shortcut.

• Deprecated the following parameters to render_table:

  • template: replaced by Table.template

  • paginate_by: replaced by Table.page_size

  • show_hits: no replacement

  • hit_label: no replacement

  • page: no replacement

  • blank_on_empty: no replacement

  • links: replaced by Table.actions

• Bumped dependency tri.declarative to 4.x

8.0.0 (2019-06-14)

• Renamed module from tri.table to tri_table

• Dropped support for python2 and Django < 2.0

7.0.2 (2019-05-06)

• Fixed cases where from_model lost the type when inheriting

7.0.1 (2019-05-03)

• Fixed a bug where columns that had query or bulk but attr=None would crash

7.0.0 (2019-04-12)

• Make Column shortcuts compatible with subclassing. The previous fix didn’t work all the way.

• Use the new major tri.declarative, and update to follow the new style of class member shortcuts

• Removed support for django 1.8

• bulk_queryset is now usable to create your own bulk actions without using Table.bulk_form

• Bulk form now auto creates via Form.from_model correctly

• Query is now auto created via Query.from_model correctly

6.3.0 (2019-03-15)

• Make Column shortcuts compatible with subclassing

6.2.1 (2019-03-05)

• Fixed a crash when you used a custom paginator in django 2.0+

6.2.0 (2019-03-04)

• Fixes for jinja2 compatibility (still not fully working)

• preprocess_data now takes a new keyword argument table

• You can now get the paginator context itself via Table.paginator_context

• Paginator template is configurable

• Fixed a bug where we triggered our own deprecation warning for Column

• Use the new paginator API for django 2.0+

6.1.0 (2019-01-29)

• Deprecated Column argument attrs in favor of header__attrs

• Added CSS classes ascending/descending on headers

• Added ability to customize superheaders via Column.superheader

• Added ability to customize Column header template via header__template

• Deprecated title parameter to Column

• Deprecated css_class parameter to Column

• Removed class=’row{1,2}’ from <tr> tags. This is better accomplished with CSS.

6.0.3 (2018-12-06)

• Bug fix: “Select all” header button should fire click event, not just toggle the state.

6.0.2 (2018-12-06)

• Bug fix: “Select all items” question hidden when select all clicked again.

• Bug fix: only show “Select all item” question if a paginator is present.

6.0.1 (2018-12-04)

• Bug fix: “Select all items” question should only be presented once.

6.0.0 (2018-12-03)

• Removed argument pks to post_bulk_edit. This argument is incompatible with non-paginated bulk edit, and it’s redundant with the queryset argument.

• Added support for bulk editing of an entire queryset, not just the selected items on the current page.

• Fixed bug where the template context was not carried over to the row rendering when using a custom row template.

• Removed paginator template tag, moved the functionality into Table.render_paginator. This means it can be used from jinja2 and is generally easier to work with.

• Avoid filtering with tri.query if not needed. This means you can now take a slice of a queryset before you pass it to tri.table, if and only if you don’t then have filters to apply.

• New feature: refinable attribute preprocess_data on Table. This is useful if you want to for example display more than one row per result of a queryset or convert the paginated data into a list and do some batch mutation on the items.

• preprocess_row returning None is now deprecated. You should now return the row. Just returning the object you were sent is probably what you want.

5.3.1 (2018-10-10)

• Added Column.boolean_tristate for optionally filter boolean fields.

• Add support for setting namespace on tables to be able to reuse column names between two tables in the same view.

• Removed buggy use of setdefaults. This could cause overriding of nested arguments to not take.

5.3.0 (2018-08-19)

• Added preprocess_row feature. You can use it to mutate a row in place before access.

• Made Table a RefinableObject

5.2.2 (2018-06-29)

• Fix bad mark_safe invocation on custom cell format output.

5.2.1 (2018-06-18)

• Fixed bug with backwards compatibility for Link.

5.2.0 (2018-06-15)

• New feature: default sort ordering. Just pass default_sort_order to Table.

• Link class is now just inherited from tri_form Link. Introduced a deprecation warning for the constructor argument url.

• Simplified prepare handling for Table. You should no longer need to care about this for most operations. You will still need to call prepare to trigger the parsing of URL parameters for sorting etc.

• Fixed many_to_many_factory

5.1.1 (2018-04-09)

• Lazy and memoized BoundCell.value

5.1.0 (2018-01-08)

• Fix sorting of columns that contains None, this was not working in Python 3

5.0.0 (2017-08-22)

• Moved to tri.declarative 0.35, tri.form 5.0 and tri.query 4.0. Check release notes for tri.form and tri.query for backwards incompatible changes

• Removed deprecated template_name parameter to render_table

• Note that foo__class to specify a constructor/callable is no longer a valid parameter, because of updated tri.form, use foo__call_target or just foo

4.3.1 (2017-05-31)

• Bugfix: sorting on reverse relations didn’t work

4.3.0 (2017-04-25)

• Bugfix for Django 1.10 template handling

• Updated to tri.form 4.7.1

• Moved bulk button inside the table tag

• Dropped support for Django 1.7

4.2.0 (2017-04-21)

• New feature: post bulk edit callback

4.1.2 (2017-04-19)

• Fixed silly non-ascii characters in README.rst and also changed to survive silly non-ascii characters in that same file.

4.1.1 (2017-04-10)

• Fix missing copy of attrs__class

4.1.0 (2017-03-22)

• Column class now inherits from object, making the implementation more pythonic. (Attributes still possible to override in constructor call, see NamespaceAwareObject)

• *.template overrides can now be specified as django.template.Template instances.

• The template_name parameter to render_table is now deprecated and superceeded by a template parameter.

4.0.0 (2016-09-15)

• Updated to newest tri.form, tri.query, tri.declarative. This gives us simpler factories for from_model methods.

• Added shortcuts to Column: time and decimal

• The following shortcuts have been updated to use the corresponding Variable shortcuts: date, datetime and email

• Fix failure in endpoint result return on empty payload. [] is a valid endpoint dispatch result.

• render_table/render_table_to_response no longer allow table to be passed as a positional argument

3.0.1 (2016-09-06)

• Fix crash on unidentified sort parameter.

3.0.0 (2016-09-02)

• bound_row is passed to row level callables. This is a potential breaking change if you didn’t do **_ at the end of your function signatures (which you should!)

• bound_row and bound_column is passed to cell level callables. This is a potential breaking change like above.

• BoundRow now supports extra.

• compatibible with Django 1.9 & 1.10

• Added strict check on the kwargs config namespace of Table

• Added extra namespace to Table

• Added bound_cell parameter to rendering of cell templates.

2.5.0 (2016-07-14)

• Added optional endpoint_dispatch_prefix table configuration to enable multiple tables on the same endpoint.

2.4.0 (2016-07-13)

• Made more parts of BoundCell available for reuse.

2.3.0 (2016-07-12)

• Added pass-through of extra arguments to Link objects for custom attributes.

2.2.0 (2016-06-23)

• Fix missing namespace collection for column custimization of Table.from_model

2.1.0 (2016-06-16)

• Renamed db_compat.register_field_factory to the clearer register_column_factory

• Improved error reporting on missing django field type column factory declaration.

• Added iteration interface to table to loop over bound rows

• Added endpoint meta class parameter to table to enable custom json endpoints

2.0.0 (2016-06-02)

• Support for ajax backend

• Dependent tri.form and tri.query libraries have new major versions

1.16.0 (2016-04-25)

• Minor bugfix for fields-from-model handling of auto fields

1.15.0 (2016-04-21)

• Table.from_model implemented

1.14.0 (2016-04-19)

• Added after attribute on Column to enable custom column ordering (See tri.declarative.sort_after())

• Enable mixing column definitions in both declared fields and class meta.

• Don’t show any results if the form is invalid

1.13.0 (2016-04-08)

• Add python 3 support

1.12.0 (2016-02-29)

• Changed syntax for specifying html attributes and classes. They are now use the same way of addressing as other things, e.g.: Column(attrs__foo=”bar”, attrs__class__baz=True) will yield something like <th class=”baz” foo=bar>…</th>

1.11.0 (2016-02-04)

• Fix missing evaluation of row__attr et al.

1.10.0 (2016-01-28)

• Changed cell__template and row__template semantics slightly to enable customized cell ordering in templates.

  row__template implementations can now access a BoundCell object to use the default cell rendering.

  cell__template implementation are now assumed to render the <td> tags themself.

1.9.0 (2016-01-19)

• Fixed to work with latest version of tri.form