Learn web development

Руководство Django часть 4: административная панель Django

В процессе перевода.

и

Теперь, когда модели для сайта местной библиотеки созданы, добавим некоторые "настоящие" данные о книгах, используя административную панель Django Admin. Для начала мы покажем, как зарегистрировать в ней модели, потом как войти и создать какие-нибудь данные. В конце статьи мы покажем некоторые способы дальнейшего улучшения вида админ-панели.

Предусловия: Сначала выполните: Руководство часть 3: использование моделей.
Цель:

Уяснить преимущества и ограничения админ-панели Django, научиться использовать её для создания записей для наших моделей.

Обзор

Приложение Django admin может использовать ваши модели для автоматического создания части сайта, предназначенной для создания, просмотра, обновления и удаления записей. Это может сэкономить вам много времени в процессе разработки, упрощая тестирование ваших моделей на предмет правильности данных. Оно также может быть полезным для управления данными на стадии публикации, в зависимости от типа веб-сайта. Проект Django рекомендует это приложение только для управления внутренними данными (т.е.для использования администраторами, либо людьми внутри вашей организации), так как модельно-ориентированный подход не обязательно является наилучшим интерфейсом для всех пользователей и раскрывает много лишних подробностей о моделях.

Все необходимые настройки, которые необходимо включить  в admin приложение вашего веб-сайта, были сделаны автоматически, когда вы создали каркас проекта ( информацию о необходимых актуальных зависимостях смотрите здесь -  Django docs) . В результате все, что необходимо сделать для того, чтобы добавить модели в приложение admin, это зарегистрировать их. В конце этой статьи мы представим краткую демонстрацию того, каким образом  можно дополнительно настроить админ-панель для лучшего отображения данные наших моделей.

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

Регистрация моделей 

Вначале откройте файл admin.py в папке приложения (/locallibrary/catalog/admin.py). Пока он выглядит так (заметьте, что он уже содержит импорт  django.contrib.admin):

from django.contrib import admin

# Register your models here.

Зарегистрируйте модели путем вставки следующего текста в нижнюю часть этого файла. Этот код просто импортирует модели и затем вызывает  admin.site.register для регистрации каждой из них.

from .models import Author, Genre, Book, BookInstance

admin.site.register(Book)
admin.site.register(Author)
admin.site.register(Genre)
admin.site.register(BookInstance)
Примечание: Если вы приняли участие в создании модели для представления естественного языка книги (см. обучающую статью о моделях), импортируйте и зарегистрируйте её тоже!

Это самый простой способ регистрации модели или моделей. Админ-панель имеет множество настроек. Мы рассмотрим другие способы регистрации ваших моделей ниже.

Создание суперпользователя

Для того, чтобы войти в админ-панель, нам необходимо иметь учетную запись пользователя со статусом Staff (сотрудники). Для просмотра и создания записей, пользователю также понадобится разрешение для управления всеми нашими объектами. Вы можете создать учетную запись  "superuser", которая дает полный доступ к сайту и все необходимые разрешения, используя manage.py.

Для создания суперпользователя вызовите следующую команду из той же папки, где расположен manage.py. Вас попросят ввести имя пользователя, адрес электронной почты и надежный пароль. 

python3 manage.py createsuperuser

После выполнения этой команды новый суперпользователь будет добавлен в базу данных. Теперь перезапустите сервер, чтобы можно было протестировать вход на сайт:

python3 manage.py runserver

Вход в админ-панель и ее использование

Для входа в админ-панель откройте ссылку /admin (например  http://127.0.0.1:8000/admin) и введите логин и пароль вашего нового суперпользователя  (вас перенаправят на login-страницу и потом обратно на /admin после ввода всех деталей).

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

Admin Site - Home page

Кликните на ссылке Add справа от Books, чтобы создать новую книгу (появится диалоговое окно как на картинке внизу). Заметьте, что заголовок каждого поля - это тип используемого виджета, и    help_text (если есть) совпадаетс со значением, которое вы указали в модели. 

Введите значение для полей. Вы можете создавать новых авторов или жанры, нажимая на значок "+ ", расположенный рядом с соответствующим полем (или выберите существующее значение из списков, если вы уже создали их). Когда вы закончили, нажмите на SAVE,  Save and add another, или Save and continue editing, чтобы сохранить записи.

Admin Site - Book Add

Примечание: А сейчас, хотелось бы, что бы вы добавили несколько книг, авторов и жанров (например,  Фэнтези) в ваше приложение. Удостоверьтесь, что каждый автор и жанр включает пару различных книг (позже, когда мы реализуем представления "list" и "detail", это сделает их более интересными).

После того, когда книги добавлены, для перехода на главную страницу админ-панели кликните на ссылке Home в верхней части страницы. Потом кликните на ссылке Books для отображения текущего списка книг (или на одной из других ссылок, чтобы увидеть список соответствующей модели). После добавления нескольких книг список может выглядеть наподобие скриншота ниже.  Отображается название каждой из книг. Его возвращает метод __str__() в модели Book, созданной в предыдущей статье.

Admin Site - List of book objects

Для удаления книги из этого списка выберите чекбокс рядом с ней и действие delete...  из выпадающего списка Action, а затем нажмите кнопку Go. Также можно добавить новую книгу, нажав на кнопку ADD BOOK

Вы можете редактировать книгу, кликнув по ссылке с ее названием. Страница редактирования книги, приведенная ниже, практически идентична странице добавления новой книги. Основные отличия - это заголовок страницы (Change book) и наличие кнопок Delete, HISTORY и VIEW ON SITE.  Последняя присутствует, така как мы определили метод get_absolute_url() в нашей модели.

Admin Site - Book Edit

Теперь перейдите назад на страницу Home (используя ссылку Home в навигационной цепочке вверху страницы) и просмотрите списки Author и Genre. В них уже должно быть несколько элементов, созданных при добавлении новых книг. Если хотите, добавьте еще.

Однако у вас не будет ни одного экземпляра книги, потому что они не создаются из модели Book (хотя можно создать книгу из модели BookInstance — такова природа поля ForeignKey). Для отображения страницы Add book instance (см. рисунок ниже) вернитесь на страницу Home  и нажмите кнопку Add. Обратите внимание на длинный уникальный Id для идентификации конкретного экземпляра книги в библиотеке.

Admin Site - BookInstance Add

Создайте несколько экземпляров для каждой из ваших книг. Установите статус Available (доступен) для некоторых экземплров и On loan (выдан) для остальных. Если статус экземпляра not Available (недоступен), то также установите дату возврата (Due back).

Вот и все!  Вы изучили как запустить и использовать админ-панель. Также были созданы записи для Book, BookInstance, Genre и Author, которые можно будет использовать после создания наших собственных представлений и шаблонов.

"Продвинутая" конфигурация

Django выполняет неплохую работу по созданию базовой админ-панели используя информацию из зарегистрированых моделей:

  • каждая модель имеет список записей, каждая из которых идентифицируется строкой, создаваемой методом __str__() модели, и связана с представлением для ее редактирования. По умолчанию, в верхней части этого представления находится меню действий, которое может быть использовано для удаления нескольких записей за раз
  • Формы для редактирования и добавления записей содержат все поля модели, которые расположены вертикально в порядке их объявления в модели.  

Можно настроить интерфейс пользователя для упрощения его использования. Некоторые доступные настройки:

  • List views: 
    • добавление дополнительных отображаемых полей или информации для каждой записи. 
    • добавление фильтров для отбора записей по разным критериям (например, статус выдачи книги).
    • добавление дополнительных вариантов выбора в меню действий и места расположения этого меню на форме.
  • Detail views
    • выбор отображаемых полей, их порядка, группирования и т.д. 
    • добавление связанных полей к записи  (например, возможности добавления и редактирования записей книг при создании записи автора).

В этом разделе рассмотрим некоторые изменения для совершенствования интерфейса пользователя нашей местной библиотеки, а именно: добавление дополнительной информации в списки моделей Book и Author ,  а также улучшение расположения элементов соответствующих представлений редактирования. Пользовательский интерфейс моделей Language and Genre изменять не будем, так как это не даст заметного улучшения, поскольку он содержит только по одному полю!

Полное руководство по всем возможным вариантам настройки админ-панели можно найти в The Django Admin site (документация Django).

Регистрация класса ModelAdmin

Для измененения отображения модели в пользовательском интерфейсе админ-панели, необходимо определить класс ModelAdmin  (он описывает расположение элементов интерфейса, где Model - наименование модели) и зарегистрировать его для использования с этой моделью.

Давайте начнем с модели Author. Откройте файл admin.py в каталоге приложения (/locallibrary/catalog/admin.py). Закомментируйте исходную регистрацию (используя префикс #) этой модели:

# admin.site.register(Author)

Теперь добавьте новый класс AuthorAdmin и зарегистрируйте его как показано ниже:

# Define the admin class
class AuthorAdmin(admin.ModelAdmin):
    pass

# Register the admin class with the associated model
admin.site.register(Author, AuthorAdmin)

Сейчас мы добавим классы ModelAdmin для моделей Book  BookInstance. Нам снова нужно закомментировать исходную регистрацию:

#admin.site.register(Book)
#admin.site.register(BookInstance)

В этот раз для создания и регистрации новых моделей используем декоратор  @register (он делает то же самое, что и метод admin.site.register()):

# Register the Admin classes for Book using the decorator

@admin.register(Book)
class BookAdmin(admin.ModelAdmin):
    pass

# Register the Admin classes for BookInstance using the decorator

@admin.register(BookInstance) 
class BookInstanceAdmin(admin.ModelAdmin):
    pass

Пока что все наши admin-классы пустые (см. "pass"), поэтому ничего не изменится ! Добавим код для задания особенностей интерфейса моделей.

Настройка отображения списков

Сейчас приложение LocalLibrary отображает всех авторов, используя имя объекта, возвращаемое методом __str__() модели. Это приемлемо, когда есть только несколько авторов, но, если их количество значительно, возможны дубликаты. Чтобы различить их или просто отобразить более интересную информацию о каждом авторе, можно использовать list_display (для добавления дополнительных полей). 

Замените класс AuthorAdmin кодом, приведенным ниже. Названия полей, которые будут отображаться в списке, перечислены в кортеже list_display в требуемом порядке  (это те же имена, что и в исходной модели).

class AuthorAdmin(admin.ModelAdmin):
    list_display = ('last_name', 'first_name', 'date_of_birth', 'date_of_death')

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

Admin Site - Improved Author List

Для нашей модели Book добавим отображение полей author и genre. Поле author  - это  внешний ключ (ForeignKey ) связи один к одному, поэтому оно будет представлено значением __str()__  для связанной записи. Замените класс BookAdmin на версию, приведенную ниже.

class BookAdmin(admin.ModelAdmin):
    list_display = ('title', 'author', 'display_genre')

К сожалению, мы не можем напрямую поместить поле genre в list_display, так как оно является  ManyToManyField (Django не позволяет это из-за большой "стоимости" доступа к базе данных). Вместо этого мы определим функцию display_genre для получения строкового представления информации (вызов этой функции есть в list_display,  ее определение см. ниже).

Примечание: Получение здесь значения поля genre возможно не самая хорошая идея вследствие "стоимости" операции базы данных. Мы показываем это, потому что вызов функций в ваших моделях может быть очень полезен по другим причинам, например, для добавления ссылки  Delete рядом с каждым пунктом списка.

Добавьте следующий код в вашу модель Book (models.py). В нем создается строка из первых трех значений поля genre (если они существуют) и short_description,  которое может быть использовано в админ-панели.

    def display_genre(self):
        """
        Creates a string for the Genre. This is required to display genre in Admin.
        """
        return ', '.join([ genre.name for genre in self.genre.all()[:3] ])
    display_genre.short_description = 'Genre'

После сохранения модели и обновления админ-панели перезапустите ее и перейдите на страницу списка Books. Вы должны увидеть список книгу, наподобие приведенного ниже:

Admin Site - Improved Book List

Модель Genre (и модель Language, если вы ее определили) имеет единственное поле. Поэтому нет необходимости создания для них дополнительных моделей с целью отображения дополнительных полей.

Примечание: целесообразно, чтобы в списке модели BookInstance отображались хотя бы статус и ожидаемая дата возврата. Мы добавили это в качестве "мспытания" в конце этой статьи!

Добавление фильтров списка

Если в вашем списке есть множество элементов, может быть полезной возможность фильтрации отображаемых пунктов. Это выполняется путем перечисления их в атрибуте list_filter. Замените класс BookInstanceAdmin на следующий:

class BookInstanceAdmin(admin.ModelAdmin):
    list_filter = ('status', 'due_back')

Представление списка теперь будет содержать панель фильтрации справа. Обратите внимание, как выбирать даты и статус для фильтрации:

Admin Site - BookInstance List Filters

Organise detail view layout

By default, the detail views lay out all fields vertically, in their order of declaration in the model. You can change the order of declaration, which fields are displayed (or excluded), whether sections are used to organise the information, whether fields are displayed horizontally or vertically, and even what edit widgets are used in the admin forms.

Note: The LocalLibrary models are relatively simple so there isn't a huge need for us to change the layout; we'll make some changes anyway however, just to show you how.

Controlling which fields are displayed and laid out

Update your AuthorAdmin class to add the fields line, as shown below (in bold):

class AuthorAdmin(admin.ModelAdmin):
    list_display = ('last_name', 'first_name', 'date_of_birth', 'date_of_death')
    fields = ['first_name', 'last_name', ('date_of_birth', 'date_of_death')]

The fields attribute lists just those fields that are to be displayed on the form, in order. Fields are displayed vertically by default, but will display horizontally if you further group them in a tuple (as shown in the "date" fields above).

Restart your application and go to the author detail view — it should now appear as shown below:

Admin Site - Improved Author Detail

Note: You can also use the exclude attribute to declare a list of attributes to be excluded from the form (all other attributes in the model will be displayed). 

Sectioning the detail view

You can add "sections" to group related model information within the detail form, using the fieldsets attribute.

In the BookInstance model we have information related to what the book is (i.e. name, imprint, and id) and when it will be available (status, due_back). We can add these in different sections by adding the text in bold to our BookInstanceAdmin class. 

@admin.register(BookInstance)
class BookInstanceAdmin(admin.ModelAdmin):
    list_filter = ('status', 'due_back')
    
    fieldsets = (
        (None, {
            'fields': ('book','imprint', 'id')
        }),
        ('Availability', {
            'fields': ('status', 'due_back')
        }),
    )

Each section has its own title (or None, if you don't want a title) and an associated tuple of fields in a dictionary — the format is complicated to describe, but fairly easy to understand if you look at the code fragment immediately above.

Restart and navigate to a book instance view; the form should appear as shown below:

Admin Site - Improved BookInstance Detail with sections

Inline editing of associated records

Sometimes it can make sense to be able to add associated records at the same time. For example, it may make sense to have both the book information and information about the specific copies you've got on the same detail page.

You can do this by declaring inlines, of type TabularInline (horizonal layout) or StackedInline (vertical layout, just like the default model layout). You can add the BookInstance information inline to our Book detail by adding the lines below in bold near your BookAdmin:

class BooksInstanceInline(admin.TabularInline):
    model = BookInstance

@admin.register(Book)
class BookAdmin(admin.ModelAdmin):
    list_display = ('title', 'author', 'display_genre')
    inlines = [BooksInstanceInline]

Try relaunching your app then looking at the view for a Book — at the bottom you should now see the book instances relating to this book:

Admin Site - Book with Inlines

In this case all we've done is declare our tablular inline class, which just adds all fields from the inlined model. You can specify all sorts of additional information for the layout, including the fields to display, their order, whether they are read only or not,  etc. (see TabularInline for more information). 

Note: There are some painful limits in this functionality! In the screenshot above we have three existing book instances, followed by three placeholders for new book instances (which look very similar!). It would be better to have NO spare book instances by default and just add them with the Add another Book instance link, or to be able to just list the BookInstances as non-readable links from here. The first option can be done by setting the extra attribute to 0 in BookInstanceInline model, try it by yourself.

Challenge yourself

We've learned a lot in this section, so now it is time for you to try a few things.

  1. For the BookInstance list view, add code to display the book, status, due back date, and id (rather than the default __str__() text).
  2. Add an inline listing of Book items to the Author detail view using the same approach as we did for Book/BookInstance.

Summary

That's it! You've now learned how to set up the administration site in both its simplest and improved form, how to create a superuser, and how to navigate the admin site and view, delete, and update records. Along the way you've created a bunch of Books, BookInstances, Genres and Authors that we'll be able to list and display once we create our own view and templates.

Further reading

Метки документа и участники

 Внесли вклад в эту страницу: yuriy65, Denizz
 Обновлялась последний раз: yuriy65,