Django + jqGrid

En este post veremos como integrar jqGrid (potente grid basado en jQuery) en los templates Django.

Si desean una mayor usabilidad o quieren agregar un extra a sus aplicaciones web Django, este post les mostrará como hacerlo.

La administración en Django (admin Django) se basa en la utilización de una serie de vistas, por ejemplo tenemos la lista de cambios (template change_list.html) que tiene una serie de funcionalidades para buscar, ordenar, paginar y filtrar registros, también tenemos los formularios para agregar o modificar registros (template change_form.html).

Todas estas funcionalidades implican la recarga de toda la página o cargar nuevas páginas para su visualización(en el caso de los formularios para agregar o modificar un registro).

Como punto de partida mostrare una sencillo proyecto hecho en Django 1.2  para el registro de estudiantes (datos personales y carrera profesional en la que se encuentra); tenemos dos modelos en Django, Estudiante y Carrera, aquí se muestra el código y las vistas del admin Django que se generan.

Árbol de directorios:

• proyecto/
  • app/
    • __init__.py
    • admin.py
    • models.py
    • views.py
    • test.py
  • media/ (copia del directorio ubicado en ‘/path_django/django/contrib/admin/media/’)
  • templates/ (copia del directorio ubicado en ‘/path_django/django/contrib/admin/templates/’)
  • __init__.py
  • manage.py
  • settings.py
  • urls.py

Aquí no explicare a detalle el deployment de la aplicación en Django 1.2, como un pequeño alcance lo estoy trabajando bajo apache y mod-wsgi, en el proyecto agrego dos directorios (media y templates); uno tiene el contenido estático(css, imágenes, javascript) y el otro  los templates .html base; estos directorios los he copiado del mismo core Django( ‘django/contrib/admin/templates’ y ‘django/contrib/admin/media’).

Solo bastará cambiar el parámetro TEMPLATE_DIRS del fichero settings.py apuntando al directorio templates y configurando el apache para que lea el contenido estático dentro del directorio media; todo eso ya es otro tema.

Archivo models.py

# -*- coding: utf-8 -*-
from django.db import models

GENDER_CHOICES = (
                     ('M', 'Masculino'),
                     ('F', 'Femenino'),
                 )

CIVIL_CHOICES = (
                    ('Soltero', 'Soltero'),
                    ('Casado', 'Casado'),
                    ('Viudo', 'Viudo'),
                    ('Divorciado', 'Divorciado'),
                )

class Carrera(models.Model):
    Codigo = models.CharField("Código",max_length=20,unique=True)
    Carrera = models.CharField( max_length=50)
    Observaciones = models.TextField(blank=True,null=True)

    def __unicode__(self):
        return self.Carrera

    class Meta:
        verbose_name = "Carrera Profesional"
        verbose_name_plural = "Carreras Profesionales"

class Estudiante(models.Model):
    Codigo = models.CharField("Código",max_length=7,unique=True)
    Nombres = models.CharField("Nombres",max_length=50)
    ApellidoPaterno = models.CharField("Ape. Pat.",max_length=50)
    ApellidoMaterno = models.CharField("Ape. Mat.",max_length=50)
    Nacimiento = models.DateField("Nacimiento",null=True,blank=True)
    Sexo = models.CharField(max_length=1,choices=GENDER_CHOICES)
    Direccion = models.CharField("Dirección",max_length=150,null=True,blank=True)
    Email = models.EmailField("E-mail",null=True,blank=True)
    EstadoCivil = models.CharField("Estado Civil",max_length=20,choices=CIVIL_CHOICES,default='Soltero')
    Telefono = models.CharField("Teléfono",max_length=20,null=True,blank=True)
    Carrera = models.ForeignKey(Carrera)
    Observaciones = models.TextField(blank=True,null=True)

    def __unicode__(self):
        return u'%s %s %s' % (self.ApellidoPaterno,self.ApellidoMaterno,self.Nombres)

    class Meta:
        verbose_name = "Estudiante"
        verbose_name_plural = "Estudiante"

Archivo admin.py

# -*- coding: utf-8 -*-
from django.contrib import admin
from proyecto.app.models import Estudiante, Carrera

class EstudianteAdmin(admin.ModelAdmin):
    list_display = ('Codigo','__unicode__','Nacimiento','Direccion','Email','Telefono','Carrera')
    search_fields = ('Nombres','ApellidoPaterno','ApellidoMaterno',)
    radio_fields = { "Sexo": admin.HORIZONTAL}
    list_filter = ('Carrera',)
admin.site.register(Estudiante, EstudianteAdmin)

class CarreraAdmin(admin.ModelAdmin):
    list_display = ('Carrera','Codigo')
    search_fields = ('Carrera','Codigo')
admin.site.register(Carrera, CarreraAdmin)

Habilitamos el admin en el archivo urls.py

from django.conf.urls.defaults import *

# Uncomment the next two lines to enable the admin:
from django.contrib import admin
admin.autodiscover()

urlpatterns = patterns('',
 # Example:
 # (r'^proyecto/', include('proyecto.foo.urls')),

 # Uncomment the admin/doc line below to enable admin documentation:
 # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

 # Uncomment the next line to enable the admin:
  (r'^admin/', include(admin.site.urls)),
)

Con estos archivos generaremos las siguientes vistas estandar Django:

• Listado de Estudiantes.

• Formulario para agregar estudiantes.

• Formulario para modificar estudiantes.

Para empezar a trabajar con el jqGrid, debemos descargarlo de la pagina oficial, aquí esta la dirección de descarga  http://www.trirand.com/blog/?page_id=6

Trabajaremos con la version 3.8.1, la carpeta descargada (jqgrid3.8.1) la ubicaremos en nuestro directorio media por ser contenido estático, exactamente dentro de ‘proyecto/media/js/’

Si desean pueden chequear la documentación oficial (jqGrid Wiki Site), esta muy bien explicado.

A continuación vamos a crear nuestras propias vistas que reemplacen a las vistas estándar Django, todas ellas se encontraran en el archivo views.py, recuerden que deben actualizar el archivo urls.py agregando las urls que llamen a dichas vistas.

Sobreescribir listado de estudiantes (archivo views.py), con la vista jqgrid_estudiante.

# -*- coding: utf-8 -*-
#import necesarios para trabajar.
from django.shortcuts import render_to_response
from django.http import HttpResponseRedirect, HttpResponse
from django.template import RequestContext
from proyecto.app.models import Estudiante
from proyecto.app.models import Carrera
from django.utils import simplejson
from django.utils.safestring import mark_safe
#imports para la paginacion
from django.core.paginator import Paginator, InvalidPage, EmptyPage

def jqgrid_estudiante(request):
    if request.user.is_authenticated() and request.user.has_perm('app.add_estudiante') or request.user.has_perm('app.change_estudiante') or request.user.has_perm('app.delete_estudiante'):
        return render_to_response("jqgrid_estudiante.html", { "user": request.user }, context_instance = RequestContext(request))
    else:
        return HttpResponseRedirect('../../')

Esta vista renderiza el archivo jqgrid_estudiante.html, el cual posee el codigo que llama al grid con todos sus componentes, aqui mostramos su contenido.

{% extends "admin/base_site.html" %}
{% load adminmedia admin_list i18n %}

{% block extrastyle %}
 {{ block.super }}
 <link rel="stylesheet" type="text/css" href="{% admin_media_prefix %}css/changelists.css" />
 {{ media }}

<!-- Llamamos a los archivos que se necesitan para construir el jqgrid -->
<link rel="stylesheet" type="text/css" media="screen" href="{% admin_media_prefix %}js/jqgrid3.8.1/css/redmond/jquery-ui-1.8.2.custom.css" />
<link rel="stylesheet" type="text/css" media="screen" href="{% admin_media_prefix %}js/jqgrid3.8.1/css/ui.jqgrid.css" />

<script src="{% admin_media_prefix %}js/jqgrid3.8.1/js/jquery-1.4.2.min.js" type="text/javascript"></script>
<script src="{% admin_media_prefix %}js/jqgrid3.8.1/js/i18n/grid.locale-es.js" type="text/javascript"></script>
<script src="{% admin_media_prefix %}js/jqgrid3.8.1/js/jquery.jqGrid.min.js" type="text/javascript"></script>
{% endblock %}

{% block bodyclass %}change-list{% endblock %}

 {% block breadcrumbs %}
<div>
 › Demostración jqGrid en Django</div>
 {% endblock %}

{% block coltype %}flex{% endblock %}

{% block content %}

<table id="jqgrid_estudiante"></table>
<div id="pagernav"></div>
<!-- pasamos los argumentos de los permisos que tiene el usuario -->
<input type="hidden" id="grid_perms_add" value="{{ perms.app.add_estudiante }}"/>
<input type="hidden" id="grid_perms_change" value="{{ perms.app.change_estudiante }}"/>
<input type="hidden" id="grid_perms_delete" value="{{ perms.app.delete_estudiante }}"/>

<script src="{% admin_media_prefix %}js/jqgrid_estudiante.js" type="text/javascript"> </script>
{% endblock %}

Archivo jqgrid_estudiante.js

//verificamos los permisos del usuario y asignamos variables(true, false)
if (jQuery("#grid_perms_add").val() == 'True'){
var add_grid = true ;
}else{
var add_grid = false;
}

if (jQuery("#grid_perms_change").val() == 'True'){
var edit_grid = true ;
}else{
var edit_grid = false;
}

if (jQuery("#grid_perms_delete").val() == 'True'){
var del_grid = true ;
}else{
var del_grid = false;
}

jQuery("#jqgrid_estudiante").jqGrid({
//url que llama a la base de datos y trae el listado de estudiantes, traemos los datos en formato json.
url:'ver/?add=' + jQuery("#grid_perms_add").val() + '&change=' + jQuery("#grid_perms_change").val() + '&delete=' + jQuery("#grid_perms_delete").val(),
datatype: "json",
colNames:['Nº','Código','Ape. Pat.','Ape. Mat.','Nombres','Nacimiento','Sexo','Dirección','Email','Teléfono','Estado Civil','Carrera','Observaciones'],
colModel:[

 {name:'id',index:'id',width:40,search:false,align:'center',editable:false,editoptions:{readonly:true,size:10}},

 {name:'Codigo',index:'Codigo',width:70,align:'center',editable:true,editoptions:{size:40},editrules:{required:true}},

 {name:'ApellidoPaterno',index:'ApellidoPaterno',width:80,align:'center',editable:true,editoptions:{size:40},editrules:{required:true}},

 {name:'ApellidoMaterno',index:'ApellidoMaterno',width:80,align:'center',editable:true,editoptions:{size:40},editrules:{required:true}},

 {name:'Nombres',index:'Nombres',width:80,align:'center',editable:true,editoptions:{size:40},editrules:{required:true}},

 {name:'Nacimiento',index:'Nacimiento',width:90,search:false,align:'center',editable:true,editoptions:{size:40},editrules:{required:false,date:true}},

 {name:'Sexo',index:'Sexo',width:55,search:false,editable:true,align:'center',edittype:"select",editoptions:{value:"M:Masculino;F:Femenino"},editrules:{required:true}},

 {name:'Direccion',index:'Direccion',search:false,width:150,align:'center',editable:true,editoptions:{size:40},editrules:{required:true}},

 {name:'Email',index:'Email',width:125,search:false,editable:true,editoptions:{size:40},editrules:{required:false,email:true}},

 {name:'Telefono',index:'Telefono',width:80,search:false,align:'center',editable:true,editoptions:{size:10},editrules:{required:false}},

 {name:'EstadoCivil',index:'EstadoCivil',width:70,search:false,align:'center',editable:true,edittype:"select",editoptions:{value: "Soltero:Soltero;Casado:Casado;Viudo:Viudo;Divorciado:Divorciado"},editrules:{required:true}},

 {name:'Carrera',index:'Carrera',width:130,search:false,editable:true,edittype:"select",editoptions:{dataUrl:'obtener_carreras/'},editrules:{required:true}},

 {name:'Observaciones',index:'Observaciones',width:110,search:false,editable:true,edittype:"textarea",editoptions:{rows:"3",cols:"37"},editrules:{required:false}}
],
rowNum:10,
rowList:[10,20,30],
pager: '#pagernav',
sortname: 'id',
viewrecords: true,
sortorder: 'desc',
caption:'Estudiantes',
//ruta para ejecutar las operaciones de agregar, modificar o eliminar un registro
editurl:'master/?add=' + jQuery("#grid_perms_add").val() + '&change=' + jQuery("#grid_perms_change").val() + '&delete=' + jQuery("#grid_perms_delete").val(),
height:'100%',
width: '100%'

});

jQuery("#jqgrid_estudiante").jqGrid('navGrid','#pagernav',
{search:true,add:add_grid,edit:edit_grid,del:del_grid}, //options
{width:400,height:430,reloadAfterSubmit:true,closeAfterEdit: true}, // edit options
{width:400,height:430,reloadAfterSubmit:true,closeAfterAdd: true}, // add options
{width:270,reloadAfterSubmit:true}, // del options
{} // search options
);

Vista que procesa el parámetro url (‘admin/app/estudiante/ver/’) del archivo jqgrid_estudiante.js mostrado lineas arriba.

def ver_jqgrid_estudiante(request):
    if request.user.is_authenticated():
        page = request.GET.get('page','')
        limit = request.GET.get('rows', '')
        sidx = request.GET.get('sidx', '')
        sord = request.GET.get('sord', '')
        busqueda = request.GET.get('_search','')

        if sord == 'asc':
            sord = '-'
        elif sord == 'desc':
            sord = ''

        students = Estudiante.objects.all()

        if busqueda == 'true':
            campo = request.GET.get('searchField','')
            operacion = request.GET.get('searchOper','')
            palabra = request.GET.get('searchString','')

            if campo == 'Codigo':
                if operacion == "eq":
                    students = students.filter(Codigo__exact = palabra)
                elif operacion == "nq":
                    students = students.exclude(Codigo__exact = palabra)
                elif operacion == "bw":
                    students = students.filter(Codigo__startswith = palabra)
                elif operacion == "bn":
                    students = students.exclude(Codigo__startswith = palabra)
                elif operacion == "ew":
                    students = students.filter(Codigo__endswith = palabra)
                elif operacion == "en":
                    students = students.exclude(Codigo__endswith = palabra)
                elif operacion == "cn":
                    students = students.filter(Codigo__contains = palabra)
                elif operacion == "nc":
                    students = students.exclude(Codigo__contains = palabra)
            elif campo == 'ApellidoPaterno':
                if operacion == "eq":
                    students = students.filter(ApellidoPaterno__exact = palabra)
                elif operacion == "nq":
                    students = students.exclude(ApellidoPaterno__exact = palabra)
                elif operacion == "bw":
                    students = students.filter(ApellidoPaterno__startswith = palabra)
                elif operacion == "bn":
                    students = students.exclude(ApellidoPaterno__startswith = palabra)
                elif operacion == "ew":
                    students = students.filter(ApellidoPaterno__endswith = palabra)
                elif operacion == "en":
                    students = students.exclude(ApellidoPaterno__endswith = palabra)
                elif operacion == "cn":
                    students = students.filter(ApellidoPaterno__contains = palabra)
                elif operacion == "nc":
                    students = students.exclude(ApellidoPaterno__contains = palabra)
            elif campo == 'ApellidoMaterno':
                if operacion == "eq":
                    students = students.filter(ApellidoMaterno__exact = palabra)
                elif operacion == "nq":
                    students = students.exclude(ApellidoMaterno__exact = palabra)
                elif operacion == "bw":
                    students = students.filter(ApellidoMaterno__startswith = palabra)
                elif operacion == "bn":
                    students = students.exclude(ApellidoMaterno__startswith = palabra)
                elif operacion == "ew":
                    students = students.filter(ApellidoMaterno__endswith = palabra)
                elif operacion == "en":
                    students = students.exclude(ApellidoMaterno__endswith = palabra)
                elif operacion == "cn":
                    students = students.filter(ApellidoMaterno__contains = palabra)
                elif operacion == "nc":
                    students = students.exclude(ApellidoMaterno__contains = palabra)
            elif campo == 'Nombres':
                if operacion == "eq":
                    students = students.filter(Nombres__exact = palabra)
                elif operacion == "nq":
                    students = students.exclude(Nombres__exact = palabra)
                elif operacion == "bw":
                    students = students.filter(Nombres__startswith = palabra)
                elif operacion == "bn":
                    students = students.exclude(Nombres__startswith = palabra)
                elif operacion == "ew":
                    students = students.filter(Nombres__endswith = palabra)
                elif operacion == "en":
                    students = students.exclude(Nombres__endswith = palabra)
                elif operacion == "cn":
                    students = students.filter(Nombres__contains = palabra)
                elif operacion == "nc":
                    students = students.exclude(Nombres__contains = palabra)

        estudiantes = students.order_by(str(sord) + str(sidx))

        n_estudiantes = estudiantes.count()
        paginator = Paginator(estudiantes, int(limit))

        try:
            page = request.GET.get('page', '1')
        except ValueError:
            page = 1

        try:
            resultados = paginator.page(page)
        except (EmptyPage, InvalidPage):
            resultados = paginator.page(paginator.num_pages)

        filas = []
        i = 1
        for r in resultados.object_list:
            fila = {"id" :r.id, "cell" :[i,r.Codigo,r.ApellidoPaterno,r.ApellidoMaterno,r.Nombres,str(r.Nacimiento),r.Sexo,r.Direccion,r.Email,r.Telefono,r.EstadoCivil,r.Carrera.Carrera,r.Observaciones]}
            filas.append(fila)
            i+=1
        results = {"page": page,"total": paginator.num_pages ,"records": n_estudiantes,"rows": filas }
        return HttpResponse(simplejson.dumps(results, indent=4),mimetype='application/json')
else:
    return HttpResponseRedirect('../../../')

Vista que procesa el parámetro editurl (‘admin/app/estudiante/master/’) del archivo jqgrid_estudiante.js mostrado lineas arriba.

def master_jqgrid_estudiante(request):
    if request.user.is_authenticated() and request.GET.get('add','') == 'True' or request.GET.get('change','') == 'True' or request.GET.get('delete','') == 'True':
        operacion = request.POST['oper']
        estudiante_id = request.POST['id']

        if operacion == "add" or operacion == "edit":
            codigo = request.POST['Codigo']
            ape_pat = request.POST['ApellidoPaterno']
            ape_mat = request.POST['ApellidoMaterno']
            nombres = request.POST['Nombres']
            nac = request.POST['Nacimiento']
            sexo = request.POST['Sexo']
            direccion = request.POST['Direccion']
            email = request.POST['Email']
            civil = request.POST['EstadoCivil']
            tel = request.POST['Telefono']
            carrera_id = request.POST['Carrera']
            obs = request.POST['Observaciones']

        if operacion == "add":
            guardar_estudiante = Estudiante(Codigo = codigo, ApellidoPaterno = ape_pat,ApellidoMaterno = ape_mat, Nombres = nombres, Nacimiento = nac,Sexo = sexo,Direccion = direccion,Email = email, EstadoCivil = civil,Telefono = tel, Carrera_id = carrera_id,Observaciones = obs)
            guardar_estudiante.save()
        elif operacion == "edit":
            obj_estudiante = Estudiante.objects.get(id = estudiante_id)
            obj_estudiante.Codigo = codigo
            obj_estudiante.ApellidoPaterno = ape_pat
            obj_estudiante.ApellidoMaterno = ape_mat
            obj_estudiante.Nombres = nombres
            obj_estudiante.Nacimiento = nac
            obj_estudiante.Sexo = sexo
            obj_estudiante.Direccion = direccion
            obj_estudiante.Email = email
            obj_estudiante.EstadoCivil = civil
            obj_estudiante.Telefono = tel
            obj_estudiante.Carrera_id = carrera_id
            obj_estudiante.Observaciones = obs
            obj_estudiante.save()
        elif operacion == "del":
            obj_estudiante = Estudiante.objects.get(id = estudiante_id)
            obj_estudiante.delete()
        return jqgrid_estudiante(request)
