Hi ha una part del desenvolupament web que sempre hem odiat: escriure interfícies d'administració. Desenvolupar les parts del lloc que el públic general veu sempre és diferent i interessant, però els trossos que els administradors utilitzen per modificar el lloc són sempre el mateix. Hauràs d'identificar usuaris, mostrar formularis, i barallar-se amb les complexes sistemes de validació... és avorrit i repetitiu.

Django també és avorrit i repetitiu? Ho fa tot per tu -- en unes poques línies de codi, ni una més.

Una de les parts més antigues i potents de Django és la interfície d'administració automàtica. Aquest agafa les metadades del teu model per proporcionar una interfície realment productiva de manera que els productors de continguts poden usar immediatament per començar a afegir contingut en el lloc.

Activant la interfície d'administrador

Nosaltres pensem que la interfícies d'administració és la part més interessant de Django -- i molts Django-nautes també hi estan d'acord -- però com que actualment no tothom ho necessita, és una part opcional. Això significa que hi ha tres passos que has de seguir per activar la interfície d'administració:

1. Afegeix les metadades d'administració en els teus models.
   
   No tots els models poden (o haurien) de ser editables pels usuaris administradors, tu has de marcar els models que haurien de tenir una interfície d'administració. Has d'afegir una classe Admin interna en el teu model (o fer-ho amb la classe Meta, si la tens). Així, afegeix una interfície d'administració en el teu model Book de capítol anterior:

   class Book(models.Model):
       title = models.CharField(maxlength=100)
       authors = models.ManyToManyField(Author)
       publisher = models.ForeignKey(Publisher)
       publication_date = models.DateField()
   
       class Admin:
           pass
   

   Amb les etiquetes de la declaració d'Admin tenim una interfície d'administració. Hi ha un nombre d'opcions que pots posar junt amb Admin, però per ara ens centrarem amb l'opció per defecte, així que posarem pass per indicar a Python que la classe Admin és buida.

   Si segueixes aquest exemple en el teu codi, probablement serà una bona idea afegir les declaracions d'Admin a les classe Publisher i Author de la mateixa forma.

2. Intal·la els models d'administració. Simplement afegeix "django.contrib.admin" al paràmetre de configuració INSTALLED_APPS i executa python manage.py syncdb per instal·lar les taules extra que utilitza l'administració.

   Nota:
   Quan executes per primera vegada syncdb, probablement t'ha preguntat per crear el compte de super-usuari. Si no ho has fet, cal que executis django/contrib/auth/bin/create_superuser.py per crear un usuari administrador. Sinó, no podràs identificar-te en la interfície d'administració.

3. Afegeix el patró URL al teu fitxer urls.py. Si encara estàs utilitzant el creat per startproject, el patró URL d'administració hauria de ser-hi, comentat. Sinó, la URL hauria de ser així:

   from django.conf.urls.defaults import *
   
   urlpatterns = patterns('',
       (r'^admin/', include('django.contrib.admin.urls')),
   )
   

Ara, executa python manage.py runserver per engegar el servidor de desenvolupament; veuràs quelcom així:

Validating models...
0 errors found.

Django version 0.96-pre, using settings 'ch6.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Ara pots visitar la URL indicada (http://127.0.0.1:8000/admin/ en aquest exemple, identificar-te i jugar-hi.

Utilitzant la interfície d'administració

La interfície d'administració s'ha dissenyat per ser utilitzat per usuaris no tècnics, i que fos auto-explicatori. No obstant, unes quantes indicacions sobre les seves característiques no hi fan cap mal.

Això és la pantalla d'identificació:

Utilitzaràs el nom d'usuari i password que has indicat el primer cop que has executat syncdb. Un cop t'has identificat, veuràs que pots gestionar els usuaris, grups, i permisos per a l'administració; en veuràs més coses després.

Cada objecte on has declarat la classe Admin es mostra en l'index de la pàgina principal. Enllaços per afegir i modificar els objectes et porten a dues pàgines on veurem llistes per modificar i editar els objectes:

Les llistes de modificació són essencialment pàgines d'índex d'objecte en el sistema:

Hi ha un nombre d'opcions que poden controlar quins camps pareixen en aquesets llistes i l'aparença de característiques extra com són marges de dades, camps de certa, i interfícies de filtratge. N'explicarem més sobre aquestes característiques més endavant.

Els formularis d'edició s'utilitzen per editar objectes existents i crear-ne de nous. Cada cap definit en el teu model apareix aquí, i fixa't que els camps de diferents tipus tenen diferents controls (p.e. els camps de data i hora tenen controls de calendari; les claus foranies utilitzen un caixa de selecció, etc.)

Fixa't que l'administrador també comprovar les entrades per tu; intenta deixar en blanc un camp requerit, o posar una data errònia dins del camp de data i veuràs els errors que apareixen quan intentes guardar-ho:

La validació ara funciona amb un potent marc-de-treball potent que en parlarem en el capítol 7.

Quan editem un objecte existent, fixa't en l'enllat "history" a dalt a la dreta. Cada canvi que fas com a administrador queda registrat, i pots examinar aquests registres fent clic en el botó d'història:

Els esborrats en cascada. És a dir, quan esborrem un objecte existent, veuràs que el sistema d'administració et pregunta que confirmis l'acció d'esborrat per evitar registres orfes. Que pot no ser obvi és que aquesta pàgina et mostri tots els objectes relacionats que seran eliminats si hi estem d'acord:

Usuaris, grups i permisos

Des de que t'has identificat com a super-usuari, tens accés per crear, modificar, i eliminar qualsevol objecte. Tanmateix, l'administrador té un sistema de permisos d'usuari que pot usar per donar a altres usuaris només les part de l'administració que necessiti.

Edita aquests usuaris i permisos amb l'administrador com si modifiquessis qualsevol altra objecte; l'enllaç als models User i Group que hi ha l'índex d'administració amb tots els objectes que has definit.

Els objectes d'usuari tenen els camps estàndard: nom d'usuari, contrasenya, correu-e i nom real, a banda d'un conjunt de camps que defineix quins permisos té l'usuari en l'administració. Primer, hi ha aquests tres camps:

• L'etiqueta "is active" controla si l'usuari és actiu. Si no està activa, l'usuari no té accés a cap URL que calgui identificar-se.
• L'etiqueta "is staff" controla si l'usuari té permisos per identificar-se en l'administrador (p.e. és considera un "membre staff" algú de la teva organització). Ja que aquest sistema d'usuari pot utilitzar-se per controlar l'accés als llocs públics (p.e. no administradors) (ho veurem en el capítol 12), aquesta etiqueta diferencia entre el usuaris públics i els administradors.
• L'etiqueta "is superuser" dona a l'usuari un accés complert als permisos d'usuari per accedir a cada element de l'administrador; els permisos normals s'ignoren.

Per a usuaris administradors "normals" -- actius, membres del personal (staff) no super-usuaris -- l'accés està definit depenent dels permisos assignats. Cada objecte editable en l'administrador té tres permisos: un permís de "creació", un permís de "modificació" i un permís d'"esborrat". Assignant permisos a un usuari es garanteix l'accés a fer el que descriuen aquests permisos.

Nota
Fixa't que l'accés per editar usuaris i permisos també poden control·lar-se per aquest sistema de permisos. Si dones permisos a un usuari per a modificar usuaris, podrà donar-se els seus propis permisos, cosa que potser no voldràs.

També pots assignar usuaris a grups. Un grup és simplement un conjunt de permisos per aplicar a tots els membres d'aquest grup. Els grups són molt útils per donar permisos a un gran nombre d'usuaris.

Personalitzar la interfície d'usuari

Hi ha moltes formes per personalitzar com la interfície d'administrador és veu i actua. Només en tractarem un quants que relacionarem amb el nostre model Book, però el Capítol 12 tractarà de personalitzar la interfície d'usuari amb més detall.

