Changeset 8215 for django/branches/gis/docs/admin.txt
- Timestamp:
- 08/05/08 12:15:33 (5 months ago)
- Files:
-
- django/branches/gis (modified) (1 prop)
- django/branches/gis/docs/admin.txt (modified) (26 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/branches/gis
- Property svnmerge-integrated changed from /django/trunk:1-7978 to /django/trunk:1-8214
django/branches/gis/docs/admin.txt
r7979 r8215 19 19 ======== 20 20 21 There are four steps in activating the Django admin site: 22 23 1. Determine which of your application's models should be editable in the 21 There are five steps in activating the Django admin site: 22 23 1. Add ``django.contrib.admin`` to your ``INSTALLED_APPS`` setting. 24 25 2. Determine which of your application's models should be editable in the 24 26 admin interface. 25 27 26 2. For each of those models, optionally create a ``ModelAdmin`` class that28 3. For each of those models, optionally create a ``ModelAdmin`` class that 27 29 encapsulates the customized admin functionality and options for that 28 30 particular model. 29 31 30 3. Instantiate an ``AdminSite`` and tell it about each of your models and32 4. Instantiate an ``AdminSite`` and tell it about each of your models and 31 33 ``ModelAdmin`` classes. 32 34 33 4. Hook the ``AdminSite`` instance into your URLconf.35 5. Hook the ``AdminSite`` instance into your URLconf. 34 36 35 37 ``ModelAdmin`` objects … … 42 44 from django.contrib import admin 43 45 from myproject.myapp.models import Author 44 46 45 47 class AuthorAdmin(admin.ModelAdmin): 46 48 pass … … 67 69 68 70 date_hierarchy = 'pub_date' 71 72 ``form`` 73 ~~~~~~~~ 74 75 The default ``forms.ModelForm`` class used to generate the form on the 76 add/change pages for models. You can easily change this to your own 77 ``ModelForm`` to override the default form behavior of the add/change pages. 69 78 70 79 ``fieldsets`` … … 83 92 84 93 A full example, taken from the ``django.contrib.flatpages.FlatPage`` model:: 85 94 86 95 class FlatPageAdmin(admin.ModelAdmin): 87 96 fieldsets = ( … … 107 116 ``fields`` 108 117 A tuple of field names to display in this fieldset. This key is required. 109 118 110 119 Example:: 111 120 112 121 { 113 122 'fields': ('first_name', 'last_name', 'address', 'city', 'state'), … … 117 126 tuple. In this example, the ``first_name`` and ``last_name`` fields will 118 127 display on the same line:: 119 128 120 129 { 121 130 'fields': (('first_name', 'last_name'), 'address', 'city', 'state'), … … 123 132 124 133 ``classes`` 125 A stringcontaining extra CSS classes to apply to the fieldset.126 134 A list containing extra CSS classes to apply to the fieldset. 135 127 136 Example:: 128 137 129 138 { 130 'classes': 'wide',139 'classes': ['wide', 'extrapretty'], 131 140 } 132 141 133 Apply multiple classes by separating them with spaces. Example::134 135 {136 'classes': 'wide extrapretty',137 }138 139 142 Two useful classes defined by the default admin-site stylesheet are 140 143 ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style will be … … 144 147 ``description`` 145 148 A string of optional extra text to be displayed at the top of each fieldset, 146 under the heading of the fieldset. It's used verbatim, so you can use any HTML 147 and you must escape any special HTML characters (such as ampersands) yourself. 149 under the heading of the fieldset. 150 151 Note that this value is *not* HTML-escaped when it's displayed in 152 the admin interface. This lets you include HTML if you so desire. 153 Alternatively you can use plain text and 154 ``django.utils.html.escape()`` to escape any HTML special 155 characters. 156 157 ``fields`` 158 ~~~~~~~~~~ 159 160 Use this option as an alternative to ``fieldsets`` if the layout does not 161 matter and if you want to only show a subset of the available fields in the 162 form. For example, you could define a simpler version of the admin form for 163 the ``django.contrib.flatpages.FlatPage`` model as follows:: 164 165 class FlatPageAdmin(admin.ModelAdmin): 166 fields = ('url', 'title', 'content') 167 168 In the above example, only the fields 'url', 'title' and 'content' will be 169 displayed, sequencially, in the form. 170 171 .. admonition:: Note 172 173 This ``fields`` option should not be confused with the ``fields`` 174 dictionary key that is within the ``fieldsets`` option, as described in 175 the previous section. 148 176 149 177 ``filter_horizontal`` 150 178 ~~~~~~~~~~~~~~~~~~~~~ 151 179 152 Use a nifty unobtrusive Java script "filter" interface instead of the180 Use a nifty unobtrusive JavaScript "filter" interface instead of the 153 181 usability-challenged ``<select multiple>`` in the admin form. The value is a 154 182 list of fields that should be displayed as a horizontal filter interface. See … … 193 221 194 222 Here's a full example model:: 195 223 196 224 class Person(models.Model): 197 225 name = models.CharField(max_length=50) … … 201 229 return self.birthday.strftime('%Y')[:3] + "0's" 202 230 decade_born_in.short_description = 'Birth decade' 203 231 204 232 class PersonAdmin(admin.ModelAdmin): 205 233 list_display = ('name', 'decade_born_in') … … 219 247 return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name) 220 248 colored_name.allow_tags = True 221 249 222 250 class PersonAdmin(admin.ModelAdmin): 223 251 list_display = ('first_name', 'last_name', 'colored_name') … … 236 264 return self.birthday.strftime('%Y')[:3] == 5 237 265 born_in_fifties.boolean = True 238 266 239 267 class PersonAdmin(admin.ModelAdmin): 240 268 list_display = ('name', 'born_in_fifties') … … 265 293 colored_first_name.allow_tags = True 266 294 colored_first_name.admin_order_field = 'first_name' 267 295 268 296 class PersonAdmin(admin.ModelAdmin): 269 297 list_display = ('first_name', 'colored_first_name') … … 356 384 If this isn't provided, the Django admin will use the model's default ordering. 357 385 386 .. admonition:: Note 387 388 Django will only honor the first element in the list/tuple; any others 389 will be ignored. 390 358 391 ``prepopulated_fields`` 359 392 ~~~~~~~~~~~~~~~~~~~~~~~ … … 365 398 prepopulated_fields = {"slug": ("title",)} 366 399 367 When set the given fields will use a bit of Javascript to populate from the 368 fields assigned. 369 370 ``prepopulated_fields`` doesn't accept DateTimeFields, ForeignKeys nor 371 ManyToManyFields. 400 When set, the given fields will use a bit of JavaScript to populate from the 401 fields assigned. The main use for this functionality is to automatically 402 generate the value for ``SlugField`` fields from one or more other fields. The 403 generated value is produced by concatenating the values of the source fields, 404 and then by transforming that result into a valid slug (e.g. substituting 405 dashes for spaces). 406 407 ``prepopulated_fields`` doesn't accept ``DateTimeField``, ``ForeignKey``, nor 408 ``ManyToManyField`` fields. 372 409 373 410 ``radio_fields`` … … 397 434 398 435 ``raw_id_fields`` is a list of fields you would like to change 399 into a ``Input`` widget for the primary key. 436 into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: 437 438 class ArticleAdmin(admin.ModelAdmin): 439 raw_id_fields = ("newspaper",) 400 440 401 441 ``save_as`` … … 485 525 -------------------------------- 486 526 487 There are times where you would like add a bit of CSS and/or Java script to527 There are times where you would like add a bit of CSS and/or JavaScript to 488 528 the add/change views. This can be accomplished by using a Media inner class 489 529 on your ``ModelAdmin``:: … … 499 539 apply as `regular media definitions on forms`_. 500 540 501 .. _regular media definitions on forms: ../newforms/#media 541 .. _regular media definitions on forms: ../forms/#media 542 543 Adding custom validation to the admin 544 ------------------------------------- 545 546 Adding custom validation of data in the admin is quite easy. The automatic 547 admin interfaces reuses the Django `forms`_ module. The ``ModelAdmin`` class 548 gives you the ability define your own form:: 549 550 class ArticleAdmin(admin.ModelAdmin): 551 form = MyArticleAdminForm 552 553 ``MyArticleAdminForm`` can be defined anywhere as long as you import where 554 needed. Now within your form you can add your own custom validation for 555 any field:: 556 557 class MyArticleAdminForm(forms.ModelForm): 558 def clean_name(self): 559 # do something that validates your data 560 return self.cleaned_data["name"] 561 562 It is important you use a ``ModelForm`` here otherwise things can break. See 563 the `forms`_ documentation on `custom validation`_ for more information. 564 565 .. _forms: ../forms/ 566 .. _custom validation: ../forms/#custom-form-and-field-validation 502 567 503 568 ``InlineModelAdmin`` objects … … 505 570 506 571 The admin interface has the ability to edit models on the same page as a 507 parent model. These are called inlines. You can add them a model being508 specif ing them in a ``ModelAdmin.inlines`` attribute::572 parent model. These are called inlines. You can add them to a model by 573 specifying them in a ``ModelAdmin.inlines`` attribute:: 509 574 510 575 class BookInline(admin.TabularInline): 511 576 model = Book 512 577 513 578 class AuthorAdmin(admin.ModelAdmin): 514 579 inlines = [ … … 516 581 ] 517 582 518 Django provides two subclasses of ``InlineModelAdmin`` and they are: :583 Django provides two subclasses of ``InlineModelAdmin`` and they are: 519 584 520 585 * ``TabularInline`` … … 563 628 to the initial forms. See the `formsets documentation`_ for more information. 564 629 565 .. _formsets documentation: ../ newforms/#formsets630 .. _formsets documentation: ../forms/#formsets 566 631 567 632 ``max_num`` … … 574 639 .. _max_num in formsets: ../modelforms/#limiting-the-number-of-objects-editable 575 640 641 ``raw_id_fields`` 642 ~~~~~~~~~~~~~~~~~ 643 644 By default, Django's admin uses a select-box interface (<select>) for 645 fields that are ``ForeignKey``. Sometimes you don't want to incur the 646 overhead of having to select all the related instances to display in the 647 drop-down. 648 649 ``raw_id_fields`` is a list of fields you would like to change 650 into a ``Input`` widget for either a ``ForeignKey`` or ``ManyToManyField``:: 651 652 class BookInline(admin.TabularInline): 653 model = Book 654 raw_id_fields = ("pages",) 655 576 656 ``template`` 577 657 ~~~~~~~~~~~~ … … 599 679 to_person = models.ForeignKey(Person, related_name="friends") 600 680 from_person = models.ForeignKey(Person, related_name="from_friends") 601 681 602 682 If you wanted to display an inline on the ``Person`` admin add/change pages 603 683 you need to explicitly define the foreign key since it is unable to do so … … 607 687 model = Friendship 608 688 fk_name = "to_person" 609 689 610 690 class PersonAdmin(admin.ModelAdmin): 611 691 inlines = [ … … 613 693 ] 614 694 695 Working with Many-to-Many Intermediary Models 696 ---------------------------------------------- 697 698 By default, admin widgets for many-to-many relations will be displayed inline 699 on whichever model contains the actual reference to the ``ManyToManyField``. 700 However, when you specify an intermediary model using the ``through`` 701 argument to a ``ManyToManyField``, the admin will not display a widget by 702 default. This is because each instance of that intermediary model requires 703 more information than could be displayed in a single widget, and the layout 704 required for multiple widgets will vary depending on the intermediate model. 705 706 However, we still want to be able to edit that information inline. Fortunately, 707 this is easy to do with inline admin models. Suppose we have the following 708 models:: 709 710 class Person(models.Model): 711 name = models.CharField(max_length=128) 712 713 class Group(models.Model): 714 name = models.CharField(max_length=128) 715 members = models.ManyToManyField(Person, through='Membership') 716 717 class Membership(models.Model): 718 person = models.ForeignKey(Person) 719 group = models.ForeignKey(Group) 720 date_joined = models.DateField() 721 invite_reason = models.CharField(max_length=64) 722 723 The first step in displaying this intermediate model in the admin is to 724 define an inline class for the ``Membership`` model:: 725 726 class MembershipInline(admin.TabularInline): 727 model = Membership 728 extra = 1 729 730 This simple example uses the default ``InlineModelAdmin`` values for the 731 ``Membership`` model, and limits the extra add forms to one. This could be 732 customized using any of the options available to ``InlineModelAdmin`` classes. 733 734 Now create admin views for the ``Person`` and ``Group`` models:: 735 736 class PersonAdmin(admin.ModelAdmin): 737 inlines = (MembershipInline,) 738 739 class GroupAdmin(admin.ModelAdmin): 740 inlines = (MembershipInline,) 741 742 Finally, register your ``Person`` and ``Group`` models with the admin site:: 743 744 admin.site.register(Person, PersonAdmin) 745 admin.site.register(Group, GroupAdmin) 746 747 Now your admin site is set up to edit ``Membership`` objects inline from 748 either the ``Person`` or the ``Group`` detail pages. 749 615 750 ``AdminSite`` objects 616 751 ===================== … … 629 764 from django.conf.urls.defaults import * 630 765 from django.contrib import admin 631 766 632 767 admin.autodiscover() 633 768
