diff options
Diffstat (limited to 'docs/model-api.txt')
| -rw-r--r-- | docs/model-api.txt | 112 |
1 files changed, 100 insertions, 12 deletions
diff --git a/docs/model-api.txt b/docs/model-api.txt index 0a3abe4e26..e66e96de68 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -94,7 +94,7 @@ Django places only two restrictions on model field names: the way Django's query lookup syntax works. For example:: class Example(models.Model): - foo__bar = models.IntegerField() 'foo__bar' has two underscores! + foo__bar = models.IntegerField() # 'foo__bar' has two underscores! These limitations can be worked around, though, because your field name doesn't necessarily have to match your database column name. See `db_column`_ below. @@ -188,7 +188,8 @@ JavaScript shortcuts. ~~~~~~~~~~~~~~ A ``CharField`` that checks that the value is a valid e-mail address. -This doesn't accept ``maxlength``. +This doesn't accept ``maxlength``; its ``maxlength`` is automatically set to +75. ``FileField`` ~~~~~~~~~~~~~ @@ -497,6 +498,12 @@ or outside your model class altogether:: class Foo(models.Model): gender = models.CharField(maxlength=1, choices=GENDER_CHOICES) +For each model field that has ``choices`` set, Django will add a method to +retrieve the human-readable name for the field's current value. See +`get_FOO_display`_ in the database API documentation. + +.. _get_FOO_display: ../db_api/#get-foo-display + Finally, note that choices can be any iterable object -- not necessarily a list or tuple. This lets you construct choices dynamically. But if you find yourself hacking ``choices`` to be dynamic, you're probably better off using @@ -543,7 +550,9 @@ The default value for the field. ``editable`` ~~~~~~~~~~~~ -If ``False``, the field will not be editable in the admin. Default is ``True``. +If ``False``, the field will not be editable in the admin or via form +processing using the object's ``AddManipulator`` or ``ChangeManipulator`` +classes. Default is ``True``. ``help_text`` ~~~~~~~~~~~~~ @@ -872,6 +881,10 @@ the relationship should work. All are optional: relationship, allowing ``ManyToMany`` relationships to be non-symmetrical. + ``db_table`` The name of the table to create for storing the many-to-many + data. If this is not provided, Django will assume a default + name based upon the names of the two tables being joined. + ======================= ============================================================ One-to-one relationships @@ -1203,6 +1216,9 @@ screen via ``<script src="">`` tags. This can be used to tweak a given type of admin page in JavaScript or to provide "quick links" to fill in default values for certain fields. +If relative URLs are used, Django admin will automatically prepend these links +with ``settings.ADMIN_MEDIA_PREFIX``. + ``list_display`` ---------------- @@ -1222,10 +1238,13 @@ A few special cases to note about ``list_display``: of the related object. * ``ManyToManyField`` fields aren't supported, because that would entail - executing a separate SQL statement for each row in the table. + 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``, Django will display a pretty "on" or - "off" icon instead of ``True`` or ``False``. + * 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, Django will call it and display the output. This method should have a ``short_description`` @@ -1262,6 +1281,54 @@ A few special cases to note about ``list_display``: return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name) colored_name.allow_tags = True + * If the string given is a method of the model 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(maxlength=50) + birthday = models.DateField() + + class Admin: + list_display = ('name', 'born_in_fifties') + + def born_in_fifties(self): + return self.birthday.strftime('%Y')[:3] == 5 + born_in_fifties.boolean = True + + + * The ``__str__()`` method is just as valid in ``list_display`` as any + other model method, so it's perfectly OK to do this:: + + list_display = ('__str__', '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(maxlength=50) + color_code = models.CharField(maxlength=6) + + class Admin: + list_display = ('first_name', 'colored_first_name') + + 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' + + The above will tell Django to order by the ``first_name`` field when + trying to sort by ``colored_first_name`` in the admin. + ``list_display_links`` ---------------------- @@ -1374,7 +1441,10 @@ 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``. +``TextField``. You can also perform a related lookup on a ``ForeignKey`` with +the lookup API "follow" notation:: + + search_fields = ['foreign_key__related_fieldname'] 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 @@ -1680,11 +1750,29 @@ But this template code is good:: <a href="{{ object.get_absolute_url }}">{{ object.name }}</a> -(Yes, we know ``get_absolute_url()`` couples URLs to models, which violates the -DRY principle, because URLs are defined both in a URLconf and in the model. -This is a rare case in which we've intentionally violated that principle for -the sake of convenience. With that said, we're working on an even cleaner way -of specifying URLs in a more DRY fashion.) +The ``permalink`` decorator +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**New in Django development version.** + +The problem with the way we wrote ``get_absolute_url()`` above is that it +slightly violates the DRY principle: the URL for this object is defined both +in the URLConf file and in the model. + +You can further decouple your models from the URLconf using the ``permalink`` +decorator. This decorator is passed the view function and any parameters you +would use for accessing this instance directly. Django then works out the +correct full URL path using the URLconf. For example:: + + from django.db.models import permalink + + def get_absolute_url(self): + return ('people.views.details', str(self.id)) + get_absolute_url = permalink(get_absolute_url) + +In this way, you're tying the model's absolute URL to the view that is used +to display it, without repeating the URL information anywhere. You can still +use the ``get_absolute_url`` method in templates, as before. Executing custom SQL -------------------- |