Fazendo Mais com o Admin do Django

from django.contrib import admin from more_with_admin.examples import models
class CommentInline(admin.TabularInline):
    model = models.Comment

class DocumentAdmin(admin.ModelAdmin):
    inlines = [CommentInline,]

class CommentAdmin(admin.ModelAdmin):
    pass

admin.site.register(models.Document, DocumentAdmin) 
admin.site.register(models.Comment, CommentAdmin)
      

A Figura 4 mostra a nova página de inclusão/edição após a inclusão do controle TabularInline.

Certamente, ela é poderosa, mas pode ser arrasadora se você quiser ter apenas uma visualização rápida dos comentários.

Você pode utilizar duas abordagens aqui. Uma é editar os widgets HTML associados à inline usando a interface do widget do admin do Django. A documentação do Django descreve widgets em detalhes. A outra abordagem é modificar o modelo de inclusão/edição diretamente. Essa abordagem é mais útil quando você não quer usar nenhum recurso específico do admin.

Se você não quiser permitir nenhuma edição dos comentários (talvez porque os usuários não tenham permissões suficientes), mas certamente quer que eles consigam ver os comentários, utilize a abordagem de modificação de change_form.html.

Variáveis Fornecidas pelo Admin do Django

Para incluir funcionalidade a uma página de instância do modelo, você precisa saber quais dados já estão disponíveis a partir do admin. As duas principais variáveis são descritas abaixo.

Criando uma Tag de Modelo para Inclusão na Página do Admin

Listar os comentários relacionados requer código que não pode ser inserido diretamente em um modelo do Django. A melhor solução para isso é utilizar uma tag de modelo. Primeiro, crie o diretório da tag de modelo e o arquivo __init__.py:

$ mkdir examples/templatetags/
$ touch examples/templatetags/__init__.py

Crie um novo arquivo chamado examples/templatetags/example_tags.py e inclua o código mostrado abaixo.

from django import template
from examples import models

register = template.Library()

@register.inclusion_tag('comments.html')
def display_comments(document_id):
    document = models.Document.objects.get(id__exact=document_id)
    comments = models.Comment.objects.filter(document=document)[0:5]
    return { 'comments': comments }
      

Como essa é uma tag de inclusão, você precisa criar o arquivo de modelo correspondente: comments.html. Edite o arquivo examples/templates/comments.html e insira o código da listagem 8.

{% for comment in comments %}
<blockquote>{{ comment.text }}</blockquote>
{% endfor %}

Agora é hora de incluir isso na página administrativa. Comente as referências a CommentInline em admin.py e faça as mudanças mostradas na Listagem 9 para sua versão local de change_form.html.

{% extends "admin/change_form.html" %}

{% load example_tags %}

{% block after_field_sets %}
  {% if object_id %}{% display_comments object_id %}{% endif %}
  {% endblock %}

É importante verificar a existência de object_id antes de tentar utilizá-lo, pois change_form.html também é utilizado para a criação de novas instâncias, em cujo caso object_id ainda não está disponível.

O bloco after_field_sets é apenas um dos vários fornecidos como pontos de extensão no admin. Consulte a página de origem change_form.html para conhecer outros.

A Figura 5 mostra o formulário atualizado.

Voltar para parte superior

Modificando o Comportamento Administrativo

As substituições de modelos só podem fazer isso. E se você quiser alterar o comportamento e o fluxo reais do admin? Remover a origem é uma possibilidade, mas isso o bloqueia na versão específica do Django que você está utilizando no momento da atualização.

Substituindo Métodos AdminModel

Por padrão, um clique em Salvar no admin retorna o usuário à página de listas. Geralmente isso é bom, mas e se você quiser ir diretamente a uma página de visualização para um objeto que está fora do admin? Esse é um caso de uso comum quando você está desenvolvendo um content management system (CMS).

Fornecendo o Método get_absolute_url() A Listagem 10 supõe que o Documento tenha sido modificado para incluir um método get_absolute_url(), que é a forma recomendada para um modelo Django especificar sua representação canônica. Se isso for especificado, o admin do Django também fornecerá um botão útil Visualizar no Site em cada página desse modelo.

