A string describing a path from one object to another via attribute/index
accesses. For convenience, the class has an alias A to allow for more concise code.
Relations are separated by a __ character.
To support list-of-dicts from QuerySet.values(), if the context is a dictionary,
and the accessor is a key in the dictionary, it is returned right away.
Indicates whether to paginate, and if so, what
default values to use. If the value evaluates to False, pagination
will be disabled. A dict can be used to specify default values for
the call to paginate (e.g. to define a default
per_page value).
A special silent item can be used to enable automatic handling of
pagination exceptions using the following logic:
data (QuerySet, list of dicts) – The data to display.
This is a required variable, a TypeError will be raised if it’s not passed.
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.
orderable (bool) – Enable/disable column ordering on this table
empty_text (str) – Empty text to render when the table has no data.
(default Table.Meta.empty_text)
exclude (iterable or str) – The names of columns that should not be
included in the table.
attrs (dict) – HTML attributes to add to the <table> tag.
When accessing the attribute, the value is always returned as an
AttributeDict to allow easily conversion to HTML.
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.
pinned_row_attrs (dict) – Same as row_attrs but for pinned rows.
sequence (iterable) –
The sequence/order of columns the columns (from
left to right).
Items in the sequence must be column names, or
"..." (string containing three periods). '...' can be used as a
catch-all for columns that are not specified.
prefix (str) – A prefix for query string fields.
To avoid name-clashes when using multiple tables on single page.
order_by_field (str) – If not None, defines the name of the order by
query string field in the URL.
page_field (str) – If not None, defines the name of the current page
query string field.
per_page_field (str) – If not None, defines the name of the per page
query string field.
template_name (str) – The template to render when using {%render_table%}
(defaults to DJANGO_TABLES2_TEMPLATE, which is "django_tables2/table.html"
by default).
default (str) – Text to render in empty cells (determined by
Column.empty_values, default Table.Meta.default)
request – Django’s request to avoid using RequestConfig
show_header (bool) – If False, the table will not have a header
(<thead>), defaults to True
show_footer (bool) – If False, the table footer will not be rendered,
even if some columns have a footer, defaults to True.
extra_columns (str, Column) – list of (name,column)-tuples containing
extra columns to add to the instance. If column is None, the column
with name will be removed from the table.
Return a row iterator of the data which would be shown in the table where
the first row is the table headers.
Parameters:
exclude_columns (iterable) – columns to exclude in the data iterator.
This can be used to output the table data as CSV, excel, for example using the
ExportMixin.
If a column is defined using a Table.render_foo methods, the returned value from
that method is used. If you want to differentiate between the rendered cell
and a value, use a value_Foo-method:
Return data for bottom pinned rows containing data for each row.
Iterable type like: QuerySet, list of dicts, list of objects.
Having a non-zero number of pinned rows
will not result in an empty result set message being rendered,
even if there are no regular data rows
Returns:
None (default) no pinned rows at the bottom, iterable, data for pinned rows at the bottom.
Note
To show pinned row this method should be overridden.
Returns a set of HTML class names for cells (both td and th) of a
bound column in this table.
By default this returns the column class names defined in the table’s
attributes.
This method can be overridden to change the default behavior, for
example to simply returnclasses_set.
Parameters:
classes_set (set of string) – a set of class names to be added
to the cell, retrieved from the column’s attributes. In the case
of a header cell (th), this also includes ordering classes.
To set the classes for a column, see Column.
To configure ordering classes, see Changing class names for ordered column headers
bound_column (BoundColumn) – the bound column the class names are
determined for. Useful for accessing bound_column.name.
Returns:
A set of class names to be added to cells of this column
If you want to add the column names to the list of classes for a column,
override this method in your custom table:
Return data for top pinned rows containing data for each row.
Iterable type like: QuerySet, list of dicts, list of objects.
Having a non-zero number of pinned rows
will not result in an empty result set message being rendered,
even if there are no regular data rows
Returns:
None (default) no pinned rows at the top, iterable, data for pinned rows at the top.
Note
To show pinned row this method should be overridden.
Some settings are only available in Table.Meta and not as an argument to
the Table constructor.
Note
If you define a classMeta on a child of a table already having a
classMeta defined, you need to specify the parent’s Meta class as
the parent for the classMeta in the child:
All attributes are overwritten if defined in the child’s classMeta,
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 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):
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:
classPersonTable(tables.Table):classMeta:model=Personrow_attrs={"data-id":lambdarecord: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:
>>> classPerson(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>}>>> classForgetfulPerson(Person):... classMeta:... 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.
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.
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
The default value for the column. This can be
a value or a callable object [1]. If an object in the data provides
None for a column, the default will be used instead.
The default value may affect ordering, depending on the type of data
the table is using. The only case where ordering is not affected is
when a QuerySet is used as the table data (since sorting is
performed by the database).
empty_values (iterable) – list of values considered as a missing value,
for which the column will render the default value. Defaults to
(None,'')
exclude_from_export (bool) – If True, this column will not be added to
the data iterator returned from as_values().
footer (str, callable) – Defines the footer of this column. If a callable
is passed, it can take optional keyword arguments column,
bound_column and table.
order_by (str, tuple or Accessor) – Allows one or more accessors to be
used for ordering rather than accessor.
orderable (bool) – If False, this column will not be allowed to
influence row ordering/sorting.
verbose_name (str) – A human readable version of the column name.
visible (bool) – If True, this column will be rendered.
Columns with visible=False will not be rendered, but will be included
in .Table.as_values() and thus also in Exporting table data.
localize –
If the cells in this column will be localized by the
localize filter:
Controls if cell content will be wrapped in an
a tag. The different ways to define the href attribute:
If True, the record.get_absolute_url() or the related model’s
get_absolute_url() is used.
If a callable is passed, the returned value is used, if it’s not None.
The callable can optionally accept any argument valid for Table.render_foo methods-methods,
for example record or value.
If a dict is passed, it’s passed on to ~django.urls.reverse.
If a tuple is passed, it must be either a (viewname, args) or (viewname, kwargs)
tuple, which is also passed to ~django.urls.reverse.
Using the linkify argument to control the linkification. These columns will all display
the value returned from str(record.user):
# If the column is named 'user', the column will use record.user.get_absolute_url()
user = tables.Column(linkify=True)
# We can also do that explicitly:
user = tables.Column(linkify=lambda record: record.user.get_absolute_url())
# or, if no get_absolute_url is defined, or a custom link is required, we have a couple
# of ways to define what is passed to reverse()
user = tables.Column(linkify={"viewname": "user_detail", "args": [tables.A("user__pk")]})
user = tables.Column(linkify=("user_detail", [tables.A("user__pk")])) # (viewname, args)
user = tables.Column(linkify=("user_detail", {"pk": tables.A("user__pk")})) # (viewname, kwargs)
initial_sort_descending (bool): If `True`, a column will sort in descending order
on "first click" after table has been rendered. If `False`, column will follow
default behavior, and sort ascending on "first click". Defaults to `False`.
This method can be overridden by table.order_FOO() methods methods on the
table or by subclassing Column; but only overrides if second element
in return tuple is True.
If the value for this cell is in empty_values, this method is
skipped and an appropriate default value is rendered instead.
Subclasses should set empty_values to () if they want to handle
all values in render.
Return the content for a specific cell for exports.
Similar to render but without any html content.
This can be used to get the data in the formatted as it is presented but in a
form that could be added to a csv file.
The default implementation just calls the render function but any
subclasses where render returns html content should override this
method.
A subclass of Column that renders as a checkbox form input.
This column allows a user to select a set of rows. The selection
information can then be used to apply some operation (e.g. “delete”) onto
the set of objects that correspond to the selected rows.
The value that is extracted from the table data for this column is
used as the value for the checkbox, i.e. <inputtype="checkbox"value="..."/>
This class implements some sensible defaults:
HTML input’s name attribute is the column name (can override
via attrs argument).
In addition to attrs keys supported by Column, the
following are available:
input – <input> elements in both <td> and <th>.
th__input – Replaces input attrs in header cells.
td__input – Replaces input attrs in body cells.
checked (Accessor, bool, callable) – Allow rendering the checkbox as
checked. If it resolves to a truthy value, the checkbox will be
rendered as checked.
Note
You might expect that you could select multiple checkboxes in the
rendered table and then do something with that. This functionality
is not implemented. If you want something to actually happen, you will
need to implement that yourself.
This property typically is not accessed directly when a table is
rendered. Instead, BoundColumn.header is accessed which in turn
accesses this property. This allows the header to fallback to the
column name (it is only available on a BoundColumn object hence
accessing that first) when this property doesn’t return something
useful.
If the value for this cell is in empty_values, this method is
skipped and an appropriate default value is rendered instead.
Subclasses should set empty_values to () if they want to handle
all values in render.
Column.attrs keys a and span can be used to add additional attributes.
Parameters:
verify_exists (bool) – attempt to determine if the file exists
If verify_exists, the HTML class exists or missing is
added to the element to indicate the integrity of the storage.
text (str or callable) – Either static text, or a callable. If set, this
will be used to render the text inside the link instead of
the file’s basename (default)
If the value for this cell is in empty_values, this method is
skipped and an appropriate default value is rendered instead.
Subclasses should set empty_values to () if they want to handle
all values in render.
Render the contents of JSONField or
HStoreField as an indented string.
New in version 1.5.0.
Note
Automatic rendering of data to this column requires PostgreSQL support
(psycopg2 installed) to import the fields, but this column can also be
used manually without it.
Parameters:
json_dumps_kwargs – kwargs passed to json.dumps, defaults to {'indent':2}
If the value for this cell is in empty_values, this method is
skipped and an appropriate default value is rendered instead.
Subclasses should set empty_values to () if they want to handle
all values in render.
Renders a normal value as an internal hyperlink to another page.
Note
This column should not be used anymore, the linkify keyword argument to
regular columns can be used to achieve the same results.
It’s common to have the primary value in a row hyperlinked to the page
dedicated to that record.
The first arguments are identical to that of
reverse and allows an internal URL to be
described. If this argument is None, then get_absolute_url.
(see Django references) will be used.
The last argument attrs allows custom HTML attributes to be added to the
rendered <ahref="..."> tag.
Parameters:
viewname (str or None) – See reverse, or use None
to use the model’s get_absolute_url
attrs (dict) – HTML attributes that are added to the rendered
<a...>...</a> tag.
text (str or callable) – Either static text, or a callable. If set, this
will be used to render the text inside link instead of value (default).
The callable gets the record being rendered as argument.
Example:
# models.pyclassPerson(models.Model):name=models.CharField(max_length=200)# urls.pyurlpatterns=patterns('',url("people/([0-9]+)/",views.people_detail,name="people_detail"))# tables.pyfromdjango_tables2.utilsimportA# alias for AccessorclassPeopleTable(tables.Table):name=tables.LinkColumn("people_detail",args=[A("pk")])
In order to override the text value (i.e. <a...>text</a>) consider
the following example:
# tables.pyfromdjango_tables2.utilsimportA# alias for AccessorclassPeopleTable(tables.Table):name=tables.LinkColumn("people_detail",text="static text",args=[A("pk")])age=tables.LinkColumn("people_detail",text=lambdarecord:record.name,args=[A("pk")])
In the first example, a static text would be rendered ("statictext")
In the second example, you can specify a callable which accepts a record object (and thus
can return anything from it)
In addition to attrs keys supported by Column, the following are
available:
Display the list of objects from a ManyRelatedManager
Ordering is disabled for this column.
Parameters:
transform – callable to transform each item to text, it gets an item as argument
and must return a string-like representation of the item.
By default, it calls force_str on each item.
filter – callable to filter, limit or order the QuerySet, it gets the
ManyRelatedManager as first argument and must return a filtered QuerySet.
By default, it returns all()
separator – separator string to join the items with. default: ","
linkify_item – callable, arguments to reverse() or True to wrap items in a <a> tag.
For a detailed explanation, see linkify argument to Column.
For example, when displaying a list of friends with their full name:
If the value for this cell is in empty_values, this method is
skipped and an appropriate default value is rendered instead.
Subclasses should set empty_values to () if they want to handle
all values in render.
template_name (str) – name of the template to render
extra_context (dict) – optional extra template context
A Template object is created from the
template_code or template_name and rendered with a context containing:
record – data record for the current row
value – value from record that corresponds to the current column
default – appropriate default value to use as fallback.
row_counter – The number of the row this cell is being rendered in.
any context variables passed using the extra_context argument to TemplateColumn.
Example:
classExampleTable(tables.Table):foo=tables.TemplateColumn("{{ record.bar }}")# contents of `myapp/bar_column.html` is `{{ label }}: {{ value }}`bar=tables.TemplateColumn(template_name="myapp/name2_column.html",extra_context={"label":"Label"})
If the value for this cell is in empty_values, this method is
skipped and an appropriate default value is rendered instead.
Subclasses should set empty_values to () if they want to handle
all values in render.
controls table pagination. If a dict, passed as
the paginate keyword argument to RequestConfig. As such, any
Truthy value enables pagination. (default: enable pagination).
The dict can be used to specify values for arguments for the call to
paginate.
If you want to use a non-standard paginator for example, you can add a key
paginator_class to the dict, containing a custom Paginator class.
Add a list with multiple Table object’s to the context. Typically used with
TemplateResponseMixin.
The tables attribute must be either a list of Table instances or
classes extended from Table which are not already instantiated. In that
case, get_tables_data must be able to return the tables data, either by
having an entry containing the data for each table in tables, or by
overriding this method in order to return this data.
if defined, tables is assumed to be a list of table
classes which will be instantiated with the corresponding item from
this list of TableData instances.
Prefix to be used for each table. The string must
contain one instance of {}, which will be replaced by an integer
different for each table in the view. Default is ‘table_{}-‘.
is the name of the GET attribute used to trigger
the export. It’s value decides the export format, refer to
TableExport for a list of available formats.
column names excluded from the export.
For example, one might want to exclude columns containing buttons from
the export. Excluding columns from the export is also possible using the
exclude_from_export argument to the Column constructor:
Implement lazy pagination, preventing any count() queries.
By default, for any valid page, the total number of pages for the paginator will be
current+1 if the number of records fetched for the current page offset is
bigger than the number of records per page.
current if the number of records fetched is less than the number of records per page.
The number of additional records fetched can be adjusted using look_ahead, which
defaults to 1 page. If you like to provide a little more extra information on how much
pages follow the current page, you can use a higher value.
Note
The number of records fetched for each page is per_page*look_ahead+1, so increasing
the value for look_ahead makes the view a bit more expensive.