Настройка modeladmin

Приложение modeladmin разработано, чтобы предоставить вам максимальную гибкость в том, как ваши модели и их объекты представлены в CMS Wagtail. Эта страница предназначена для предоставления справочной информации, чтобы помочь вам лучше понять возможности приложения и указать правильное направление в зависимости от типа настроек, которые вы хотите внести.

• Класс Wagtail ModelAdmin отличается от Django
• Изменение отображаемого в списке
• Добавление дополнительных стилей и/или JavaScript
• Переопределение шаблонов
• Переопределение представлений
• Переопределение вспомогательных классов

Класс Wagtail ModelAdmin отличается от Django

Класс Wagtail ModelAdmin предназначен для использования аналогично классу Django с тем же именем, и часто использует те же имена атрибутов и методов для достижения аналогичных результатов. Однако есть несколько ключевых отличий:

Формы добавления и редактирования всё ещё определяются panels и edit_handlers

В Wagtail контроль над отображаемыми полями в формах добавления/редактирования для ваших Model, а также определение их группировки и упорядочивания, достигается путём добавления атрибута panels или edit_handler к вашему классу Model. Это остаётся неизменным, независимо от того, является ли ваша модель типом Page, сниппетом или стандартной Django-моделью Model. Из-за этого класс Wagtail ModelAdmin в основном отвечает за настройку списка. Например, атрибуты list_display, list_filter и search_fields присутствуют и поддерживают в основном те же значения, что и класс Django ModelAdmin, в то время как fields, fieldsets, exclude и другие атрибуты, которые вы могли использовать для настройки представлений добавления/редактирования Django, просто не поддерживаются версией Wagtail.

Модели «типов страниц» необходимо обрабатывать по-другому, чем другие модели

Хотя список представлений modeladmin и поддерживаемые параметры настройки работают одинаково для всех типов Model, в отношении других представлений управления обработка отличается в зависимости от того, представляет ли ваш класс ModelAdmin модель типа страницы (которая расширяет wagtailcore.models.Page) или нет.

Страницы в Wagtail имеют уникальные свойства и требуют дополнительных представлений, элементов интерфейса и общей обработки для эффективного управления. Например, они имеют древовидную структуру, которую необходимо надлежащим образом сохранять при добавлении, удалении и перемещении страниц. У них также есть система ревизий, свои собственные соображения по разрешениям и возможность предварительного просмотра изменений перед сохранением. Из-за этой дополнительной сложности Wagtail предоставляет свои собственные специальные представления для управления любыми пользовательскими типами страниц, которые вы можете добавить в свой проект (вне зависимости от того, создаёте ли вы для них класс ModelAdmin или нет).

Для обеспечения согласованного пользовательского опыта modeladmin просто перенаправляет пользователей на существующие представления управления страницами Wagtail, где это возможно. Вы должны помнить об этом, если когда-либо захотите изменить то, что происходит при добавлении, удалении, публикации страниц определённого типа или применении к ним каких-либо других действий. Настройка CreateView или EditView для вашего типа страницы Model (даже просто для добавления дополнительного файла стилей или JavaScript) не повлияет, так как эти представления не используются.

Если вам всё же потребуется настроить добавление, редактирование или другое поведение модели типа страницы, обратите внимание на следующий раздел документации: Плагины.

Класс Wagtail ModelAdmin «модульный»

В отличие от класса Django с тем же именем, ModelAmin wagtailadmin действует в основном как «контроллер». Хотя у него есть набор атрибутов и методов, позволяющих настроить, как различные компоненты должны обрабатывать вашу модель, он намеренно спроектирован так, чтобы выполнять как можно меньше работы самостоятельно; вся реальная работа передаётся наборам отдельных, взаимозаменяемых компонентов.

Теория заключается в следующем: если вы хотите сделать что-то по-другому или добавить некоторую функциональность, которой modeladmin ещё не обладает, вы можете создать новые классы (или расширить предоставленные modeladmin) и легко настроить свой класс ModelAdmin для использования их вместо стандартных.

