Tables¶

Wagtail provides a set of base table components that can be used to build tables in the Wagtail admin. For more details on how to use these components, refer to the documentation for customizing generic listings and page listings.

Base table components¶

These are the basic building blocks for constructing tables in the Wagtail admin.

class wagtail.admin.ui.tables.BaseColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

A column that encapsulates the header and data cells for rendering.

Parameters:

name – The internal name of the column, used to identify it within the table.
label – The human-readable label for the column header. If not provided, a label will be generated from the name.
accessor – A dotted path to an attribute accessed from the current row’s object, or a callable that takes the current row’s object, that returns the value for this column. This is unused by default, but may be used by subclasses such as Column.
classname – Optional CSS classes to apply to all cells in this column.
sort_key – An optional key for a query parameter that identifies the field by which the table can be sorted when this column’s header is clicked. If not provided, the column will not be sortable.
width – An optional width for the column.
ascending_title_text – An optional text for the column header’s title attribute when the column is sorted in ascending order. If not provided, a default string will be used that incorporates the column label.
descending_title_text – An optional text for the column header’s title attribute when the column is sorted in descending order. If not provided, a default string will be used that incorporates the column label.

get_cell(instance)¶: Returns an object encapsulating this column and an item of data, which we can use for rendering a table cell into a template.

get_cell_context_data(instance, parent_context)¶: Compiles the context dictionary to pass to the cell template when rendering a table cell for the given instance.

get_header_context_data(parent_context)¶: Compiles the context dictionary to pass to the header template when rendering the column header.

render_cell_html(instance, parent_context)¶: Renders a table cell containing data for the given instance.

render_header_html(parent_context)¶: Renders the column’s header.

cell_template_name = None¶: The name of the template used to render a cell of this column.

header_template_name = 'wagtailadmin/tables/column_header.html'¶: The name of the template used to render the column header.

class wagtail.admin.ui.tables.Column(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: BaseColumn

A column that displays a single field of data from the model.

get_cell_context_data(instance, parent_context)¶: Compiles the context dictionary to pass to the cell template when rendering a table cell for the given instance.

get_value(instance)¶: Given an instance (i.e. any object containing data), extracts the field of data to be displayed in a cell of this column. By default, this uses the accessor to retrieve the value.

cell_template_name = 'wagtailadmin/tables/cell.html'¶: The name of the template used to render a cell of this column.

empty_value_display = ''¶: The text to display in cells where the value is empty.

class wagtail.admin.ui.tables.Table(columns, data, template_name=None, base_url=None, ordering=None, classname=None, attrs=None, caption=None)¶

Bases: Component

A component that renders a table.

Parameters:

columns – An iterable of Column objects representing the columns of the table.
data – An iterable of objects representing the rows of the table. Each object will be passed to the columns to extract the data for each cell.
template_name – An optional name of the template used to render the table. If not provided, a default template will be used.
base_url – An optional base URL to use for constructing sorting links in the column headers.
ordering – An optional string representing the current ordering of the table, used to determine the state of the sorting links in the column headers. This should match the sort_key of one of the columns, optionally prefixed with “-” to indicate descending order.
classname – Optional CSS classes to apply to the <table> element.
attrs – An optional dictionary of additional HTML attributes to apply to the <table> element.
caption – An optional caption for the table.

get_context_data(parent_context)¶: Return the context data to render this component with.

Column types¶

These are the various column types provided by Wagtail that can be used within tables that list any type of objects. They are all subclasses of BaseColumn and can be used directly or subclassed to create new column types.

class wagtail.admin.ui.tables.BooleanColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A column that displays a True/False/None value as a tick/cross/question icon.

class wagtail.admin.ui.tables.BulkActionsCheckboxColumn(*args, obj_type, **kwargs)¶

Bases: BaseColumn

A checkbox column for the bulk actions feature.

When using this column, there should be another column (such as a TitleColumn) that has an element with the id {obj_type}_{instance.pk}_title that contains the title of the object (and nothing else) for screen reader purposes.

Parameters:: obj_type – A string representing the type of object being listed, used to construct the aria-describedby attribute for the checkboxes.

class wagtail.admin.ui.tables.DateColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A column that displays a date in human-readable format.

class wagtail.admin.ui.tables.DownloadColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A column that displays the object’s url property as a link to download a file.

class wagtail.admin.ui.tables.LiveStatusTagColumn(**kwargs)¶

Bases: StatusTagColumn

A column that displays a live/draft status tag.

class wagtail.admin.ui.tables.LocaleColumn(**kwargs)¶

Bases: Column

A column that displays a Locale label.

class wagtail.admin.ui.tables.NumberColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A specialized column that displays numbers with locale-aware formatting.

class wagtail.admin.ui.tables.orderable.OrderingColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: BaseColumn

A column that displays a reordering control for each row.

class wagtail.admin.ui.tables.ReferencesColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, get_url=None, describe_on_delete=False)¶

Bases: Column

A column that displays references that were extracted from the current row’s object.

Parameters:

get_url – An optional callable that takes the current row’s object and returns the URL to link to. If not provided, the references will be displayed without a link.
describe_on_delete – An optional boolean that determines whether to display a description of the reference’s on_delete behavior. Useful when confirming deletion of an object that has references to it, so the user can understand the consequences of deleting the object.

class wagtail.admin.ui.tables.RelatedObjectsColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A column that displays a list of objects related to the object through a one-to-many relationship.

class wagtail.admin.ui.tables.StatusFlagColumn(name, true_label=None, false_label=None, **kwargs)¶

Bases: Column

A column that displays a boolean value as a status tag (or lack thereof, if the corresponding label is None).

Parameters:

true_label – The string to display when the value is True.
false_label – The string to display when the value is False.

class wagtail.admin.ui.tables.StatusTagColumn(name, primary=None, **kwargs)¶

Bases: Column

A column that displays a status tag.

Parameters:: primary – An optional boolean or callable that takes the current row’s object and returns a boolean, indicating whether the status tag should be styled as “primary”.

class wagtail.admin.ui.tables.TitleColumn(name, url_name=None, get_url=None, get_title_id=None, label_prefix=None, get_label_id=None, link_classname=None, link_attrs=None, id_accessor='pk', **kwargs)¶

Bases: Column

A column that displays a title wrapped in a link (<a>) or <label>. The cell’s template has the ability to render action buttons.

Parameters:

url_name – An optional URL pattern name to use for constructing the link URL for each cell in this column.
get_url – An optional callable that takes the current row’s object and returns the URL to link to for that row. If both this and url_name are provided, this takes precedence.
get_title_id – An optional callable that takes the current row’s object and returns a string to use as the id attribute for an element that contains the object’s title, such as "page_{obj.pk}_title". This can be used by other columns (such as BulkActionsCheckboxColumn) for screen reader purposes.
label_prefix – An optional string prefix to use for constructing the for attribute when the title is rendered as a <label>. The id of the corresponding input element must be in the format of "{label_prefix}-{id}".
get_label_id – An optional callable that takes the current row’s object and returns a string to use as the for attribute when the title is rendered as a <label>. If both this and label_prefix are provided, this takes precedence.
link_classname – An optional string of CSS classes to apply to the <a> element when the title is wrapped in a link.
link_attrs – An optional dictionary of additional HTML attributes to apply to the <a> element when the title is wrapped in a link.
id_accessor – An optional dotted path to an attribute accessed from the current row’s object, that returns the value to use as the id when constructing URLs or label attributes. Defaults to "pk".

class wagtail.admin.ui.tables.UpdatedAtColumn(**kwargs)¶

Bases: DateColumn

A column that displays the _updated_at date annotation in human-readable format.

class wagtail.admin.ui.tables.UsageCountColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A column that displays the number of times an object has been referenced.

class wagtail.admin.ui.tables.UserColumn(name, blank_display_name='', **kwargs)¶

Bases: Column

A column that displays the username and avatar for a user.

Parameters:: blank_display_name – The text to display when the user’s name is empty.

Page-specific table components¶

These are table components that are specific to page listings in the Wagtail admin.

class wagtail.admin.ui.tables.pages.PageTitleColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: BaseColumn

A column that displays the title of a page with indicators for site root, locale, lock status, and privacy restrictions, as well as additional context such as the parent page and result scope when the results have been filtered or searched.

class wagtail.admin.ui.tables.pages.ParentPageColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A column that displays the parent page of a given page. It uses a _parent_page annotation if present on the page instance for efficiency, before falling back to calling get_parent().

class wagtail.admin.ui.tables.pages.BulkActionsColumn(*args, **kwargs)¶

Bases: BulkActionsCheckboxColumn

A page-specific version of BulkActionsCheckboxColumn that is aware of the parent page instance.

class wagtail.admin.ui.tables.pages.PageTypeColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: Column

A column that displays the page’s content type.

class wagtail.admin.ui.tables.pages.NavigateToChildrenColumn(name, label=None, accessor=None, classname=None, sort_key=None, width=None, ascending_title_text=None, descending_title_text=None)¶

Bases: BaseColumn

A column that provides a link to explore the child pages of a page.

class wagtail.admin.ui.tables.pages.PageTable(*args, parent_page=None, show_locale_labels=False, actions_next_url=None, **kwargs)¶

Bases: OrderableTableMixin, Table

A page-specific version of Table that supports reordering and supplies additional information to the context.

Supporting components¶

These are additional components that can be used to enhance the functionality of tables in the Wagtail admin, such as adding buttons or making tables orderable.

class wagtail.admin.ui.tables.ButtonsColumnMixin¶

Bases: object

A mixin for columns that contain buttons. The column’s template should iterate over the buttons variable in the context to render them.

get_buttons(instance, parent_context)¶: Returns a list of button components to be supplied as buttons in the template context.

buttons = []¶: A list of button components.

class wagtail.admin.ui.tables.orderable.OrderableTableMixin(*args, sort_order_field=None, reorder_url=None, **kwargs)¶

Bases: object

A mixin class that adds a reordering functionality to a table.