Ticket #10415: 10415-custom_admin_templates_and_views_docs.diff

docs/ref/contrib/admin/index.txt

@@ -667 +667 @@
 changelist displays actions at the top of the page (``actions_on_top = True;
 actions_on_bottom = False``).
 
+.. attribute:: ModelAdmin.change_list_template
+
+.. versionadded:: 1.0
+
+Path to a custom template that will be used by the model objects "change list"
+view. The template file searching order and precedence rules and modular
+extension strategy recommendations outlined in the `Overriding Admin Templates`_
+section apply here.
+
+If you don't specify it, a default template shipped with Django that provides
+the standard appearance is used.
+
+.. attribute:: ModelAdmin.change_form_template
+
+.. versionadded:: 1.0
+
+Path to a custom template that will be used by both the model object creation
+and change views. The template file searching order and precedence rules and
+modular extension strategy recommendations outlined in the `Overriding Admin
+Templates`_ section apply here.
+
+If you don't specify it, a default template shipped with Django that provides
+the standard appearance is used.
+
+.. attribute:: ModelAdmin.object_history_template
+
+.. versionadded:: 1.0
+
+Path to a custom template that will be used by the model object change history
+display view. The template file searching order and precedence rules and modular
+extension strategy recommendations outlined in the `Overriding Admin Templates`_
+section apply here.
+
+If you don't specify it, a default template shipped with Django that provides
+the standard appearance is used.
+
+.. attribute:: ModelAdmin.delete_confirmation_template
+
+.. versionadded:: 1.0
+
+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.
+The template file searching order and precedence rules and modular extension
+strategy recommendations outlined in the `Overriding Admin Templates`_ section
+apply here.
+
+If you don't specify it, a default template shipped with Django that provides
+the standard appearance is used.
+
 ``ModelAdmin`` methods
 ----------------------
 
@@ -762 +811 @@
 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 instancies CRUD operations. Because of that they implement the
+complex logic specific to the generic nature of the admin app and there aren't
+many possibilities to customize their behavior other than replace their
+implementation.
+
+.. versionadded:: 1.0
+
+Nonetheless, you still can customize the presentation of their respective pages
+(possibly transforming them completely) if needed: For this, you override the
+method in your ``ModelAdmin`` subclass to augment the context provided to the
+template layer using its ``extra_context`` parameter and at the same time
+override the associated template used by the admin with the respective
+``*_template`` option described in the `ModelAdmin options`_ section. An
+example::
+
+    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, form_url='', extra_context=None):
+            my_context = {
+                'osm_data': self.get_osm_info(),
+            }
+            return super(MyModelAdmin, self).change_view(request,
+                extra_context=my_context))
+
 ``ModelAdmin`` media definitions
 --------------------------------
 
@@ -1106 +1212 @@
 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 +1237 @@
 ------------------------
 
 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 +1257 @@
 Python class), and register your models and ``ModelAdmin`` subclasses
 with it instead of using the default.
 
+``AdminSite`` attributes
+------------------------
+
+.. attribute:: AdminSite.index_template
+
+.. versionadded:: 1.0
+
+Path to a custom template that will be used by the admin site main index view.
+The template file searching order and precedence rules and modular extension
+strategy recommendations outlined in the `Overriding Admin Templates`_ section
+apply here.
+
+.. attribute:: AdminSite.login_template
+
+.. versionadded:: 1.0
+
+Path to a custom template that will be used by the admin site login view.
+The template file searching order and precedence rules and modular extension
+strategy recommendations outlined in the `Overriding Admin Templates`_ section
+apply here.
+
 Hooking ``AdminSite`` instances into your URLconf
 -------------------------------------------------