diff options
Diffstat (limited to 'docs/model-api.txt')
| -rw-r--r-- | docs/model-api.txt | 106 |
1 files changed, 97 insertions, 9 deletions
diff --git a/docs/model-api.txt b/docs/model-api.txt index c4d57bf8c4..1aa8c811f4 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -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`` ~~~~~~~~~~~~~ @@ -217,12 +218,27 @@ steps: subdirectory of ``MEDIA_ROOT`` it should upload files. 3. All that will be stored in your database is a path to the file - (relative to ``MEDIA_ROOT``). You'll must likely want to use the + (relative to ``MEDIA_ROOT``). You'll most likely want to use the convenience ``get_<fieldname>_url`` function provided by Django. For example, if your ``ImageField`` is called ``mug_shot``, you can get the absolute URL to your image in a template with ``{{ object.get_mug_shot_url }}``. +For example, say your ``MEDIA_ROOT`` is set to ``'/home/media'``, and +``upload_to`` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` part of +``upload_to`` is strftime formatting; ``'%Y'`` is the four-digit year, +``'%m'`` is the two-digit month and ``'%d'`` is the two-digit day. If you +upload a file on Jan. 15, 2007, it will be saved in the directory +``/home/media/photos/2007/01/15``. + +Note that whenever you deal with uploaded files, you should pay close attention +to where you're uploading them and what type of files they are, to avoid +security holes. *Validate all uploaded files* so that you're sure the files are +what you think they are. For example, if you blindly let somebody upload files, +without validation, to a directory that's within your Web server's document +root, then somebody could upload a CGI or PHP script and execute that script by +visiting its URL on your site. Don't allow that. + .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 ``FilePathField`` @@ -528,7 +544,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`` ~~~~~~~~~~~~~ @@ -671,8 +689,9 @@ you can use the name of the model, rather than the model object itself:: class Manufacturer(models.Model): # ... -Note, however, that support for strings around model names in ``ForeignKey`` is -quite new, and it can be buggy in some cases. +Note, however, that you can only use strings to refer to models in the same +models.py file -- you cannot use a string to reference a model in a different +application, or to reference a model that has been imported from elsewhere. Behind the scenes, Django appends ``"_id"`` to the field name to create its database column name. In the above example, the database table for the ``Car`` @@ -794,7 +813,10 @@ here's how you'd represent that:: As with ``ForeignKey``, a relationship to self can be defined by using the string ``'self'`` instead of the model name, and you can refer to as-yet -undefined models by using a string containing the model name. +undefined models by using a string containing the model name. However, you +can only use strings to refer to models in the same models.py file -- you +cannot use a string to reference a model in a different application, or to +reference a model that has been imported from elsewhere. It's suggested, but not required, that the name of a ``ManyToManyField`` (``toppings`` in the example above) be a plural describing the set of related @@ -1203,10 +1225,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`` @@ -1225,6 +1250,34 @@ A few special cases to note about ``list_display``: return self.birthday.strftime('%Y')[:3] + "0's" decade_born_in.short_description = 'Birth decade' + * If the string given is a method of the model, 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(maxlength=50) + last_name = models.CharField(maxlength=50) + color_code = models.CharField(maxlength=6) + + class Admin: + list_display = ('first_name', 'last_name', 'colored_name') + + 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 + + * 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') + + * For any element of ``list_display`` that is not a field on the model, the + change list page will not allow ordering by that column. This is because + ordering is done at the database level, and Django has no way of knowing + how to order the result of a custom method at the SQL level. + ``list_display_links`` ---------------------- @@ -1349,6 +1402,41 @@ user searches for ``john lennon``, Django will do the equivalent of this SQL WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%') AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%') +**New in Django development version:** 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 not 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. + Managers ======== |