From e6d2b14e359035f2e19089be629983162e7573e1 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Thu, 16 Apr 2009 12:47:34 +0000 Subject: [PATCH] Fixed #10726 -- Added documentation on AdminSite urls. Thanks to Alex Gaynor for the initial draft. git-svn-id: http://code.djangoproject.com/svn/django/trunk@10565 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/contrib/admin/index.txt | 103 +++++++++++++++++++++---------- 1 file changed, 71 insertions(+), 32 deletions(-) diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 4b1d002b9c..f277d08d4d 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -1137,40 +1137,11 @@ 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. -Linking to admin views -====================== - -.. versionadded:: 1.1 - -All the admin views use :ref:`named URL patterns ` so it's -easy to link to admin views with ``urlresolvers.reverse`` or the :ttag:`url` -template tag. - -Each model gets its own set of views and its own name using the model's app name -and model name. For example, the "add" view for a ``Choice`` model in a -``polls`` app would be named ``"admin_polls_choice_add"``. - -All the available views and their names are: - - ============== ====================================== =================== - View View name Parameters - ============== ====================================== =================== - Change list ``"admin___changelist"`` None - Add object ``"admin___add"`` None - Change object ``"admin___change"`` ``object_id`` - Delete object ``"admin___delete"`` ``object_id`` - Object history ``"admin___history"`` ``object_id`` - ============== ====================================== =================== - -For example, to get the change URL for a particular ``Choice`` object:: - - >>> from django.core import urlresolvers - >>> c = Choice.objects.get(...) - >>> change_url = urlresolvers.reverse('admin_polls_choice_change', (c.id,)) - ``AdminSite`` objects ===================== +.. class:: AdminSite + A Django administrative site is represented by an instance of ``django.contrib.admin.sites.AdminSite``; by default, an instance of this class is created as ``django.contrib.admin.site`` and you can @@ -1246,14 +1217,82 @@ respectively:: ('^advanced-admin/', include(advanced_site.urls)), ) +``AdminSite`` instances take a single argument to their constructor, their +name, which can be anything you like. This argument becomes the prefix to the +URL names for the purposes of :ref:`reversing them`. This +is only necessary if you are using more than one ``AdminSite``. + Adding views to admin sites --------------------------- .. versionadded:: 1.1 -Just like ``ModelAdmin``, ``AdminSite`` provides a +Just like :class:`ModelAdmin`, :class:`AdminSite` provides a :meth:`~django.contrib.admin.ModelAdmin.get_urls()` method that can be overridden to define additional views for the site. To add a new view to your admin site, extend the base :meth:`~django.contrib.admin.ModelAdmin.get_urls()` method to include a pattern for your new view. + +.. note:: + Any view you render that uses the admin templates, or extends the base + admin template, should include in it's context a variable named + ``admin_site`` that contains the name of the :class:`AdminSite` instance. For + :class:`AdminSite` instances, this means ``self.name``; for :class:`ModelAdmin` + instances, this means ``self.admin_site.name``. + +.. _admin-reverse-urls: + +Reversing Admin URLs +==================== + +.. versionadded:: 1.1 + +When an :class:`AdminSite` is deployed, the views provided by that site are +accessible using Django's :ref:`URL reversing system `. + +The :class:`AdminSite` provides the following named URL patterns: + + ====================== =============================== ============= + Page URL name Parameters + ====================== =============================== ============= + Index ``admin_index`` + Logout ``admin_logout`` + Password change ``admin_password_change`` + Password change done ``admin_password_change_done`` + i18n javascript ``admin_jsi18n`` + Application index page ``admin_app_list`` ``app_label`` + ====================== =============================== ============= + +These names will be prefixed with the name of the :class:`AdminSite` instance, +plus an underscore. For example, if your :class:`AdminSite` was named +``custom``, then the Logout view would be served using a URL with the name +``custom_admin_logout``. The default :class:`AdminSite` doesn't use a prefix +in it's URL names. + +Each :class:`ModelAdmin` instance provides an additional set of named URLs: + + ====================== ===================================================== ============= + Page URL name Parameters + ====================== ===================================================== ============= + Changelist ``admin_{{ app_label }}_{{ model_name }}_changelist`` + Add ``admin_{{ app_label }}_{{ model_name }}_add`` + History ``admin_{{ app_label }}_{{ model_name }}_history`` ``object_id`` + Delete ``admin_{{ app_label }}_{{ model_name }}_delete`` ``object_id`` + Change ``admin_{{ app_label }}_{{ model_name }}_change`` ``object_id`` + ====================== ===================================================== ============= + +Again, these names will be prefixed by the name of the :class:`AdminSite` in +which they are deployed. + +So - if you wanted to get a reference to the Change view for a particular +``Choice`` object (from the polls application) in the default admin, you would +call:: + + >>> from django.core import urlresolvers + >>> c = Choice.objects.get(...) + >>> change_url = urlresolvers.reverse('admin_polls_choice_change', (c.id,)) + +However, if the admin instance was named ``custom``, you would need to call:: + + >>> change_url = urlresolvers.reverse('custom_admin_polls_choice_change', (c.id,))