Personalize o formulário do site de administração¶

Ao registrarmos o modelo de Question``através da linha ``admin.site.register(Question), o Django constrói um formulário padrão para representá-lo. Comumente, você desejará personalizar a apresentação e o funcionamento dos formulários do site de administração do Django. Para isto, você precisará informar ao Django as opções que você quer utilizar ao registrar o seu modelo.

Vamos ver como isto funciona reordenando os campos no formulário de edição. Substitua a linha àdmin.site.register(Question)` por:

from django.contrib import admin

from .models import Question


class QuestionAdmin(admin.ModelAdmin):
    fields = ["pub_date", "question_text"]


admin.site.register(Question, QuestionAdmin)

Você seguirá este padrão – crie uma classe de “model admin”, em seguida, passe-a como o segundo argumento para o admin.site.register() – todas as vezes que precisar alterar as opções administrativas para um modelo.

Essa mudança específica no código acima faz com que a “Publication date” apareça antes do campo “Question”:

Isso não é impressionante com apenas dois campos, mas para formulários com dúzias deles, escolher uma ordem intuitiva é um detalhe importante para a usabilidade.

E por falar em dúzias de campos, você pode querer dividir o formulário em grupos:

from django.contrib import admin

from .models import Question


class QuestionAdmin(admin.ModelAdmin):
    fieldsets = [
        (None, {"fields": ["question_text"]}),
        ("Date information", {"fields": ["pub_date"]}),
    ]


admin.site.register(Question, QuestionAdmin)

O primeiro elemento de cada tupla em fieldsets é o título do grupo. Aqui está como o nosso formulário se parece agora:

Adicionando objetos relacionados¶

Ok, nós temos nossa página de administração Questão, mas a Questão tem múltiplas Questões, e a página de administração não exibe escolhas.

Ainda.

There are two ways to solve this problem. The first is to register Choice with the admin just as we did with Question:

from django.contrib import admin

from .models import Choice, Question

# ...
admin.site.register(Choice)

Agora “Choices” é uma opção disponível no site de administração do Django. O formulário de “Add choice” se parece com isto:

Nesse formulário, o campo “Question” é uma caixa de seleção contendo todas as enquetes no banco de dados. O Django sabe que uma ForeignKey deve ser representada no site de administração como um campo <select>. No nosso caso, só existe uma enquete até agora.

Also note the “Add another question” link next to “Question.” Every object with a ForeignKey relationship to another gets this for free. When you click “Add another question”, you’ll get a popup window with the “Add question” form. If you add a question in that window and click “Save”, Django will save the question to the database and dynamically add it as the selected choice on the “Add choice” form you’re looking at.

Mas, sério, essa é uma maneira ineficiente de adicionar objetos Choice ao sistema. Seria muito melhor se você pudesse adicionar várias opções diretamente quando criasse um objeto Question. Vamos fazer isso acontecer.

Remova a chamada register() do modelo Choice. Então edite o código de registro de Question para que fique assim:

from django.contrib import admin

from .models import Choice, Question


class ChoiceInline(admin.StackedInline):
    model = Choice
    extra = 3


class QuestionAdmin(admin.ModelAdmin):
    fieldsets = [
        (None, {"fields": ["question_text"]}),
        ("Date information", {"fields": ["pub_date"], "classes": ["collapse"]}),
    ]
    inlines = [ChoiceInline]


admin.site.register(Question, QuestionAdmin)

Isso informa ao Django: Objetos “Choice são editados na mesma página de administração de Question. Por padrão, forneça campos suficientes para 3 escolhas.”

Carregue a página “Add question” para ver como está:

Funciona assim: há três blocos para Escolhas relacionadas – como especificado em extra –, mas a cada vez que você retorna à página de “Alteração” para um objeto já criado, você ganha outros três blocos extra.

At the end of the three current slots you will find an “Add another Choice” link. If you click on it, a new slot will be added. If you want to remove the added slot, you can click on the X to the top right of the added slot. This image shows an added slot:

One small problem, though. It takes a lot of screen space to display all the fields for entering related Choice objects. For that reason, Django offers a tabular way of displaying inline related objects. To use it, change the ChoiceInline declaration to read:

class ChoiceInline(admin.TabularInline): ...

Com o TabularInline (em vez de StackedInline), os objetos relacionados são exibidos de uma maneira mais compacta, formatada em tabela:

Note that there is an extra “Delete?” column that allows removing rows added using the “Add another Choice” button and rows that have already been saved.

Personalize a listagem da página de administração¶

Agora que a página de administração de Pergunta está bonita, vamos fazer algumas melhorias à página “change list” – aquela que exibe todas as enquetes do sistema.

Aqui é como ela está até agora:

By default, Django displays the str() of each object. But sometimes it’d be more helpful if we could display individual fields. To do that, use the list_display admin option, which is a list of field names to display, as columns, on the change list page for the object:

class QuestionAdmin(admin.ModelAdmin):
    # ...
    list_display = ["question_text", "pub_date"]

For good measure, let’s also include the was_published_recently() method from Tutorial 2:

class QuestionAdmin(admin.ModelAdmin):
    # ...
    list_display = ["question_text", "pub_date", "was_published_recently"]

Agora a página de edição de enquetes está assim:

Você pode clicar no cabeçalho da coluna para ordená-las por estes valores – exceto no caso do was_published_recently, porque a ordenação pelo resultado de um método arbitrário não é suportada. Também note que o cabeçalho da coluna para was_published_recently é, por padrão, o nome do método (com underscores substituídos por espaços), e que cada linha contem a representação da saída.

You can improve that by using the display() decorator on that method (extending the polls/models.py file that was created in Tutorial 2), as follows:

from django.contrib import admin


class Question(models.Model):
    # ...
    @admin.display(
        boolean=True,
        ordering="pub_date",
        description="Published recently?",
    )
    def was_published_recently(self):
        now = timezone.now()
        return now - datetime.timedelta(days=1) <= self.pub_date <= now

For more information on the properties configurable via the decorator, see list_display.

Edite o arquivo polls/admin.py de novo e adicione uma melhoria à página de lista de edição Question: Um filtro usando list_filter. Adicione a seguinte linha ao QuestionAdmin:

list_filter = ["pub_date"]

Isso adiciona uma barra lateral “Filter” que permite às pessoas filtrarem a lista de edição pelo campo pub_date:

O tipo do filtro apresentado depende do tipo do campo pelo qual você está filtrando. Como pub_date é uma instância da classe DateTimeField, o Django consegue deduzir que os filtros apropriados são: “Qualquer data”, “Hoje”, “Últimos 7 dias”, “Esse mês”, “Esse ano”.

Isso está ficando bom. Vamos adicionar capacidade de pesquisa:

search_fields = ["question_text"]

Isso adiciona um campo de pesquisa ao topo da lista de edição. Quando alguém informa termos de pesquisa, o Django irá pesquisar o campo question_text. Você pode usar quantos campos quiser – entretanto, por ele usar uma consulta LIKE internamente, limitar o número de campos de pesquisa a um número razoável, será mais fácil para o seu banco de dados para fazer pesquisas.

Agora é também uma boa hora para observar que a página de edição fornece uma paginação gratuitamente. O padrão é mostrar 100 itens por página. Paginação da página de edição, campos de pesquisa, filters, hierarquia por data, e ordenação por cabeçalho de coluna todos trabalham em sincronia como deveriam.

Personalize a aparência do site de administração¶

Obviamente, ter “Django administration” no topo de cada página de administração é ridículo. Isso é só um texto de exemplo.

You can change it, though, using Django’s template system. The Django admin is powered by Django itself, and its interfaces use Django’s own template system.

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

$ python -c "import django; print(django.__path__)"

...\> py -c "import django; print(django.__path__)"

{% block branding %}
<div id="site-name"><a href="{% url 'admin:index' %}">Polls Administration</a></div>
{% if user.is_anonymous %}
  {% include "admin/color_theme_toggle.html" %}
{% endif %}
{% endblock %}

Personalize a página inicial do site de administração¶

De maneira similar, você pode querer personalizar a aparência da página inicial do site de administração do Django.

Por padrão, ele exibe todas as aplicações em INSTALLED_APPS, que estão registrados na aplicação de administração, em ordem alfabética. E você pode querer fazer alterações significativas no layout. Além do que, a página inicial é provavelmente a página mais importante da página de administração, e deve ser fácil de usar.

O template para personalizar é admin/index.html. (Faça o mesmo que admin/base_site.html na seção anterior – copie ele do diretório padrão para o seu diretório de template personalizado). Edite o arquivo e você verá que ele usa uma variável de template chamada app_list. Esta variável contém cada aplicação instalada no Django. Ao invés de usar isto, você pode criar links diretos para páginas do site de administração específicas em qualquer forma que você achar melhor.

When you’re comfortable with the admin, read part 8 of this tutorial to learn how to use third-party packages.