El libro de Django 1.

anterior | siguiente

Captulo 6: El sitio de Administracin Django

Contenidos
Captulo 6: El sitio de
Administracin Django
Activar la interfaz de
administracin
Usar la interfaz de
administracin
Usuarios, Grupos y
Permisos
Personalizar la interfaz de
administracin
Personalizar la apariencia
de la interfaz de
administracin
Personalizar la pgina
ndice del administrador
Cundo y porqu usar la
interfaz de administracin
Qu sigue?

Tema anterior
Captulo 5: Interactuar con
una base de datos: Modelos

Prximo tema
Captulo 7: Procesamiento de
formularios

Para cierto tipo de Sitios Web, una interfaz de administracin es una parte esencial de la infraestructura. Se trata de
una interfaz basada en web, limitada a los administradores autorizados, que permite agregar, editar y eliminar el
contenido del sitio. La interfaz que usas para escribir en tu blog, el sitio privado que los editores usan para moderar
los comentarios de los lectores, la herramienta que tus clientes utilizan para actualizar los comunicados de prensa en
la web que construiste para ellos todos son ejemplos de interfaces de administracin.
Aunque hay un problema con las interfaces de administracin: es aburrido construirlas. El desarrollo web es divertido
cuando ests desarrollando funcionalidades de lado pblico del sitio, pero construir interfaces de administracin es
siempre lo mismo. Tienes que autenticar usuarios, mostrar y manipular formularios, validar las entradas y dems. Es
aburrido y repetitivo.
Cul es la solucin de Django para estas tareas aburridas y repetitivas? Las hace todas por ti en slo un par de
lneas de cdigo, ni ms ni menos. Con Django, construir interfaces de administracin es un problema resuelto.
Este captulo trata sobre la interfaz de administracin automtica de Django. Esta caracterstica funciona leyendo los
meta-datos en tus modelos para brindar una interfaz potente y lista para produccin que los administradores del sitio
podrn usar inmediatamente. Aqu discutimos cmo activar, usar y personalizar esta utilidad.

Activar la interfaz de administracin

Pensamos que la interfaz de administracin es la caracterstica ms atractiva de Django y la mayora de
Djangonautas estn de acuerdo pero como no todo el mundo lo necesita, es una pieza opcional. Esto significa que
hay que dar tres pasos para activar la interfaz de administracin:
1. Agrega meta-datos de administracin a tus modelos.

Bsqueda rpida
Ir a
Enter search terms or a module,
class or function name.

No todos los modelos pueden (o deberan) ser editables por los usuarios administradores, por lo
que necesitas marcar los modelos que deberan tener una interfaz de administracin. Esto lo
hacemos aadiendo al modelo una clase interna Admin (junto con la clase Meta, si es que hay una).
As que, para agregar una interfaz de administracin a nuestro modelo Book del captulo anterior,
usamos:
class Book(models.Model):
title = models.CharField(maxlength=100)
authors = models.ManyToManyField(Author)
publisher = models.ForeignKey(Publisher)
publication_date = models.DateField()
num_pages = models.IntegerField(blank=True, null=True)
def __str__(self):
return self.title
class Admin:
pass

La declaracin de Admin marca la clase como poseedora de una interfaz de administracin. Hay
una serie de opciones que podemos incluir bajo Admin, pero por ahora vamos a limitarnos al
comportamiento por defecto, as que escribimos pass para decirle a Python que la clase Admin est
vaca.
Si ests siguiendo este ejemplo escribiendo tu propio cdigo, probablemente sea buena idea
agregar ahora declaraciones de Admin a las clases Publisher y Author.
2. Instalar la aplicacin admin. Esto se hace agregando "django.contrib.admin" a tus INSTALLED_APPS de
tu archivo de configuracin settings.py.
3. Adems, asegurate de que las aplicaciones "django.contrib.sessions", "django.contrib.auth", y
"django.contrib.contenttypes" no estn comentadas, ya que la aplicacin admin depende de ellas.
Tambin descomenta todas las lneas de MIDDLEWARE_CLASSES configurando la tupla, y borra la
definicin de TEMPLATE_CONTEXT_PROCESSOR para permitir que tome los valores por defecto.
4. Ejecuta python manage.py syncdb. Este paso instalar las tablas de la base de datos que la interfaz
de administracin necesita.

