.. _tables:

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 :ref:`table cookbook <cookbook-tables>`; for
the exhaustive list of options see :doc:`Table` and :doc:`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:

.. code-block:: python

    Table(
        auto__model=Album,
        page_size=10,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('66dd5d59-d8fc-481f-9c38-7ac3a554d8b8', this)">▼ Hide result</div>
    <iframe id="66dd5d59-d8fc-481f-9c38-7ac3a554d8b8" src="doc_includes/tables/test_tables.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Read the full documentation and the :doc:`cookbook` for more.

Creating tables from models
---------------------------

Say I have some model:

.. code-block:: python

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

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

.. code-block:: python

    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:

.. code-block:: python

    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 :doc:`queries` for more on filtering.

Explicit tables
---------------

You can also create tables explicitly:

.. code-block:: python

    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.

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('e136f808-4979-4ba6-8f5e-9913b41b1f6a', this)">▼ Hide result</div>
    <iframe id="e136f808-4979-4ba6-8f5e-9913b41b1f6a" src="doc_includes/tables/test_explicit_tables.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Table of plain python objects
-----------------------------

.. code-block:: python

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

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('823fd3ed-57f4-4e16-bad7-1a3d4eb00956', this)">▼ Hide result</div>
    <iframe id="823fd3ed-57f4-4e16-bad7-1a3d4eb00956" src="doc_includes/tables/test_table_of_plain_python_objects.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

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