Действия администратора

Написание функций действий

Сначала нужно написать функцию, которая будет вызываться при запуске действия в панели администратора. Функции действий — это обычные функции, принимающие три аргумента:

• Текущий ModelAdmin
• HttpRequest, представляющий текущий запрос,
• QuerySet, содержащий набор объектов, выбранных пользователем.

Для нашей функции публикации статей не понадобятся ни ModelAdmin, ни объект запроса, но мы воспользуемся набором запросов:

def make_published(modeladmin, request, queryset):
    queryset.update(status="p")

for obj in queryset:
    do_something_with(obj)

Вот и всё, что нужно для написания действия! Однако сделаем ещё один необязательный, но полезный шаг и зададим для действия «красивое» название в панели администратора. По умолчанию это действие появилось бы в списке под названием «Make published» — именем функции, в котором символы подчёркивания заменены пробелами. Это вполне допустимо, но можно задать более понятное название с помощью декоратора action() для функции make_published:

from django.contrib import admin

...


@admin.action(description="Mark selected stories as published")
def make_published(modeladmin, request, queryset):
    queryset.update(status="p")

Добавление действий в ModelAdmin

Теперь нужно сообщить нашему ModelAdmin о действии. Это делается так же, как и для любого другого параметра конфигурации. Таким образом, полная admin.py с действием и его регистрацией будет выглядеть так:

from django.contrib import admin
from myapp.models import Article


@admin.action(description="Mark selected stories as published")
def make_published(modeladmin, request, queryset):
    queryset.update(status="p")


class ArticleAdmin(admin.ModelAdmin):
    list_display = ["title", "status"]
    ordering = ["title"]
    actions = [make_published]


admin.site.register(Article, ArticleAdmin)

Этот код создаст список изменений в панели администратора, который будет выглядеть примерно так:

Вот и всё! Если вы хотите написать собственные действия, теперь у вас есть всё необходимое, чтобы приступить к работе. В оставшейся части этого документа рассматриваются более продвинутые приёмы.

Обработка ошибок в действиях

Если при выполнении действия могут возникнуть предсказуемые ошибки, следует корректно сообщить пользователю о проблеме. Для этого нужно обработать исключения и использовать django.contrib.admin.ModelAdmin.message_user(), чтобы вывести в ответе понятное пользователю описание проблемы.

Действия как методы ModelAdmin

В приведённом выше примере действие make_published определено как функция. Это вполне допустимо, но не идеально с точки зрения проектирования кода: поскольку действие тесно связано с объектом Article, имеет смысл привязать его непосредственно к объекту ArticleAdmin.

Это можно сделать так:

class ArticleAdmin(admin.ModelAdmin):
    ...

    actions = ["make_published"]

    @admin.action(description="Mark selected stories as published")
    def make_published(self, request, queryset):
        queryset.update(status="p")

Обратите внимание: во-первых, мы перенесли make_published в метод и переименовали параметр modeladmin в self; во-вторых, теперь мы поместили строку 'make_published' в actions вместо прямой ссылки на функцию. Это указывает ModelAdmin, что действие нужно искать как метод.

Определение действий в виде методов обеспечивает более идиоматичный доступ к самому ModelAdmin и позволяет действию вызывать любые методы, предоставляемые панелью администратора.

Например, с помощью self можно вывести пользователю сообщение об успешном выполнении действия:

from django.contrib import messages
from django.utils.translation import ngettext


class ArticleAdmin(admin.ModelAdmin):
    ...

    def make_published(self, request, queryset):
        updated = queryset.update(status="p")
        self.message_user(
            request,
            ngettext(
                "%d story was successfully marked as published.",
                "%d stories were successfully marked as published.",
                updated,
            )
            % updated,
            messages.SUCCESS,
        )

В результате действие будет вести себя так же, как и сама панель администратора после успешного выполнения действия:

Действия с промежуточными страницами

По умолчанию после выполнения действия пользователь перенаправляется обратно на исходную страницу списка изменений. Однако для некоторых действий, особенно более сложных, потребуется вернуть промежуточную страницу. Например, встроенное действие удаления запрашивает подтверждение перед удалением выбранных объектов.

