Skip to content

Latest commit

 

History

History
387 lines (258 loc) · 11.7 KB

api-reference.rst

File metadata and controls

387 lines (258 loc) · 11.7 KB
Raw

API Reference

.Accessor (.A)

django_tables2.utils.Accessor

.RequestConfig

django_tables2.config.RequestConfig

.Table

django_tables2.tables.Table

.Table.Meta

Provides a way to define global settings for table, as opposed to defining them for each instance.

For example, if you want to create a table of users with their primary key added as a data-id attribute on each <tr>, You can use the following:

class UsersTable(tables.Table):
    class Meta:
        row_attrs = {"data-id": lambda record: record.pk}

Which adds the desired row_attrs to every instance of UsersTable, in contrast of defining it at construction time:

table = tables.Table(User.objects.all(),
                     row_attrs={"data-id": lambda record: record.pk})

Some settings are only available in Table.Meta and not as an argument to the ~.Table constructor.

Note

If you define a class Meta on a child of a table already having a class Meta defined, you need to specify the parent's Meta class as the parent for the class Meta in the child:

class PersonTable(table.Table):
    class Meta:
        model = Person
        exclude = ("email", )

class PersonWithEmailTable(PersonTable):
    class Meta(PersonTable.Meta):
        exclude = ()

All attributes are overwritten if defined in the child's class Meta, no merging is attempted.

Arguments:
attrs (dict): Add custom HTML attributes to the table.

Allows custom HTML attributes to be specified which will be added to the <table> tag of any table rendered via .Table.as_html or the template-tags.render_table template tag.

This is typically used to enable a theme for a table (which is done by adding a CSS class to the <table> element):

class SimpleTable(tables.Table):
    name = tables.Column()

    class Meta:
        attrs = {"class": "paleblue"}

If you supply a a callable as a value in the dict, it will be called at table instantiation and the returned value will be used:

Consider this example where each table gets an unique "id" attribute:

import itertools
counter = itertools.count()

class UniqueIdTable(tables.Table):
    name = tables.Column()

    class Meta:
        attrs = {"id": lambda: f"table_{next(counter)}"}

Note

This functionality is also available via the attrs keyword argument to a table's constructor.

row_attrs (dict): Add custom html attributes to the table rows.

Allows custom HTML attributes to be specified which will be added to the <tr> tag of the rendered table. Optional keyword arguments are table and record.

This can be used to add each record's primary key to each row:

class PersonTable(tables.Table):
    class Meta:
        model = Person
        row_attrs = {"data-id": lambda record: record.pk}

# will result in
'<tr data-id="1">...</tr>'

Note

This functionality is also available via the row_attrs keyword argument to a table's constructor.

empty_text (str): Defines the text to display when the table has no rows.

If the table is empty and bool(empty_text) is True, a row is displayed containing empty_text. This is allows a message such as There are currently no FOO. to be displayed.

Note

This functionality is also available via the empty_text keyword argument to a table's constructor.

show_header (bool): Whether or not to show the table header.

Defines whether the table header should be displayed or not, by default, the header shows the column names.

Note

This functionality is also available via the show_header keyword argument to a table's constructor.

exclude (tuple): Exclude columns from the table.

This is useful in subclasses to exclude columns in a parent:

>>> class Person(tables.Table):
...     first_name = tables.Column()
...     last_name = tables.Column()
...
>>> Person.base_columns
{'first_name': <django_tables2.columns.Column object at 0x10046df10>,
'last_name': <django_tables2.columns.Column object at 0x10046d8d0>}
>>> class ForgetfulPerson(Person):
...     class Meta:
...         exclude = ("last_name", )
...
>>> ForgetfulPerson.base_columns
{'first_name': <django_tables2.columns.Column object at 0x10046df10>}

Note

This functionality is also available via the exclude keyword argument to a table's constructor.

However, unlike some of the other .Table.Meta options, providing the exclude keyword to a table's constructor won't override the .Meta.exclude. Instead, it will be effectively be added to it. i.e. you can't use the constructor's exclude argument to undo an exclusion.

fields (tuple): Fields to show in the table.

Used in conjunction with ~.Table.Meta.model, specifies which fields should have columns in the table. If None, all fields are used, otherwise only those named:

# models.py
class Person(models.Model):
    first_name = models.CharField(max_length=200)
    last_name = models.CharField(max_length=200)

# tables.py
class PersonTable(tables.Table):
    class Meta:
        model = Person
        fields = ("first_name", )
model (django.core.db.models.Model): Create columns from model.

A model to inspect and automatically create corresponding columns.

This option allows a Django model to be specified to cause the table to automatically generate columns that correspond to the fields in a model.

order_by (tuple or str): The default ordering tuple or comma separated str.

A hyphen - can be used to prefix a column name to indicate descending order, for example: ('name', '-age') or name,-age.

Note

This functionality is also available via the order_by keyword argument to a table's constructor.

sequence (iterable): The sequence of the table columns.

This allows the default order of columns (the order they were defined in the Table) to be overridden.

The special item '...' can be used as a placeholder that will be replaced with all the columns that were not explicitly listed. This allows you to add columns to the front or back when using inheritance.

Example:

>>> class Person(tables.Table):
...     first_name = tables.Column()
...     last_name = tables.Column()
...
...     class Meta:
...         sequence = ("last_name", "...")
...
>>> Person.base_columns.keys()
['last_name', 'first_name']

The '...' item can be used at most once in the sequence value. If it is not used, every column must be explicitly included. For example in the above example, sequence = ('last_name', ) would be invalid because neither "..." or "first_name" were included.

Note

This functionality is also available via the sequence keyword argument to a table's constructor.

orderable (bool): Default value for column's orderable attribute.

If the table and column don't specify a value, a column's orderable value will fall back to this. This provides an easy mechanism to disable ordering on an entire table, without adding orderable=False to each column in a table.

Note

This functionality is also available via the orderable keyword argument to a table's constructor.

template_name (str): The name of template to use when rendering the table.

Note

This functionality is also available via the template_name keyword argument to a table's constructor.

localize (tuple): Specifies which fields should be localized in the

table. Read localization-control for more information.

unlocalize (tuple): Specifies which fields should be unlocalized in

the table. Read localization-control for more information.

Columns

.Column

django_tables2.columns.Column

.BooleanColumn

django_tables2.columns.BooleanColumn

.CheckBoxColumn

django_tables2.columns.CheckBoxColumn

.DateColumn

django_tables2.columns.DateColumn

.DateTimeColumn

django_tables2.columns.DateTimeColumn

.EmailColumn

django_tables2.columns.EmailColumn

.FileColumn

django_tables2.columns.FileColumn

.JSONColumn

django_tables2.columns.JSONColumn

.LinkColumn

django_tables2.columns.LinkColumn

.ManyToManyColumn

django_tables2.columns.ManyToManyColumn

.RelatedLinkColumn

django_tables2.columns.RelatedLinkColumn

.TemplateColumn

django_tables2.columns.TemplateColumn

.URLColumn

django_tables2.columns.URLColumn

Views, view mixins and paginators

.SingleTableMixin

django_tables2.views.SingleTableMixin

.MultiTableMixin

django_tables2.views.MultiTableMixin

.SingleTableView

django_tables2.views.SingleTableView

.export.TableExport

django_tables2.export.TableExport

.export.ExportMixin

django_tables2.export.ExportMixin

.LazyPaginator

django_tables2.paginators.LazyPaginator

See internal for internal classes.