-
-
Notifications
You must be signed in to change notification settings - Fork 31.6k
/
tutorial02.txt
513 lines (376 loc) · 20.2 KB
/
tutorial02.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
=====================================
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/
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.
Expose the admin media files
============================
Django's admin is intended to be fully functional and good looking. For that
reason, Django ships with admin media files -- CSS, JavaScript and images --
that comprise the admin's design. To set up a Django admin instance, the first
thing to do is put those media files online somewhere.
(Note: Although Django ships with a default design for its admin site, you can
change it however you'd like. The admin uses Django's own template system and
is powered -- surprise, surprise -- by Django itself, so it is completely
customizable.)
The files are in the ``media`` directory of the Django distribution. To
"activate" them, copy that directory under a Web document root somewhere, so
that you can access them via the Web.
Be careful not to put your Python source code under the Web document root. Just
do the media files.
Then, tell Django where you put them, via ``ADMIN_MEDIA_PREFIX`` in the
``myproject.settings.admin`` settings file. Examples::
# You can leave off the domain if they're on the same domain as your admin
# site will be.
ADMIN_MEDIA_PREFIX = '/adminmedia/'
# Otherwise, use the fully-qualified domain.
ADMIN_MEDIA_PREFIX = 'http://www.foo.com/adminmedia/'
Make sure to include a trailing slash.
Hook into mod_python
====================
Now let's take the opportunity to hook Django into Apache/mod_python. Edit your
``httpd.conf`` file and add this::
<Location "/admin/">
SetHandler python-program
PythonHandler django.core.handlers.modpython
SetEnv DJANGO_SETTINGS_MODULE myproject.settings.admin
PythonDebug On
</Location>
This tells Apache: "Use mod_python for any URL at or under '/admin/', using the
Django mod_python handler." It also passes the value of ``DJANGO_SETTINGS_MODULE``,
so mod_python knows which project to use. Note that we're passing the path to
the ``admin`` settings, not the ``main`` settings. That's because this is the
admin site, which has slightly different settings.
Also, if you've manually altered your ``PYTHONPATH`` to put your project on it,
you'll need to tell mod_python::
PythonPath "['/path/to/project'] + sys.path"
You can also add directives such as ``PythonAutoReload Off`` for performance.
See the `mod_python documentation`_ for a full list of options.
When you've done that, restart Apache 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
.. _mod_python documentation: http://modpython.org/live/current/doc-html/directives.html
Create a user account
=====================
We can't log in, though, because we haven't created an admin user account yet.
Drop into the Python interactive interpreter and type this::
# The function django.models.auth.users.create_user() creates a new user
# and returns the new auth.User object.
# Don't use 'username' and 'password'. Those are just examples.
>>> from django.models.auth import users
>>> u = users.create_user('username', 'your_email@domain.com', 'password')
# But we're not done. We need to explicitly set is_staff and is_active to
# allow this user to access the admin. Might as well make it a superuser,
# too.
u.is_staff = True
u.is_active = True
u.is_superuser = True
# Remember, call the save() method to save changes.
u.save()
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')}),
),
)
Reload the Django admin index page. Note that you might have to restart Apache,
depending on your Apache settings. Because mod_python saves code in memory for
performance, Python code changes generally aren't reflected until Apache
restarts. One way around this is to set ``MaxRequestsPerChild 1`` in your
httpd.conf to force Apache to reload everything for each request. But don't do
that on a production server, or we'll revoke your Django privileges.
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`_.
.. _Django admin CSS guide: http://www.djangoproject.com/documentation/admin_css/
Coming soon
===========
The tutorial ends here for the time being. But check back within 48 hours for
the next installments:
* Writing public-facing apps
* Using the cache framework
* Using the RSS framework
* Using the comments framework