diff --git a/django/contrib/admindocs/templates/admin_doc/model_index.html b/django/contrib/admindocs/templates/admin_doc/model_index.html index 4dd7caa2a6..47c94c0c70 100644 --- a/django/contrib/admindocs/templates/admin_doc/model_index.html +++ b/django/contrib/admindocs/templates/admin_doc/model_index.html @@ -36,7 +36,7 @@ diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index bad7dec390..64d9c52492 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 -------------------------------- @@ -783,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): @@ -803,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: @@ -1106,7 +1195,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 +1220,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 +1240,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 ------------------------------------------------- diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index adac7523b4..4943bcc2a5 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -615,3 +615,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/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. 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 ---------------- diff --git a/docs/topics/i18n.txt b/docs/topics/i18n.txt index 140adce74c..86c03221aa 100644 --- a/docs/topics/i18n.txt +++ b/docs/topics/i18n.txt @@ -978,15 +978,17 @@ message files (``.po``). Translation work itself just involves editing existing files of this type, but if you want to create your own message files, or want to test or compile a changed message file, you will need the ``gettext`` utilities: - * Download the following zip files from - http://sourceforge.net/projects/gettext + * Download the following zip files from the GNOME servers + http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/ or from one + of its mirrors_ - * ``gettext-runtime-X.bin.woe32.zip`` - * ``gettext-tools-X.bin.woe32.zip`` - * ``libiconv-X.bin.woe32.zip`` + * ``gettext-runtime-X.zip`` + * ``gettext-tools-X.zip`` - * Extract the 3 files in the same folder (i.e. ``C:\Program - Files\gettext-utils``) + ``X`` is the version number, we recomend using ``0.15`` or higher. + + * Extract the contents of the ``bin\`` directories in both files to the + same folder on your system (i.e. ``C:\Program Files\gettext-utils``) * Update the system PATH: @@ -995,6 +997,8 @@ test or compile a changed message file, you will need the ``gettext`` utilities: * Add ``;C:\Program Files\gettext-utils\bin`` at the end of the ``Variable value`` field +.. _mirrors: http://ftp.gnome.org/pub/GNOME/MIRRORS + You may also use ``gettext`` binaries you have obtained elsewhere, so long as the ``xgettext --version`` command works properly. Some version 0.14.4 binaries have been found to not support this command. Do not attempt to use Django 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