Tutorial¶
This is a step-by-step guide to learn how to install and use django-tables2 using Django 1.11.
pip install django-tables2
- Start a new Django app using
python manage.py startapp tutorial
- Add both
'django_tables2'
and'tutorial'
to yourINSTALLED_APPS
setting insettings.py
.
Now, add a model to your tutorial/models.py
:
# tutorial/models.py
class Person(models.Model):
name = models.CharField(max_length=100, verbose_name='full name')
Create the database tables for the newly added model:
$ python manage.py makemigrations tutorial
$ python manage.py migrate tutorial
Add some data so you have something to display in the table:
$ python manage.py shell
>>> from tutorial.models import Person
>>> Person.objects.bulk_create([Person(name='Jieter'), Person(name='Bradley')])
[<Person: Person object>, <Person: Person object>]
Now write a view to pass a Person
queryset into a template:
# tutorial/views.py
from django.shortcuts import render
from .models import Person
def people(request):
return render(request, 'tutorial/people.html', {'people': Person.objects.all()})
Add the view to your urls.py
:
# urls.py
from django.conf.urls import url
from django.contrib import admin
from tutorial.views import people
urlpatterns = [
url(r'^admin/', admin.site.urls),
url(r'^people/', people)
]
Finally, create the template:
{# tutorial/templates/tutorial/people.html #}
{% load render_table from django_tables2 %}
<!doctype html>
<html>
<head>
<title>List of persons</title>
</head>
<body>
{% render_table people %}
</body>
</html>
You should be able to load the page in the browser (http://localhost:8000/people/ by default), you should see:

While simple, passing a queryset directly to {% render_table %}
does not
allow for any customisation. For that, you must define a custom Table
class:
# tutorial/tables.py
import django_tables2 as tables
from .models import Person
class PersonTable(tables.Table):
class Meta:
model = Person
template_name = 'django_tables2/bootstrap.html'
You will then need to instantiate and configure the table in the view, before adding it to the context:
# tutorial/views.py
from django.shortcuts import render
from django_tables2 import RequestConfig
from .models import Person
from .tables import PersonTable
def people(request):
table = PersonTable(Person.objects.all())
RequestConfig(request).configure(table)
return render(request, 'people.html', {'table': table})
Using RequestConfig
automatically pulls values from request.GET
and
updates the table accordingly. This enables data ordering and pagination.
Rather than passing a queryset to {% render_table %}
, instead pass the
table instance:
{# tutorial/templates/tutorial/people.html #}
{% load render_table from django_tables2 %}
<!doctype html>
<html>
<head>
<title>List of persons</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" />
</head>
<body>
{% render_table table %}
</body>
</html>
This results in a table rendered with the bootstrap3 stylesheet:

At this point you have not actually customised anything but the template. There are several topic you can read into to futher customize the table:
- Table data
- Customizing the rendered table
- API Reference
If you think you don’t have a lot customization to do and don’t want to make
a full class declaration use django_tables2.tables.table_factory
.