Com està ara, la llista d'edició dels nostres llibres només mostra una cadena de representació del model que hem afegit en la funció __str__. Això funció bé per només per a uns quants llibres, però si volem tenir centenars o milers de llibres, serà molt difícil localitzar un únic . Tanmateix, podem afegir fàcilment alguna pantalla amb funcions de cerca i filtratge a aquesta interfície. Canvieu la declaració de Admin per:

class Book(models.Model):
    title = models.CharField(maxlength=100)
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    publication_date = models.DateField()

    class Admin:
        list_display   = ('title', 'publisher', 'publication_date')
        list_filter    = ('publisher', 'publication_date')
        ordering       = ('-publication_date',)
        search_fields  = ('title',)

Aquestes quatre línies de codi canvien dramàticament la nostra llista de la interfície:

Cadascuna d'aquestes línies indiquen a l'administrador que construeixi un peça diferent d'aquesta interfície:

• L'opció ordering controla en quin ordre és mostren els objectes. És simplement una llista dels camps en que s'ordenaran els resultats; prefixant amb un signe negatiu per invertir l'ordre. En aquest exemple, s'ordenaran per data de publicació, amb els més recents primer.
• L'opció list_display controla quines columnes apareixeran en la llista de modificació. Per defecte, només apareix una única columna amb la representació string de l'objecte; aquí hem canviat per mostrar el títol, l'editorial i la data de publicació.
• L'opció list_filter crea una barra de filtres al costat dret de la llista. Hem activat el filtratge per data (que permet veure només llibres publicats l'última setmana, mes, etc), i per editorial.
• Finalment, l'opció search_fields crea un camp per permetre la cerca de textos. Això permet cerques pel camp títol (així, podries escriure "Django" per mostrar tots els llibres amb "Django" en el títol).

Utilitzant aquestes opcions -- i altres que explicarem en el capítol 12 -- pots amb només uns quantes línies de codi fer una interfície molt potent i preparada per la producció per a modificar dades.

Personalitza l'aparença de l'administrador

Realment, tenir el text "Django administration" a la capçalera de cada pàgina d'administració seria ridícul. Ja que només és un text.

Això és fàcil canviar-ho, utilitzant el sistema de plantilles de Django. L'administrador de Django està fet amb el propi Django, i les seves interfícies utilitzen el propi sistema de plantilles de Django.

Obriu el vostre fitxer de configuració (mysite/settings.py, recordeu) i mireu el paràmetre TEMPLATE_DIRS. TEMPLATE_DIRS és una tupla de directoris del sistema de fitxers que comprova quan els carreguen les plantilles de Django. És un camí de cerca.

Per defecte, TEMPLATE_DIRS és buit. Així, afegint-hi una línia, indica a Django on hi ha plantilles:

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

Nota
Assegura't incloure una coma al final -- Python l'utilitza per diferenciar entre tuples d'un sol element i expressions entre parèntesi.

Ara copia la plantilla admin/base_site.html de dins del directori de plantilles d'administració de Django (django/contrib/admin/templates) dins del subdirectori admin o qualsevol directori que utilitzis dins del directori TEMPLATE_DIRS. Per exemple, si inclous /home/mytemplates al paràmetre TEMPLATE_DIRS, com hem indicat a dalt, després django/contrib/admin/templates/admin/base_site.html a /home/mytemplates/admin/base_site.html. No t'oblidis el subdirectori admin.

Llavors, modifica el fitxer admin/base_site.html modificant el text genèric Django per el del vostre lloc web.

Fixa't que qualsevol plantilla d'administració de Django pot sobre-escriure's. Per sobre-escriure una plantilla, fes el mateix que has fet amb admin/base_site.html -- copia'l des del directori per defecte a dins del teus directori personalitzat i fes els canvis en la còpia.

Els lectors astuts es preguntaran com, si el paràmetre TEMPLATE_DIRS era buit per defecte, com Django trobava les plantilles? La resposta és que, per defecte, Django automàticament mira les plantilles dins del sub-directori templates/ de cada paquet d'aplicació. Mira el capítol 10 "Carregadors de plantilles" per tenir més informació sobre com funciona.