Nota: Es probable que la primera vez que ejecutaste syncdb con "django.contrib.auth" en
INSTALLED_APPS, te preguntara algo sobre crear un superusuario. Si no lo hiciste en ese
momento, tendrs que ejecutar django/contrib/auth/bin/create_superuser.py para crear este
usuario administrador. En caso contrario no sers capaz de identificarte para entrar a la interfaz
de administracin.
5. Agrega el patrn de URL en tu urls.py. Si an ests usando el que fue creado por startproject, el
patrn de la URL de administracin ya debera estar ah, pero comentado. De cualquier forma, los
converted by W eb2PDFConvert.com

patrones de URL deberan terminar siendo algo as:

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

Eso es todo. Ahora ejecuta python manage.py runserver para iniciar el servidor de pruebas. Vers algo como esto:
Validating models...
0 errors found.
Django version 0.97, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Ahora puedes visitar la URL que te brinda Django (http://127.0.0.1:8000/admin/ en el ejemplo precedente),
identificarte, y jugar un poco.

Usar la interfaz de administracin

La interfaz de administracin est diseada para ser usada por usuarios no tcnicos, y como tal debera ser lo
suficientemente clara como para explicarse por s misma. An as, se brindan unas pocas notas sobre sus
caractersticas.
Lo primero que vers es una pgina de identificacin, como se muestra en la Figura 6-1.

Figura 6-1. Pantalla de autenticacin de Django.

Usars el nombre de usuario y la clave que configuraste cuando agregaste tu superusuario. Una vez identificado,
vers que puedes gestionar usuarios, grupos y permisos (veremos ms sobre esto en breve).
Cada objeto al que se le di una declaracin Admin aparece en el ndice de la pgina principal, como se muestra en
la Figura 6-2

converted by W eb2PDFConvert.com

Figura 6-2. El ndice principal de la Administracin de Django.

Los enlaces para agregar y modificar objetos llevan a dos pginas a las que nos referiremos como listas de
cambio[1] y formularios de edicin[2] de objetos:

Las listas de cambio son esencialmente pginas de ndices de objetos en el sistema, como se muestra en la Figura
6-3.

Figura 6-3. Una tpica vista de lista de cambio

Hay varias opciones que pueden controlar los campos que aparecen en esas listas y la aparicin de caractersticas
converted by W eb2PDFConvert.com

extra como campos de bsqueda e accesos directo a filtros predefinidos. Ms adelante hablaremos sobre esto.
Los formularios de edicin se usan para modificar objetos existente y crear nuevos (mira la Figura 6-4). Cada campo
definido en tu modelo aparece aqu, y notars que campos de tipos diferentes tienen diferentes controles. (Por
ejemplo, los campos de fecha/hora tienen controles tipo calendario, las claves forneas usan cajas de seleccin,
etc.)

Figura 6-4. Un tpico formulario de edicin

Te dars cuenta que la interfaz de administracin tambin controla por ti la validez de los datos ingresados. Intenta
dejar un campo requerido en blanco o poner una fecha invlida en un campo de fecha, y vers esos avisos de esos
errores cuando intentes guardar el objeto, como se muestra en la Figura 6-5.

converted by W eb2PDFConvert.com

Figura 6-5. Un formulario de edicin mostrando errores

Cuando editas un objeto existente, vers el botn Historia en la esquina superior derecha de la ventana. Cada
cambio realizado a travs de la interfaz de administracin es registrado, y puedes examinar este registro haciendo
click en este botn (mira la Figura 6-6).

Figura 6-6. Pgina de historia de un objeto django.

Cuando eliminas un objeto existente, la interfaz de administracin solicita una confirmacin para prevenir costosos
errores. La eliminacin de un objeto se desencadena en cascada, y la pgina de confirmacin de eliminacin del
objeto muestra todos los objetos relacionados que se eliminarn con l (mira la Figura 6-7).
converted by W eb2PDFConvert.com

Figura 6-7. Una pgina de confirmacin de eliminacin de un objeto Django

Usuarios, Grupos y Permisos

Desde que ests identificado como un superusuario, tienes acceso a crear, editar y eliminar cualquier objeto. Sin
embargo, la interfaz de administracin tiene un sistema de permisos de usuario que puedes usar para darle a otros
usuarios acceso limitado a las partes de la interfaz que ellos necesitan.
Puedes editar estos usuarios y permisos a travs de la interfaz de administracin, como si fuese cualquier otro
objeto. Los vnculos a los modelos Usuarios y Grupos se encuentran en el ndice de la pgina principal junto con todo
el resto de los modelos que haz definido.
Los objetos usuario tienen el los campos estndar nombre de usuario, contrasea, direccin de correo, y nombre
real que puedes esperar, seguidos de un conjunto de campos que definen lo que el usuario tiene permitido hacer en
la interfaz de administracin. Primero, hay un conjunto de tres opciones seleccionables:
La opcin Es staff indica que el usuario est habilitado a ingresar a la interfaz de administracin
(por ejemplo, indica que el usuario es considerado un miembro del staff en tu organizacin). Como
el mismo sistema de usuarios puede usarse para controlar el acceso al sitio pblico (es decir,
sitios restringidos no administrativos. Mira el Captulo 12.), esta opcin diferencia entre usuarios
pblicos y administradores.
La opcin Activo define si el usuario est activo en todo sentido. Si est desactivada, el usuario
no tendr acceso a ninguna URL que requiera identificacin.
La opcin es superusuario da al usuario completo e irrestricto acceso a todos los elementos de la
interfaz de administracin, y sus permisos regulares son ignorados.
Los administradores normales esto es, activos, no superusuarios y miembros del staff tienen accesos que
dependen del conjunto de permisos concedidos. Cada objeto editable a travs de la interfaz de administracin tiene
tres permisos: un permiso de crear[3], un permiso de modificar[4], y un permiso de eliminar[5]. Lgicamente,
asignando permisos a un usuario habilitas que este acceda a realizar la accin que el permiso describe.

Nota: El acceso a editar usuarios y permisos tambin es controlado por el sistema de permisos. Si le das a
alguien el permiso de editar usuarios, estar en condiciones de editar sus propios permisos, que probablemente
no es lo que queras!
Tambin puedes asignar usuarios a grupos. Un grupo es simplemente un conjunto de permisos a aplicar a todos los
usuarios de ese grupo. Los grupos son tiles para otorgar idnticos permisos a un gran nmero de usuarios.

Personalizar la interfaz de administracin

Puedes personalizar el aspecto y la forma en que la interfaz de administracin se comporta de varias maneras. En
converted by W eb2PDFConvert.com

esta seccin slo vamos a cubrir algunas de ellas relacionadas con nuestro modelo Libro. El Captulo 17 descubre
la personalizacin de la interfaz de administracin en detalle.
Como estamos ahora, la lista de cambio de nuestros libros slo muestra la cadena de representacin del modelo
que agregamos con el mtodo __str__
Esto funciona bien slo para algunos libros, pero si tuviramos cientos o miles de libros, se volvera tan difcil como
encontrar una aguja en un pajar. Sin embargo, fcilmente podremos agregar algunas columnas, funciones de
bsqueda y filtros y a esta interfaz. Cambia la declaracin de Admin como sigue:
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,)

