From 74131e82eb1a1bdad1789889c38c8d96b6ab25aa Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 10 Jun 2009 12:44:53 +0000 Subject: Fixed #11056 -- Corrected reference to File class in storage docs. Thanks to wam for the report. git-svn-id: http://code.djangoproject.com/svn/django/trunk@10970 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/files/storage.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/files/storage.txt b/docs/ref/files/storage.txt index 0ca577059e..c8aafa8626 100644 --- a/docs/ref/files/storage.txt +++ b/docs/ref/files/storage.txt @@ -43,8 +43,8 @@ modify the filename as necessary to get a unique name. The actual name of the stored file will be returned. The ``content`` argument must be an instance of -:class:`django.db.files.File` or of a subclass of -:class:`~django.db.files.File`. +:class:`django.core.files.File` or of a subclass of +:class:`~django.core.files.File`. ``Storage.delete(name)`` ~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.3 From 6c36d4c4f8379433cdce150a64dad6a1f16097cd Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 10 Jun 2009 12:45:29 +0000 Subject: Fixed #10981 -- Clarified documentation regarding lazy cross-application relationships. Thanks to Ramiro for the suggestion. git-svn-id: http://code.djangoproject.com/svn/django/trunk@10971 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/fields.txt | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 2ec74e4306..177df12862 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -800,21 +800,22 @@ you can use the name of the model, rather than the model object itself:: class Manufacturer(models.Model): # ... -Note, however, that this only refers to models in the same ``models.py`` file -- -you cannot use a string to reference a model defined in another application or -imported from elsewhere. - -.. versionchanged:: 1.0 - Refering models in other applications must include the application label. +.. versionadded:: 1.0 -To refer to models defined in another -application, you must instead explicitly specify the application label. For -example, if the ``Manufacturer`` model above is defined in another application -called ``production``, you'd need to use:: +To refer to models defined in another application, you can explicitly specify +a model with the full application label. For example, if the ``Manufacturer`` +model above is defined in another application called ``production``, you'd +need to use:: class Car(models.Model): manufacturer = models.ForeignKey('production.Manufacturer') +This sort of reference can be useful when resolving circular import +dependencies between two applications. + +Database Representation +~~~~~~~~~~~~~~~~~~~~~~~ + 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`` model will have a ``manufacturer_id`` column. (You can change this explicitly by @@ -824,6 +825,9 @@ deal with the field names of your model object. .. _foreign-key-arguments: +Arguments +~~~~~~~~~ + :class:`ForeignKey` accepts an extra set of arguments -- all optional -- that define the details of how the relation works. @@ -871,6 +875,9 @@ the model is related. This works exactly the same as it does for :class:`ForeignKey`, including all the options regarding :ref:`recursive ` and :ref:`lazy ` relationships. +Database Representation +~~~~~~~~~~~~~~~~~~~~~~~ + Behind the scenes, Django creates an intermediary join table to represent the many-to-many relationship. By default, this table name is generated using the names of the two tables being joined. Since some databases don't support table @@ -882,6 +889,9 @@ You can manually provide the name of the join table using the .. _manytomany-arguments: +Arguments +~~~~~~~~~ + :class:`ManyToManyField` accepts an extra set of arguments -- all optional -- that control how the relationship functions. -- cgit v1.3 From 992ded1ad1a46b5605769735d28aad22d4cb04d5 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 17 Jun 2009 13:47:39 +0000 Subject: Fixed #9919 -- Added note on the need to mark transactions as dirty when using raw SQL. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11022 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/querysets.txt | 2 ++ docs/topics/db/sql.txt | 46 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 46 insertions(+), 2 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 6c08fe079e..eb8fbfd833 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -616,6 +616,8 @@ call, since they are conflicting options. Both the ``depth`` argument and the ability to specify field names in the call to ``select_related()`` are new in Django version 1.0. +.. _extra: + ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/db/sql.txt b/docs/topics/db/sql.txt index 4352908909..9c534709ca 100644 --- a/docs/topics/db/sql.txt +++ b/docs/topics/db/sql.txt @@ -29,6 +29,45 @@ is required. For example:: return row +.. _transactions-and-raw-sql: + +Transactions and raw SQL +------------------------ +If you are using transaction decorators (such as ``commit_on_success``) to +wrap your views and provide transaction control, you don't have to make a +manual call to ``transaction.commit_unless_managed()`` -- you can manually +commit if you want to, but you aren't required to, since the decorator will +commit for you. However, if you don't manually commit your changes, you will +need to manually mark the transaction as dirty, using +``transaction.set_dirty()``:: + + @commit_on_success + def my_custom_sql_view(request, value): + from django.db import connection, transaction + cursor = connection.cursor() + + # Data modifying operation + cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [value]) + + # Since we modified data, mark the transaction as dirty + transaction.set_dirty() + + # Data retrieval operation. This doesn't dirty the transaction, + # so no call to set_dirty() is required. + cursor.execute("SELECT foo FROM bar WHERE baz = %s", [value]) + row = cursor.fetchone() + + return render_to_response('template.html', {'row': row}) + +The call to ``set_dirty()`` is made automatically when you use the Django ORM +to make data modifying database calls. However, when you use raw SQL, Django +has no way of knowing if your SQL modifies data or not. The manual call to +``set_dirty()`` ensures that Django knows that there are modifications that +must be committed. + +Connections and cursors +----------------------- + ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_ (except when it comes to :ref:`transaction handling `). If you're not familiar with the Python DB-API, note that the SQL statement in @@ -39,9 +78,12 @@ necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the ``"?"`` placeholder, which is used by the SQLite Python bindings. This is for the sake of consistency and sanity.) +An easier option? +----------------- + A final note: If all you want to do is a custom ``WHERE`` clause, you can just -use the ``where``, ``tables`` and ``params`` arguments to the standard lookup -API. +use the ``where``, ``tables`` and ``params`` arguments to the +:ref:`extra clause ` in the standard queryset API. .. _Python DB-API: http://www.python.org/peps/pep-0249.html -- cgit v1.3 From 6c81952b379712a5bbd4e4d73ec88a07d875b68e Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 17 Jun 2009 14:09:56 +0000 Subject: Fixed #10336 -- Added improved documentation of generic views. Thanks to Jacob and Adrian for the original text (from the DjangoBook), and Ramiro for doing the work of porting the docs. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11025 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/index.txt | 11 ++++--- docs/internals/documentation.txt | 5 --- docs/ref/generic-views.txt | 71 +++++++--------------------------------- docs/topics/index.txt | 1 + 4 files changed, 19 insertions(+), 69 deletions(-) (limited to 'docs/ref') diff --git a/docs/index.txt b/docs/index.txt index 6f6151b6d6..5ea7cfed5d 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -98,10 +98,13 @@ The view layer :ref:`Storage API ` | :ref:`Managing files ` | :ref:`Custom storage ` - - * **Advanced:** - :ref:`Generic views ` | - :ref:`Generating CSV ` | + + * **Generic views:** + :ref:`Overview` | + :ref:`Built-in generic views` + + * **Advanced:** + :ref:`Generating CSV ` | :ref:`Generating PDF ` * **Middleware:** diff --git a/docs/internals/documentation.txt b/docs/internals/documentation.txt index b89b296540..f33af32597 100644 --- a/docs/internals/documentation.txt +++ b/docs/internals/documentation.txt @@ -130,11 +130,6 @@ TODO The work is mostly done, but here's what's left, in rough order of priority. - * Fix up generic view docs: adapt Chapter 9 of the Django Book (consider - this TODO item my permission and license) into - ``topics/generic-views.txt``; remove the intro material from - ``ref/generic-views.txt`` and just leave the function reference. - * Change the "Added/changed in development version" callouts to proper Sphinx ``.. versionadded::`` or ``.. versionchanged::`` directives. diff --git a/docs/ref/generic-views.txt b/docs/ref/generic-views.txt index 427ef91090..af23506505 100644 --- a/docs/ref/generic-views.txt +++ b/docs/ref/generic-views.txt @@ -9,67 +9,18 @@ again and again. In Django, the most common of these patterns have been abstracted into "generic views" that let you quickly provide common views of an object without actually needing to write any Python code. -Django's generic views contain the following: +A general introduction to generic views can be found in the :ref:`topic guide +`. - * A set of views for doing list/detail interfaces. - - * A set of views for year/month/day archive pages and associated - detail and "latest" pages (for example, the Django weblog's year_, - month_, day_, detail_, and latest_ pages). - - * A set of views for creating, editing, and deleting objects. - -.. _year: http://www.djangoproject.com/weblog/2005/ -.. _month: http://www.djangoproject.com/weblog/2005/jul/ -.. _day: http://www.djangoproject.com/weblog/2005/jul/20/ -.. _detail: http://www.djangoproject.com/weblog/2005/jul/20/autoreload/ -.. _latest: http://www.djangoproject.com/weblog/ - -All of these views are used by creating configuration dictionaries in -your URLconf files and passing those dictionaries as the third member of the -URLconf tuple for a given pattern. For example, here's the URLconf for the -simple weblog app that drives the blog on djangoproject.com:: - - from django.conf.urls.defaults import * - from django_website.apps.blog.models import Entry - - info_dict = { - 'queryset': Entry.objects.all(), - 'date_field': 'pub_date', - } - - urlpatterns = patterns('django.views.generic.date_based', - (r'^(?P\d{4})/(?P[a-z]{3})/(?P\w{1,2})/(?P[-\w]+)/$', 'object_detail', info_dict), - (r'^(?P\d{4})/(?P[a-z]{3})/(?P\w{1,2})/$', 'archive_day', info_dict), - (r'^(?P\d{4})/(?P[a-z]{3})/$', 'archive_month', info_dict), - (r'^(?P\d{4})/$', 'archive_year', info_dict), - (r'^$', 'archive_index', info_dict), - ) - -As you can see, this URLconf defines a few options in ``info_dict``. -``'queryset'`` gives the generic view a ``QuerySet`` of objects to use (in this -case, all of the ``Entry`` objects) and tells the generic view which model is -being used. - -Documentation of each generic view follows, along with a list of all keyword -arguments that a generic view expects. Remember that as in the example above, -arguments may either come from the URL pattern (as ``month``, ``day``, -``year``, etc. do above) or from the additional-information dictionary (as for -``queryset``, ``date_field``, etc.). +This reference contains details of Django's built-in generic views, along with +a list of all keyword arguments that a generic view expects. Remember that +arguments may either come from the URL pattern or from the ``extra_context`` +additional-information dictionary. Most generic views require the ``queryset`` key, which is a ``QuerySet`` instance; see :ref:`topics-db-queries` for more information about ``QuerySet`` objects. -Most views also take an optional ``extra_context`` dictionary that you can use -to pass any auxiliary information you wish to the view. The values in the -``extra_context`` dictionary can be either functions (or other callables) or -other objects. Functions are evaluated just before they are passed to the -template. However, note that QuerySets retrieve and cache their data when they -are first evaluated, so if you want to pass in a QuerySet via -``extra_context`` that is always fresh you need to wrap it in a function or -lambda that returns the QuerySet. - "Simple" generic views ====================== @@ -801,12 +752,12 @@ specify the page number in the URL in one of two ways: /objects/?page=3 - * To loop over all the available page numbers, use the ``page_range`` - variable. You can iterate over the list provided by ``page_range`` + * To loop over all the available page numbers, use the ``page_range`` + variable. You can iterate over the list provided by ``page_range`` to create a link to every page of results. These values and lists are 1-based, not 0-based, so the first page would be -represented as page ``1``. +represented as page ``1``. For more on pagination, read the :ref:`pagination documentation `. @@ -818,7 +769,7 @@ As a special case, you are also permitted to use ``last`` as a value for /objects/?page=last -This allows you to access the final page of results without first having to +This allows you to access the final page of results without first having to determine how many pages there are. Note that ``page`` *must* be either a valid page number or the value ``last``; @@ -909,7 +860,7 @@ library ` to build and display the form. **Description:** A page that displays a form for creating an object, redisplaying the form with -validation errors (if there are any) and saving the object. +validation errors (if there are any) and saving the object. **Required arguments:** diff --git a/docs/topics/index.txt b/docs/topics/index.txt index 20d7aa3061..a760d3d80c 100644 --- a/docs/topics/index.txt +++ b/docs/topics/index.txt @@ -14,6 +14,7 @@ Introductions to all the key parts of Django you'll need to know: forms/index forms/modelforms templates + generic-views files testing auth -- cgit v1.3 From c9d882c4b6087f2831bb3bc62b473f57904663bf Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 17 Jun 2009 23:57:27 +0000 Subject: Fixed #11336 -- Dummy commit to force refresh of some index pages by Sphinx, caused by file ommitted from [11025] and included in [11026]. Thanks to Peter Landry for the report, and Ramiro for the explanation. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11031 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/index.txt | 157 +++++++++++++++++++++++++++-------------------------- docs/ref/index.txt | 1 + 2 files changed, 80 insertions(+), 78 deletions(-) (limited to 'docs/ref') diff --git a/docs/index.txt b/docs/index.txt index 5ea7cfed5d..89ee463dfa 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,3 +1,4 @@ + .. _index: ==================== @@ -33,70 +34,70 @@ Having trouble? We'd like to help! First steps =========== - * **From scratch:** + * **From scratch:** :ref:`Overview ` | :ref:`Installation ` - - * **Tutorial:** - :ref:`Part 1 ` | - :ref:`Part 2 ` | - :ref:`Part 3 ` | + + * **Tutorial:** + :ref:`Part 1 ` | + :ref:`Part 2 ` | + :ref:`Part 3 ` | :ref:`Part 4 ` The model layer =============== - * **Models:** - :ref:`Model syntax ` | - :ref:`Field types ` | + * **Models:** + :ref:`Model syntax ` | + :ref:`Field types ` | :ref:`Meta options ` - - * **QuerySets:** - :ref:`Executing queries ` | + + * **QuerySets:** + :ref:`Executing queries ` | :ref:`QuerySet method reference ` - - * **Model instances:** - :ref:`Instance methods ` | + + * **Model instances:** + :ref:`Instance methods ` | :ref:`Accessing related objects ` - - * **Advanced:** - :ref:`Managers ` | - :ref:`Raw SQL ` | - :ref:`Transactions ` | - :ref:`Aggregation ` | + + * **Advanced:** + :ref:`Managers ` | + :ref:`Raw SQL ` | + :ref:`Transactions ` | + :ref:`Aggregation ` | :ref:`Custom fields ` - - * **Other:** - :ref:`Supported databases ` | - :ref:`Legacy databases ` | + + * **Other:** + :ref:`Supported databases ` | + :ref:`Legacy databases ` | :ref:`Providing initial data ` The template layer ================== - * **For designers:** - :ref:`Syntax overview ` | + * **For designers:** + :ref:`Syntax overview ` | :ref:`Built-in tags and filters ` - - * **For programmers:** - :ref:`Template API ` | + + * **For programmers:** + :ref:`Template API ` | :ref:`Custom tags and filters ` The view layer ============== - * **The basics:** - :ref:`URLconfs ` | - :ref:`View functions ` | + * **The basics:** + :ref:`URLconfs ` | + :ref:`View functions ` | :ref:`Shortcuts ` - + * **Reference:** :ref:`Request/response objects ` - - * **File uploads:** - :ref:`Overview ` | - :ref:`File objects ` | - :ref:`Storage API ` | - :ref:`Managing files ` | + + * **File uploads:** + :ref:`Overview ` | + :ref:`File objects ` | + :ref:`Storage API ` | + :ref:`Managing files ` | :ref:`Custom storage ` * **Generic views:** @@ -106,50 +107,50 @@ The view layer * **Advanced:** :ref:`Generating CSV ` | :ref:`Generating PDF ` - - * **Middleware:** - :ref:`Overview ` | + + * **Middleware:** + :ref:`Overview ` | :ref:`Built-in middleware classes ` Forms ===== - * **The basics:** - :ref:`Overview ` | - :ref:`Form API ` | - :ref:`Built-in fields ` | + * **The basics:** + :ref:`Overview ` | + :ref:`Form API ` | + :ref:`Built-in fields ` | :ref:`Built-in widgets ` - - * **Advanced:** - :ref:`Forms for models ` | - :ref:`Integrating media ` | - :ref:`Formsets ` | + + * **Advanced:** + :ref:`Forms for models ` | + :ref:`Integrating media ` | + :ref:`Formsets ` | :ref:`Customizing validation ` - - * **Extras:** - :ref:`Form preview ` | + + * **Extras:** + :ref:`Form preview ` | :ref:`Form wizard ` The development process ======================= - * **Settings:** - :ref:`Overview ` | + * **Settings:** + :ref:`Overview ` | :ref:`Full list of settings ` - * **django-admin.py and manage.py:** - :ref:`Overview ` | + * **django-admin.py and manage.py:** + :ref:`Overview ` | :ref:`Adding custom commands ` - + * **Testing:** :ref:`Overview ` - - * **Deployment:** - :ref:`Overview ` | + + * **Deployment:** + :ref:`Overview ` | :ref:`Apache/mod_wsgi ` | :ref:`Apache/mod_python ` | - :ref:`FastCGI/SCGI/AJP ` | - :ref:`Apache authentication ` | - :ref:`Serving static files ` | + :ref:`FastCGI/SCGI/AJP ` | + :ref:`Apache authentication ` | + :ref:`Serving static files ` | :ref:`Tracking code errors by e-mail ` Other batteries included @@ -183,22 +184,22 @@ Other batteries included The Django open-source project ============================== - * **Community:** - :ref:`How to get involved ` | - :ref:`The release process ` | + * **Community:** + :ref:`How to get involved ` | + :ref:`The release process ` | :ref:`Team of committers ` - - * **Design philosophies:** + + * **Design philosophies:** :ref:`Overview ` - - * **Documentation:** + + * **Documentation:** :ref:`About this documentation ` - - * **Third-party distributions:** + + * **Third-party distributions:** :ref:`Overview ` - - * **Django over time:** - :ref:`API stability ` | + + * **Django over time:** + :ref:`API stability ` | :ref:`Archive of release notes ` | `Backwards-incompatible changes`_ .. _Backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges diff --git a/docs/ref/index.txt b/docs/ref/index.txt index 3ffa1fcce1..6cc796d8e4 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -20,3 +20,4 @@ API Reference signals templates/index unicode + -- cgit v1.3 From 15a908b4d1c890a480e2a50b0f23ad6fd259ce29 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Thu, 18 Jun 2009 00:16:48 +0000 Subject: Refs #11336 -- Another dummy commit to force refresh of some index pages by Sphinx, caused by file ommitted from [11025] and included in [11026]. Thanks to Peter Landry for the report, and Ramiro for the explanation. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11032 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/generic-views.txt | 1 + docs/topics/index.txt | 1 + 2 files changed, 2 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/generic-views.txt b/docs/ref/generic-views.txt index af23506505..4752a705a0 100644 --- a/docs/ref/generic-views.txt +++ b/docs/ref/generic-views.txt @@ -1088,3 +1088,4 @@ In addition to ``extra_context``, the template's context will be: variable's name depends on the ``template_object_name`` parameter, which is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, this variable's name will be ``foo``. + diff --git a/docs/topics/index.txt b/docs/topics/index.txt index a760d3d80c..7fa283aa1a 100644 --- a/docs/topics/index.txt +++ b/docs/topics/index.txt @@ -26,3 +26,4 @@ Introductions to all the key parts of Django you'll need to know: serialization settings signals + -- cgit v1.3 From 457a1f9a031543e3d5d1cfb3944712fe71ebba2f Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Thu, 18 Jun 2009 13:32:12 +0000 Subject: Fixed #11272 -- Made some clarifications to the overview and tutorial. Thanks to jjinux for the review notes. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11044 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/intro/overview.txt | 10 +++++----- docs/intro/tutorial01.txt | 36 ++++++++++++++++++------------------ docs/intro/tutorial02.txt | 8 ++++---- docs/intro/tutorial03.txt | 8 ++++---- docs/ref/contrib/contenttypes.txt | 4 ++-- docs/topics/http/sessions.txt | 3 +++ 6 files changed, 36 insertions(+), 33 deletions(-) (limited to 'docs/ref') diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 297dd38f79..594c9fe582 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -144,10 +144,10 @@ as registering your model in the admin site:: headline = models.CharField(max_length=200) content = models.TextField() reporter = models.ForeignKey(Reporter) - + # In admin.py in the same directory... - + import models from django.contrib import admin @@ -243,9 +243,9 @@ might look like:

Articles for {{ year }}

{% for article in article_list %} -

{{ article.headline }}

-

By {{ article.reporter.full_name }}

-

Published {{ article.pub_date|date:"F j, Y" }}

+

{{ article.headline }}

+

By {{ article.reporter.full_name }}

+

Published {{ article.pub_date|date:"F j, Y" }}

{% endfor %} {% endblock %} diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index c0ad3dd8cf..ae4af665f1 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -42,13 +42,13 @@ code, then run the command ``django-admin.py startproject mysite``. This will create a ``mysite`` directory in your current directory. .. admonition:: Mac OS X permissions - + If you're using Mac OS X, you may see the message "permission denied" when you try to run ``django-admin.py startproject``. This is because, on Unix-based systems like OS X, a file must be marked as "executable" before it can be run as a program. To do this, open Terminal.app and navigate (using the ``cd`` command) to the directory where :ref:`django-admin.py - ` is installed, then run the command + ` is installed, then run the command ``chmod +x django-admin.py``. .. note:: @@ -90,14 +90,14 @@ These files are: * :file:`__init__.py`: An empty file that tells Python that this directory should be considered a Python package. (Read `more about packages`_ in the official Python docs if you're a Python beginner.) - + * :file:`manage.py`: A command-line utility that lets you interact with this Django project in various ways. You can read all the details about :file:`manage.py` in :ref:`ref-django-admin`. - + * :file:`settings.py`: Settings/configuration for this Django project. :ref:`topics-settings` will tell you all about how settings work. - + * :file:`urls.py`: The URL declarations for this Django project; a "table of contents" of your Django-powered site. You can read more about URLs in :ref:`topics-http-urls`. @@ -134,22 +134,22 @@ It worked! .. admonition:: Changing the port By default, the :djadmin:`runserver` command starts the development server - on the internal IP at port 8000. - + on the internal IP at port 8000. + If you want to change the server's port, pass it as a command-line argument. For instance, this command starts the server on port 8080: - + .. code-block:: bash python manage.py runserver 8080 - + If you want to change the server's IP, pass it along with the port. So to listen on all public IPs (useful if you want to show off your work on other computers), use: - + .. code-block:: bash - + python manage.py runserver 0.0.0.0:8000 Full docs for the development server can be found in the @@ -164,21 +164,21 @@ database's connection parameters: * :setting:`DATABASE_ENGINE` -- Either 'postgresql_psycopg2', 'mysql' or 'sqlite3'. Other backends are :setting:`also available `. - + * :setting:`DATABASE_NAME` -- The name of your database. If you're using SQLite, the database will be a file on your computer; in that case, ``DATABASE_NAME`` should be the full absolute path, including filename, of that file. If the file doesn't exist, it will automatically be created when you synchronize the database for the first time (see below). - - When specifying the path, always use forward slashes, even on Windows + + When specifying the path, always use forward slashes, even on Windows (e.g. ``C:/homes/user/mysite/sqlite3.db``). - + * :setting:`DATABASE_USER` -- Your database username (not used for SQLite). - + * :setting:`DATABASE_PASSWORD` -- Your database password (not used for SQLite). - + * :setting:`DATABASE_HOST` -- The host your database is on. Leave this as an empty string if your database server is on the same physical machine (not used for SQLite). @@ -594,7 +594,7 @@ your models, not only for your own sanity when dealing with the interactive prompt, but also because objects' representations are used throughout Django's automatically-generated admin. -.. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not +.. admonition:: Why :meth:`~django.db.models.Model.__unicode__` and not :meth:`~django.db.models.Model.__str__`? If you're familiar with Python, you might be in the habit of adding diff --git a/docs/intro/tutorial02.txt b/docs/intro/tutorial02.txt index fa1912213a..203c945c02 100644 --- a/docs/intro/tutorial02.txt +++ b/docs/intro/tutorial02.txt @@ -86,8 +86,8 @@ Enter the admin site ==================== Now, try logging in. (You created a superuser account in the first part of this -tutorial, remember? If you didn't create one or forgot the password you can -:ref:`create another one `.) You should see +tutorial, remember? If you didn't create one or forgot the password you can +:ref:`create another one `.) You should see the Django admin index page: .. image:: _images/admin02t.png @@ -238,8 +238,8 @@ the admin page doesn't display choices. Yet. -There are two ways to solve this problem. The first register ``Choice`` with the -admin just as we did with ``Poll``. That's easy:: +There are two ways to solve this problem. The first is to register ``Choice`` +with the admin just as we did with ``Poll``. That's easy:: from mysite.polls.models import Choice diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index 867b7d1224..77c54c2e43 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -71,7 +71,7 @@ For more on :class:`~django.http.HttpRequest` objects, see the :ref:`ref-request-response`. For more details on URLconfs, see the :ref:`topics-http-urls`. -When you ran ``python django-admin.py startproject mysite`` at the beginning of +When you ran ``django-admin.py startproject mysite`` at the beginning of Tutorial 1, it created a default URLconf in ``mysite/urls.py``. It also automatically set your :setting:`ROOT_URLCONF` setting (in ``settings.py``) to point at that file:: @@ -98,8 +98,7 @@ This is worth a review. When somebody requests a page from your Web site -- say, the :setting:`ROOT_URLCONF` setting. It finds the variable named ``urlpatterns`` and traverses the regular expressions in order. When it finds a regular expression that matches -- ``r'^polls/(?P\d+)/$'`` -- it loads the -associated Python package/module: ``mysite.polls.views.detail``. That -corresponds to the function ``detail()`` in ``mysite/polls/views.py``. Finally, +function ``detail()`` from ``mysite/polls/views.py``. Finally, it calls that ``detail()`` function like so:: detail(request=, poll_id='23') @@ -486,7 +485,8 @@ Here's what happens if a user goes to "/polls/34/" in this system: further processing. Now that we've decoupled that, we need to decouple the 'mysite.polls.urls' -URLconf by removing the leading "polls/" from each line:: +URLconf by removing the leading "polls/" from each line, and removing the +lines registering the admin site:: urlpatterns = patterns('mysite.polls.views', (r'^$', 'index'), diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index f814eccaab..94900b3892 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -347,8 +347,8 @@ doesn't work with a :class:`~django.contrib.contenttypes.generic.GenericRelation`. For example, you might be tempted to try something like:: - Bookmark.objects.aggregate(Count('tags')) - + Bookmark.objects.aggregate(Count('tags')) + This will not work correctly, however. The generic relation adds extra filters to the queryset to ensure the correct content type, but the ``aggregate`` method doesn't take them into account. For now, if you need aggregates on generic diff --git a/docs/topics/http/sessions.txt b/docs/topics/http/sessions.txt index fa3864a7c2..d3956504c7 100644 --- a/docs/topics/http/sessions.txt +++ b/docs/topics/http/sessions.txt @@ -4,6 +4,9 @@ How to use sessions =================== +.. module:: django.contrib.sessions + :synopsis: Provides session management for Django projects. + Django provides full support for anonymous sessions. The session framework lets you store and retrieve arbitrary data on a per-site-visitor basis. It stores data on the server side and abstracts the sending and receiving of cookies. -- cgit v1.3 From 7c18404a2499db964343a0b4a6e57b17c2c2b619 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Thu, 18 Jun 2009 13:33:18 +0000 Subject: Fixed #11312 -- Fixed the default value given for DEFAULT_FILE_STORAGE in the docs. THanks to x00nix@gmail.com for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11046 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/settings.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 0cca6fe05d..e8c673d995 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -195,7 +195,7 @@ DATABASE_NAME Default: ``''`` (Empty string) The name of the database to use. For SQLite, it's the full path to the database -file. When specifying the path, always use forward slashes, even on Windows +file. When specifying the path, always use forward slashes, even on Windows (e.g. ``C:/homes/user/mysite/sqlite3.db``). .. setting:: DATABASE_OPTIONS @@ -228,7 +228,7 @@ The port to use when connecting to the database. An empty string means the default port. Not used with SQLite. .. setting:: DATABASE_USER - + DATABASE_USER ------------- @@ -251,7 +251,7 @@ See also ``DATETIME_FORMAT``, ``TIME_FORMAT``, ``YEAR_MONTH_FORMAT`` and ``MONTH_DAY_FORMAT``. .. setting:: DATETIME_FORMAT - + DATETIME_FORMAT --------------- @@ -330,7 +330,7 @@ isn't manually specified. Used with ``DEFAULT_CHARSET`` to construct the DEFAULT_FILE_STORAGE -------------------- -Default: ``django.core.files.storage.FileSystemStorage`` +Default: ``'django.core.files.storage.FileSystemStorage'`` Default file storage class to be used for any file-related operations that don't specify a particular storage system. See :ref:`topics-files`. @@ -519,14 +519,14 @@ system's standard umask. .. warning:: **Always prefix the mode with a 0.** - + If you're not familiar with file modes, please note that the leading ``0`` is very important: it indicates an octal number, which is the way that modes must be specified. If you try to use ``644``, you'll get totally incorrect behavior. - -.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html + +.. _documentation for os.chmod: http://docs.python.org/lib/os-file-dir.html .. setting:: FIXTURE_DIRS @@ -1153,7 +1153,7 @@ running in the correct environment. Django cannot reliably use alternate time zones in a Windows environment. If you're running Django on Windows, this variable must be set to match the system timezone. - + .. _See available choices: http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE .. setting:: URL_VALIDATOR_USER_AGENT -- cgit v1.3 From 97fb6cf2b3c1546d1aa08a90a38d146d2b0046ef Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Thu, 18 Jun 2009 13:35:06 +0000 Subject: Fixed #11141 -- Corrected a code example in the admin docs. Thanks to jodal for the report, and SmileyChris for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11049 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/admin/index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 6719527d2f..bad7dec390 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -347,7 +347,7 @@ A few special cases to note about ``list_display``: birthday = models.DateField() def born_in_fifties(self): - return self.birthday.strftime('%Y')[:3] == 5 + return self.birthday.strftime('%Y')[:3] == '195' born_in_fifties.boolean = True class PersonAdmin(admin.ModelAdmin): -- cgit v1.3 From 755762e5b9990f7cba74c2af99333637ac5efa29 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Thu, 18 Jun 2009 13:37:10 +0000 Subject: Fixed #11221 -- Replaced a reference to a non-existent URL with an actual explanation of sequences. Thanks to Rob Hudson for the report, and SmileyChris for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11053 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/django-admin.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 71804cf022..f657db20f4 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -611,7 +611,11 @@ sqlsequencereset Prints the SQL statements for resetting sequences for the given app name(s). -See http://simon.incutio.com/archive/2004/04/21/postgres for more information. +Sequences are indexes used by some database engines to track the next available +number for automatically incremented fields. + +Use this command to generate SQL which will fix cases where a sequence is out +of sync with its automatically incremented field data. startapp ------------------ -- cgit v1.3 From 18b29c523bdd78531810e98c02f9f2a9c3508f7b Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 24 Jun 2009 14:00:53 +0000 Subject: Fixed #11356 -- Added links to the growing collection of 3rd party database backends that are available. Thank to Nathan Auch for the draft text. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11093 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/databases.txt | 35 ++++++++++++++++++++++++++++++----- docs/topics/install.txt | 35 ++++++++++++++++++++++++++++------- 2 files changed, 58 insertions(+), 12 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 76a4159235..9a35b6cb8f 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -251,7 +251,7 @@ Here's a sample configuration which uses a MySQL option file:: DATABASE_OPTIONS = { 'read_default_file': '/path/to/my.cnf', } - + # my.cnf [client] database = DATABASE_NAME @@ -445,10 +445,10 @@ If you're getting this error, you can solve it by: * Switching to another database backend. At a certain point SQLite becomes too "lite" for real-world applications, and these sorts of concurrency errors indicate you've reached that point. - - * Rewriting your code to reduce concurrency and ensure that database + + * Rewriting your code to reduce concurrency and ensure that database transactions are short-lived. - + * Increase the default timeout value by setting the ``timeout`` database option option:: @@ -457,7 +457,7 @@ If you're getting this error, you can solve it by: "timeout": 20, # ... } - + This will simply make SQLite wait a bit longer before throwing "database is locked" errors; it won't really do anything to solve them. @@ -601,3 +601,28 @@ some limitations on the usage of such LOB columns in general: Oracle. A workaround to this is to keep ``TextField`` columns out of any models that you foresee performing ``distinct()`` queries on, and to include the ``TextField`` in a related model instead. + +.. _third-party-notes: + +Using a 3rd-party database backend +================================== + +In addition to the officially supported databases, there are backends provided +by 3rd parties that allow you to use other databases with Django: + +* `Sybase SQL Anywhere`_ +* `IBM DB2`_ +* `Microsoft SQL Server 2005`_ +* Firebird_ +* ODBC_ + +The Django versions and ORM features supported by these unofficial backends +vary considerably. Queries regarding the specific capabilities of these +unofficial backends, along with any support queries, should be directed to +the support channels provided by each 3rd party project. + +.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/ +.. _IBM DB2: http://code.google.com/p/ibm-db/ +.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/ +.. _Firebird: http://code.google.com/p/django-firebird/ +.. _ODBC: http://code.google.com/p/django-pyodbc/ diff --git a/docs/topics/install.txt b/docs/topics/install.txt index 4268759828..b66c8aef15 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -61,13 +61,27 @@ for each platform. Get your database running ========================= -If you plan to use Django's database API functionality, you'll need to -make sure a database server is running. Django works with PostgreSQL_, -MySQL_, Oracle_ and SQLite_ (although SQLite doesn't require a separate server -to be running). +If you plan to use Django's database API functionality, you'll need to make +sure a database server is running. Django supports many different database +servers and is officially supported with PostgreSQL_, MySQL_, Oracle_ and +SQLite_ (although SQLite doesn't require a separate server to be running). -Additionally, you'll need to make sure your Python database bindings are -installed. +In addition to the officially supported databases, there are backends provided +by 3rd parties that allow you to use other databases with Django: + +* `Sybase SQL Anywhere`_ +* `IBM DB2`_ +* `Microsoft SQL Server 2005`_ +* Firebird_ +* ODBC_ + +The Django versions and ORM features supported by these unofficial backends +vary considerably. Queries regarding the specific capabilities of these +unofficial backends, along with any support queries, should be directed to the +support channels provided by each 3rd party project. + +In addition to a database backend, you'll need to make sure your Python +database bindings are installed. * If you're using PostgreSQL, you'll need the psycopg_ package. Django supports both version 1 and 2. (When you configure Django's database layer, specify @@ -89,6 +103,9 @@ installed. :ref:`Oracle backend ` for important information regarding supported versions of both Oracle and ``cx_Oracle``. +* If you're using an unofficial 3rd party backend, please consult the + documentation provided for any additional requirements. + If you plan to use Django's ``manage.py syncdb`` command to automatically create database tables for your models, you'll need to ensure that Django has permission to create and alter tables in the @@ -111,7 +128,11 @@ Django will need permission to create a test database. .. _pysqlite: http://pysqlite.org/ .. _cx_Oracle: http://cx-oracle.sourceforge.net/ .. _Oracle: http://www.oracle.com/ - +.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/ +.. _IBM DB2: http://code.google.com/p/ibm-db/ +.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/ +.. _Firebird: http://code.google.com/p/django-firebird/ +.. _ODBC: http://code.google.com/p/django-pyodbc/ .. _removing-old-versions-of-django: Remove any old versions of Django -- cgit v1.3 From bbd7b64e7606534716be15d31a23f2b081f018ff Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 24 Jun 2009 14:01:36 +0000 Subject: Fixed #11354 -- Remove stray whitespace in queryset docs. Thanks to flebel for the report. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11094 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/querysets.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/ref') diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index eb8fbfd833..348486b341 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -35,7 +35,7 @@ You can evaluate a ``QuerySet`` in the following ways: * **Slicing.** As explained in :ref:`limiting-querysets`, a ``QuerySet`` can be sliced, using Python's array-slicing syntax. Usually slicing a - ``QuerySet`` returns another (unevaluated ) ``QuerySet``, but Django will + ``QuerySet`` returns another (unevaluated) ``QuerySet``, but Django will execute the database query if you use the "step" parameter of slice syntax. -- cgit v1.3 From 4acf7f43e79d1781462b4035b871446dd8c58cf4 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 24 Jun 2009 14:02:22 +0000 Subject: Fixed #10415 -- Added documentation for features added in r7627 and r7630; extensibility points for the ModelAdmin and AdminSite. Thanks to Ramiro Morales for the draft text. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11095 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/admin/index.txt | 108 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 105 insertions(+), 3 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index bad7dec390..ec8b358974 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -667,6 +667,43 @@ 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.change_list_template + +Path to a custom template that will be used by the model objects "change list" +view. Templates can override or extend base admin templates as described in +`Overriding Admin Templates`_. + +If you don't specify this attribute, a default template shipped with Django +that provides the standard appearance is used. + +.. attribute:: ModelAdmin.change_form_template + +Path to a custom template that will be used by both the model object creation +and change views. Templates can override or extend base admin templates as +described in `Overriding Admin Templates`_. + +If you don't specify this attribute, a default template shipped with Django +that provides the standard appearance is used. + +.. attribute:: ModelAdmin.object_history_template + +Path to a custom template that will be used by the model object change history +display view. Templates can override or extend base admin templates as +described in `Overriding Admin Templates`_. + +If you don't specify this attribute, a default template shipped with Django +that provides the standard appearance is used. + +.. attribute:: ModelAdmin.delete_confirmation_template + +Path to a custom template that will be used by the view responsible of showing +the confirmation page when the user decides to delete one or more model +objects. Templates can override or extend base admin templates as described in +`Overriding Admin Templates`_. + +If you don't specify this attribute, a default template shipped with Django +that provides the standard appearance is used. + ``ModelAdmin`` methods ---------------------- @@ -762,6 +799,56 @@ return a subset of objects for this foreign key field based on the user:: This uses the ``HttpRequest`` instance to filter the ``Car`` foreign key field to only the cars owned by the ``User`` instance. +Other methods +~~~~~~~~~~~~~ + +.. method:: ModelAdmin.add_view(self, request, form_url='', extra_context=None) + +Django view for the model instance addition page. See note below. + +.. method:: ModelAdmin.change_view(self, request, object_id, extra_context=None) + +Django view for the model instance edition page. See note below. + +.. method:: ModelAdmin.changelist_view(self, request, extra_context=None) + +Django view for the model instances change list/actions page. See note below. + +.. method:: ModelAdmin.delete_view(self, request, object_id, extra_context=None) + +Django view for the model instance(s) deletion confirmation page. See note below. + +.. method:: ModelAdmin.history_view(self, request, object_id, extra_context=None) + +Django view for the page that shows the modification history for a given model +instance. + +Unlike the hook-type ``ModelAdmin`` methods detailed in the previous section, +these five methods are in reality designed to be invoked as Django views from +the admin application URL dispatching handler to render the pages that deal +with model instances CRUD operations. As a result, completely overriding these +methods will significantly change the behavior of the admin application. + +One comon reason for overriding these methods is to augment the context data +that is provided to the template that renders the view. In the following +example, the change view is overridden so that the rendered template is +provided some extra mapping data that would not otherwise be available:: + + class MyModelAdmin(admin.ModelAdmin): + + # A template for a very customized change view: + change_form_template = 'admin/myapp/extras/openstreetmap_change_form.html' + + def get_osm_info(self): + # ... + + def change_view(self, request, object_id, extra_context=None): + my_context = { + 'osm_data': self.get_osm_info(), + } + return super(MyModelAdmin, self).change_view(request, object_id, + extra_context=my_context)) + ``ModelAdmin`` media definitions -------------------------------- @@ -1106,7 +1193,7 @@ directory, our link would appear on every model's change form. Templates which may be overridden per app or model -------------------------------------------------- -Not every template in ``contrib\admin\templates\admin`` may be overridden per +Not every template in ``contrib/admin/templates/admin`` may be overridden per app or per model. The following can: * ``app_index.html`` @@ -1131,8 +1218,8 @@ Root and login templates ------------------------ If you wish to change the index or login templates, you are better off creating -your own ``AdminSite`` instance (see below), and changing the ``index_template`` -or ``login_template`` properties. +your own ``AdminSite`` instance (see below), and changing the :attr:`AdminSite.index_template` +or :attr:`AdminSite.login_template` properties. ``AdminSite`` objects ===================== @@ -1151,6 +1238,21 @@ or add anything you like. Then, simply create an instance of your Python class), and register your models and ``ModelAdmin`` subclasses with it instead of using the default. +``AdminSite`` attributes +------------------------ + +.. attribute:: AdminSite.index_template + +Path to a custom template that will be used by the admin site main index view. +Templates can override or extend base admin templates as described in +`Overriding Admin Templates`_. + +.. attribute:: AdminSite.login_template + +Path to a custom template that will be used by the admin site login view. +Templates can override or extend base admin templates as described in +`Overriding Admin Templates`_. + Hooking ``AdminSite`` instances into your URLconf ------------------------------------------------- -- cgit v1.3 From 970be97530e5eef5c872462e065be630c183847d Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 24 Jun 2009 14:04:18 +0000 Subject: Fixed #8861 -- Added note on the availability of ModelForm.instance. Thanks to Ramiro Morales for the patch. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11097 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/admin/index.txt | 6 ++++-- docs/topics/forms/modelforms.txt | 20 +++++++++++++++----- 2 files changed, 19 insertions(+), 7 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index ec8b358974..64d9c52492 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -870,7 +870,7 @@ Adding custom validation to the admin ------------------------------------- Adding custom validation of data in the admin is quite easy. The automatic admin -interfaces reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you +interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you the ability define your own form:: class ArticleAdmin(admin.ModelAdmin): @@ -890,7 +890,9 @@ any field:: It is important you use a ``ModelForm`` here otherwise things can break. See the :ref:`forms ` documentation on :ref:`custom validation -` for more information. +` and, more specifically, the +:ref:`model form validation notes ` for more +information. .. _admin-inlines: diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt index 8acb3f7646..add581268b 100644 --- a/docs/topics/forms/modelforms.txt +++ b/docs/topics/forms/modelforms.txt @@ -397,16 +397,26 @@ to be rendered first, we could specify the following ``ModelForm``:: ... model = Book ... fields = ['title', 'author'] +.. _overriding-modelform-clean-method: Overriding the clean() method ----------------------------- You can override the ``clean()`` method on a model form to provide additional -validation in the same way you can on a normal form. However, by default the -``clean()`` method validates the uniqueness of fields that are marked as -``unique``, ``unique_together`` or ``unique_for_date|month|year`` on the model. -Therefore, if you would like to override the ``clean()`` method and maintain the -default validation, you must call the parent class's ``clean()`` method. +validation in the same way you can on a normal form. + +In this regard, model forms have two specific characteristics when compared to +forms: + +By default the ``clean()`` method validates the uniqueness of fields that are +marked as ``unique``, ``unique_together`` or ``unique_for_date|month|year`` on +the model. Therefore, if you would like to override the ``clean()`` method and +maintain the default validation, you must call the parent class's ``clean()`` +method. + +Also, a model form instance bound to a model object will contain a +``self.instance`` attribute that gives model form methods access to that +specific model instance. Form inheritance ---------------- -- cgit v1.3