Чтобы показать промежуточную страницу, верните из действия объект HttpResponse (или его подкласс). Например, можно написать функцию экспорта, которая использует функции сериализации Django, чтобы выгрузить некоторые выбранные объекты в формате JSON:

from django.core import serializers
from django.http import HttpResponse


def export_as_json(modeladmin, request, queryset):
    response = HttpResponse(content_type="application/json")
    serializers.serialize("json", queryset, stream=response)
    return response

Как правило, приведённый выше подход не считается удачным решением. Чаще всего лучше вернуть HttpResponseRedirect и перенаправить пользователя на созданное вами представление, передав список выбранных объектов в строке GET-запроса. Это позволяет реализовать сложную логику взаимодействия на промежуточных страницах. Например, если вы хотите сделать более полноценную функцию экспорта, следует предоставить пользователю возможность выбрать формат и, возможно, список полей для включения в экспорт. Лучше всего написать небольшое действие, которое перенаправляет пользователя в ваше представление экспорта:

from django.contrib.contenttypes.models import ContentType
from django.http import HttpResponseRedirect


def export_selected_objects(modeladmin, request, queryset):
    selected = queryset.values_list("pk", flat=True)
    ct = ContentType.objects.get_for_model(queryset.model)
    return HttpResponseRedirect(
        "/export/?ct=%s&ids=%s"
        % (
            ct.pk,
            ",".join(str(pk) for pk in selected),
        )
    )

Как видите, действие довольно короткое; вся сложная логика будет находиться в представлении экспорта. Оно должно обрабатывать объекты любых типов, поэтому здесь и используется ContentType.

Написание этого представления оставляем в качестве упражнения для читателя.

Доступность действий на всём сайте

AdminSite.add_action(action, name=None) [исходный код]

Некоторые действия полезно сделать доступными для любых объектов на сайте администратора — например, описанное выше действие экспорта. Сделать действие доступным глобально можно с помощью AdminSite.add_action(). Например:

from django.contrib import admin

admin.site.add_action(export_selected_objects)

Так действие export_selected_objects станет доступно глобально под именем «export_selected_objects». Можно явно задать имя действия — это удобно, если позже вы захотите программно удалить действие, — передав второй аргумент в AdminSite.add_action():

admin.site.add_action(export_selected_objects, "export_selected")

Отключение действий

Иногда нужно отключить определённые действия — особенно те, которые зарегистрированы на всём сайте, — для отдельных объектов. Есть несколько способов отключить действия:

class MyModelAdmin(admin.ModelAdmin):
    actions = None

Настройка разрешений для действий

Действия можно сделать доступными только пользователям с определёнными разрешениями, обернув функцию действия декоратором action() и передав аргумент permissions:

@admin.action(permissions=["change"])
def make_published(modeladmin, request, queryset):
    queryset.update(status="p")

Действие make_published() будет доступно только пользователям, прошедшим проверку ModelAdmin.has_change_permission().

Если в permissions указано несколько разрешений, действие будет доступно, если пользователь пройдёт хотя бы одну из проверок.

Допустимые значения permissions и соответствующие проверки методов:

• 'add': ModelAdmin.has_add_permission()
• 'change': ModelAdmin.has_change_permission()
• 'delete': ModelAdmin.has_delete_permission()
• 'view': ModelAdmin.has_view_permission()

Можно указать любое другое значение, если вы реализуете соответствующий метод has_<value>_permission(self, request) в ModelAdmin.

Например:

from django.contrib import admin
from django.contrib.auth import get_permission_codename


class ArticleAdmin(admin.ModelAdmin):
    actions = ["make_published"]

    @admin.action(permissions=["publish"])
    def make_published(self, request, queryset):
        queryset.update(status="p")

    def has_publish_permission(self, request):
        """Does the user have the publish permission?"""
        opts = self.opts
        codename = get_permission_codename("publish", opts)
        return request.user.has_perm("%s.%s" % (opts.app_label, codename))