Создание функций для действий¶

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

• Экземпляр класса ModelAdmin,

• Экземпляр класса HttpRequest, представляющий текущий запрос,

• Экземпляр класса QuerySet, содержащий набор объектов, которые выделил пользователь.

Наша функция «опубликовать-эти-статьи» не нуждается в экземпляре ModelAdmin или в объекте реквеста, но использует выборку:

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

for obj in queryset:
    do_something_with(obj)

That’s actually all there is to writing an action! However, we’ll take one more optional-but-useful step and give the action a «nice» title in the admin. By default, this action would appear in the action list as «Make published» – the function name, with underscores replaced by spaces. That’s fine, but we can provide a better, more human-friendly name by giving the make_published function a short_description attribute:

def make_published(modeladmin, request, queryset):
    queryset.update(status='p')
make_published.short_description = "Mark selected stories as published"

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

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

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

def make_published(modeladmin, request, queryset):
    queryset.update(status='p')
make_published.short_description = "Mark selected stories as published"

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']

    def make_published(self, request, queryset):
        queryset.update(status='p')
    make_published.short_description = "Mark selected stories as published"

Следует отметить, что сначала мы переместили 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

Установка разрешений на действия¶

Actions may limit their availability to users with specific permissions by setting an allowed_permissions attribute on the action function:

def make_published(modeladmin, request, queryset):
    queryset.update(status='p')
make_published.allowed_permissions = ('change',)

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

If allowed_permissions has more than one permission, the action will be available as long as the user passes at least one of the checks.

Available values for allowed_permissions and the corresponding method checks are:

• 'add': ModelAdmin.has_add_permission()

• 'change': ModelAdmin.has_change_permission()

• 'удалить': 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']

    def make_published(self, request, queryset):
        queryset.update(status='p')
    make_published.allowed_permissions = ('publish',)

    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))