Tables¶

iommi tables make it easy to create full featured HTML tables.

This page explains what a Table is and what you get for free. If you want to do something specific, go to the table cookbook; for the exhaustive list of options see Table and Column.

A table generates the header, rows and cells, and comes with sorting, filtering, pagination, bulk edit, link creation, automatic rowspan and header grouping already wired up. The point is that these aren’t features you assemble: they are on by default and you turn them off or reconfigure them from the outside, which is why a useful table is usually one line of code.

Customization goes all the way down – table, row, cell, and the template for any of them – so you rarely have to abandon the abstraction to get the markup you want.

A simple example:

Table(
    auto__model=Album,
    page_size=10,
)

▼ Hide result

Toggle structure

Read the full documentation and the Cookbook for more.

Creating tables from models¶

Say I have some model:

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

    def __str__(self):
        return f'Foo: {self.a}'

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

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

def my_view(request):
    return Table(auto__model=Bar)

This automatically creates a table with pagination and sorting. If you pass query_from_indexes=True you will get filters for all the model fields that have database indexes. This filtering system includes an advanced filter language. See Queries for more on filtering.

Explicit tables¶

You can also create tables explicitly:

class AlbumTable(Table):
    # Shortcut for creating checkboxes to select rows
    select = Column.select()

    name = Column()

    # Show the name field from Artist. This works for plain old objects too.
    artist_name = Column(
        attr='artist__name',

        # put this field into the query language
        filter__include=True,
    )
    year = Column.number(
        # Enable bulk editing for this field
        bulk__include=True,
    )

    class Meta:
        rows = Album.objects.all()
        title = 'Albums'

albums = AlbumTable().as_view()

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

▼ Hide result

Toggle structure

Table of plain python objects¶

# 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)

# I can declare a table:
class FooTable(Table):
    a = Column.number()

    b = Column()

    # Display the last value of the tuple
    c = Column(
        cell__format=lambda value, **_: value[-1],
    )

    # Calculate a value not present in Foo
    sum_c = Column(
        cell__value=lambda row, **_: sum(row.c),
        sortable=False,
    )

def plain_objs_view(request):
    # and now create a list of items
    foos = [Foo(i) for i in range(4)]

    # now to get an HTML table:
    return FooTable(rows=foos)

▼ Hide result

Toggle structure

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