Parte II

Django Admin

Uma das partes mais poderosas do Django é a Interface Automática de Administração (admin). Ela lê os metadados do seu model e provê uma poderosa interface para começar a adicionar conteúdo ao site.

Visão geral

Há cinco etapas na ativação do Django admin:

1. Adicionar django.contrib.admin na variável INSTALLED_APPS no arquivo settings.py
2. Determinar quais models da sua aplicação devem ser editáveis na interface admin.
3. Para cada um desses models, é possível criar uma classe ModelAdmin que encapsula e personaliza as funcionalidades do admin.
4. Instanciar uma classe AdminSite e relacionar seus models ao ModelAdmin.
5. Criar uma instância do AdminSite na URLconf, no arquivo urls.py

Objetos do ModelAdmin

As classes ModelAdmin são representações de um model na interface admin. São armazenadas em um arquivo chamado admin.py. Agora, vamos dar uma olhada em um exemplo muito simples da ModelAdmin:

from django.contrib import admin
from myproject.myapp.models import Author
 
class AuthorAdmin(admin.ModelAdmin):
  pass
admin.site.register(Author,AuthorAdmin)

Será que você precisa de um objeto ModelAdmin em tudo?

No exemplo anterior, a classe ModelAdmin não define quaisquer valores personalizados (ainda). Sendo assim, a interface padrão do admin será exibida. Se você estiver satisfeito com a interface padrão do admin, não precisa definir um objeto ModelAdmin. Pode apenas registrar a classe model sem fornecer uma descrição ModelAdmin. O exemplo anterior poderia ser simplificado para:

from django.contrib import admin
from myproject.myapp.models import Author
 
admin.site.register(Author)

Opções do ModelAdmin

O ModelAdmin é muito flexível. Tem várias opções para lidar com a personalização da interface. Todas as opções são definidas como uma subclasse do ModelAdmin:

class AuthorAdmin(admin.ModelAdmin):
  ...
 
date_hierarchy

Ao atribuir para date_hierarchy o nome de um DateField ou DateTimeField do seu model, será incluída uma lista para uma navegação detalhada por esse campo.

Exemplo:

date_hierarchy = 'data_cadastro'

form

Por padrão, uma ModelForm é criada dinamicamente para o seu model. É utilizado para criar o formulário que exibirá as páginas de adicionar/ modificar dados. Você pode facilmente fornecer seu próprio ModelForm para substituir qualquer comportamento padrão sobre a forma adicionar/ modificar páginas.
Para ver um exemplo, vá para seção Adicionando Validação Personalizada para o admin.

fieldsets

Usado para controlar o layout das páginas “adicionar” e “modificar”.
Um fieldset é um array de dois valores, em que cada representa um elemento html fieldset.
Os dois valores estão no formato (name, field_options), onde name é uma string representando o título do fieldset e field_options é um dicionário de informações sobre o fieldset, incluindo uma lista de campos a serem exibidos no mesma.

Um exemplo completo, a partir da model django.contrib.flatpages.FlatPage:

class FlatPageAdmin(admin.ModelAdmin):
  fieldsets = (
      (None , {
          'fields' : ( 'url' , 'titulo' , 'conteudo' , 'sites' )
       }),
       ( 'Advanced options' , {
           'classes': ( 'collapse', ),
           'fields': ('enable_comments','registration_required','template_name')
       })
  )

Se não for configurado a propriedade fieldsets, o Django irá exibir por padrão cada campo que seja editável (editable=True) e que não seja de auto incremento (AutoField=True), em um único fieldset, na mesma ordem que os campos foram definidos no model.

O dicionário field_options pode ter as seguintes chaves:

fields

Um array contendo o nome dos campos que serão exibidos neste fieldset. Esta chave é obrigatória.
Exemplo:

{
  'fields' : ( 'nome' , 'sobrenome' , 'endereco' , 'cidade' , 'UF' ),
}

Para exibir vários campos na mesma linha, junte os campos em seus próprios arrays. Neste exemplo, o os campos nome e sobrenome serão exibidos na mesma linha:

{
  'fields': (( 'nome','sobrenome' ),'endereco','cidade','UF' ),
}

classes

Uma lista extra contendo classes CSS para aplicar ao fieldset.
Exemplo:

{
  'classes' : [ 'wide' , 'extrapretty' ],
}

Duas classes úteis definidas pela folha de estilo (stylesheet) padrão do admin são collapse e wide. Fieldsets com estilo collapse serão inicializados reduzidos contendo um botão “clique para expandir”, e com wide ganharão um espaço horizontal extra.

description

Uma string com um texto opcional a ser apresentado no início de cada fieldset, abaixo do título.
Nesse texto os caracteres especiais não são escapados. Utilize django.utils.html.escape() para escapar.

fields

Utilize esta opção como uma alternativa para fieldsets se o layout não o agradar ou se quiser exibir somente um subconjunto dos campos disponíveis no formulário. Por exemplo, você poderia definir uma versão mais simples do form admin com django.contrib.flatpages.FlatPage:

class FlatPageAdmin(admin.ModelAdmin):
  fields = ('url','titulo','conteudo')

No exemplo acima, apenas os campos “url”, “titulo” e “conteúdo” serão exibidos, seqüencialmente, no form.

Nota :
A opção fields não deve ser confundida com o array de campos usado como chave dentro dos fieldsets, tal como descrito na seção anterior.

exclude

Este atributo, se for informado, deve ser uma lista de nomes de campos que não apareceram no form.
Por exemplo, vamos considerar o seguinte model:

class Autor(models.Model):
  nome = models.CharField(max_length=100)
  titulo = models.CharField(max_length=3)
  data_nascimento = models.DateField(blank=True,null=True)

Se você deseja um form que mostre apenas os campos nome e titulo, deve proceder dessa forma:

class AutorAdmin(admin.ModelAdmin):
  fields = ('nome','titulo')
 
class AutorAdmin(admin.ModelAdmin):
  exclude = ('data_nascimento',)

filter_horizontal

Cria um campo personalizado usando javascript ao invés do elemento select no form. The value is a list of fields that should be displayed as a horizontal filter interface. O valor é uma lista de campos que serão exibidos de forma horizontal.

filter_vertical

A mesma coisa que filter_horizontal, mas na forma vertical.

list_display

Utilizado para controlar os campos que são exibidos na página do admin.

Exemplo:

list_display = ('nome','sobrenome')

Se list_display não for utilizada, o admin exibirá uma coluna única com o resultado do método __unicode__() representado em cada objeto.

Há quatro possíveis valores que podem ser utilizados em list_display:

1. Um campo do model. Por exemplo:

class PessoaAdmin(admin.ModelAdmin):
  list_display = ('nome','sobrenome')

2. Uma chamada que aceita como parâmetro um objeto. Por exemplo:

def upper_case_name(obj):
  return "%s %s" % (obj.nome,obj.sobrenome).upper()
upper_case_name.short_description = 'Nome'
 
class PessoaAdmin(admin.ModelAdmin):
  list_display = (upper_case_name,)

3. Uma string representando um atributo do ModelAdmin. Este é o mesmo método chamado. Por exemplo:

class PessoaAdmin (admin.ModelAdmin):
  list_display = ('upper_case_name',)
 
def upper_case_name(self,obj):
  return "%s %s" % (obj.nome,obj.sobrenome).upper()
upper_case_name.short_description = 'Nome'

4. Uma string representando um atributo do model. Exemplo:

class Pessoa(models.Model):
  nome = models.CharField(max_length=50)
  data_nascimento = models.DateField ()
 
  def decada_nasc(self):
    return self.data_nascimento.strftime('%Y')[: 3 ] + "0's"
  decada_nasc.short_description = 'Década da data do nascimento'
 
class PersonAdmin(admin.ModelAdmin):
  list_display = ('nome','decada_nasc')

A alguns casos especiais sobre list_display:

Se o campo for um ForeignKey, Django irá exibir o resultado de __unicode__ () do objeto relacionado.
Campos ManyToManyField não são suportados, porque isso implicaria a execução de uma instrução SQL separada para cada linha na tabela. No entanto, se ainda assim quiser utilizar, é necessário criar um método personalizado contendo o list_display.
Se o campo for um BooleanField ou NullBooleanField, será exibido um ícone de “on” ou “off” ao invés de True ou False.
Se a string fornecida for um método do model, ModelAdmin ou uma função, o Django irá escapar os caracteres HTML. É possível definir quais tags HTML não serão escapadas definindo o valor do atributo allow_tags para True. Exemplo:

class Person(models.Model):
  nome = models.CharField(max_length=50)
  sobrenome = models.CharField(max_length=50)
  cor = models.CharField(max_length=6)
 
  def colorir_nome(self):
    return '<span style="color: #%s;">%s </span>' % (self.cor, self.nome)
  colorir_nome.allow_tags = True
 
class PessoaAdmin(admin.ModelAdmin):
  list_display = ('nome', 'sobrenome', 'cor')

Se a string fornecida for um método do model, ModelAdmin ou uma função e retornar um valor Verdadeiro ou Falso,o Django exibirá um ícone de “on” ou “off” se for definido um atributo com o mesmo nome do método e tiver um valor True.

class Person(models.Model):
  nome = models.CharField(max_length=50)
  data_nascimento = models.DateField()
 
  def nasceu_anos_50(self):
    return self.data_nascimento.strftime('%Y')[:3] == 5
  nasceu_anos_50.boolean = True
 
class PessoaAdmin(admin.ModelAdmin):
  list_display = ('nome', 'nasceu_anos_50')

Os métodos __str__() e __unicode__() são válidos apenas dentro de um list_display ou qualquer outro método de um model, logo é perfeitamente possível o código abaixo:

list_display = ('__unicode__', 'outro_campo_qualquer')

Normalmente, os elementos de um list_display não são campos reais de uma tabela em um banco de dados e não podem ser usados para ordenação de dados. No entanto, se um elemento do list_display representa um determinado campo na tabela, é possível defini-lo como um campo de ordenação utilizando o atributo admin_order_field. Exemplo:

class Person(models.Model):
  nome = models.CharField(max_length=50)
  cor = models.CharField(max_length=6)
 
  def colorir_nome(self):
      return '<span style="color: #%s;">%s</span>' % (self.cor,self.nome)
  colorir_nome.allow_tags = True
  colorir_nome.admin_order_field = 'nome'
 
class PessoaAdmin(admin.ModelAdmin):
  list_display = ('nome', ' colorir_nome')

list_display_links

Utilizado para controlar quais campos definidos no list_display serão linkados à página de “mudanças” do objeto. Por padrão, a página de mudanças terá um link para a primeira coluna – o primeiro campo especificado no list_display. Se for usar list_display_links é necessário definir list_display. Exemplo:

class PessoaAdmin(admin.ModelAdmin):
  list_display = ('nome', 'sobrenome', 'data_nascimento')
  list_display_links = ('nome', 'sobrenome')

list_filter

Utilizado para ativar os filtros na barra lateral direita da página de mudanças do admin. Um exemplo de como list_display e list_filter funcionam:

class UsuarioAdmin(admin.ModelAdmin):
  list_display = ('usuario', 'email', 'nome', 'sobrenome', 'bloqueado')
  list_filter = ('bloquado', 'is_administrador')

list_per_page

Controla quantos itens serão exibidos por cada página quando houver paginação. O padrão é 100.

list_select_related

Obtem os dados de objetos relacionados. Quando utilizado, armazena a consulta em cache, aumentando assim a performance pois evita re-consultas ao banco de dados. O valor deve ser ou True ou False. O padrão é false.
Se um dos campos definidos em list_display for uma ForeignKey, o Django usará esse procedimento independente se for definido um valor True ou False.

Considerações Finais

Existe uma grupo brasileiro dedicado a tradução completa do manual do django. Até agora esse grupo tem feito um excelente trabalho, que pode ser comprovado no site Django Brasil.

Compartilhe esse artigo

Pages: 1 2 3 4