Enfim, estou aqui para escrever algo sobre o branch do NewForms-Admin [1].

Nas últimas semanas tenho convivido diariamente com Bazaar [2], NewForms-Admin e problemas dos mais variados com meu PC principal. Destes, apenas o terceiro não é uma ótima coisa, mas me excitei bastante com o assunto de hoje.

Quem tem alguma convivência comigo no assunto de Django, sabe muito bem da minha birra com o Admin e helpers do NewForms (form_for_instance e form_for_model). É que esses dois em especial sempre se apresentaram boas ferramentas para Hello World* mas nada eficazes para a prática. O Admin antigo ainda tinha um problema de filosofia, misturando as definições, que eram distribuídas pelas classes de modelo afora.

Mas as maravilhas que o NewForms tem feito estão fazendo ótimos efeitos. O ModelForms foi realmente uma boa sacada, e o NewForms-Admin também, que comecei a utilizar por recomendação do Yuri [3], que já vem utilizando-o desde junho e que iríamos usar uma aplicação em comum, e acabei por gostando muito desta nova versão do contrib.

Pois bem, vamos ao que interessa.

O que é o NewForms-Admin

Quem conviveu com os forms antigos (oldforms [4]) sabe a grande diferença que fez os novos forms (newforms [5]), mas uma das coisas que impedem de os forms antigos serem eliminados por completo é exatamente o Admin, uma convidativa e útil ferramenta do framework.

Este branch - um branch é uma ramificação do projeto com um objetivo que, ao ficar completa, volta a fazer parte do tronco oficial, o trunk - tem o objetivo de sanar alguns erros de filosofia e aplicar os NewForms ao Admin, ou seja, resolver todos seus problemas críticos.

É importante informar que o branch é um Django completo, que vez por outra é sincronizado com o trunk, garantindo assim suas melhorias constantes, ainda que com um pequeno delay. Portanto, o branch trata-se de um Django completo, porém, diferente.

Baixando o branch

Antes de baixar e instalar o branch é importante salientar que ainda que ele esteja muito estável e consistente, ainda assim, é um branch. Portanto, é recomendável que mantenha o trunk instalado normalmente como instalação oficial do Django, indicando manualmente em seu projeto a versão do branch - você verá como fazer isso neste artigo.

Faça o download o branch, utilizando-se do svn [6]:

svn co http://code.djangoproject.com/svn/django/branches/newforms-admin/

Faça isso de preferência em alguma pasta semelhante à esta (o meu caso) - observando que este caminho é típico de Linux/Unix/MacOSX, mas você pode se utilizar de um caminho parecido no Windows:

/home/django/

Será criada uma pasta no seguinte caminho, contendo o Django completo - incluindo documentação, testes, etc.:

/home/django/newforms-admin/

Preparando um projeto de primeiras impressões

Agora crie seu projeto, vamos dar a ele o nome de "meu_projeto":

django-admin.py startproject meu_projeto

No meu caso, foi criado um projeto no seguinte caminho:

/home/marinho/Lab/meu_projeto

Dentro, crio uma aplicação, chamada "financas":

django-admin.py startapp financas

Ok, agora basta proceder com o básico da preparação de um projeto em Django - configurar conexão com o banco de dados, caminho para o templates e configurar INSTALLED_APPS, não se esquecendo de que uma das aplicações que devem ser acrescentadas a esta setting é o 'django.contrib.admin' - este artigo foi criado seguindo a premissa de que o leitor conhece o básico do framework.

Vamos agora modificar o projeto para que ele utilize o Django do branch, e não o instalado nas bibliotecas do Python. Para isso, adicione as seguintes linhas no início do arquivo manage.py:

import os, sys
sys.path = ['/home/django/newforms-admin/'] + sys.path

É importante que o caminho do branch fique ANTES do sys.path para que ele sobreponha a versão instalada no Python.

Criando as classes de modelo - primeiras diferenças

Vamos criar três classes de modelo para colocar em prática as novidades do branch, como abaixo:

class Historico(models.Model):
    descricao = models.CharField(max_length=50)

    def __unicode__(self):
        return self.descricao

class Pessoa(models.Model):
    nome = models.CharField(max_length=50)

    def __unicode__(self):
        return self.nome

class Lancamento(models.Model):
    tipo = models.CharField(max_length=1, choices=(('C', 'Crédito'), ('D', 'Débito')), default='D')
    historico = models.ForeignKey('Historico')
    pessoa = models.ForeignKey('Pessoa')
    valor = models.DecimalField(max_digits=15, decimal_places=2)
    data_vencimento = models.DateField(null=True, blank=True)
    data_pagamento = models.DateField(null=True, blank=True)
    status = models.CharField(max_length=1, choices=(('P', 'Pendente'), ('G', 'Pago')), default='P')
    observacoes = models.TextField(null=True, blank=True)

    def __unicode__(self):
        return "%s - %f" %( self.pessoa, self.valor )

Note a ausência da class Admin nas classes - lembrando que o método __unicode__ continua tão importante como sempre foi, assim como a class Meta.

Criando um módulo específico para o Admin

Agora vamos criar um módulo para contêr as parametrizações do Admin, chamado admin.py, dentro da pasta da aplicação:

from django.contrib import admin

from financas.models import Historico, Pessoa, Lancamento

admin.site.register(Historico)
admin.site.register(Pessoa)
admin.site.register(Lancamento)

Configurando a URL

Outra mudança essencial foi na forma como se declara a URL do Admin. Veja abaixo como fica a pattern:

(r'^admin/(.*)', admin.site.root),

Mas isso ainda não é suficiente porque, como pode observar, o admin.site.root está em Python, o que implica na seguinte importação no início do arquivo urls.py:

from django.contrib import admin

Ok, isso será suficiente para o projeto funcionar e permitir o acesso à página de administração, entretanto, ao fazer esse teste você irá sentir a falta das classes que parametrizamos no módulo admin.py. Isso ocorre porque esse módulo precisa também ser importado no módulo urls.py, assim:

from financas.admin import *

Pronto, ao rodar o runserver irá notar as classes prontamente de volta à produção! Mas ainda não é suficiente, vamos dar uma olhadela em como fazer aqueles mesmos parâmetros que estávamos acostumados na class Admin, se lembra? Para isso, voltemos ao módulo admin.py, que deve agora ficar da seguinte forma:

from django.contrib import admin
from django.contrib.admin.options import ModelAdmin

from financas.models import Historico, Pessoa, Lancamento

class AdminLancamento(ModelAdmin):
    list_display = ('pessoa','historico','valor','data_vencimento','status')
    search_fields = ('pessoa','historico','valor')
    list_filter = ('pessoa','historico','valor','data_vencimento','status')

admin.site.register(Historico)
admin.site.register(Pessoa)
admin.site.register(Lancamento, AdminLancamento)

Pronto, agora voltamos ao estágio que estávamos no antigo Admin: parametrizações funcionando corretamente :)

Numa próxima oportunidade, vamos explorar outras novidades do branch, como a classe InlineModelAdmin, os templates (que estão um tanto mais coesos), como utilizar Ajax a torte e a direito, master/detalhe, etc.

Espero que tenha sido util! Um abraço e boa semana para todos!

Links relacionados