mirror of
https://github.com/django/django.git
synced 2024-12-01 15:42:04 +01:00
d330be0169
git-svn-id: http://code.djangoproject.com/svn/django/trunk@261 bcc190cf-cafb-0310-a4f2-bffc1f526a37
454 lines
18 KiB
Plaintext
454 lines
18 KiB
Plaintext
=====================================
|
|
Writing your first Django app, part 2
|
|
=====================================
|
|
|
|
By Adrian Holovaty <holovaty@gmail.com>
|
|
|
|
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.
|
|
|
|
.. _Tutorial 1: http://www.djangoproject.com/documentation/tutorial1/
|
|
|
|
.. admonition:: Philosophy
|
|
|
|
Generating admin sites for your staff or clients to add, change and delete
|
|
content is tedious work that doesn't require much creativity. For that reason,
|
|
Django entirely automates creation of admin interfaces for models.
|
|
|
|
Django was written in a newsroom environment, with a very clear separation
|
|
between "content publishers" and the "public" site. Site managers use the
|
|
system to add news stories, events, sports scores, etc., and that content is
|
|
displayed on the public site. Django solves the problem of creating a unified
|
|
interface for site administrators to edit content.
|
|
|
|
The admin isn't necessarily intended to be used by site visitors; it's for site
|
|
managers.
|
|
|
|
Create a user account
|
|
=====================
|
|
|
|
Run the following command to create a superuser account for your admin site::
|
|
|
|
django-admin.py createsuperuser --settings="myproject.settings.main"
|
|
|
|
(Note: You can use either "myproject.settings.main" or "myproject.settings.admin"
|
|
here. They both reference the same database.)
|
|
|
|
The script will prompt you for a username, e-mail address and password (twice).
|
|
|
|
Start the development server
|
|
============================
|
|
|
|
To make things easy, Django comes with a pure-Python Web server that builds on
|
|
the BaseHTTPServer included in Python's standard library. Let's start the
|
|
server and explore the admin site.
|
|
|
|
Just run the following command to start the server::
|
|
|
|
django-admin.py runserver --settings="myproject.settings.admin"
|
|
|
|
It'll start a Web server running locally -- on port 8000, by default. If you
|
|
want to change the server's port, pass it as a command-line argument::
|
|
|
|
django-admin.py runserver 8080 --settings="myproject.settings.admin"
|
|
|
|
DON'T use this server in anything resembling a production environment. It's
|
|
intended only for use while developing.
|
|
|
|
Now, open a Web browser and go to "/admin/" on your domain. You should see the
|
|
admin's login screen:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin01.png
|
|
:alt: Django admin login screen
|
|
|
|
Enter the admin site
|
|
====================
|
|
|
|
Now, try logging in.
|
|
|
|
If it didn't work, read the `"I can't log in" questions`_ in the FAQ.
|
|
|
|
If it worked, you should see the Django admin index page:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin02t.png
|
|
:alt: Django admin index page
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin02.png
|
|
|
|
By default, you should see four types of editable content: groups, users,
|
|
redirects and flat files. These are core features Django ships with by default.
|
|
|
|
.. _"I can't log in" questions: http://www.djangoproject.com/documentation/faq/#the-admin-site
|
|
|
|
Make the poll app modifiable in the admin
|
|
=========================================
|
|
|
|
But where's our poll app? It's not displayed on the admin index page.
|
|
|
|
Just one thing to do: We need to specify in the ``polls.Poll`` model that Poll
|
|
objects have an admin interface. Edit the ``myproject/apps/polls/models/polls.py``
|
|
file and make the following change to add an ``admin`` attribute::
|
|
|
|
class Poll(meta.Model):
|
|
fields = (
|
|
# ...
|
|
)
|
|
admin = meta.Admin(
|
|
fields = (
|
|
(None, {'fields': ('question', 'pub_date')}),
|
|
),
|
|
)
|
|
|
|
Restart your development Web server, and reload the Django admin page. You'll
|
|
have to restart the server each time you make a change to Python code -- but
|
|
we're working on changing that.
|
|
|
|
You can stop the development server by hitting CONTROL-C (Unix) or CTRL-BREAK
|
|
(Windows).
|
|
|
|
Explore the free admin functionality
|
|
====================================
|
|
|
|
Now that ``Poll`` has the ``admin`` attribute, Django knows that it should be
|
|
displayed on the admin index page:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin03t.png
|
|
:alt: Django admin index page, now with polls displayed
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin03.png
|
|
|
|
Click "Polls." Now you're at the "change list" page for polls. This page
|
|
displays all the polls in the database and lets you choose one to change it.
|
|
There's the "What's up?" poll we created in the first tutorial:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin04t.png
|
|
:alt: Polls change list page
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin04.png
|
|
|
|
Click the "What's up?" poll to edit it:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin05t.png
|
|
:alt: Editing form for poll object
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin05.png
|
|
|
|
Things to note here:
|
|
|
|
* The form is automatically generated from the Poll model.
|
|
* The different model field types (``meta.DateTimeField``, ``meta.CharField``)
|
|
correspond to the appropriate HTML input widget. Each type of field knows
|
|
how to display itself in the Django admin.
|
|
* Each ``DateTimeField`` gets free JavaScript shortcuts. Dates get a "Today"
|
|
shortcut and calendar popup, and times get a "Now" shortcut and a convenient
|
|
popup that lists commonly entered times.
|
|
|
|
The bottom part of the page gives you a couple of options:
|
|
|
|
* Save -- Saves changes and returns to the change-list page for this type of
|
|
object.
|
|
* Save and continue editing -- Saves changes and reloads the admin page for
|
|
this object.
|
|
* Save and add another -- Saves changes and loads a new, blank form for this
|
|
type of object.
|
|
* Delete -- Displays a delete confirmation page.
|
|
|
|
Change the "Date published" by clicking the "Today" and "Now" shortcuts. Then
|
|
click "Save and continue editing." Then click "History" in the upper right.
|
|
You'll see a page listing all changes made to this object via the Django admin,
|
|
with the timestamp and username of the person who made the change:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin06t.png
|
|
:alt: History page for poll object
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin06.png
|
|
|
|
Customize the admin form
|
|
========================
|
|
|
|
Take a few minutes to marvel at all the code you didn't have to write.
|
|
|
|
Let's customize this a bit. We can reorder the fields by changing the
|
|
order of the field names in the ``admin`` attribute of the model::
|
|
|
|
admin = meta.Admin(
|
|
fields = (
|
|
(None, {'fields': ('pub_date', 'question')}),
|
|
),
|
|
)
|
|
|
|
That made the "Publication date" show up first instead of second:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin07.png
|
|
:alt: Fields have been reordered
|
|
|
|
This isn't impressive with only two fields, but for admin forms with dozens
|
|
of fields, choosing an intuitive order is an important usability detail.
|
|
|
|
And speaking of forms with dozens of fields, you might want to split the form
|
|
up into fieldsets::
|
|
|
|
admin = meta.Admin(
|
|
fields = (
|
|
(None, {'fields': ('question',)}),
|
|
('Date information', {'fields': ('pub_date',)}),
|
|
),
|
|
)
|
|
|
|
The first element of each tuple in ``fields`` is the title of the fieldset.
|
|
Here's what our form looks like now:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin08t.png
|
|
:alt: Form has fieldsets now
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin08.png
|
|
|
|
You can assign arbitrary HTML classes to each fieldset. Django provides a
|
|
``"collapse"`` class that displays a particular fieldset initially collapsed.
|
|
This is useful when you have a long form that contains a number of fields that
|
|
aren't commonly used::
|
|
|
|
admin = meta.Admin(
|
|
fields = (
|
|
(None, {'fields': ('question',)}),
|
|
('Date information', {'fields': ('pub_date',), 'classes': 'collapse'}),
|
|
),
|
|
)
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin09.png
|
|
:alt: Fieldset is initially collapsed
|
|
|
|
Adding related objects
|
|
======================
|
|
|
|
OK, we have our Poll admin page. But a ``Poll`` has multiple ``Choices``, and the admin
|
|
page doesn't display choices.
|
|
|
|
Yet.
|
|
|
|
In this case, there are two ways to solve this problem. The first is to give
|
|
the ``Choice`` model its own ``admin`` attribute, just as we did with ``Poll``.
|
|
Here's what that would look like::
|
|
|
|
class Choice(meta.Model):
|
|
# ...
|
|
admin = meta.Admin(
|
|
fields = (
|
|
(None, {'fields': ('poll_id', 'choice', 'votes')}),
|
|
),
|
|
)
|
|
|
|
(Note that we used "poll_id" to refer to the ``ForeignKey(Poll)`` field. The
|
|
field name is automatically calculated from the model's class name, lowercased,
|
|
plus '_id'.)
|
|
|
|
Now "Choices" is an available option in the Django admin. The "Add choice" form
|
|
looks like this:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin10.png
|
|
:alt: Choice admin page
|
|
|
|
In that form, the "Poll" field is a select box containing every poll in the
|
|
database. In our case, only one poll exists at this point.
|
|
|
|
Also note the "Add Another" link next to "Poll." Every object with a ForeignKey
|
|
relationship to another gets this for free. When you click "Add Another," you'll
|
|
get a popup window with the "Add poll" form. If you add a poll in that window
|
|
and click "Save," Django will save the poll to the database and dynamically add
|
|
it as the selected choice on the "Add choice" form you're looking at.
|
|
|
|
But, really, this is an inefficient way of adding Choice objects to the system.
|
|
It'd be better if you could add a bunch of Choices directly when you create the
|
|
Poll object. Let's make that happen.
|
|
|
|
Remove the ``admin`` for the Choice model. Then, edit the ``ForeignKey(Poll)``
|
|
field like so::
|
|
|
|
meta.ForeignKey(Poll, edit_inline=True, num_in_admin=3),
|
|
|
|
This tells Django: "Choice objects are edited on the Poll admin page. By
|
|
default, provide enough fields for 3 Choices."
|
|
|
|
Then change the other fields in ``Choice`` to give them ``core=True``::
|
|
|
|
meta.CharField('choice', 'choice', maxlength=200, core=True),
|
|
meta.IntegerField('votes', 'votes', core=True),
|
|
|
|
This tells Django: "When you edit a Choice on the Poll admin page, the 'choice'
|
|
and 'votes' fields are required. The presence of at least one of them signifies
|
|
the addition of a new Choice object, and clearing at least one of them
|
|
signifies the deletion of that existing Choice object."
|
|
|
|
Load the "Add poll" page to see how that looks:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin11t.png
|
|
:alt: Add poll page now has choices on it
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin11.png
|
|
|
|
It works like this: There are three slots for related Choices -- as specified
|
|
by ``num_in_admin`` -- but each time you come back to the "Change" page for an
|
|
already-created object, you get one extra slot. (This means there's no
|
|
hard-coded limit on how many related objects can be added.) If you wanted space
|
|
for three extra Choices each time you changed the poll, you'd use
|
|
``num_extra_on_change=3``.
|
|
|
|
One small problem, though. It takes a lot of screen space to display all the
|
|
fields for entering related Choice objects. For that reason, Django offers an
|
|
alternate way of displaying inline related objects::
|
|
|
|
meta.ForeignKey(Poll, edit_inline=True, num_in_admin=3, edit_inline_type=meta.TABULAR),
|
|
|
|
With that ``edit_inline_type=meta.TABULAR``, the related objects are displayed
|
|
in a more compact, table-based format:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin12.png
|
|
:alt: Add poll page now has more compact choices
|
|
|
|
Customize the admin change list
|
|
===============================
|
|
|
|
Now that the Poll admin page is looking good, let's make some tweaks to the
|
|
"change list" page -- the one that displays all the polls in the system.
|
|
|
|
Here's what it looks like at this point:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin04t.png
|
|
:alt: Polls change list page
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin04.png
|
|
|
|
By default, Django displays the ``repr()`` of each object. But it'd be more
|
|
helpful if we could display individual fields. To do that, use the
|
|
``list_display`` option, which is a tuple of field names to display, as columns,
|
|
on the change list page for the object::
|
|
|
|
class Poll(meta.Model):
|
|
# ...
|
|
admin = meta.Admin(
|
|
fields = (
|
|
(None, {'fields': ('question', 'pub_date')}),
|
|
),
|
|
list_display = ('question', 'pub_date'),
|
|
)
|
|
|
|
Just for good measure, let's also include the ``was_published_today`` custom
|
|
method from Tutorial 1::
|
|
|
|
list_display = ('question', 'pub_date', 'was_published_today'),
|
|
|
|
Now the poll change list page looks like this:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin13t.png
|
|
:alt: Polls change list page, updated
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin13.png
|
|
|
|
You can click on the column headers to sort by those values -- except in the
|
|
case of the ``was_published_today`` header, because sorting by the output of
|
|
an arbitrary method is not supported. Also note that the column header for
|
|
``was_published_today`` is, by default, the name of the method. But you can
|
|
change that by giving that method a ``short_description`` attribute::
|
|
|
|
def was_published_today(self):
|
|
return self.pub_date.date() == datetime.date.today()
|
|
was_published_today.short_description = 'Was published today'
|
|
|
|
|
|
Let's add another improvement to the Poll change list page: Filters. Add the
|
|
following line to ``Poll.admin``::
|
|
|
|
list_filter = ('pub_date', )
|
|
|
|
That adds a "Filter" sidebar that lets people filter the change list by the
|
|
``pub_date`` field:
|
|
|
|
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin14t.png
|
|
:alt: Polls change list page, updated
|
|
:target: http://media.djangoproject.com/img/doc/tutorial/admin14.png
|
|
|
|
The type of filter displayed depends on the type of field you're filtering on.
|
|
Because ``pub_date`` is a DateTimeField, Django knows to give the default
|
|
filter options for DateTimeFields: "Any date," "Today," "Past 7 days,"
|
|
"This month," "This year." Explore using ``list_filter`` on other types of
|
|
fields.
|
|
|
|
This is shaping up well. Let's add some search capability::
|
|
|
|
search_fields = ('question', )
|
|
|
|
That adds a search box at the top of the change list. When somebody enters
|
|
search terms, Django will search the ``question`` field. You can use as many
|
|
fields as you'd like -- although because it uses a LIKE query behind the
|
|
scenes, keep it reasonable, to keep your database happy.
|
|
|
|
Finally, because Poll objects have dates, it'd be convenient to be able to
|
|
drill down by date. Add this line::
|
|
|
|
date_hierarchy = 'pub_date',
|
|
|
|
That adds hierarchical navigation, by date, to the top of the change list page.
|
|
At top level, it displays all available years. Then it drills down to months
|
|
and, ultimately, days.
|
|
|
|
Now's also a good time to note that change lists give you free pagination. The
|
|
default is to display 50 items per page. Change-list pagination, search boxes,
|
|
filters, date-hierarchies and column-header-ordering all work together like you
|
|
think they should.
|
|
|
|
Customize the admin look and feel
|
|
=================================
|
|
|
|
Clearly having "Django administration" and "example.com" at the top of each
|
|
admin page is ridiculous. It's just placeholder text.
|
|
|
|
That's easy to change, though, using Django's template system.
|
|
|
|
Open your admin settings file and look at the ``TEMPLATE_DIRS`` setting.
|
|
``TEMPLATE_DIRS`` is a tuple of filesystem directories to check when loading
|
|
Django templates. It's a search path.
|
|
|
|
The ``django-admin.py startproject`` command automatically prepopulated
|
|
this setting with the location of Django's default admin templates, according
|
|
to where you have Django installed. But let's add an extra line to
|
|
``TEMPLATE_DIRS`` so that it checks a custom directory first, before checking
|
|
the default admin template directory::
|
|
|
|
TEMPLATE_DIRS = (
|
|
"/home/mytemplates/admin",
|
|
"/usr/lib/python2.3/site-packages/django/conf/admin_templates",
|
|
)
|
|
|
|
Now copy the template ``base_site.html`` from within the default Django admin
|
|
template directory, into ``/home/mytemplates/admin`` (or wherever you're
|
|
putting your custom admin templates). Edit the file and replace the generic
|
|
Django stuff with your own site's name as you see fit.
|
|
|
|
Note that any of Django's default admin templates can be overridden. To
|
|
override a template, just do the same thing you did with ``base_site.html`` --
|
|
copy it from the default directory into your custom directory, and make
|
|
changes.
|
|
|
|
Customize the admin index page
|
|
==============================
|
|
|
|
On a similar note, you might want to customize the look and feel of the Django
|
|
admin index page.
|
|
|
|
By default, it displays all available apps, according to your ``INSTALLED_APPS``
|
|
setting. But the order in which it displays things is random, and you may want
|
|
to make significant changes to the layout. After all, the index is probably the
|
|
most important page of the admin, and it should be easy to use.
|
|
|
|
The template to customize is ``index.html``. (Do the same as with
|
|
``base_site.html`` in the previous section -- copy it from the default directory
|
|
to your custom template directory.) Edit the file, and you'll see it uses a
|
|
template tag called ``{% get_admin_app_list as app_list %}``. That's the magic
|
|
that retrieves every installed Django app. Instead of using that, you can
|
|
hard-code links to object-specific admin pages in whatever way you think is
|
|
best.
|
|
|
|
Django offers another shortcut in this department. Run the command
|
|
``django-admin.py adminindex polls`` to get a chunk of template code for
|
|
inclusion in the admin index template. It's a useful starting point.
|
|
|
|
For full details on customizing the look and feel of the Django admin site in
|
|
general, see the `Django admin CSS guide`_.
|
|
|
|
When you're comfortable with the admin site, read `part 3 of this tutorial`_ to
|
|
start working on public poll views.
|
|
|
|
.. _Django admin CSS guide: http://www.djangoproject.com/documentation/admin_css/
|
|
.. _part 3 of this tutorial: http://www.djangoproject.com/documentation/tutorial3/
|