-
-
Notifications
You must be signed in to change notification settings - Fork 31.6k
/
index.txt
2105 lines (1512 loc) · 81.9 KB
/
index.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
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=====================
The Django admin site
=====================
.. module:: django.contrib.admin
:synopsis: Django's admin site.
One of the most powerful parts of Django is the automatic admin interface. It
reads metadata in your model to provide a powerful and production-ready
interface that content producers can immediately use to start adding content to
the site. In this document, we discuss how to activate, use and customize
Django's admin interface.
Overview
========
There are seven steps in activating the Django admin site:
1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS`
setting.
2. The admin has four dependencies - :mod:`django.contrib.auth`,
:mod:`django.contrib.contenttypes`,
:mod:`django.contrib.messages` and
:mod:`django.contrib.sessions`. If these applications are not
in your :setting:`INSTALLED_APPS` list, add them.
3. Add ``django.contrib.messages.context_processors.messages`` to
:setting:`TEMPLATE_CONTEXT_PROCESSORS` as well as
:class:`django.contrib.auth.middleware.AuthenticationMiddleware` and
:class:`django.contrib.messages.middleware.MessageMiddleware` to
:setting:`MIDDLEWARE_CLASSES`. (These are all active by default, so
you only need to do this if you've manually tweaked the settings.)
4. Determine which of your application's models should be editable in the
admin interface.
5. For each of those models, optionally create a ``ModelAdmin`` class that
encapsulates the customized admin functionality and options for that
particular model.
6. Instantiate an ``AdminSite`` and tell it about each of your models and
``ModelAdmin`` classes.
7. Hook the ``AdminSite`` instance into your URLconf.
After you've taken these steps, you'll be able to use your Django admin site
by visiting the URL you hooked it into (``/admin/``, by default).
Other topics
------------
.. toctree::
:maxdepth: 1
actions
admindocs
.. seealso::
For information about serving the static files (images, JavaScript, and
CSS) associated with the admin in production, see :ref:`serving-files`.
Having problems? Try :doc:`/faq/admin`.
``ModelAdmin`` objects
======================
.. class:: ModelAdmin
The ``ModelAdmin`` class is the representation of a model in the admin
interface. These are stored in a file named ``admin.py`` in your
application. Let's take a look at a very simple example of
the ``ModelAdmin``::
from django.contrib import admin
from myproject.myapp.models import Author
class AuthorAdmin(admin.ModelAdmin):
pass
admin.site.register(Author, AuthorAdmin)
.. admonition:: Do you need a ``ModelAdmin`` object at all?
In the preceding example, the ``ModelAdmin`` class doesn't define any
custom values (yet). As a result, the default admin interface will be
provided. If you are happy with the default admin interface, you don't
need to define a ``ModelAdmin`` object at all -- you can register the
model class without providing a ``ModelAdmin`` description. The
preceding example could be simplified to::
from django.contrib import admin
from myproject.myapp.models import Author
admin.site.register(Author)
``ModelAdmin`` options
----------------------
The ``ModelAdmin`` is very flexible. It has several options for dealing with
customizing the interface. All options are defined on the ``ModelAdmin``
subclass::
class AuthorAdmin(admin.ModelAdmin):
date_hierarchy = 'pub_date'
.. attribute:: ModelAdmin.actions
A list of actions to make available on the change list page. See
:doc:`/ref/contrib/admin/actions` for details.
.. attribute:: ModelAdmin.actions_on_top
.. attribute:: ModelAdmin.actions_on_bottom
Controls where on the page the actions bar appears. By default, the admin
changelist displays actions at the top of the page (``actions_on_top = True;
actions_on_bottom = False``).
.. attribute:: ModelAdmin.actions_selection_counter
Controls whether a selection counter is displayed next to the action dropdown.
By default, the admin changelist will display it
(``actions_selection_counter = True``).
.. attribute:: ModelAdmin.date_hierarchy
Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField``
in your model, and the change list page will include a date-based drilldown
navigation by that field.
Example::
date_hierarchy = 'pub_date'
This will intelligently populate itself based on available data,
e.g. if all the dates are in one month, it'll show the day-level
drill-down only.
.. attribute:: ModelAdmin.exclude
This attribute, if given, should be a list of field names to exclude from
the form.
For example, let's consider the following model::
class Author(models.Model):
name = models.CharField(max_length=100)
title = models.CharField(max_length=3)
birth_date = models.DateField(blank=True, null=True)
If you want a form for the ``Author`` model that includes only the ``name``
and ``title`` fields, you would specify ``fields`` or ``exclude`` like
this::
class AuthorAdmin(admin.ModelAdmin):
fields = ('name', 'title')
class AuthorAdmin(admin.ModelAdmin):
exclude = ('birth_date',)
Since the Author model only has three fields, ``name``, ``title``, and
``birth_date``, the forms resulting from the above declarations will
contain exactly the same fields.
.. attribute:: ModelAdmin.fields
If you need to achieve simple changes in the layout of fields in the forms
of the "add" and "change" pages like only showing a subset of the available
fields, modifying their order or grouping them in rows you can use the
``fields`` option (for more complex layout needs see the
:attr:`~ModelAdmin.fieldsets` option described in the next section). For
example, you could define a simpler version of the admin form for the
``django.contrib.flatpages.FlatPage`` model as follows::
class FlatPageAdmin(admin.ModelAdmin):
fields = ('url', 'title', 'content')
In the above example, only the fields ``url``, ``title`` and ``content``
will be displayed, sequentially, in the form. ``fields`` can contain
values defined in :attr:`ModelAdmin.readonly_fields` to be displayed as
read-only.
.. versionadded:: 1.4
To display multiple fields on the same line, wrap those fields in their own
tuple. In this example, the ``url`` and ``title`` fields will display on the
same line and the ``content`` field will be displayed below them in its
own line::
class FlatPageAdmin(admin.ModelAdmin):
fields = (('url', 'title'), 'content')
.. admonition:: Note
This ``fields`` option should not be confused with the ``fields``
dictionary key that is within the :attr:`~ModelAdmin.fieldsets` option,
as described in the next section.
If neither ``fields`` nor :attr:`~ModelAdmin.fieldsets` options are present,
Django will default to displaying each field that isn't an ``AutoField`` and
has ``editable=True``, in a single fieldset, in the same order as the fields
are defined in the model.
.. attribute:: ModelAdmin.fieldsets
Set ``fieldsets`` to control the layout of admin "add" and "change" pages.
``fieldsets`` is a list of two-tuples, in which each two-tuple represents a
``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of
the form.)
The two-tuples are in the format ``(name, field_options)``, where ``name``
is a string representing the title of the fieldset and ``field_options`` is
a dictionary of information about the fieldset, including a list of fields
to be displayed in it.
A full example, taken from the :class:`django.contrib.flatpages.FlatPage`
model::
class FlatPageAdmin(admin.ModelAdmin):
fieldsets = (
(None, {
'fields': ('url', 'title', 'content', 'sites')
}),
('Advanced options', {
'classes': ('collapse',),
'fields': ('enable_comments', 'registration_required', 'template_name')
}),
)
This results in an admin page that looks like:
.. image:: _images/flatfiles_admin.png
If neither ``fieldsets`` nor :attr:`~ModelAdmin.fields` options are present,
Django will default to displaying each field that isn't an ``AutoField`` and
has ``editable=True``, in a single fieldset, in the same order as the fields
are defined in the model.
The ``field_options`` dictionary can have the following keys:
* ``fields``
A tuple of field names to display in this fieldset. This key is
required.
Example::
{
'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
}
Just like with the :attr:`~ModelAdmin.fields` option, to display
multiple fields on the same line, wrap those fields in their own
tuple. In this example, the ``first_name`` and ``last_name`` fields
will display on the same line::
{
'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
}
``fields`` can contain values defined in
:attr:`~ModelAdmin.readonly_fields` to be displayed as read-only.
* ``classes``
A list containing extra CSS classes to apply to the fieldset.
Example::
{
'classes': ['wide', 'extrapretty'],
}
Two useful classes defined by the default admin site stylesheet are
``collapse`` and ``wide``. Fieldsets with the ``collapse`` style
will be initially collapsed in the admin and replaced with a small
"click to expand" link. Fieldsets with the ``wide`` style will be
given extra horizontal space.
* ``description``
A string of optional extra text to be displayed at the top of each
fieldset, under the heading of the fieldset.
Note that this value is *not* HTML-escaped when it's displayed in
the admin interface. This lets you include HTML if you so desire.
Alternatively you can use plain text and
``django.utils.html.escape()`` to escape any HTML special
characters.
.. attribute:: ModelAdmin.filter_horizontal
By default, a :class:`~django.db.models.ManyToManyField` is displayed in
the admin site with a ``<select multiple>``. However, multiple-select boxes
can be difficult to use when selecting many items. Adding a
:class:`~django.db.models.ManyToManyField` to this list will instead use
a nifty unobtrusive JavaScript "filter" interface that allows searching
within the options. The unselected and selected options appear in two boxes
side by side. See :attr:`~ModelAdmin.filter_vertical` to use a vertical
interface.
.. attribute:: ModelAdmin.filter_vertical
Same as :attr:`~ModelAdmin.filter_horizontal`, but uses a vertical display
of the filter interface with the box of unselected options appearing above
the box of selected options.
.. attribute:: ModelAdmin.form
By default a ``ModelForm`` is dynamically created for your model. It is
used to create the form presented on both the add/change pages. You can
easily provide your own ``ModelForm`` to override any default form behavior
on the add/change pages. Alternatively, you can customize the default
form rather than specifying an entirely new one by using the
:meth:`ModelAdmin.get_form` method.
For an example see the section `Adding custom validation to the admin`_.
.. admonition:: Note
If your ``ModelForm`` and ``ModelAdmin`` both define an ``exclude``
option then ``ModelAdmin`` takes precedence::
class PersonForm(forms.ModelForm):
class Meta:
model = Person
exclude = ['name']
class PersonAdmin(admin.ModelAdmin):
exclude = ['age']
form = PersonForm
In the above example, the "age" field will be excluded but the "name"
field will be included in the generated form.
.. attribute:: ModelAdmin.formfield_overrides
This provides a quick-and-dirty way to override some of the
:class:`~django.forms.Field` options for use in the admin.
``formfield_overrides`` is a dictionary mapping a field class to a dict of
arguments to pass to the field at construction time.
Since that's a bit abstract, let's look at a concrete example. The most
common use of ``formfield_overrides`` is to add a custom widget for a
certain type of field. So, imagine we've written a ``RichTextEditorWidget``
that we'd like to use for large text fields instead of the default
``<textarea>``. Here's how we'd do that::
from django.db import models
from django.contrib import admin
# Import our custom widget and our model from where they're defined
from myapp.widgets import RichTextEditorWidget
from myapp.models import MyModel
class MyModelAdmin(admin.ModelAdmin):
formfield_overrides = {
models.TextField: {'widget': RichTextEditorWidget},
}
Note that the key in the dictionary is the actual field class, *not* a
string. The value is another dictionary; these arguments will be passed to
:meth:`~django.forms.Field.__init__`. See :doc:`/ref/forms/api` for
details.
.. warning::
If you want to use a custom widget with a relation field (i.e.
:class:`~django.db.models.ForeignKey` or
:class:`~django.db.models.ManyToManyField`), make sure you haven't
included that field's name in ``raw_id_fields`` or ``radio_fields``.
``formfield_overrides`` won't let you change the widget on relation
fields that have ``raw_id_fields`` or ``radio_fields`` set. That's
because ``raw_id_fields`` and ``radio_fields`` imply custom widgets of
their own.
.. attribute:: ModelAdmin.inlines
See :class:`InlineModelAdmin` objects below as well as
:meth:`ModelAdmin.get_formsets`.
.. attribute:: ModelAdmin.list_display
Set ``list_display`` to control which fields are displayed on the change
list page of the admin.
Example::
list_display = ('first_name', 'last_name')
If you don't set ``list_display``, the admin site will display a single
column that displays the ``__unicode__()`` representation of each object.
You have four possible values that can be used in ``list_display``:
* A field of the model. For example::
class PersonAdmin(admin.ModelAdmin):
list_display = ('first_name', 'last_name')
* A callable that accepts one parameter for the model instance. For
example::
def upper_case_name(obj):
return ("%s %s" % (obj.first_name, obj.last_name)).upper()
upper_case_name.short_description = 'Name'
class PersonAdmin(admin.ModelAdmin):
list_display = (upper_case_name,)
* A string representing an attribute on the ``ModelAdmin``. This
behaves same as the callable. For example::
class PersonAdmin(admin.ModelAdmin):
list_display = ('upper_case_name',)
def upper_case_name(self, obj):
return ("%s %s" % (obj.first_name, obj.last_name)).upper()
upper_case_name.short_description = 'Name'
* A string representing an attribute on the model. This behaves almost
the same as the callable, but ``self`` in this context is the model
instance. Here's a full model example::
class Person(models.Model):
name = models.CharField(max_length=50)
birthday = models.DateField()
def decade_born_in(self):
return self.birthday.strftime('%Y')[:3] + "0's"
decade_born_in.short_description = 'Birth decade'
class PersonAdmin(admin.ModelAdmin):
list_display = ('name', 'decade_born_in')
A few special cases to note about ``list_display``:
* If the field is a ``ForeignKey``, Django will display the
``__unicode__()`` of the related object.
* ``ManyToManyField`` fields aren't supported, because that would
entail executing a separate SQL statement for each row in the table.
If you want to do this nonetheless, give your model a custom method,
and add that method's name to ``list_display``. (See below for more
on custom methods in ``list_display``.)
* If the field is a ``BooleanField`` or ``NullBooleanField``, Django
will display a pretty "on" or "off" icon instead of ``True`` or
``False``.
* If the string given is a method of the model, ``ModelAdmin`` or a
callable, Django will HTML-escape the output by default. If you'd
rather not escape the output of the method, give the method an
``allow_tags`` attribute whose value is ``True``.
Here's a full example model::
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
color_code = models.CharField(max_length=6)
def colored_name(self):
return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
colored_name.allow_tags = True
class PersonAdmin(admin.ModelAdmin):
list_display = ('first_name', 'last_name', 'colored_name')
* If the string given is a method of the model, ``ModelAdmin`` or a
callable that returns True or False Django will display a pretty
"on" or "off" icon if you give the method a ``boolean`` attribute
whose value is ``True``.
Here's a full example model::
class Person(models.Model):
first_name = models.CharField(max_length=50)
birthday = models.DateField()
def born_in_fifties(self):
return self.birthday.strftime('%Y')[:3] == '195'
born_in_fifties.boolean = True
class PersonAdmin(admin.ModelAdmin):
list_display = ('name', 'born_in_fifties')
* The ``__str__()`` and ``__unicode__()`` methods are just as valid in
``list_display`` as any other model method, so it's perfectly OK to
do this::
list_display = ('__unicode__', 'some_other_field')
* Usually, elements of ``list_display`` that aren't actual database
fields can't be used in sorting (because Django does all the sorting
at the database level).
However, if an element of ``list_display`` represents a certain
database field, you can indicate this fact by setting the
``admin_order_field`` attribute of the item.
For example::
class Person(models.Model):
first_name = models.CharField(max_length=50)
color_code = models.CharField(max_length=6)
def colored_first_name(self):
return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
colored_first_name.allow_tags = True
colored_first_name.admin_order_field = 'first_name'
class PersonAdmin(admin.ModelAdmin):
list_display = ('first_name', 'colored_first_name')
The above will tell Django to order by the ``first_name`` field when
trying to sort by ``colored_first_name`` in the admin.
.. attribute:: ModelAdmin.list_display_links
Set ``list_display_links`` to control which fields in ``list_display``
should be linked to the "change" page for an object.
By default, the change list page will link the first column -- the first
field specified in ``list_display`` -- to the change page for each item.
But ``list_display_links`` lets you change which columns are linked. Set
``list_display_links`` to a list or tuple of fields (in the same
format as ``list_display``) to link.
``list_display_links`` can specify one or many fields. As long as the
fields appear in ``list_display``, Django doesn't care how many (or
how few) fields are linked. The only requirement is: If you want to use
``list_display_links``, you must define ``list_display``.
In this example, the ``first_name`` and ``last_name`` fields will be
linked on the change list page::
class PersonAdmin(admin.ModelAdmin):
list_display = ('first_name', 'last_name', 'birthday')
list_display_links = ('first_name', 'last_name')
.. _admin-list-editable:
.. attribute:: ModelAdmin.list_editable
Set ``list_editable`` to a list of field names on the model which will
allow editing on the change list page. That is, fields listed in
``list_editable`` will be displayed as form widgets on the change list
page, allowing users to edit and save multiple rows at once.
.. note::
``list_editable`` interacts with a couple of other options in
particular ways; you should note the following rules:
* Any field in ``list_editable`` must also be in ``list_display``.
You can't edit a field that's not displayed!
* The same field can't be listed in both ``list_editable`` and
``list_display_links`` -- a field can't be both a form and
a link.
You'll get a validation error if either of these rules are broken.
.. attribute:: ModelAdmin.list_filter
Set ``list_filter`` to activate filters in the right sidebar of the change
list page of the admin, as illustrated in the following screenshot:
.. image:: _images/users_changelist.png
``list_filter`` should be a list of elements, where each element should be
of one of the following types:
* a field name, where the specified field should be either a
``BooleanField``, ``CharField``, ``DateField``, ``DateTimeField``,
``IntegerField``, ``ForeignKey`` or ``ManyToManyField``, for example::
class PersonAdmin(ModelAdmin):
list_filter = ('is_staff', 'company')
Field names in ``list_filter`` can also span relations
using the ``__`` lookup, for example::
class PersonAdmin(UserAdmin):
list_filter = ('company__name',)
.. versionadded:: 1.4
* a class inheriting from :mod:`django.contrib.admin.SimpleListFilter`,
which you need to provide the ``title`` and ``parameter_name``
attributes to and override the ``lookups`` and ``queryset`` methods,
e.g.::
from datetime import date
from django.utils.translation import ugettext_lazy as _
from django.contrib.admin import SimpleListFilter
class DecadeBornListFilter(SimpleListFilter):
# Human-readable title which will be displayed in the
# right admin sidebar just above the filter options.
title = _('decade born')
# Parameter for the filter that will be used in the URL query.
parameter_name = 'decade'
def lookups(self, request, model_admin):
"""
Returns a list of tuples. The first element in each
tuple is the coded value for the option that will
appear in the URL query. The second element is the
human-readable name for the option that will appear
in the right sidebar.
"""
return (
('80s', _('in the eighties')),
('90s', _('in the nineties')),
)
def queryset(self, request, queryset):
"""
Returns the filtered queryset based on the value
provided in the query string and retrievable via
`self.value()`.
"""
# Compare the requested value (either '80s' or '90s')
# to decide how to filter the queryset.
if self.value() == '80s':
return queryset.filter(birthday__gte=date(1980, 1, 1),
birthday__lte=date(1989, 12, 31))
if self.value() == '90s':
return queryset.filter(birthday__gte=date(1990, 1, 1),
birthday__lte=date(1999, 12, 31))
class PersonAdmin(ModelAdmin):
list_filter = (DecadeBornListFilter,)
.. note::
As a convenience, the ``HttpRequest`` object is passed to the
``lookups`` and ``queryset`` methods, for example::
class AuthDecadeBornListFilter(DecadeBornListFilter):
def lookups(self, request, model_admin):
if request.user.is_superuser:
return super(AuthDecadeBornListFilter,
self).lookups(request, model_admin)
def queryset(self, request, queryset):
if request.user.is_superuser:
return super(AuthDecadeBornListFilter,
self).queryset(request, queryset)
Also as a convenience, the ``ModelAdmin`` object is passed to
the ``lookups`` method, for example if you want to base the
lookups on the available data::
class AdvancedDecadeBornListFilter(DecadeBornListFilter):
def lookups(self, request, model_admin):
"""
Only show the lookups if there actually is
anyone born in the corresponding decades.
"""
qs = model_admin.queryset(request)
if qs.filter(birthday__gte=date(1980, 1, 1),
birthday__lte=date(1989, 12, 31)).exists():
yield ('80s', _('in the eighties'))
if qs.filter(birthday__gte=date(1990, 1, 1),
birthday__lte=date(1999, 12, 31)).exists():
yield ('90s', _('in the nineties'))
.. versionadded:: 1.4
* a tuple, where the first element is a field name and the second
element is a class inheriting from
:mod:`django.contrib.admin.FieldListFilter`, for example::
from django.contrib.admin import BooleanFieldListFilter
class PersonAdmin(ModelAdmin):
list_filter = (
('is_staff', BooleanFieldListFilter),
)
.. note::
The ``FieldListFilter`` API is considered internal and might be
changed.
.. versionadded:: 1.4
It is possible to specify a custom template for rendering a list filter::
class FilterWithCustomTemplate(SimpleListFilter):
template = "custom_template.html"
See the default template provided by django (``admin/filter.html``) for
a concrete example.
.. attribute:: ModelAdmin.list_max_show_all
.. versionadded:: 1.4
Set ``list_max_show_all`` to control how many items can appear on a "Show
all" admin change list page. The admin will display a "Show all" link on the
change list only if the total result count is less than or equal to this
setting. By default, this is set to ``200``.
.. attribute:: ModelAdmin.list_per_page
Set ``list_per_page`` to control how many items appear on each paginated
admin change list page. By default, this is set to ``100``.
.. attribute:: ModelAdmin.list_select_related
Set ``list_select_related`` to tell Django to use
:meth:`~django.db.models.query.QuerySet.select_related` in retrieving
the list of objects on the admin change list page. This can save you a
bunch of database queries.
The value should be either ``True`` or ``False``. Default is ``False``.
Note that Django will use
:meth:`~django.db.models.query.QuerySet.select_related`,
regardless of this setting if one of the ``list_display`` fields is a
``ForeignKey``.
.. attribute:: ModelAdmin.ordering
Set ``ordering`` to specify how lists of objects should be ordered in the
Django admin views. This should be a list or tuple in the same format as a
model's :attr:`~django.db.models.Options.ordering` parameter.
If this isn't provided, the Django admin will use the model's default
ordering.
.. versionadded:: 1.4
If you need to specify a dynamic order (for example depending on user or
language) you can implement a :meth:`~ModelAdmin.get_ordering` method.
.. versionchanged:: 1.4
Django honors all elements in the list/tuple; before 1.4, only the first
was respected.
.. attribute:: ModelAdmin.paginator
The paginator class to be used for pagination. By default,
:class:`django.core.paginator.Paginator` is used. If the custom paginator
class doesn't have the same constructor interface as
:class:`django.core.paginator.Paginator`, you will also need to
provide an implementation for :meth:`ModelAdmin.get_paginator`.
.. attribute:: ModelAdmin.prepopulated_fields
Set ``prepopulated_fields`` to a dictionary mapping field names to the
fields it should prepopulate from::
class ArticleAdmin(admin.ModelAdmin):
prepopulated_fields = {"slug": ("title",)}
When set, the given fields will use a bit of JavaScript to populate from
the fields assigned. The main use for this functionality is to
automatically generate the value for ``SlugField`` fields from one or more
other fields. The generated value is produced by concatenating the values
of the source fields, and then by transforming that result into a valid
slug (e.g. substituting dashes for spaces).
``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``,
nor ``ManyToManyField`` fields.
.. attribute:: ModelAdmin.radio_fields
By default, Django's admin uses a select-box interface (<select>) for
fields that are ``ForeignKey`` or have ``choices`` set. If a field is
present in ``radio_fields``, Django will use a radio-button interface
instead. Assuming ``group`` is a ``ForeignKey`` on the ``Person`` model::
class PersonAdmin(admin.ModelAdmin):
radio_fields = {"group": admin.VERTICAL}
You have the choice of using ``HORIZONTAL`` or ``VERTICAL`` from the
``django.contrib.admin`` module.
Don't include a field in ``radio_fields`` unless it's a ``ForeignKey`` or has
``choices`` set.
.. attribute:: ModelAdmin.raw_id_fields
By default, Django's admin uses a select-box interface (<select>) for
fields that are ``ForeignKey``. Sometimes you don't want to incur the
overhead of having to select all the related instances to display in the
drop-down.
``raw_id_fields`` is a list of fields you would like to change
into an ``Input`` widget for either a ``ForeignKey`` or
``ManyToManyField``::
class ArticleAdmin(admin.ModelAdmin):
raw_id_fields = ("newspaper",)
The ``raw_id_fields`` ``Input`` widget should contain a primary key if the
field is a ``ForeignKey`` or a comma separated list of values if the field
is a ``ManyToManyField``. The ``raw_id_fields`` widget shows a magnifying
glass button next to the field which allows users to search for and select
a value:
.. image:: _images/raw_id_fields.png
.. attribute:: ModelAdmin.readonly_fields
By default the admin shows all fields as editable. Any fields in this
option (which should be a ``list`` or ``tuple``) will display its data
as-is and non-editable. Note that when specifying :attr:`ModelAdmin.fields`
or :attr:`ModelAdmin.fieldsets` the read-only fields must be present to be
shown (they are ignored otherwise).
If ``readonly_fields`` is used without defining explicit ordering through
:attr:`ModelAdmin.fields` or :attr:`ModelAdmin.fieldsets` they will be
added last after all editable fields.
A read-only field can not only display data from a model's field, it can
also display the output of a a model's method or a method of the
``ModelAdmin`` class itself. This is very similar to the way
:attr:`ModelAdmin.list_display` behaves. This provides an easy way to use
the admin interface to provide feedback on the status of the objects being
edited, for example::
class PersonAdmin(ModelAdmin):
readonly_fields = ('address_report',)
def address_report(self, instance):
return ", ".join(instance.get_full_address()) or \
"<span class='errors'>I can't determine this address.</span>"
# short_description functions like a model field's verbose_name
address_report.short_description = "Address"
# in this example, we have used HTML tags in the output
address_report.allow_tags = True
.. attribute:: ModelAdmin.save_as
Set ``save_as`` to enable a "save as" feature on admin change forms.
Normally, objects have three save options: "Save", "Save and continue
editing" and "Save and add another". If ``save_as`` is ``True``, "Save
and add another" will be replaced by a "Save as" button.
"Save as" means the object will be saved as a new object (with a new ID),
rather than the old object.
By default, ``save_as`` is set to ``False``.
.. attribute:: ModelAdmin.save_on_top
Set ``save_on_top`` to add save buttons across the top of your admin change
forms.
Normally, the save buttons appear only at the bottom of the forms. If you
set ``save_on_top``, the buttons will appear both on the top and the
bottom.
By default, ``save_on_top`` is set to ``False``.
.. attribute:: ModelAdmin.search_fields
Set ``search_fields`` to enable a search box on the admin change list page.
This should be set to a list of field names that will be searched whenever
somebody submits a search query in that text box.
These fields should be some kind of text field, such as ``CharField`` or
``TextField``. You can also perform a related lookup on a ``ForeignKey`` or
``ManyToManyField`` with the lookup API "follow" notation::
search_fields = ['foreign_key__related_fieldname']
For example, if you have a blog entry with an author, the following
definition would enable search blog entries by the email address of the
author::
search_fields = ['user__email']
When somebody does a search in the admin search box, Django splits the
search query into words and returns all objects that contain each of the
words, case insensitive, where each word must be in at least one of
``search_fields``. For example, if ``search_fields`` is set to
``['first_name', 'last_name']`` and a user searches for ``john lennon``,
Django will do the equivalent of this SQL ``WHERE`` clause::
WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')
For faster and/or more restrictive searches, prefix the field name
with an operator:
``^``
Matches the beginning of the field. For example, if ``search_fields``
is set to ``['^first_name', '^last_name']`` and a user searches for
``john lennon``, Django will do the equivalent of this SQL ``WHERE``
clause::
WHERE (first_name ILIKE 'john%' OR last_name ILIKE 'john%')
AND (first_name ILIKE 'lennon%' OR last_name ILIKE 'lennon%')
This query is more efficient than the normal ``'%john%'`` query,
because the database only needs to check the beginning of a column's
data, rather than seeking through the entire column's data. Plus, if
the column has an index on it, some databases may be able to use the
index for this query, even though it's a ``LIKE`` query.
``=``
Matches exactly, case-insensitive. For example, if
``search_fields`` is set to ``['=first_name', '=last_name']`` and
a user searches for ``john lennon``, Django will do the equivalent
of this SQL ``WHERE`` clause::
WHERE (first_name ILIKE 'john' OR last_name ILIKE 'john')
AND (first_name ILIKE 'lennon' OR last_name ILIKE 'lennon')
Note that the query input is split by spaces, so, following this
example, it's currently not possible to search for all records in which
``first_name`` is exactly ``'john winston'`` (containing a space).
``@``
Performs a full-text match. This is like the default search method but
uses an index. Currently this is only available for MySQL.
Custom template options
~~~~~~~~~~~~~~~~~~~~~~~
The `Overriding Admin Templates`_ section describes how to override or extend
the default admin templates. Use the following options to override the default
templates used by the :class:`ModelAdmin` views:
.. attribute:: ModelAdmin.add_form_template
Path to a custom template, used by :meth:`add_view`.
.. attribute:: ModelAdmin.change_form_template
Path to a custom template, used by :meth:`change_view`.
.. attribute:: ModelAdmin.change_list_template
Path to a custom template, used by :meth:`changelist_view`.
.. attribute:: ModelAdmin.delete_confirmation_template
Path to a custom template, used by :meth:`delete_view` for displaying a
confirmation page when deleting one or more objects.
.. attribute:: ModelAdmin.delete_selected_confirmation_template
Path to a custom template, used by the :meth:`delete_selected`
action method for displaying a confirmation page when deleting one
or more objects. See the :doc:`actions
documentation</ref/contrib/admin/actions>`.
.. attribute:: ModelAdmin.object_history_template
Path to a custom template, used by :meth:`history_view`.
.. _model-admin-methods:
``ModelAdmin`` methods
----------------------
.. warning::
:meth:`ModelAdmin.save_model` and :meth:`ModelAdmin.delete_model` must
save/delete the object, they are not for veto purposes, rather they allow
you to perform extra operations.
.. method:: ModelAdmin.save_model(self, request, obj, form, change)
The ``save_model`` method is given the ``HttpRequest``, a model instance,
a ``ModelForm`` instance and a boolean value based on whether it is adding
or changing the object. Here you can do any pre- or post-save operations.
For example to attach ``request.user`` to the object prior to saving::
class ArticleAdmin(admin.ModelAdmin):
def save_model(self, request, obj, form, change):
obj.user = request.user
obj.save()
.. method:: ModelAdmin.delete_model(self, request, obj)
The ``delete_model`` method is given the ``HttpRequest`` and a model
instance. Use this method to do pre- or post-delete operations.
.. method:: ModelAdmin.save_formset(self, request, form, formset, change)