mirror of
https://github.com/django/django.git
synced 2025-08-03 18:38:50 +00:00
Fixed #30573 -- Rephrased documentation to avoid words that minimise the involved difficulty.
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
This commit is contained in:
Tobias Kunze
Mariusz Felisiak
parent
addabc492b
commit
4a954cfd11
149 changed files with 1101 additions and 1157 deletions
|
|
@ -9,7 +9,7 @@ then change it." This works well for a majority of use cases. However, if you
|
|||
need to make the same change to many objects at once, this workflow can be
|
||||
quite tedious.
|
||||
|
||||
In these cases, Django's admin lets you write and register "actions" -- simple
|
||||
In these cases, Django's admin lets you write and register "actions" --
|
||||
functions that get called with a list of objects selected on the change list
|
||||
page.
|
||||
|
||||
|
|
@ -43,7 +43,7 @@ Writing actions
|
|||
The easiest way to explain actions is by example, so let's dive in.
|
||||
|
||||
A common use case for admin actions is the bulk updating of a model. Imagine a
|
||||
simple news application with an ``Article`` model::
|
||||
news application with an ``Article`` model::
|
||||
|
||||
from django.db import models
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ Writing action functions
|
|||
------------------------
|
||||
|
||||
First, we'll need to write a function that gets called when the action is
|
||||
triggered from the admin. Action functions are just regular functions that take
|
||||
triggered from the admin. Action functions are regular functions that take
|
||||
three arguments:
|
||||
|
||||
* The current :class:`ModelAdmin`
|
||||
|
|
@ -89,7 +89,7 @@ request object, but we will use the queryset::
|
|||
|
||||
For the best performance, we're using the queryset's :ref:`update method
|
||||
<topics-db-queries-update>`. Other types of actions might need to deal
|
||||
with each object individually; in these cases we'd just iterate over the
|
||||
with each object individually; in these cases we'd iterate over the
|
||||
queryset::
|
||||
|
||||
for obj in queryset:
|
||||
|
|
@ -138,7 +138,7 @@ That code will give us an admin change list that looks something like this:
|
|||
.. image:: _images/adding-actions-to-the-modeladmin.png
|
||||
|
||||
That's really all there is to it! If you're itching to write your own actions,
|
||||
you now know enough to get started. The rest of this document just covers more
|
||||
you now know enough to get started. The rest of this document covers more
|
||||
advanced techniques.
|
||||
|
||||
Handling errors in actions
|
||||
|
|
@ -159,12 +159,12 @@ advanced options.
|
|||
Actions as :class:`ModelAdmin` methods
|
||||
--------------------------------------
|
||||
|
||||
The example above shows the ``make_published`` action defined as a simple
|
||||
function. That's perfectly fine, but it's not perfect from a code design point
|
||||
of view: since the action is tightly coupled to the ``Article`` object, it
|
||||
makes sense to hook the action to the ``ArticleAdmin`` object itself.
|
||||
The example above shows the ``make_published`` action defined as a function.
|
||||
That's perfectly fine, but it's not perfect from a code design point of view:
|
||||
since the action is tightly coupled to the ``Article`` object, it makes sense
|
||||
to hook the action to the ``ArticleAdmin`` object itself.
|
||||
|
||||
That's easy enough to do::
|
||||
You can do it like this::
|
||||
|
||||
class ArticleAdmin(admin.ModelAdmin):
|
||||
...
|
||||
|
|
@ -180,9 +180,9 @@ Notice first that we've moved ``make_published`` into a method and renamed the
|
|||
``'make_published'`` in ``actions`` instead of a direct function reference. This
|
||||
tells the :class:`ModelAdmin` to look up the action as a method.
|
||||
|
||||
Defining actions as methods gives the action more straightforward, idiomatic
|
||||
access to the :class:`ModelAdmin` itself, allowing the action to call any of the
|
||||
methods provided by the admin.
|
||||
Defining actions as methods gives the action more idiomatic access to the
|
||||
:class:`ModelAdmin` itself, allowing the action to call any of the methods
|
||||
provided by the admin.
|
||||
|
||||
.. _custom-admin-action:
|
||||
|
||||
|
|
@ -208,17 +208,15 @@ performing an action:
|
|||
Actions that provide intermediate pages
|
||||
---------------------------------------
|
||||
|
||||
By default, after an action is performed the user is simply redirected back
|
||||
to the original change list page. However, some actions, especially more
|
||||
complex ones, will need to return intermediate pages. For example, the
|
||||
built-in delete action asks for confirmation before deleting the selected
|
||||
objects.
|
||||
By default, after an action is performed the user is redirected back to the
|
||||
original change list page. However, some actions, especially more complex ones,
|
||||
will need to return intermediate pages. For example, the built-in delete action
|
||||
asks for confirmation before deleting the selected objects.
|
||||
|
||||
To provide an intermediary page, simply return an
|
||||
:class:`~django.http.HttpResponse` (or subclass) from your action. For
|
||||
example, you might write a simple export function that uses Django's
|
||||
:doc:`serialization functions </topics/serialization>` to dump some selected
|
||||
objects as JSON::
|
||||
To provide an intermediary page, return an :class:`~django.http.HttpResponse`
|
||||
(or subclass) from your action. For example, you might write a export function
|
||||
that uses Django's :doc:`serialization functions </topics/serialization>` to
|
||||
dump some selected objects as JSON::
|
||||
|
||||
from django.core import serializers
|
||||
from django.http import HttpResponse
|
||||
|
|
@ -236,7 +234,7 @@ This allows you to provide complex interaction logic on the intermediary
|
|||
pages. For example, if you wanted to provide a more complete export function,
|
||||
you'd want to let the user choose a format, and possibly a list of fields to
|
||||
include in the export. The best thing to do would be to write a small action
|
||||
that simply redirects to your custom export view::
|
||||
that redirects to your custom export view::
|
||||
|
||||
from django.contrib import admin
|
||||
from django.contrib.contenttypes.models import ContentType
|
||||
|
|
@ -247,9 +245,9 @@ that simply redirects to your custom export view::
|
|||
ct = ContentType.objects.get_for_model(queryset.model)
|
||||
return HttpResponseRedirect("/export/?ct=%s&ids=%s" % (ct.pk, ",".join(selected)))
|
||||
|
||||
As you can see, the action is the simple part; all the complex logic would
|
||||
belong in your export view. This would need to deal with objects of any type,
|
||||
hence the business with the ``ContentType``.
|
||||
As you can see, the action is rather short; all the complex logic would belong
|
||||
in your export view. This would need to deal with objects of any type, hence
|
||||
the business with the ``ContentType``.
|
||||
|
||||
Writing this view is left as an exercise to the reader.
|
||||
|
||||
|
|
@ -303,8 +301,7 @@ Disabling a site-wide action
|
|||
site-wide.
|
||||
|
||||
If, however, you need to re-enable a globally-disabled action for one
|
||||
particular model, simply list it explicitly in your ``ModelAdmin.actions``
|
||||
list::
|
||||
particular model, list it explicitly in your ``ModelAdmin.actions`` list::
|
||||
|
||||
# Globally disable delete selected
|
||||
admin.site.disable_action('delete_selected')
|
||||
|
|
@ -323,8 +320,8 @@ Disabling a site-wide action
|
|||
Disabling all actions for a particular :class:`ModelAdmin`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you want *no* bulk actions available for a given :class:`ModelAdmin`, simply
|
||||
set :attr:`ModelAdmin.actions` to ``None``::
|
||||
If you want *no* bulk actions available for a given :class:`ModelAdmin`, set
|
||||
:attr:`ModelAdmin.actions` to ``None``::
|
||||
|
||||
class MyModelAdmin(admin.ModelAdmin):
|
||||
actions = None
|
||||
|
|
|
|||
|
|
@ -83,8 +83,7 @@ Other topics
|
|||
|
||||
The ``ModelAdmin`` class is the representation of a model in the admin
|
||||
interface. Usually, these are stored in a file named ``admin.py`` in your
|
||||
application. Let's take a look at a very simple example of
|
||||
the ``ModelAdmin``::
|
||||
application. Let's take a look at an example of the ``ModelAdmin``::
|
||||
|
||||
from django.contrib import admin
|
||||
from myproject.myapp.models import Author
|
||||
|
|
@ -1195,8 +1194,8 @@ subclass::
|
|||
A read-only field can not only display data from a model's field, it can
|
||||
also display the output of a model's method or a method of the
|
||||
``ModelAdmin`` class itself. This is very similar to the way
|
||||
:attr:`ModelAdmin.list_display` behaves. This provides an easy way to use
|
||||
the admin interface to provide feedback on the status of the objects being
|
||||
:attr:`ModelAdmin.list_display` behaves. This provides a way to use the
|
||||
admin interface to provide feedback on the status of the objects being
|
||||
edited, for example::
|
||||
|
||||
from django.contrib import admin
|
||||
|
|
@ -1742,7 +1741,7 @@ templates used by the :class:`ModelAdmin` views:
|
|||
kwargs['form'] = MySuperuserForm
|
||||
return super().get_form(request, obj, **kwargs)
|
||||
|
||||
You may also simply return a custom :class:`~django.forms.ModelForm` class
|
||||
You may also return a custom :class:`~django.forms.ModelForm` class
|
||||
directly.
|
||||
|
||||
.. method:: ModelAdmin.get_formsets_with_inlines(request, obj=None)
|
||||
|
|
@ -2159,9 +2158,9 @@ return the uncompressed versions of the various JavaScript files, including
|
|||
Adding custom validation to the admin
|
||||
-------------------------------------
|
||||
|
||||
Adding custom validation of data in the admin is quite easy. The automatic
|
||||
admin interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives
|
||||
you the ability define your own form::
|
||||
You can also add custom validation of data in the admin. The automatic admin
|
||||
interface reuses :mod:`django.forms`, and the ``ModelAdmin`` class gives you
|
||||
the ability define your own form::
|
||||
|
||||
class ArticleAdmin(admin.ModelAdmin):
|
||||
form = MyArticleAdminForm
|
||||
|
|
@ -2535,8 +2534,7 @@ layout required for multiple widgets will vary depending on the intermediate
|
|||
model.
|
||||
|
||||
However, we still want to be able to edit that information inline. Fortunately,
|
||||
this is easy to do with inline admin models. Suppose we have the following
|
||||
models::
|
||||
we can do this with inline admin models. Suppose we have the following models::
|
||||
|
||||
from django.db import models
|
||||
|
||||
|
|
@ -2560,7 +2558,7 @@ define an inline class for the ``Membership`` model::
|
|||
model = Membership
|
||||
extra = 1
|
||||
|
||||
This simple example uses the default ``InlineModelAdmin`` values for the
|
||||
This example uses the default ``InlineModelAdmin`` values for the
|
||||
``Membership`` model, and limits the extra add forms to one. This could be
|
||||
customized using any of the options available to ``InlineModelAdmin`` classes.
|
||||
|
||||
|
|
@ -2633,9 +2631,9 @@ specific information.
|
|||
Overriding admin templates
|
||||
==========================
|
||||
|
||||
It is relatively easy to override many of the templates which the admin module
|
||||
uses to generate the various pages of an admin site. You can even override a
|
||||
few of these templates for a specific app, or a specific model.
|
||||
You can override many of the templates which the admin module uses to generate
|
||||
the various pages of an admin site. You can even override a few of these
|
||||
templates for a specific app, or a specific model.
|
||||
|
||||
Set up your projects admin template directories
|
||||
-----------------------------------------------
|
||||
|
|
@ -2732,7 +2730,7 @@ app or per model. The following can:
|
|||
* ``submit_line.html``
|
||||
|
||||
For those templates that cannot be overridden in this way, you may still
|
||||
override them for your entire project. Just place the new version in your
|
||||
override them for your entire project by placing the new version in your
|
||||
``templates/admin`` directory. This is particularly useful to create custom 404
|
||||
and 500 pages.
|
||||
|
||||
|
|
@ -2923,11 +2921,11 @@ Customizing the :class:`AdminSite` class
|
|||
----------------------------------------
|
||||
|
||||
If you'd like to set up your own admin site with custom behavior, you're free
|
||||
to subclass ``AdminSite`` and override or add anything you like. Then, simply
|
||||
create an instance of your ``AdminSite`` subclass (the same way you'd
|
||||
instantiate any other Python class) and register your models and
|
||||
``ModelAdmin`` subclasses with it instead of with the default site. Finally,
|
||||
update :file:`myproject/urls.py` to reference your :class:`AdminSite` subclass.
|
||||
to subclass ``AdminSite`` and override or add anything you like. Then, create
|
||||
an instance of your ``AdminSite`` subclass (the same way you'd instantiate any
|
||||
other Python class) and register your models and ``ModelAdmin`` subclasses with
|
||||
it instead of with the default site. Finally, update :file:`myproject/urls.py`
|
||||
to reference your :class:`AdminSite` subclass.
|
||||
|
||||
.. code-block:: python
|
||||
:caption: myapp/admin.py
|
||||
|
|
@ -3000,9 +2998,9 @@ returns a site instance.
|
|||
Multiple admin sites in the same URLconf
|
||||
----------------------------------------
|
||||
|
||||
It's easy to create multiple instances of the admin site on the same
|
||||
Django-powered website. Just create multiple instances of ``AdminSite`` and
|
||||
root each one at a different URL.
|
||||
You can create multiple instances of the admin site on the same Django-powered
|
||||
website. Create multiple instances of ``AdminSite`` and place each one at a
|
||||
different URL.
|
||||
|
||||
In this example, the URLs ``/basic-admin/`` and ``/advanced-admin/`` feature
|
||||
separate versions of the admin site -- using the ``AdminSite`` instances
|
||||
|
|
|
|||
|
|
@ -55,9 +55,9 @@ Two points to keep in mind:
|
|||
various operations in the change form and we need that to be rendered too.
|
||||
|
||||
Sometimes you'll need to work with ``jQuery`` plugins that are not registered
|
||||
in the ``django.jQuery`` namespace. To do that, simply change how the code
|
||||
listens for events. Instead of wrapping the listener in the ``django.jQuery``
|
||||
namespace, just listen to the event triggered from there. For example:
|
||||
in the ``django.jQuery`` namespace. To do that, change how the code listens for
|
||||
events. Instead of wrapping the listener in the ``django.jQuery`` namespace,
|
||||
listen to the event triggered from there. For example:
|
||||
|
||||
.. code-block:: html+django
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue