{{{
#!rst

THIS TRANSLATION IS IN PROGRESS:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------------------------------------------------------------------+
|    This is an **in progress** translation document, that means there is somebody working on it. |
|    For more information on translating documents please look at `TranslateDocumentation Wiki`_. |
|    Please **do not** edit this page.                                                            |
|                                                                                                 |
| .. _TranslateDocumentation Wiki : http://code.djangoproject.com/wiki/TranslateDocumentation     |
+-------------------------------------------------------------------------------------------------+   

.. sidebar:: Escrevendo sua primeira aplicação Django, parte 2
  :subtitle: tradução para o português.

  Documento original: `Writing your first Django app, part 2`_
  
  Tradução: Marcos Vinícius `<marvinware2005@yahoo.com>`
  
  Referente a revisão: 3454

.. _Writing your first Django app, part 2: http://www.djangoproject.com/documentation/tutorial2/

.. contents:: **Conteúdos do capítulo**

=================================================
Escrevendo sua primeira aplicação Django, parte 2
=================================================

Este documento cobre a versão 0.95 de Django e a versão do desenvolvimento. Docs anteriores: `0.90`_, `0.91`_
----------------------------------------------------------------------------------------------------------------

.. _0.90: http://www.djangoproject.com/documentation/0_90/ 
.. _0.91: http://www.djangoproject.com/documentation/0_91/ 

Esse tutorial começa onde o `Tutorial 1`_ terminou. Nós vamos continuar nossa aplicação de "Questionário Web" e focar no site de administração gerado pelo Django.

.. _`Tutorial 1`: http://www.djangoproject.com/documentation/tutorial1/

.. admonition:: Filosofia

    Gerar sites de aministração para sua equipe ou clientes criar, atualizar e excluir informações é um trabalho 
    chato e não requer muita criatividade. Por isso, Django automatiza totalmente a criação de interfaces 
    de administração para seus models.
    Django foi escrito num ambie nte jornalístico, com uma clara separação entre "quem publica o conteúdo" e o 
    "site público". Os gerenciadores do site usam o sistema para adicionar noticias, eventos, resultados 
    esportivos, etc, e o conteúdo é mostrado no site público. Django resolve o problema de criar uma 
    interface unificada para os administradores do site editar conteúdo.

    A interface de administração não tem a intenção de ser usada pelos visitantes do site, mas sim 
    pelos administradores do site.

Ative o site de Administração
=============================

O site de administração do Django não é ativo por padrão - é um recurso opcional. Para ativar o site de administração na sua instalação, siga esses três passos:

    * Adicione ``django.contrib.admin`` em ``INSTALLED_APPS`` no seu arquivo de settings
    * Execute ``python manage.py syncdb``. Como você adicionou uma nova aplicação em ``INSTALLED_APPS``, as tabelas 
      do banco de dados precisam ser atualizadas.
    * Edite seu arquivo ``mysite/urls.py`` e descomente a linha "Uncomment this for admin:". Esse arquivo é um 
      URLConf; nós vamos nos aprofundar em URLConfs no próximo tutorial. Por enquanto, tudo que você precisa saber 
      é que eles mapeiam as URLs para as aplicações.

Inicie o servidor de desenvolvimento:
=====================================

Vamos iniciar o servidor de desenvolvimento e explorar o site de administração.
Lembre que no Tutorial 1 você iniciou o servidor de desenvolvimento da seguinte forma::

    python manage.py runserver

Abra um web browser e vá para "/admin/" no seu domínio local, ex: http://127.0.0.1:8000/admin/. Você deverá ver a seguinte tela de login:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin01.png
   :alt: Tela de login do site de administração do Django

Entre no site de administração:
===============================

Agora, tente logar. (Você criou uma conta de superusuário na primeira parte deste tutorial, lembra?!) Você deverá ver a pagina index do site de administração do Django:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin02t.png
   :alt: Index do site de administração
   :target: http://media.djangoproject.com/img/doc/tutorial/admin02.png

Por padrão, você deverá ver dois tipos de conteúdo editavel: "groups" e "users". Esses são os principais recursos que o Django traz por padrão.

Fazendo a aplicação Poll acessível no admin:
============================================

Mas, onde está nossa aplicação Poll? Ela não foi mostrada no index do admin.
Apenas uma coisa a fazer: nós temos que especificar no model ``Poll`` que seus objetos tem uma interface admin.
Edite o arquivo ``mysite/polls/models.py`` e faça a seguinte alteração para criar uma classe interna chamada ``Admin``::

    class Poll(models.Model):
        # ...
        class Admin:
            pass

A ``classe Admin`` conterá todas as configurações que controlam como esse model aparece no admin. Todas as configurações são opcionais, entretanto, criando uma classe vazia significa "dê a esse objeto uma interface no admin usando todas as configurações padrão".

Agora atualize a pagina do admin para ver as mudanças. Note que você não tem que reiniciar o servidor de desenvolvimento - o servidor vai recarregar automaticamente seu projeto, então qualquer modificação no código será vista imediatamente no browser.

Explore as funcionalidades do admin:
====================================

Agora que o model ``Poll`` tem uma classe interna ``Admin``, Django sabe que ela deve ser mostrada no index do admin.

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin03t.png
   :alt: A página index do site de administração do Django, agora com os objetos Poll mostrados
   :target: http://media.djangoproject.com/img/doc/tutorial/admin03t.png

Clique em "Polls". Agora você está na pagina "change list" de polls. Essa página mostra todos os polls no banco de dados e deixa você escolher um para altera-lo. Lá está o poll "What's up?" criado no primeiro tutorial:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin04t.png
   :alt: A "change list" do model Poll
   :target: http://media.djangoproject.com/img/doc/tutorial/admin04.png

Clique no poll "What's up?" para editá-lo:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin05t.png
   :alt: O formulário de edição para o objeto Poll
   :target: http://media.djangoproject.com/img/doc/tutorial/admin05.png

Algumas coisas para se notar:

    * O formulário é gerado automaticamente a partir do model Poll.
    * Os diferentes tipos de campo (``models.DateTimeField``, ``models.CharField``) sabem como "se mostrar" 
      no admin.
    * Cada ``DateTimeField`` tem alguns atalhos em JavaScript. Datas tem um atalho "Today" e um calendário 
      (em pop-up), 
      e horários tem um atalho "Now" e um conveniente pop-up que lista horas freqüentemente usadas.

A parte de baixo da página lhe dá algumas opções:

    * Save - salva as alterações e retorna para a "change list".
    * Save and continue editing - salva as alterações e atualiza a pagina do admin para o objeto atual.
    * Save and add another - salva as alterações e carrega um novo formulário em branco para esse tipo de objeto
    * Delete - mostra uma página de confirmação de deleção

Altere o campo "Date published" clicando nos atalhos "Today" e "Now". Então clique em "Save and continue editing". Agora clique em "History" na parte superior direita. Você verá uma página listando todas as alterações feitas nesse objeto através do admin, com um "timestamp" e o "username" da pessoa que fez a alteração:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin06t.png
   :alt: Página de histórico para objetos Poll
   :target: http://media.djangoproject.com/img/doc/tutorial/admin06.png

Personalize o formulário do admin:
==================================

Reserve alguns minutos para se maravilhar do código que você não teve que escrever.
Vamos personalizar um pouco. Nós podemos reordenar os campos adicionando um parâmetro ``field`` para a classe interna ``Admin``::

    class Admin:
        fields = (
            (None, {'fields': ('pub_date', 'question')}),
        )

Isso fez com que o campo "Date published" aparecesse primeiro, ao invés de segundo.

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin07.png
   :alt: Fields have been reordered
   :target: http://media.djangoproject.com/img/doc/tutorial/admin07.png

Isso não é muito impressionante com apenas dois campos, mas para formulários com dúzias de campos, escolher uma ordem intuitiva é um grande detalhe de usabilidade.
E falando em formulários com dúzias de campos, você poderia querer separar o formulário em "fieldsets"::

    class Admin:
        fields = (
            (None, {'fields': ('question',)}),
            ('Date information', {'fields': ('pub_date',)}),
        )

O primeiro elemento em cada tupla em ``fields`` é o título do "fieldset". Veja como o formulário está agora:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin08t.png
   :alt: Form has fieldsets now
   :target: http://media.djangoproject.com/img/doc/tutorial/admin08.png

Você pode atribuir quaisquer classes HTML para cada "fieldset". Django oferece uma classe "collapse" que mostra um determinado "fieldset" inicialmente encolhido. Isso é útil quando você tem um formulário muito grande que contem alguns campos que não são tão usados::

    class Admin:
        fields = (
            (None, {'fields': ('question',)}),
            ('Date information', {'fields': ('pub_date',), 'classes': 'collapse'}),
        )

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin09.png
   :alt: "Fieldset" inicialmente encolhido

Adicionando objetos relacionados:
=================================

Ok, nós temos nossa página de administração da classe Poll. Mas um ``Poll`` tem vários ``Choices``, e essa página não mostra os "Choices". 

Ainda.

Há duas maneiras de resolver esse problema. A primeira dar ao model Choice sua própria ``classe interna Admin``, assim como fizemos para o model ``Poll``. E aqui está como o model será::

    class Choice(models.Model):
       # ...
       class Admin:
           pass

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin10.png
   :alt: A pagina de administração de objetos Choice

Nesse formulário o campo "Poll" é um "``select box``" contendo todos os "Polls" do banco de dados. Django sabe que campos ``ForeignKey`` devem ser representados como uma "``<select>`` box". No nosso caso, apenas um "Poll" está disponível atualmente.

Note também, o link "Add another" próximo ao campo "Poll". Todo objeto com um relacionamento ForeignKey tem esse recurso automaticamente. Quando você clica em "Add another", você verá uma janela popup com o formulário "Add poll". Se você adiciona um "Poll" nessa janela e clica em "Save", Django vai salvar o "Poll" no banco de dados e dinamicamente adiciona-lo como uma opção selecionada no formulário "Add choice" que você estava.

Mas, realmente, essa é uma forma ineficiente de adicionar objetos "Choice" no sistema. Seria melhor se você pudesse adicionar vários "Choice" diretamente quando você adiciona um objeto "Poll". Vamos fazer isso acontecer.

Remova a classe interna ``Admin`` do model Choice. Agora, edite o ``ForeignKey(Poll)`` campo dessa forma::

    poll = models.ForeignKey(Poll, edit_inline=models.STACKED, num_in_admin=3)

Isso diz ao Django: "Objetos Choice são editados na página de administração do Poll. Por padrão, providencie 3 campos para Choice".

Então, altere os outros campos no model ``Choice`` para alterálos para ``core=True``::

    choice = models.CharField(maxlength=200, core=True)
    votes = models.IntegerField(core=True)

Isso diz ao Django: "Quando você editar um 'Choice' na pagina de administração do 'Poll' os campos 'choice' e 'vote' são requeridos. A presença de ao menos um deles significa a adição de um novo objeto "Choice" e limpar ambos os campos significa a deleção do objeto existente".

Carregue a página "Add poll" para ver como ela está:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin11t.png
   :alt: Página "Add poll", agora com os objetos Choice
   :target: http://media.djangoproject.com/img/doc/tutorial/admin11.png

Ela funciona assim: há três espaços para objetos "Choice" - como foi especificado em ``num_in_admin`` - mas cada vez que você volta para a página de alteração de um objeto já criado, você tem um espaço extra. (Isso significa que não há uma quantidade fixa de quantos objetos relacionados podem ser adicionados.) Se você quisesse três espaços extras cada vez que você alterar um "Poll" você deverá usar ``num_extra_on_change=3``.

Porém, há um pequeno problema. Dessa forma é necessário muito espaço em tela para mostrar os campos para os objetos relacionados. Por isso, Django oferece uma maneira alternativa de mostrar objetos relacionados "in-line"(em uma única linha)::

    poll = models.ForeignKey(Poll, edit_inline=models.TABULAR, num_in_admin=3)

Com ``edit_inline=models.TABULAR`` (ao invés de ``models.STACKED``) os objetos relacionados aparecem de uma forma mais compacta e baseados em tabelas:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin12.png
   :alt: Add poll page now has more compact choices

Personalizar a pagina de administração "change list":
=====================================================

Agora que a página de administração do "Poll" está com uma boa aparência, vamos dar uma turbinada na página "change list" - aquela que mostra todos os Polls do sistema.

Aqui é como ela está agora:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin04t.png
   :alt: Página "Change list" dos objetos Poll
   :target: http://media.djangoproject.com/img/doc/tutorial/admin04.png

Por padrão, Django mostra o método ``str()`` de cada objeto. Porém às vezes seria melhor se nós pudéssemos mostrar campos individuais. Para fazer isso, nós usamos a opção ``list_display``, que é uma tupla dos campos a mostrar, como colunas, na pagina "change list" para tal objeto::

    class Poll(models.Model):
        # ...
        class Admin:
            # ...
            list_display = ('question', 'pub_date')


Como demonstração, vamos incluir o método ``was_published_today`` criado no Tutorial 1::

    list_display = ('question', 'pub_date', 'was_published_today')

Veja como a página está:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin13t.png
   :alt: "Change list" dos objetos "Poll"
   :target: http://media.djangoproject.com/img/doc/tutorial/admin13.png

Você pode clicar nos títulos das colunas para ordenar por seus valores - exceto no caso da coluna ``was_published_today``, porque ordenar pelos valores de um método não é suportado. Note também que o título da coluna do método ``was_published_today`` é, por padrão, o nome do método (com o underscore substituído por espaço). Mas você pode mudar isso criando um atributo ``short_description`` para o método::

    def was_published_today(self):
        return self.pub_date.date() == datetime.date.today()
    was_published_today.short_description = 'Published today?'

Vamos melhorar ainda mais nossa "change list": Filtros. Adicione a seguinte linha em ``Poll.Admin``::

    list_filter = ['pub_date']

Isso adiciona um menu de filtro, que deixa as pessoas filtrarem a "change list" pelo campo ``pub_date``:

.. image:: http://media.djangoproject.com/img/doc/tutorial/admin14t.png
   :alt: Polls change list page, updated
   :target: http://media.djangoproject.com/img/doc/tutorial/admin14.png

O tipo de filtro mostrado depende do tipo do campo que você está filtrando. Como ``pub_date`` é um DateTimeField, Django sabe que as opções de filtro padrão são: "Any date," "Today," "Past 7 days," "This month," "This year."

Isso está tomando forma. Vamos adicionar alguma funcionalidade de busca::

    search_fields = ['question']

Isso adiciona uma caixa de busca em cima da "change list". Quando alguém digita os parâmetros de busca, Django ira buscar pelo campo ``question``. Você pode usar quantos campos você quiser - como esse recurso usa um SQL com LIKE por trás dos panos, não exagere, para deixar seu banco de dados feliz.

Finalmente, como objetos "Poll" tem uma data, seria conveniente ser possível realizar uma quebra (drill down) por data. Adicione essa linha::

    date_hierarchy = 'pub_date'

Isso adiciona uma navegação hierárquica, por data, no topo da "change list". Em primeira instância, são mostrados todos os anos disponíveis. Então aumenta o detalhamento em meses, e por último em dias.

Agora é também uma boa hora para notar que as mudanças têm paginação por padrão. O tamanho padrão da paginação é de 50 itens por página. Paginação na "change list", buscas, filtros, hierarquia de dados e ordenação pelo título da coluna funcionam integrados como você pensa que eles deveriam.

Personalizando a aparência (look and feel) do admin:
====================================================

Logicamente, tendo "Django administration" e "example.com" no título de cada página de administração é ridículo. Isto é só um texto padrão.
E isso é fácil de mudar, usando o sistema de templates do Django. A administração do Django é feita no próprio Django, e sua interface usa o próprio sistema de templates do Django. (!!!)

Abra seu arquivo de configurações (lembre-se, ``mysite/settings.py``) e olhe em ``TEMPLATE_DIRS``. ``TEMPLATE_DIRS`` é uma tupla de diretórios a checar quando se vai carregar um template Django. É um diretório de busca.

Por padrão, ``TEMPLATE_DIRS`` é vazio. Então, vamos adicionar uma linha, para dizer ao Django onde nossos templates estão::

    TEMPLATE_DIRS = (
        "/home/mytemplates", # Change this to your own directory.
    )

Agora, copie o template ``admin/base_site.html`` do diretório de templates padrão do admin (``django/contrib/admin/templates``) em um subdiretório ``admin`` no diretório que você está usando ``TEMPLATE_DIRS``. Por exemplo, se seu ``TEMPLATE_DIRS`` inclui ``/home/mytemplates``, como acima, então copie ``django/contrib/admin/templates/admin/base_site.html`` para ``/home/mytemplates/admin/base_site.html``. Não esqueça do subdiretório ``admin``.

Então, apenas edite o arquivo e substitua os textos genéricos do Django com os do seu site e ajuste as URLs como quiser.

Note que os templates padrão da administração do Django podem ser substituídos. Para substituir um template, apenas faça a mesma coisa que você fez com ``base_site.html`` - copie o arquivo do diretório padrão e faça as alterações.

Leitores astutos irão perguntar: Mas se ``TEMPLATE_DIRS`` estava vazia por padrão, como Django encontrou os templates padrão? A resposta é que, por padrão, Django automaticamente procura por um subdiretório templates/ de cada aplicação, para usar como um último recurso. Veja o `loader types documentation`_ para mais informações.

.. _`loader types documentation`: http://www.djangoproject.com/documentation/templates_python/#loader-types

Personalizando o index da página de administração:
==================================================

Seguindo os mesmos pensamentos, você pode querer personalizar a aparência do index da página de administração.

Por padrão, esta página mostra todos as aplicações disponíveis, de acordo com a configuração ``INSTALLED_APPS``. Mas a ordem que são mostrados é aleatória, e você pode querer fazer mudanças significativas no layout. Além do mais, o index é provavelmente a página mais importante do site de administração, e deve ser fácil de usar.

O template para personalizar é ``admin/index.html``. (Faça o mesmo como feito com ``admin/base_site.html`` na seção anterior - copie do diretório padrão para o seu próprio diretório.) Edite o arquivo, e você verá que ele usa uma template tag chamada ``{% get_admin_app_list as app_list %}``. Essa é a mágica que carrega todos as aplicações instaladas no Django. Ao invés de usar assim, você pode usar links fixos para objetos específicos da maneira que você achar melhor.

Django oferece um outro atalho nesse departamento. Rode o comando::

    python manage.py adminindex polls 

para ter um pedaço de código do template para inclusão na página index da administração. Isso é útil como um ponto de partida.

Para maiores detalhes na personalização da aparência do site de administração do Django, veja `Django admin CSS guide`_.

.. _`Django admin CSS guide`: http://www.djangoproject.com/documentation/admin_css/

Quando você se sentir confortável com o site de administração, leia a `parte 3 do tutorial`_ e comece a trabalhar com views.

.. _`parte 3 do tutorial`: http://www.djangoproject.com/documentation/tutorial3/
}}}