{"title":"Writing your first Django app, part 7","version":"5.1","locale":"en","docname":"intro/tutorial07","url":"/en/5.1/intro/tutorial07/","canonical":"https://djangodocs.dev/en/5.1/intro/tutorial07/","summary":"This tutorial begins where Tutorial 6 left off. We’re continuing the web-poll application and will focus on customizing Django’s automatically-generated admin site…","html":"

Writing your first Django app, part 7Link to this heading#

\n

This tutorial begins where Tutorial 6 left off. We’re\ncontinuing the web-poll application and will focus on customizing Django’s\nautomatically-generated admin site that we first explored in Tutorial 2.

\n\n
\n

Customize the admin formLink to this heading#

\n

By registering the Question model with admin.site.register(Question),\nDjango was able to construct a default form representation. Often, you’ll want\nto customize how the admin form looks and works. You’ll do this by telling\nDjango the options you want when you register the object.

\n

Let’s see how this works by reordering the fields on the edit form. Replace\nthe admin.site.register(Question) line with:

\n
polls/admin.py
\n
Python
from django.contrib import admin\n\nfrom .models import Question\n\n\nclass QuestionAdmin(admin.ModelAdmin):\n    fields = ["pub_date", "question_text"]\n\n\nadmin.site.register(Question, QuestionAdmin)\n
\n

You’ll follow this pattern – create a model admin class, then pass it as the\nsecond argument to admin.site.register() – any time you need to change the\nadmin options for a model.

\n

This particular change above makes the “Publication date” come before the\n“Question” field:

\n\"Fields\n

This isn’t impressive with only two fields, but for admin forms with dozens\nof fields, choosing an intuitive order is an important usability detail.

\n

And speaking of forms with dozens of fields, you might want to split the form\nup into fieldsets:

\n
polls/admin.py
\n
Python
from django.contrib import admin\n\nfrom .models import Question\n\n\nclass QuestionAdmin(admin.ModelAdmin):\n    fieldsets = [\n        (None, {"fields": ["question_text"]}),\n        ("Date information", {"fields": ["pub_date"]}),\n    ]\n\n\nadmin.site.register(Question, QuestionAdmin)\n
\n

The first element of each tuple in\nfieldsets is the title of the fieldset.\nHere’s what our form looks like now:

\n\"Form\n
\n\n
\n

Customize the admin change listLink to this heading#

\n

Now that the Question admin page is looking good, let’s make some tweaks to the\n“change list” page – the one that displays all the questions in the system.

\n

Here’s what it looks like at this point:

\n\"Polls\n

By default, Django displays the str() of each object. But sometimes it’d be\nmore helpful if we could display individual fields. To do that, use the\nlist_display admin option, which is a\nlist of field names to display, as columns, on the change list page for the\nobject:

\n
polls/admin.py
\n
Python
class QuestionAdmin(admin.ModelAdmin):\n    # ...\n    list_display = ["question_text", "pub_date"]\n
\n

For good measure, let’s also include the was_published_recently() method\nfrom Tutorial 2:

\n
polls/admin.py
\n
Python
class QuestionAdmin(admin.ModelAdmin):\n    # ...\n    list_display = ["question_text", "pub_date", "was_published_recently"]\n
\n

Now the question change list page looks like this:

\n\"Polls\n

You can click on the column headers to sort by those values – except in the\ncase of the was_published_recently header, because sorting by the output\nof an arbitrary method is not supported. Also note that the column header for\nwas_published_recently is, by default, the name of the method (with\nunderscores replaced with spaces), and that each line contains the string\nrepresentation of the output.

\n

You can improve that by using the display()\ndecorator on that method (extending the polls/models.py file that was\ncreated in Tutorial 2), as follows:

\n
polls/models.py
\n
Python
from django.contrib import admin\n\n\nclass Question(models.Model):\n    # ...\n    @admin.display(\n        boolean=True,\n        ordering="pub_date",\n        description="Published recently?",\n    )\n    def was_published_recently(self):\n        now = timezone.now()\n        return now - datetime.timedelta(days=1) <= self.pub_date <= now\n
\n

For more information on the properties configurable via the decorator, see\nlist_display.

\n

Edit your polls/admin.py file again and add an improvement to the\nQuestion change list page: filters using the\nlist_filter. Add the following line to\nQuestionAdmin:

\n
Code
list_filter = ["pub_date"]\n
\n

That adds a “Filter” sidebar that lets people filter the change list by the\npub_date field:

\n\"Polls\n

The type of filter displayed depends on the type of field you’re filtering on.\nBecause pub_date is a DateTimeField, Django\nknows to give appropriate filter options: “Any date”, “Today”, “Past 7 days”,\n“This month”, “This year”.

\n

This is shaping up well. Let’s add some search capability:

\n
Code
search_fields = ["question_text"]\n
\n

That adds a search box at the top of the change list. When somebody enters\nsearch terms, Django will search the question_text field. You can use as many\nfields as you’d like – although because it uses a LIKE query behind the\nscenes, limiting the number of search fields to a reasonable number will make\nit easier for your database to do the search.

\n

Now’s also a good time to note that change lists give you free pagination. The\ndefault is to display 100 items per page. Change list pagination, search boxes, filters, date-hierarchies, and\ncolumn-header-ordering\nall work together like you think they should.

\n
\n
\n

Customize the admin look and feelLink to this heading#

\n

Clearly, having “Django administration” at the top of each admin page is\nridiculous. It’s just placeholder text.

\n

You can change it, though, using Django’s template system. The Django admin is\npowered by Django itself, and its interfaces use Django’s own template system.

\n
\n

Customizing your project’s templatesLink to this heading#

\n

Create a templates directory in your djangotutorial directory.\nTemplates can live anywhere on your filesystem that Django can access. (Django\nruns as whatever user your server runs.) However, keeping your templates within\nthe project is a good convention to follow.

\n

Open your settings file (mysite/settings.py, remember) and add a\nDIRS option in the TEMPLATES setting:

\n
mysite/settings.py
\n
Python
TEMPLATES = [\n    {\n        "BACKEND": "django.template.backends.django.DjangoTemplates",\n        "DIRS": [BASE_DIR / "templates"],\n        "APP_DIRS": True,\n        "OPTIONS": {\n            "context_processors": [\n                "django.template.context_processors.debug",\n                "django.template.context_processors.request",\n                "django.contrib.auth.context_processors.auth",\n                "django.contrib.messages.context_processors.messages",\n            ],\n        },\n    },\n]\n
\n

DIRS is a list of filesystem directories to check\nwhen loading Django templates; it’s a search path.

\n\n

Now create a directory called admin inside templates, and copy the\ntemplate admin/base_site.html from within the default Django admin\ntemplate directory in the source code of Django itself\n(django/contrib/admin/templates) into that directory.

\n\n

Then, edit the file and replace\n{{ site_header|default:_('Django administration') }} (including the curly\nbraces) with your own site’s name as you see fit. You should end up with\na section of code like:

\n
Django template
{% block branding %}\n<div id="site-name"><a href="{% url 'admin:index' %}">Polls Administration</a></div>\n{% if user.is_anonymous %}\n  {% include "admin/color_theme_toggle.html" %}\n{% endif %}\n{% endblock %}\n
\n

We use this approach to teach you how to override templates. In an actual\nproject, you would probably use\nthe django.contrib.admin.AdminSite.site_header attribute to more easily\nmake this particular customization.

\n

This template file contains lots of text like {% block branding %}\nand {{ title }}. The {% and {{ tags are part of Django’s\ntemplate language. When Django renders admin/base_site.html, this\ntemplate language will be evaluated to produce the final HTML page, just like\nwe saw in Tutorial 3.

\n

Note that any of Django’s default admin templates can be overridden. To\noverride a template, do the same thing you did with base_site.html – copy\nit from the default directory into your custom directory, and make changes.

\n
\n
\n

Customizing your application’s templatesLink to this heading#

\n

Astute readers will ask: But if DIRS was empty by\ndefault, how was Django finding the default admin templates? The answer is\nthat, since APP_DIRS is set to True,\nDjango automatically looks for a templates/ subdirectory within each\napplication package, for use as a fallback (don’t forget that\ndjango.contrib.admin is an application).

\n

Our poll application is not very complex and doesn’t need custom admin\ntemplates. But if it grew more sophisticated and required modification of\nDjango’s standard admin templates for some of its functionality, it would be\nmore sensible to modify the application’s templates, rather than those in the\nproject. That way, you could include the polls application in any new project\nand be assured that it would find the custom templates it needed.

\n

See the template loading documentation for more\ninformation about how Django finds its templates.

\n
\n
\n
\n

Customize the admin index pageLink to this heading#

\n

On a similar note, you might want to customize the look and feel of the Django\nadmin index page.

\n

By default, it displays all the apps in INSTALLED_APPS that have been\nregistered with the admin application, in alphabetical order. You may want to\nmake significant changes to the layout. After all, the index is probably the\nmost important page of the admin, and it should be easy to use.

\n

The template to customize is admin/index.html. (Do the same as with\nadmin/base_site.html in the previous section – copy it from the default\ndirectory to your custom template directory). Edit the file, and you’ll see it\nuses a template variable called app_list. That variable contains every\ninstalled Django app. Instead of using that, you can hard-code links to\nobject-specific admin pages in whatever way you think is best.

\n

When you’re comfortable with the admin, read part 8 of this\ntutorial to learn how to use third-party packages.

\n
","rootId":"writing-your-first-django-app-part-7","toc":[{"title":"Customize the admin form","anchor":"customize-the-admin-form","children":[]},{"title":"Adding related objects","anchor":"adding-related-objects","children":[]},{"title":"Customize the admin change list","anchor":"customize-the-admin-change-list","children":[]},{"title":"Customize the admin look and feel","anchor":"customize-the-admin-look-and-feel","children":[{"title":"Customizing your project’s templates","anchor":"customizing-your-project-s-templates","children":[]},{"title":"Customizing your application’s templates","anchor":"customizing-your-application-s-templates","children":[]}]},{"title":"Customize the admin index page","anchor":"customize-the-admin-index-page","children":[]}],"breadcrumbs":[{"docname":"intro/index","title":"Getting started","url":"/en/5.1/intro/"}],"prev":{"docname":"intro/tutorial06","title":"Writing your first Django app, part 6","url":"/en/5.1/intro/tutorial06/"},"next":{"docname":"intro/tutorial08","title":"Writing your first Django app, part 8","url":"/en/5.1/intro/tutorial08/"},"formats":{"html":"/en/5.1/intro/tutorial07/","markdown":"/en/5.1/intro/tutorial07.md","json":"/en/5.1/intro/tutorial07.json"},"source":"https://github.com/django/django/blob/stable/5.1.x/docs/intro/tutorial07.txt","official":"https://docs.djangoproject.com/en/5.1/intro/tutorial07/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}