else:
    return HttpResponseRedirect('../../../')

En la configuración del formulario jqgrid mostramos un combobox donde se muestran las carrera profesionales,este campo tiene un parámetro denominado dataUrl que llama a la url ‘obtenercarreras/’, esta url es procesada por la vista obtener_carreras mostrada a continuación.Este combobox es llenado dinamicamente a medida que agreguemos nuevas carreras profesionales al modelo.

def obtener_carreras(request):
    if request.user.is_authenticated():
        carreras = Carrera.objects.all()
        inicio_select = "<select>"
        opciones = ""
        for c in carreras:
            opcion = "<option value='%s'>%s</option>" % (c.id, c.Carrera)
            opciones += opcion
        fin_select = "</select>"
        select = inicio_select + opciones + fin_select
        return HttpResponse(mark_safe(select))
    else:
        return HttpResponseRedirect('../../../')

Por último agregamos al archivo urls.py la siguientes lineas que corresponden a todas las vistas creadas:

from django.conf.urls.defaults import *

# Uncomment the next two lines to enable the admin:
from django.contrib import admin
#importamos todas las vistas del archivo views.py
from proyecto.app.views import *
admin.autodiscover()

urlpatterns = patterns('',
 # Example:
 # (r'^proyecto/', include('proyecto.foo.urls')),

 # Uncomment the admin/doc line below to enable admin documentation:
 # (r'^admin/doc/', include('django.contrib.admindocs.urls')),

 # Uncomment the next line to enable the admin:
 (r'^admin/app/estudiante/$', jqgrid_estudiante),#cargar el template listado de estudiantes.
 (r'^admin/app/estudiante/ver/$', ver_jqgrid_estudiante),#cargar el jqgrid con la data del modelo estudiante, asi como busquedas y ordenar.
 (r'^admin/app/estudiante/obtener_carreras/$', obtener_carreras),#obtener las carreras de manera dinámica
 (r'^admin/app/estudiante/master/$', master_jqgrid_estudiante),#ejecutar operaciones de agregar, modificar o eliminar registros
 (r'^admin/', include(admin.site.urls)),
)

El código anterior se resume en las siguientes imágenes.

• Listado de estudiantes.

• Buscar estudiante.

• Agregar Estudiante.

• Modificar estudiante.

• Eliminar estudiante.

Como pueden observar el listado y el mantenimiento de los registros se realizan al instante sin cargar otras páginas,los formularios validan los datos ingresados, solo debes configurar que campos son requeridos y de que tipo son(emails, números, texto,etc), además jqGrid tiene una serie de opciones adicionales por ejemplo editar los registros inline, o manejar subgrids, treegrids,editar celdas, etc.Todo es cuestión de leer la documentación, luego verificar que urls debe procesar el django. La integración se hace fácil.
Espero les haya gustado y ojala les sirva y lo utilicen en sus aplicaciones, en mi caso yo lo he utilizado para crear una aplicación que permita editar en linea el registro de calificaciones de estudiantes, mejorando la usabilidad.
Hasta pronto.