From 4acf7f43e79d1781462b4035b871446dd8c58cf4 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 24 Jun 2009 14:02:22 +0000 Subject: [PATCH] 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(-) 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 -------------------------------------------------