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

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

\n

This tutorial begins where Tutorial 1 left off. We’re\ncontinuing the Web-poll application and will focus on Django’s\nautomatically-generated admin site.

\n\n
\n

Creating an admin userLink to this heading#

\n

First we’ll need to create a user who can login to the admin site. Run the\nfollowing command:

\n
Shell
$ python manage.py createsuperuser\n
\n

Enter your desired username and press enter.

\n
Text
Username: admin\n
\n

You will then be prompted for your desired email address:

\n
Text
Email address: admin@example.com\n
\n

The final step is to enter your password. You will be asked to enter your\npassword twice, the second time as a confirmation of the first.

\n
Text
Password: **********\nPassword (again): *********\nSuperuser created successfully.\n
\n
\n
\n

Start the development serverLink to this heading#

\n

The Django admin site is activated by default. Let’s start the development\nserver and explore it.

\n

Recall from Tutorial 1 that you start the development server like so:

\n
Shell
$ python manage.py runserver\n
\n

Now, open a Web browser and go to “/admin/” on your local domain – e.g.,\nhttp://127.0.0.1:8000/admin/. You should see the admin’s login screen:

\n\"Django\n

Since translation is turned on by default,\nthe login screen may be displayed in your own language, depending on your\nbrowser’s settings and on whether Django has a translation for this language.

\n\n
\n
\n

Enter the admin siteLink to this heading#

\n

Now, try logging in with the superuser account you created in the previous step.\nYou should see the Django admin index page:

\n\"Django\n

You should see a few types of editable content: groups and users. They are\nprovided by django.contrib.auth, the authentication framework shipped\nby Django.

\n
\n
\n

Make the poll app modifiable in the adminLink to this heading#

\n

But where’s our poll app? It’s not displayed on the admin index page.

\n

Just one thing to do: we need to tell the admin that Question\nobjects have an admin interface. To do this, open the polls/admin.py\nfile, and edit it to look like this:

\n
polls/admin.py
Code
from django.contrib import admin\n\nfrom .models import Question\n\nadmin.site.register(Question)\n
\n
\n
\n

Explore the free admin functionalityLink to this heading#

\n

Now that we’ve registered Question, Django knows that it should be displayed on\nthe admin index page:

\n\"Django\n

Click “Questions”. Now you’re at the “change list” page for questions. This page\ndisplays all the questions in the database and lets you choose one to change it.\nThere’s the “What’s up?” question we created in the first tutorial:

\n\"Polls\n

Click the “What’s up?” question to edit it:

\n\"Editing\n

Things to note here:

\n\n

The bottom part of the page gives you a couple of options:

\n\n

If the value of “Date published” doesn’t match the time when you created the\nquestion in Tutorial 1, it probably means you forgot to set the correct value for\nthe TIME_ZONE setting. Change it, reload the page and check that\nthe correct value appears.

\n

Change the “Date published” by clicking the “Today” and “Now” shortcuts. Then\nclick “Save and continue editing.” Then click “History” in the upper right.\nYou’ll see a page listing all changes made to this object via the Django admin,\nwith the timestamp and username of the person who made the change:

\n\"History\n
\n
\n

Customize the admin formLink to this heading#

\n

Take a few minutes to marvel at all the code you didn’t have to write. By\nregistering 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 re-ordering the fields on the edit form. Replace\nthe admin.site.register(Question) line with:

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

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

\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
Code
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\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

You can assign arbitrary HTML classes to each fieldset. Django provides a\n"collapse" class that displays a particular fieldset initially collapsed.\nThis is useful when you have a long form that contains a number of fields that\naren’t commonly used:

\n
polls/admin.py
Code
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'], 'classes': ['collapse']}),\n    ]\n\nadmin.site.register(Question, QuestionAdmin)\n
\n\"Fieldset\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\ntuple of field names to display, as columns, on the change list page for the\nobject:

\n
polls/admin.py
Code
class QuestionAdmin(admin.ModelAdmin):\n    # ...\n    list_display = ('question_text', 'pub_date')\n
\n

Just for good measure, let’s also include the was_published_recently custom\nmethod from Tutorial 1:

\n
polls/admin.py
Code
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 giving that method (in polls/models.py) a few\nattributes, as follows:

\n
polls/models.py
Code
class Question(models.Model):\n    # ...\n    def was_published_recently(self):\n        return self.pub_date >= timezone.now() - datetime.timedelta(days=1)\n    was_published_recently.admin_order_field = 'pub_date'\n    was_published_recently.boolean = True\n    was_published_recently.short_description = 'Published recently?'\n
\n

For more information on these method properties, 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

That’s easy to change, though, using Django’s template system. The Django admin\nis powered by Django itself, and its interfaces use Django’s own template\nsystem.

\n
\n

Customizing your project’s templatesLink to this heading#

\n

Create a templates directory in your project directory (the one that\ncontains manage.py). Templates can live anywhere on your filesystem that\nDjango can access. (Django runs as whatever user your server runs.) However,\nkeeping your templates within the 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
Code
TEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [os.path.join(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

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, just 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<h1 id="site-name"><a href="{% url 'admin:index' %}">Polls Administration</a></h1>\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.\nDon’t worry if you can’t make any sense of the template right now –\nwe’ll delve into Django’s templating language in Tutorial 3.

\n

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

\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. Again,\ndon’t worry if you can’t understand the template language – we’ll cover that\nin more detail in Tutorial 3.

\n

When you’re comfortable with the admin site, read part 3 of this tutorial to start working on public poll views.

\n
","rootId":"writing-your-first-django-app-part-2","toc":[{"title":"Creating an admin user","anchor":"creating-an-admin-user","children":[]},{"title":"Start the development server","anchor":"start-the-development-server","children":[]},{"title":"Enter the admin site","anchor":"enter-the-admin-site","children":[]},{"title":"Make the poll app modifiable in the admin","anchor":"make-the-poll-app-modifiable-in-the-admin","children":[]},{"title":"Explore the free admin functionality","anchor":"explore-the-free-admin-functionality","children":[]},{"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/1.8/intro/"}],"prev":{"docname":"intro/tutorial01","title":"Writing your first Django app, part 1","url":"/en/1.8/intro/tutorial01/"},"next":{"docname":"intro/tutorial03","title":"Writing your first Django app, part 3","url":"/en/1.8/intro/tutorial03/"},"formats":{"html":"/en/1.8/intro/tutorial02/","markdown":"/en/1.8/intro/tutorial02.md","json":"/en/1.8/intro/tutorial02.json"},"source":"https://github.com/django/django/blob/stable/1.8.x/docs/intro/tutorial02.txt","official":"https://docs.djangoproject.com/en/1.8/intro/tutorial02/","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","1.8"],"inLocales":["en"]}