Personalitza la pàgina principal de l'administrador

D'una forma semblant, pots personalitzar l'aparença de la pàgina inicial de l'administrador.

Per defecte, mostra totes les aplicacions disponibles, d'acord amb el teu paràmetre INSTALLED_APPS, ordenats pel nom de l'aplicació. Pots, tanmateix, canviar aquest ordre fent que sigui més fàcil trobar les aplicacions en un cop d'ull. Després de tot, l'índex és probablement la pàgina més important de l'administrador, així doncs, hauria de ser fàcil d'utilitzar.

La plantilla per personalitzar-ho és admin/index.html. (Pensa en copiar admin/base_site.html en el teu directori de plantilles personalitzades com en l'exemple previ). Modifica el fitxer, i veuràs que utilitza una etiqueta anomenada {% get_admin_app_list as app_list %}. Aquesta és la que retorna cada aplicació instal·lada a Django. En comptes d'utilitzar aquests, pots per enllaços directes a les pàgines d'administració específiques de la manera que creguis millor. Si els enllaços directes no t'agraden, pots mirar el capítol 10 per a més detalls de com implementar les teves pròpies etiquetes.

Django ofereix una altra drecera en aquesta partat. Executa la comanda python manage.py adminindex per obtenir un tros de codi de plantilla per incloure'l en la plantilla index d'administració. És útil començar per aquest lloc.

Per tots els detalls sobre personalitzar l'aparença del lloc d'administració de Django, mireu el capítol 12.

Quan i perquè utilitzar la interfície d'administració

Pensem que la interfície d'administració de Django és espectacularment maco. En efecte, la podríem anomenar una "característica trencadora" de Django. Tanmateix, sovint rebem preguntes sobre "casos d'ús" per l'administrador -- quan l'utilitzem, i perquè? A base d'anys, hem descobert un nombre de patron per usar la interfície d'administració que creiem que serà d'ajuda.

Òbviament, és extremadament útil per modificar dades. Si tens qualsevol tasca d'entrada de dades, l'administració simplement no ha de descartar-se. Sospitem que la immensa majoria de lectors d'aquest llibre hauran tingut un munt de tasques d'entrada de dades.

L'administrador Django és especialment ideal quan usuaris no tècnics necessiten poder entrar dades, que és la característica original. En el diari on Django va ser desenvolupat inicialment, el desenvolupament d'una característica típica -- un article especial sobre la qualitat de l'aigua del municipi, diu -- va succeir així:

• El reporter responsable de la història es reuneix amb un dels desenvolupadors i parlen sobre les dades disponibles.
• El desenvolupador dissenya el model d'aquestes dades, i llavors obra una interfície d'administració al reporter.
• Mentre el reporter entra les dades a Django, el programador es posa en desenvolupar la interfície accessible públicament (la part divertida!)

En altres feines, la raó d'ús de l'administrador Django és facilitar el feina simultània entre proveïdors de continguts i programadors.

Tanmateix, més enllà de les tasques d'entrada de dades, trobem que l'administrador és útil en uns quants casos:

• Inspeccionar els models de dades: el primer que fem quan hem definit un nou model és cridar a l'administrador i entrar unes quantes dades "tontes". Això és especialment útil per trobar errors en el model de dades; tenint una interfície gra`fica per un model ràpidament revelem aquests errors.
• Gestionar les dades adquirides: hi ha petites dades associades a llocs com chicagocrime.org que s'adquireixen de llocs automàtics. No obstant, quan tenim problemes amb l'adquisició de dades automàtiques, és molt útil poder anar-hi i editar les dades fàcilment.

Què és el Següent?

Més enllà d'haver creat uns quants models i configurats la interfície d'administració per editar aquestes dades. En el pròxim capítol, anirem dins del desenvolupament web real: la creació i el processat.

Pren-te una altra tassa del que més t'agradi i tornem-hi.