Estas cuatro lneas de cdigo cambian dramticamente la interfaz de nuestra lista, como se muestra en la figura 6-8.

Figura 6-8. Pgina de lista de cambios modificada

Cada una de estas lneas indica a la interfaz de administracin que construya diferentes piezas de la interfaz:
La opcin list_display controla que columnas aparecen en la tabla de la lista. Por defecto, la lista
de cambios muestra una sola columna que contiene la representacin en cadena de caracteres del
objeto. Aqu podemos cambiar eso para mostrar el ttulo, el editor y la fecha de publicacin.
La opcin list_filter crea una barra de filtrado del lado derecho de la lista. Estaremos habilitados
a filtrar por fecha (que te permite ver slo los libros publicados la ltima semana, mes, etc.) y por
editor.
Puedes indicarle a la interfaz de administracin que filtre por cualquier campo, pero las claves
forneas, fechas, booleanos, y campos con un atributo de opciones choices son las que mejor
funcionan. Los filtros aparecen cuando tienen al menos 2 valores de dnde elegir.
La opcin ordering controla el orden en el que los objetos son presentados en la interfaz de
administracin. Es simplemente una lista de campos con los cuales ordenar el resultado;
anteponiendo un signo menos a un campo se obtiene el orden reverso. En este ejemplo,
ordenamos por fecha de publicacin con los ms recientes al principio.
Finalmente, la opcin search_fields crea un campo que permite buscar texto. En nuestro caso,
converted by W eb2PDFConvert.com