A maioria da funcionalidade no aplicativo administrativo está conectada à classe admin.ModelAdmin. Essa é a classe da qual os objetos herdam em admin.py. Existem muitos, mas muitos, métodos públicos que você pode substituir. Verifique a origem em admin-source/options.py para obter a definição de classe.

Existem duas maneiras de se alterar o comportamento do botão Salvar: Você pode substituir admin.ModelAdmin.response_add, que é responsável pelo redirecionamento real após um salvamento, ou pode substituir admin.ModelAdmin.change_view. A segunda opção é um pouco mais simples e é ilustrada abaixo.

class DocumentAdmin(admin.ModelAdmin):

    def change_view(self, request, object_id, extra_context=None):

        result = super(DocumentAdmin, self).change_view(request, object_id, extra_context)

        document = models.Document.objects.get(id__exact=object_id)

        if not request.POST.has_key('_addanother') and
              not request.POST.has_key('_continue'):
            result['Location'] = document.get_absolute_url()
        return result

Agora, quando os usuários clicam em Salvar, eles são redirecionados para a página de visualização, e não para a página de lista mostrando todos os Documentos.

Incluindo Recursos no Admin com Sinais

Sinais são um recurso pouco utilizado no Django que melhora a modularidade de seu código. Os sinais definem eventos, como salvar um modelo ou inserir um modelo, que funcionam em qualquer lugar onde o projeto Django possa atender e responder. Isso significa que você pode melhorar facilmente o comportamento dos aplicativos, sem ter que modificá-los diretamente.

O admin fornece um recurso que os desenvolvedores de aplicativo muitas vezes querem alterar: o gerenciamento de usuários via classe django.contrib.auth.models.User. Muitas vezes, o admin é o único lugar onde os usuários do Django são incluídos ou modificados, dificultando a customização dessa classe útil.

Imagine que você queira que o administrador do site receba um e-mail cada vez que um novo objeto User for criado. Como o modelo User não está diretamente disponível no projeto, pode parecer que a única maneira de se fazer isso é criando a subclasse de User ou utilizando um método indireto, como a criação de um objeto de perfil simulado para modificar.

Em vez disso, a Listagem 11 demonstra como é fácil incluir uma função que é executada quando uma instância de User é salva. Sinais geralmente são incluídos no models.py.

from django.db import models
from django.db.models import signals
from django.contrib.auth.models import User
from django.core.mail import send_mail

class Document(models.Model):
    [...]

class Comment(models.Model):
    [...]

def notify_admin(sender, instance, created, **kwargs):
    '''Notifique o administrador de que um novo usuário foi incluído.'''
    if created:
       subject = 'New user created'
       message = 'User %s was added' % instance.username
       from_addr = 'no-reply@example.com'
       recipient_list = ('admin@example.com',)
       send_mail(subject, message, from_addr, recipient_list)

signals.post_save.connect(notify_admin, sender=User)

O sinal post_save é fornecido pelo Django e dispara sempre que um modelo é salvo ou criado. O método connect() aqui está usando dois argumentos: um retorno de chamada (notify_admin) e o argumento sender, que especifica que esse retorno de chamada só está interessado em salvar eventos do modelo User.

Dentro do retorno de chamada, o sinal post_save passa o emissor (a classe de modelo), a instância desse modelo e um booleano, criado, que indica se a instância acabou de ser criada. Nesse exemplo, o método envia uma mensagem de e-mail se o User estiver sendo criado; caso contrário, ele não faz nada.

Uma lista de outros sinais fornecidos pelo Django é fornecida em Recursos, bem como a documentação sobre como gravar seus próprios sinais.

Voltar para parte superior

Modificações Intensas: Incluindo Permissões no Nível da Linha

Um recurso solicitado com frequência do admin do Django é o referente a que seu sistema de permissão seja estendido para incluir permissões de nível de linha. Por padrão, o admin permite um controle de granularidade fina de funções e direitos, mas essas funções se aplicam apenas no nível da classe: um usuário pode modificar todos os Documentos ou nenhum.

