# documentação Django 2.0.8

# Escrevendo seu primeiro app Django, parte 7

Esse tutorial começa de onde o Tutorial 6 parou. Estamos continuando a aplicação Web para enquetes e focaremos na customização do site administrativo automaticamente gerado pelo Django que exploramos no Tutorial 2.

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

Ao registrarmos o model 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á customizar a apresentação e o funcionamento dos formulários do admin 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:

polls/admin.py

    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 do modelo 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:

polls/admin.py

    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õe`s, e a página de administração não exibe escolhas.

Ainda.

Há duas formas de solucionar esse problema. A primeira é registrar `Choice` no site de administração, assim como fizemos com `Question`. Isto é fácil:

polls/admin.py

    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.

Observe também o link “Add Another” ao lado de “Question”. Todo objeto com um relacionamento de chave estrangeira para outro ganha essa opção gratuitamente. Quando você clica em “Add Another”, você terá uma janela popup com o formulário “Add question”. Se você adicionar uma enquete na janela e clicar em “Save”, o Django salvará a enquete no banco de dados e irá dinamicamente adicionar a opção já selecionada ao formulário “Add choice” que você está vendo.

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:

polls/admin.py

    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.

No final dos três blocos atuais você encontrará um link “Adicionar outra escolha”. Se você clicar nele, será adicionado um novo bloco. Se você deseja remover o bloco adicional, você pode clicar no X ao topo direito do bloco acrescentado. Observe que você não pode remover os três blocos originais. Esta imagem mostra um bloco acrescentado:

No entanto, há um pequeno problema. Um monte de espaço na tela é tomado para exibir todos os três objetos `Choice` relacionados a serem inseridos. Por essa razão, o Django oferece uma maneira alternativa para exibir cada objeto relacionado em uma única linha; você só precisa alterar a declaração `ChoiceInline` para que seja:

polls/admin.py

    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:

Observe que há uma coluna extra “Delete?” que permite a remoção de linhas adicionadas usando o botão “Add Another Choice” e linhas que já foram salvas.

## 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:

Por padrão, o Django mostra o `str()` de cada objeto. Mas algumas vezes seria mais útil se pudéssemos mostrar campos individuais. Para fazer isso, use a opção `list_display`, que é uma tupla de nomes de campos a serem exibidos, como colunas, na lista de mudança dos objetos:

polls/admin.py

    class QuestionAdmin(admin.ModelAdmin):
        # ...
        list_display = ('question_text', 'pub_date')

Apenas bom demais para mensurar, vamos também incluir o método `was_published_recently()` do Tutorial 2:

polls/admin.py

    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.

Você pode melhorar isso adicionando ao método (em `polls/models.py`) alguns atributos, como segue:

polls/models.py

    class Question(models.Model):
        # ...
        def was_published_recently(self):
            now = timezone.now()
            return now - datetime.timedelta(days=1) <= self.pub_date <= now
        was_published_recently.admin_order_field = 'pub_date'
        was_published_recently.boolean = True
        was_published_recently.short_description = 'Published recently?'

Para obter mais informações sobre essas propriedades de método, veja :attr:`~django.contrib.admin.ModelAdmin.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. Por conta de `pub_date` ser 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.

É fácil de editar, no entanto, usando o sistema de templates do Django. A página de administração de Django é feita com o próprio Django e conseqüentemente sua interface usa o sistema de templates nativo do Django.

### Personalizando os templates do seu projeto

Criar um diretório `templates` no diretório do seu projeto (aquela que contém `manage.py`). Os modelos podem viver em qualquer lugar em seu sistema de arquivos que o Django possa acessar. (Django é executado como qualquer usuário que seu servidor é executado.) No entanto, manter seus templates dentro do projeto é uma boa convenção a seguir.

Abra seu arquivo de configurações (`mysite/settings.py`, lembre-se) e adicione uma opção `DIRS`. na configuração `TEMPLATES` setting:

mysite/settings.py

    TEMPLATES = [
        {
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [os.path.join(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',
                ],
            },
        },
    ]

`DIRS` é uma lista de diretórios de arquivos que serão checados quando o Django carregar seus templates, ou seja, caminhos de busca.

Organizando templates

Just like the static files, we could have all our templates together, in one big templates directory, and it would work perfectly well. However, templates that belong to a particular application should be placed in that application’s template directory (e.g. `polls/templates`) rather than the project’s (`templates`). We’ll discuss in more detail in the reusable apps tutorial why we do this.

Agora crie um diretório chamado `admin` dentro de `templates`, e copie o template `admin/base_site.html` de dentro do diretório padrão do site de administração do Django (`django/contrib/admin/templates`) para dentro deste diretório.

Onde estão os arquivos de código-fonte do Django?

Se você tiver dificuldade em encontrar onde os arquivos do Django estão localizados em seu sistema, execute o seguinte comando:

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

Então, apenas edite o arquivo e substitua `{{ site_header|default:_('Django administration') }}` (incluindo as chaves) com nome do seu próprio site como desejar. Você deve acabar com uma secção de código como:

    {% block branding %}
    <h1 id="site-name"><a href="{% url 'admin:index' %}">Polls Administration</a></h1>
    {% endblock %}

Nós usamos esta abordagem para ensinar-lhe como substituir templates. Em um projeto real, você provavelmente usaria o atributo `django.contrib.admin.AdminSite.site_header` para fazer mais facilmente essa personalização em particular.

Esse template contém uma série de textos como `{% block branding %}` e `{{ tittle }}`. As tags `{%` e `{{` fazem pate da linguagem de templates do Django. Quando o Django renderiza o template “admin/base_site.html”, o seu conteúdo é processado por essa linguagem de templates para produzir a página HTML final, assim como vimos no Tutorial 3.

Note que qualquer template padrão do sire de administração pode ser sobrescrito. Para sobrescrever um template, apenas faça a mesma coisa que você fez com `base_site.html` – copie ele do diretório padrão para o seu próprio diretório, e faça as mudanças.

### Personalizando templates da sua aplicação

Leitores astutos irão se perguntar: Mas se `DIRS` estava vazio por padrão, como o Django pôde encontrar o diretório padrão dos templates do site de administração? A resposta é, Desde que `APP_DIRS` seja `True`, o Django irá automaticamente procurar por um subdiretório `templates/` dentro de cada pacote de aplicação, para usar como fallback(Não esqueça que `django.contrib.admin` é uma aplicação)

Nossa aplicação enquete não é muito complexa e não precisa de templates personalizados para o site de administração. Mas se ele crescer e ficar mais sofisticado e necessária a modificação dos templates padrão de administração do Django para algumas de suas funcionalidades, seria mais sensato modificar os templates da aplicação, e não os do projeto. Dessa forma, você poderia incluir a aplicação de enquete em qualquer novo projeto e ter a certeza que iria encontrar os modelos personalizados que você precisa.

Veja a documentação de carga de template - para mais informação sobre como o Django acha seus templates.

## 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 app instalada no Django. Ao invés de usar isto, você pode criar links hard-coded para páginas do admin específicas em qualquer forma que você achar melhor.

## E agora?

O tutorial dos iniciantes termina aqui. Entretanto, você pode querer verificar alguns indicadores em onde ir partindo daqui.

Se você é familiar ao sistema de empacotamento Python e está interessado em como tornar a enquete em uma “app reusável”, veja Tutorial avançado: como escrever apps reusáveis.