buscar el texto en el campo ttulo (entonces podras ingresar Django para mostrar todos los
libros con Django en el ttulo).
Usando estas opciones (y las otras descriptas en el captulo 17) puedes, con slo algunas lneas de cdigo, hacer
una interfaz de edicin de datos realmente potente y lista para produccin.

Personalizar la apariencia de la interfaz de administracin

Claramente, tener la frase Administracin de Django en la cabecera de cada pgina de administracin es ridculo.
Es slo un texto de relleno que es fcil de cambiar, usando el sistema de plantillas de Django. El sitio de
administracin de Django est propulsado por el mismo Django, sus interfaces usan el sistema de plantillas propio
de Django. (El sistema de plantillas de Django fue presentado en el Captulo 4.)
Como explicamos en el Captulo 4, la configuracin de TEMPLATE_DIRS especifica una lista de directorios a verificar
cuando se cargan plantillas Django. Para personalizar las plantillas del sitio de administracin, simplemente copia el
conjunto relevante de plantillas de la distribucin Django en uno de los directorios apuntados por TEMPLATE_DIRS.
El sitio de administracin muestra Administracin de Django en la cabecera porque esto es lo que se incluye en la
plantilla admin/base_site.html. Por defecto, esta plantilla se encuentra en el directorio de plantillas de administracin
de Django, django/contrib/admin/templates, que puedes encontrar buscando en tu directorio site-packages de Python,
o donde sea que Django fue instalado. Para personalizar esta plantilla base_site.html, copia la original dentro de un
subdirectorio llamado admin dentro de cualquiera del directorio de TEMPLATE_DIRS que ests usando. Por ejemplo, si tu
TEMPLATE_DIRS incluye "/home/misplantillas", entonces copia django/contrib/admin/templates/admin/base_site.html a
/home/misplantillas/admin/base_site.html. No te olvides del subdirectorio admin.
Luego, slo edita el nuevo archivo admin/base_site.html para reemplazar el texto genrico de Django, por el nombre
de tu propio sitio, tal como lo quieres ver.
Nota que cualquier plantilla por defecto de Django Admin puede ser reescrita. Para reescribir una plantilla, haz lo
mismo que hicimos con base_site.html: copia esta desde el directorio original a tu directorio personalizado y haz los
cambios sobre esta copia.
Puede que te preguntes cmo, si TEMPLATE_DIRS estaba vaci al principio, Django encuentra las plantillas por defecto
de la interfaz de administracin. La respuesta es que, por defecto, Django automticamente busca plantillas dentro
del subdirectorio templates/ de cada paquete de aplicacin como alternativa. Mira el captulo 10 para obtener ms
informacin sobre cmo funciona esto.

Personalizar la pgina ndice del administrador