Muitas vezes, é desejável permitir que os usuários modifiquem apenas objetos específicos. Eles costumam ser chamados de permissões de nível de linha porque refletem a capacidade de modificar apenas linhas específicas de uma tabela de banco de dados, e não uma permissão geral para modificar qualquer registro na tabela.

Um caso de uso no aplicativo examples pode ser o que você queira que os usuários consigam ver apenas os Documentos que eles criaram.

Primeiro, atualize models.py para incluir um atributo gravando quem criou o Documento, conforme mostrado abaixo.

Por que blank=True? Talvez não fique imediatamente óbvio porque um campo ForeignKey seria configurado com blank=True quando ele não é um campo de texto. Nesse caso, é porque o admin do Django utiliza em branco em vez de nulo para determinar se o valor deve ser configurado manualmente antes de o modelo ser salvo. Se você fornecer apenas null=True ou nada, o admin do Django forçará o usuário a selecionar manualmente um valor "incluído por" antes do salvamento, quando você quiser que o comportamento seja padronizado para o usuário atual no salvamento.

from django.db import models
from django.db.models import signals
from django.contrib.auth.models import User
from django.core.mail import send_mail

class Document(models.Model):
    name = models.CharField(max_length=255)
    text = models.TextField()
    added_by = models.ForeignKey(User, null=True, blank=True)

    def get_absolute_url(self):
        return 'http://example.com/preview/document/%d/' % self.id

    def __unicode__(self):
        return self.name
[...]
      

Em seguida, você precisa incluir código para gravar automaticamente qual usuário criou o Documento. Sinais não funcionam para isso porque não têm acesso ao objeto do usuário. Entretanto, a classe ModelAdmin fornece um método que inclui o pedido e, portanto, o usuário atual como um parâmetro.

Modifique o método save_model() em admin.py, conforme mostrado abaixo.

from django.contrib import admin

class DocumentAdmin(admin.ModelAdmin):
    def save_model(self, request, obj, form, change):
        if getattr(obj, 'added_by', None) is None:
            obj.added_by = request.user
        obj.last_modified_by = request.user
        obj.save()

[...]
      

Se o valor de added_by for None, esse será um novo registro que não foi salvo. (Você também poderia verificar se change é false, o que indica que o registro está sendo incluído, mas verificar se added_by está vazio significa que ele também preenche registros que foram incluídos fora do admin.)

A próxima parte das permissões no nível da linha é restringir a lista de documentos apenas aos usuários que as criaram. A classe ModelAdmin fornece um gancho para isso através de um método chamado queryset(), que determina o conjunto de consultas padrão retornado por qualquer página de lista.

Conforme mostrado na Listagem 14, substitua queryset() para restringir a listagem apenas aos Documentos criados pelo usuário atual. Os superusuários podem ver todos os documentos.

from
django.contrib import admin from more_with_admin.examples import models
class DocumentAdmin(admin.ModelAdmin):

    def queryset(self, request):
        qs = super(DocumentAdmin, self).queryset(request)

        # Se for superusuário, mostre todos os comentários
        if request.user.is_superuser:
            return qs

        return qs.filter(added_by=request.user)
[...]
      

Agora quaisquer pedidos para a página de lista Documento no admin mostram apenas aqueles criados pelo usuário atual (a menos que o usuário atual seja um superusuário, em cujo caso, todos os documentos são mostrados).

É claro que, atualmente, nada impede um determinado usuário de acessar uma página de edição para um documento desautorizado sabendo seu ID. As permissões de nível de linha realmente seguras requerem mais substituição de métodos. Como os usuários admin geralmente são confiáveis de alguma forma, às vezes as permissões básicas são suficientes para se fornecer um fluxo de trabalho simplificado.

Voltar para parte superior

Conclusão

A customização do admin do Django não requer conhecimento do código de origem do admin, mas sim uma certa pesquisa minuciosa. O admin é estruturado para ser extensível utilizando-se herança Python normal e alguns recursos exclusivos do Django, como sinais.

As vantagens da customização do admin sobre a criação de uma interface de administração totalmente nova são muitas:

• Seu aplicativo se beneficia dos avanços no Django conforme o desenvolvimento continua.
• O admin já suporta os casos de uso mais comuns.
• Aplicativos externos incluídos em seu projeto são automaticamente administráveis lado a lado com seu próprio código.

Pensando no futuro para o Django V1.1 (com release planejado para abril de 2009), o admin fornece dois novos recursos que muitas vezes são solicitados: a capacidade de edição de campos sequenciais nas páginas de lista e ações administrativas, as quais permitem atualizações em massa em muitos objetos de uma vez. Ambas as inclusões removerão a necessidade de gravar esses recursos comuns do zero durante a inclusão de pontos de extensão para customização adicional.

Recursos

• Os desenvolvedores que estão apenas começando no Django ou admin devem começar com o excelente Tutorial do Django.
  
  
• A documentação administrativa principal e o código de origem administrativo são as melhores referências completas para tudo no admin.
  
  
• As referências para sinais incluem a lista de sinais fornecidos pelo Django e sua documentação sobre a definição de seus sinais.
  
  
• Aprenda sobre os dois novos recursos administrativos do Django V1.1: ações administrativas e listas editáveis.
  
  
• Os exemplos neste artigo demonstraram a edição de páginas específicas de modelos. Se você precisar editar páginas através de vários modelos, familiarize-se com a estrutura contenttypes do Django.
  
  
• A documentação do Django inclui uma lista completa de todos os mecanismos de banco de dados suportados pelo Django. Desde o Django V1.0, é possível definir novos mecanismos externos também.
  
  
• Saiba mais sobre a técnica de substituir o comportamento de redirecionamento no admin.
  
  
• Navegue pela livraria tecnológica para localizar livros sobre esses e outros tópicos técnicos.
  
  
• Para ouvir entrevistas e discussões interessantes para desenvolvedores de software, consulte podcasts do developerWorks.
  
  
• Mantenha-se atualizado com os eventos Técnicos do developerWorks' e webcasts.
  
  
• Siga o developerWorks no Twitter.
  
  
• Consulte novas conferências, exposições, webcasts e outros Eventos em todo o mundo que são extremamente interessantes para desenvolvedores de software livre da IBM.
  
  
• Visite a Zona de software livre do developerWorks para obter informações sobre instruções extensivas, ferramentas e atualizações de projetos para ajudar você a desenvolver tecnologias de software livre e a utilizá-las com os produtos da IBM.
  
  
• Assista e aprenda sobre as tecnologias IBM e de software livre e funções de produtos gratuitamente com as Demos On Demand do developerWorks.
  
  

• Muitas distribuições Linux®, bem como Mac OS® X, são fornecidas com SQLite, mas caso não seja esse seu sistema, você pode fazer o download do SQLite no site do projeto.
  
  
• Desde a V2.5, o Python é um pacote configurável com suporte para SQLite e não requer nenhum outro driver. Para versões anteriores do Python, você deve fazer o download do pysqlite diretamente.
  
  
• Inove seu próximo projeto de desenvolvimento de software livre com software de avaliação IBM, disponível para download ou em DVD.
  
  
• DownloadVersões de avaliação do produto IBM ou explore as avaliações on-line no IBM SOA Sandbox e tenha em mãos as ferramentas de desenvolvimento de aplicativos e os produtos de middleware do DB2®, Lotus® , Rational®, Tivoli® e WebSphere®.

• Participe dos blogs do developerWorks e envolva-se na comunidade do developerWorks.
  
  

Sobre o autor

		Liza Daly é uma engenheira de software especializada em aplicativos para o segmento de mercado de publicações. Ela é desenvolvedora líder dos principais produtos on-line da Oxford University Press, O'Reilly Media, e de outros publicadores. Atualmente, ela é uma consultora independente e fundadora da Threepress, um projeto de software livre desenvolvendo aplicativos ebook.

Avalie esta página

Reserve um instante para completar este formulário para nos ajudar a servi-lo melhor. As informações o ajudaram a alcançar seu objetivo? Sim Não Não sei   Faça comentários para ajudar a melhorar esta página:   Quão úteis são as informações? 1 2 3 4 5 Não são úteis Extremamente úteis

Voltar para parte superior