• Узнайте больше о переопределении представлений
• Узнайте больше о переопределении вспомогательных классов

Изменение отображаемого в списке

Вы должны ознакомиться с атрибутами и методами, поддерживаемыми классом ModelAdmin, которые позволяют изменять отображаемое в списке IndexView. Следующая страница предоставит вам всё необходимое для начала работы: Настройка IndexView — представления списка

Добавление дополнительных стилей и/или JavaScript

Класс ModelAdmin предоставляет несколько атрибутов, которые позволяют легко добавлять дополнительные стили и JavaScript в интерфейс администрирования для вашей модели. Каждый атрибут просто должен быть списком путей к файлам, которые вы хотите включить. Если путь относится к файлу в каталоге static вашего проекта, Wagtail автоматически добавит к пути STATIC_URL, поэтому вам не нужно повторять его каждый раз в списке путей.

Если вы хотите добавить стили или скрипты в IndexView, вы должны установить следующие атрибуты:

• index_view_extra_css — где каждый элемент — имя пути предварительно скомпилированного файла стилей, который вы хотите включить.
• index_view_extra_js — где каждый элемент — имя пути к файлу JavaScript, который вы хотите включить.

Если вы хотите сделать то же самое для CreateView и EditView, вы должны установить следующие атрибуты:

• form_view_extra_css — где каждый элемент — имя пути предварительно скомпилированного файла стилей, который вы хотите включить.
• form_view_extra_js — где каждый элемент — имя пути к файлу JavaScript, который вы хотите включить.

И если вы используете InspectView для вашей модели и хотите сделать то же самое для этого представления, вы должны установить следующие атрибуты:

• inspect_view_extra_css — где каждый элемент — имя пути предварительно скомпилированного файла стилей, который вы хотите включить.
• inspect_view_extra_js — где каждый элемент — имя пути к файлу JavaScript, который вы хотите включить.

Переопределение шаблонов

Для всех представлений modeladmin Wagtail ищет шаблоны в следующих папках вашего проекта или приложения, прежде чем использовать стандартные:

1. templates/modeladmin/app-name/model-name/
2. templates/modeladmin/app-name/
3. templates/modeladmin/

Таким образом, чтобы переопределить шаблон, используемый, например, IndexView, вам нужно создать новый шаблон index.html и поместить его в одно из этих мест. Например, если вы хотите сделать это для модели ArticlePage в приложении news, вы добавите свой пользовательский шаблон как news/templates/modeladmin/news/articlepage/index.html.

Для справки, modeladmin ищет шаблоны с следующими именами для каждого представления:

• 'index.html' для IndexView
• 'inspect.html' для InspectView
• 'create.html' для CreateView
• 'edit.html' для EditView
• 'delete.html' для DeleteView
• 'choose_parent.html' для ChooseParentView

Чтобы добавить дополнительную информацию в блок одного из вышеуказанных шаблонов Wagtail, используйте Django {{ block.super }} внутри {% block ... %} , который вы хотите расширить. Например, если вы хотите отобразить изображение в форме редактирования под полями редактируемой модели, вы можете сделать следующее:

{% extends "modeladmin/edit.html" %}
{% load static %}

{% block content %}
    {{ block.super }}
    <div class="object">
        <img src="{% get_media_prefix %}{{ instance.image }}"/>
    </div>
{% endblock %}

Если по какой-либо причине вам нужно обойти это поведение и явно указать шаблон для определённого представления, вы можете установить один из следующих атрибутов в своём классе ModelAdmin:

• index_template_name для указания шаблона для IndexView
• inspect_template_name для указания шаблона для InspectView
• create_template_name для указания шаблона для CreateView
• edit_template_name для указания шаблона для EditView
• delete_template_name для указания шаблона для DeleteView
• choose_parent_template_name для указания шаблона для ChooseParentView

Переопределение представлений

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

• index_view_class
• inspect_view_class
• create_view_class (не используется для моделей «типов страниц»)
• edit_view_class (не используется для моделей «типов страниц»)
• delete_view_class (не используется для моделей «типов страниц»)
• choose_parent_view_class (используется только для моделей «типов страниц»)

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

from wagtail.contrib.modeladmin.views import IndexView
from wagtail.contrib.modeladmin.options import ModelAdmin
from .models import MyModel

class MyCustomIndexView(IndexView):
    # New functionality and existing method overrides added here
    ...


class MyModelAdmin(ModelAdmin):
    model = MyModel
    index_view_class = MyCustomIndexView

Или, если вам не нужна ни одна из функций IndexView в вашем представлении, и вы предпочитаете создать своё представление с нуля, modeladmin также поддерживает это. Однако настоятельно рекомендуется использовать modeladmin.views.WMABaseView в качестве основы для вашего представления. Это значительно упростит интеграцию с вашим классом ModelAdmin, предоставив множество полезных атрибутов и методов для начала работы.

Вы также можете использовать url_helper для лёгкого обратного преобразования URL-адресов для любого ModelAdmin, см. Обратное преобразование URL-адресов ModelAdmin.

Переопределение вспомогательных классов

Хотя «классы представлений» отвечают за большую часть работы, существует ряд других задач, которые modeladmin должен регулярно выполнять, требующих согласованного и многократного решения. Эти задачи назначены набору простых классов (в modeladmin, они называются «вспомогательными» классами) и могут быть найдены в wagtail.contrib.modeladmin.helpers.

Если вы планируете создавать и использовать собственные пользовательские представления с modeladmin, вам следует ознакомиться с этими вспомогательными классами, так как они доступны для представлений через представление modeladmin.views.WMABaseView.

Существует три типа «вспомогательного класса»:

• Вспомогательные классы URL - которые помогают с согласованным генерированием, именованием и ссылкой на URL-адреса.
• Вспомогательные классы разрешений - которые помогают гарантировать, что только пользователи с достаточными правами могут выполнять определённые действия или видеть варианты выполнения этих действий.
• Вспомогательные классы кнопок - которые, при помощи двух других, помогают генерировать кнопки для использования в нескольких местах.

Класс ModelAdmin позволяет определять и использовать свои собственные вспомогательные классы, задавая значения следующим атрибутам:

ModelAdmin.url_helper_class

По умолчанию используется класс modeladmin.helpers.url.PageAdminURLHelper, если ваш модель расширяет wagtailcore.models.Page, в противном случае используется modeladmin.helpers.url.AdminURLHelper.

Если вы обнаружите, что вышеперечисленные вспомогательные классы не подходят для ваших нужд, вы можете легко создать свой собственный вспомогательный класс, унаследовав от AdminURLHelper или PageAdminURLHelper (если ваша модель расширяет модель Wagtail’s Page), и внеся необходимые дополнения/переопределения.

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

from wagtail.contrib.modeladmin.helpers import AdminURLHelper
from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
from .models import MyModel


class MyURLHelper(AdminURLHelper):
    ...


class MyModelAdmin(ModelAdmin):
    model = MyModel
    url_helper_class = MyURLHelper

modeladmin_register(MyModelAdmin)

Или, если у вас более сложный случай использования, когда простое задание этого атрибута невозможно (например, из-за циклических импортов) или не удовлетворяет ваши потребности, вы можете переопределить метод get_url_helper_class, как показано ниже:

class MyModelAdmin(ModelAdmin):
    model = MyModel

    def get_url_helper_class(self):
        if self.some_attribute is True:
            return MyURLHelper
        return AdminURLHelper

ModelAdmin.permission_helper_class

По умолчанию используется класс modeladmin.helpers.permission.PagePermissionHelper, если ваша модель расширяет wagtailcore.models.Page, в противном случае используется modeladmin.helpers.permission.PermissionHelper.

Если вы обнаружите, что вышеперечисленные вспомогательные классы не подходят для ваших нужд, вы можете легко создать свой собственный вспомогательный класс, унаследовав от PermissionHelper (или PagePermissionHelper, если ваша модель расширяет модель Wagtail’s Page), и внести необходимые дополнения/переопределения. После определения задайте атрибут permission_helper_class в вашем классе ModelAdmin, чтобы использовать ваш пользовательский класс вместо стандартного, как показано ниже:

from wagtail.contrib.modeladmin.helpers import PermissionHelper
from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
from .models import MyModel


class MyPermissionHelper(PermissionHelper):
    ...


class MyModelAdmin(ModelAdmin):
    model = MyModel
    permission_helper_class = MyPermissionHelper

modeladmin_register(MyModelAdmin)

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

class MyModelAdmin(ModelAdmin):
    model = MyModel

    def get_permission_helper_class(self):
        if self.some_attribute is True:
            return MyPermissionHelper
        return PermissionHelper

ModelAdmin.button_helper_class

По умолчанию используется класс modeladmin.helpers.button.PageButtonHelper, если ваша модель расширяет wagtailcore.models.Page, в противном случае используется modeladmin.helpers.button.ButtonHelper.

Если вы хотите добавить или изменить кнопки для страницы IndexView вашей модели, вам нужно создать свой собственный класс вспомогательных кнопок, унаследовав от ButtonHelper или PageButtonHelper (если ваша модель расширяет модель Wagtail’s Page), и внести необходимые дополнения/переопределения. После определения задайте атрибут button_helper_class в вашем классе ModelAdmin, чтобы использовать ваш пользовательский класс вместо стандартного, как показано ниже:

from wagtail.contrib.modeladmin.helpers import ButtonHelper
from wagtail.contrib.modeladmin.options import ModelAdmin, modeladmin_register
from .models import MyModel


class MyButtonHelper(ButtonHelper):
    def add_button(self, classnames_add=None, classnames_exclude=None):
        if classnames_add is None:
            classnames_add = []
        if classnames_exclude is None:
            classnames_exclude = []
        classnames = self.add_button_classnames + classnames_add
        cn = self.finalise_classname(classnames, classnames_exclude)
        return {
            'url': self.url_helper.create_url,
            'label': _('Add %s') % self.verbose_name,
            'classname': cn,
            'title': _('Add a new %s') % self.verbose_name,
        }

    def inspect_button(self, pk, classnames_add=None, classnames_exclude=None):
        ...

    def edit_button(self, pk, classnames_add=None, classnames_exclude=None):
        ...

    def delete_button(self, pk, classnames_add=None, classnames_exclude=None):
        ...


class MyModelAdmin(ModelAdmin):
    model = MyModel
    button_helper_class = MyButtonHelper

modeladmin_register(MyModelAdmin)

Чтобы настроить кнопки, отображаемые в представлении списка ModelAdmin, вы можете изменить возвращаемый словарь в методах add_button, delete_button, edit_button или inspect_button. Например, если вы хотите изменить кнопку Delete, вы можете изменить метод delete_button в вашем классе ButtonHelper, как показано ниже:

class MyButtonHelper(ButtonHelper):
    ...
    def delete_button(self, pk, classnames_add=None, classnames_exclude=None):
        ...
        return {
            'url': reverse("your_custom_url"),
            'label': _('Delete'),
            'classname': "custom-css-class",
            'title': _('Delete this item')
        }

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

class MyModelAdmin(ModelAdmin):
    model = MyModel

    def get_button_helper_class(self):
        if self.some_attribute is True:
            return MyButtonHelper
        return ButtonHelper

Использование помощников в пользовательских представлениях

Если вы наследуете от modeladmin.views.WMABaseView (или одного из более «специфичных» классов представления), чтобы создать пользовательское представление, экземпляры каждого помощника должны быть доступны в экземплярах вашего класса, как:

• self.url_helper
• self.permission_helper
• self.button_helper

В отличие от двух других, self.button_helper не заполняется сразу при создании представления. Для отображения правильных кнопок для правильных пользователей экземпляры ButtonHelper должны быть «осознающими запрос», поэтому self.button_helper устанавливается только после выполнения метода dispatch() представления, который принимает объект HttpRequest в качестве аргумента, позволяющего идентифицировать текущего пользователя.