En una nota similar, puedes tener la intencin de personalizar la apariencia (el look & feel) de la pgina principal del
administrador. Por defecto, aqu se muestran todas las aplicaciones, de acuerdo a la configuracin que tenga
INSTALLED_APPS, ordenados por el nombre de la aplicacin. Quizs quieras, por ejemplo, cambiar el orden para hacer
ms fcil ubicar determinada aplicacin que ests buscando. Despus de todo, la pgina inicial es probablemente
la ms importante de la interfaz de administracin, y debera ser fcil utilizarla.
La plantilla para personalizarla es admin/index.html. (Recuerda copiar admin/index.html a tu directorio de plantillas
propio como en el ejemplo previo). Edita el archivo, y vers que usa una etiqueta llamada {% get_admin_app_list as
app_list %}. Esta etiqueta devuelve todas las aplicaciones Django instaladas. En vez de usar esta etiqueta, puedes
incluir vnculos explcitos a objetos especficos de la manera que creas ms conveniente. Si cdigo explcito en una
plantilla no te satisface, puedes ver el Captulo 10 para encontrar detalles sobre cmo implementar tu propias
etiquetas de plantillas.
Django ofrece otro acceso directo en este apartado. Ejecuta el comando python manage.py adminindex <aplicacin>
para obtener un pedazo de cdigo de plantilla para incluir en la pgina ndice del administrador. Es un punto de
partida bastante til.
Para detalles completos sobre la personalizacin del sitio de administracin de Django, mira el Captulo 17.

Cundo y porqu usar la interfaz de administracin

Pensamos que la interfaz de administracin de Django es bastante espectacular. De hecho, diramos que es una de
sus killer feautures, o sea, una de sus caractersticas sobresalientes. Sin embargo, a menudo nos preguntan sobre
casos de uso para la interfaz de administracin (Cundo debemos usarlo y por qu?). A lo largo de los aos,
hemos descubierto algunos patrones donde pensamos que usar la interfaz de administracin resulta til.
Obviamente, es muy til para modificar datos (se vea venir). Si tenemos cualquier tipo de tarea de introduccin de
datos, el administrador es difcil de superar. Sospechamos que la gran mayora de lectores de este libro tiene una
horda de tareas de este tipo.
La interfaz de administracin de Django brilla especialmente cuando usuarios no tcnicos necesitan ser capaces de
ingresar datos; ese es el propsito detrs de esta caracterstica, despus de todo. En el peridico donde Django fue
creado originalmente, el desarrollo de una caracterstica tpica online un reporte especial sobre la calidad del agua

converted by W eb2PDFConvert.com

del acueducto municipal, pongamos implicaba algo as:

El periodista responsable del artculo se rene con uno de los desarrolladores y discuten sobre la
informacin disponible.
El desarrollador disea un modelo basado en esta informacin y luego abre la interfaz de
administracin para el periodista.
Mientras el periodista ingresa datos a Django, el programador puede enfocarse en desarrollar la
interfaz accesible pblicamente (la parte divertida!).
En otras palabras, la razn de ser de la interfaz de administracin de Django es facilitar el trabajo simultneo de
productores de contenido y programadores.
Sin embargo, ms all de estas tareas de entrada de datos obvias, encontramos que la interfaz de administracin
es til en algunos otros casos:

Inspeccionar modelos de datos: La primer cosa que hacemos cuando hemos definido un nuevo
modelo es llamarlo desde la interfaz de administracin e ingresar algunos datos de relleno. Esto es
usual para encontrar errores de modelado; tener una una interfaz grfica al modelo revela
problemas rpidamente.
Gestin de datos adquiridos: Hay una pequea entrada de datos asociada a un sitio como
http://chicagocrime.org, puesto que la mayora de los datos provienen de una fuente automtica.
No obstante, cuando surgen problemas con los datos automticos, es til poder entrar y editarlos
fcilmente.

Qu sigue?
Hasta ahora hemos creado algunos modelos y configurado una interfaz de primera clase para modificar datos. En el

prximo captulo, nos meteremos en el verdadero guiso del desarrollo Web: creacin y procesamiento de
formularios.
[1]
[2]
[3]
[4]
[5]

N. del T.: change list es el nombre que recibe en ingls

N. del T.: edit forms es el nombre que recibe en ingls
N. del T.: En el control de seleccin de permisos aparece como Can add
N. del T.: Can change
N. del T.: Can delete

El libro de Django 1.0

anterior | siguiente
Copyright 2006, Adrian Holovaty & Jacob Kaplan-Moss.

converted by W eb2PDFConvert.com