En este artículo vamos a aprender los fundamentos básicos para usar el editor. Aprenderemos a implementarlo en nuestro script primario, y algunos aspectos básicos de la configuración, necesarios por otra parte, y que nos acompañarán ya en todos los artículos de esta serie.

En realidad, lo que vamos a ver no es nada dífícil. Sin embargo, al principio puede parecer un poco laborioso. No te asustes. Verás como ese aparente aumento de trabajo ahora nos va a ahorrar cientos de horas más adelante, en los proyectos que llevemos a cabo con el editor. Vamos, que sí, que este complemento está genial, pero oye, algo sí tendremos que currar. Este es el momento de aprender los puntos mínimos que serán comunes a cualquier proyecto.

LO QUE NECESITAMOS

Vamos a empezar con un ejercicio sencillo, basado en la primera base de datos que usamos de personal de una multinacional. En esta base de datos tenemos una tabla, con los datos de ciudades y cargos en la misma tabla que el personal, sin tablas relacionadas… Todo muy simple y minimalista, del mismo modo que hicimos cuando empezamos con DataTables. La base de datos en SQL te la dejo para descargar en este enlace. Hala. Píllala y móntala en tu localhost, con PHPMyAdmin, o la herramienta que uses.

LO QUE VAMOS A HACER

En este primer ejercicio práctico vamos a agregar unas funcionalidades muy básicas de edición de los registros de nuestra tabla, así cómo adición de nuevos registros, y eliminación de los existentes. Tras el análisis, veremos que, a pesar de las funcionalidades implementadas, el trabajo en sí adolece de ciertas carencias. No obstante, nos permitirá sentar las bases para mejorarlo en posteriores artículos, a fin de ir aprendiendo los mejores recursos del editor.

En este ejercicio vamos a usar tres scripts (en lugar de los dos que veníamos usando en los artículos de DataTables). El primario cumple la misma función que siempre. Es el que incluye todo lo demás, y renderiza la página con los resultados. Uno de los scripts secudarios es lo mismo que ya conocemos: lee los datos de la tabla y los vuelca al script principal. El tercer script contiene las funcionalidades de creación, edición y eliminación de registros. Si cargamos el script primario de este artículo en el navegador veremos algo similar a lo siguiente:

Cómo ves, la tabla tiene algunas novedades. En la parte superior izquierda vemos tres botones para crear un nuevo registro, editar uno o más ya existentes o eliminar alguno(s). Los botones de edición y eliminación aparecen desactivados hasta que seleccionemos, al menos, un registro. En la parte inferior izquierda vemos una leyenda que nos informa de que en este momento no hay registros seleccionados. Por cierto. Aquí empezamos a ver la utilidad de la selección de registros que vimos en el artículo XII de la serie de DataTables.

EL SCRIPT PRINCIPAL

El script principal de este ejercicio se llama articulo_editor_02.php y su listado es el siguiente:

En las líneas resaltadas vemos las novedades del script principal. Vamos a irlas comentando para irnos familiarizando con la incorporación y uso del editor.

En las líneas 13 y 45 vemos como se incluyen, respectivamente, el CSS y el JavaScript del editor. Como puedes ver, y tal cómo te comentaba en el artículo anterior, no se hace por CDN, sino, directamente, desde un directorio en nuestro servidor de desarrollo (o de producción, cuando llegue el caso).

<link rel="stylesheet" type="text/css" href="editor/css/editor.dataTables.css">

y

<script type="text/javascript" src="editor/js/dataTables.editor.js"></script>

EL OBJETO EDITOR

En las líneas de la 49 a la 88 vemos que definimos un objeto específico para el editor. En esta página tenemos, por tanto, dos objetos para poder operar. El objeto DataTables, que ya conocemos (en seguida comentaremos las novedades que trae) y el objeto específico para el editor. Siempre que vayamos a usar el complemento editor de DataTables deberemos crear este objeto, y configurarlo, en cada caso, según las necesidades.

Dentro del mismo vemos, en este primer ejercicio, las opciones de configuración más básicas.

En la línea 48 vemos como establecemos el nombre (y la ruta, si fuera el caso) del script secundario que se encargará de efectuar las inserciones de nuevos registros, o editar y eliminar los existentes, cuando pulsemos los correspondientes botones del editor (los que vemos en la parte superior izquierda de la tabla de HTML):

ajax: 'crud_editor_02.php',

En la línea 49 vemos la forma en que le decimos al editor la tabla HTML a la que queremos asociar el objeto que estamos creando. En tu página podría haber más de una tabla (ya vimos un ejemplo con dos tablas en uno de los artículos de DataTables). Además, aún en el caso de tener una sola tabla, sigue siendo necesario asociar el objeto editor a dicha tabla. Lo hacemos así:

table: '#tabla_de_personal',

El identificativo que le ponemos es, cómo ves, el atributo id de la correspondiente tabla HTML.

En la línea 50 vemos el uso de la opción idSrc. Se emplea para indicarle al editor el nombre del campo, en la tabla MySQL sobre la que vamos a trabajar, que contiene la clave primaria. Esto es fundamental para que luego se puedan hacer operaciones de edición y eliminación. Si bien para las más simples podríaos prescindir de este dato, ya que, como veremos, no lo vamos a usar ahora, para otras más complejas si lo necesitaremos, así que mejor aprendemos, desde ya, a usarlo:

idSrc: 'id',

Entre las líneas 53 y 79 vemos la opción i18n. Como sabes (y, si aún no lo sabes, te lo cuento yo ahora) i18n es una nomenclatura para archivos o matrices de textos en diferentes idiomas, para que los contenidos puedan internacionalizarse; es lo que se llama un númeronimo (toma palabreja) normalizado para referirse a archivos u otros medios para internacionalizar el software. La naturaleza y los protocolos de i18n exceden el objetivo de este artículo. Puedes leer más sobre este tema en pulsando aquí. De todos modos, que sepas que esta opción es, como puedes ver, a su vez, un grupo de opciones con textos (en este caso en español) para los botones de crear un nuevo registro, editar o eliminar registros existentes. A la vista de las referencias a botones empleadas se ve que parte es para cada botón.

Hay un par de puntos a los que quiero prestar especial atención. Dentro de la definición de los textos para el botón de eliminación de registros hay una opción llamada confirm, que se refiere al mensaje de confirmación que deberemos responder para hacer efectiva la eliminación de los registros seleccionados. Como ves en las líneas 19 y 20, el mensaje es diferente, según haya un registro seleccionado o cualquier otra cantidad (más de uno). Fíjate en la peculiar forma de establecer esto.

Otro punto sobre el que quiero llamar tu atención es la opción multi. Son los mensajes que se mostrarán en el formulario de edición si hay varios registros seleccionados. Esta es una situación un tanto particular. Si seleccionamos vartios registros y pulsamos el botón de edición, se nos abrirá un formulario con los campos de la ficha, de modo que si rellenamos un valor (por ejemplo la ciudad) y dejamos los demás datos sin rellenar, al pulsar el botón de actualizar la ciudad que hayamos tecleado se asignará a todos los registros seleccionados, manteniéndose intactos los demás datos. Esto se lo explicamos al usuario mediante unos mensajes definidos en esta opción. No te preocupes si todo esto ahora te suena un poco confuso. Cuando pruebes el ejercicio en tu navegador irás viendo los mensajes y comprobarás cuales te aparecen en cada caso.

La última opción que vamos a definir en el objeto del editor en este ejercicio es fields, entre las líneas 80 y 87. Se emplea para indicarle a nuestro editor cuales son los campos que deben aparecer en los formularios de edición y nuevo registro, las etiquetas (label) que tendrán, y los nombres de los campos. Observa que hemos hecho coincidir los nombres de los campos con los que hemos definido en el objeto DataTables (líneas de la 126 a la 131). Esto no es estrictamente imprescindible, pero ayuda mucho a efectos de organizarnos.

Ya dentro del objeto DataTables, en las líneas 92 a 98, vemos definidos los mensajes que aparecen en la parte inferior izquierda de la tabla HTML, para indicar el número de registros seleccionados, o si no hay ninguno. La forma de definir los textos coincide con la que hemos usado en la opción i18n.remove.confirm del objeto del editor.

En la línea 133, la opción select, con el valor true, es lo que permite que se selecciones o deseleccionen registros haciendo clic sobre ellos. Las selecciones múltiples se pueden hacer con las teclas Shift y Ctrl. Si lo recuerdas, ya hablamos de esto en el artículo XIII de la serie de DataTables.

En las líneas 134 a 139 establecemos los botones que vamos a necesitar (en este caso los de nuevo registro, edición y eliminación), y los relacionamos con objetoEditor. La opción dom puede parecer un poco críptica, con el valor que recibe. Las letras que forman ese valor establecen que botones podemos llegar a usar en nuestra tabla. En posteriores artículos profundizaremos más sobre el tema. Por ahora, simplemente, la ponemos así, porque si no, los botones no aprecerán. mención especial merece la clave l, al final del valor asignado a esta opción. Esta nos permite que, aún usando el editor, aparezca el combo selector del número de registros que queremos ver. Si no, no aparecería. Al haber puesto la l al final de la opción dom, este selector queda debajo de la tabla. Como ves, la opción buttons define cada uno de los botones de forma individual. También sobre esto profundizaremos más adelante. De momento, lo aceptamos como dogma de fé. Sí, ya se, no es la mejor manera de entender las cosas, pero a veces es necesario ir poco a poco.

Ahora haz un pequeño alto en la lectura de este artículo, y prueba el funcionamiento. Graba el script primario, y los dos secundarios que ves más adelante, en tu directorio datatables, dentro de localhost, y prueba a añadir nuevos miembros del personal a la plantilla, o editar y eliminar algunos, seleccionándolos previamente. Ten en cuenta que, cuando añadas un nuevo miembro, es posible que no lo veas aparecer, y pienses que no se ha grabado. En ese caso, usa los botones de paginación que parecen en la parte inferior derecha de la tabla HTML, porque, si no lo ves, es que, por ordenación, ha quedado en otra página. Por ejemplo, si tienes tu tabla ordenada por nombres y estás en la primera página, verás los nombres que empiezan por las primeras letras del alfabeto. Si el nombre del nuevo miembro empieza por una letra “más alta” tendrás que despazarte a otras páginas para verlo.

LOS SCRIPTS SECUNDARIOS

Cómo hemos comentado, este ejercicio tiene dos scripts secundarios. Uno de ellos corresponde al objeto DataTables, y se llama datos_externos_editor_02.php. Su listado es el siguiente:

En este script no hay ninguna novedad. Su listado coincide con el script secundario que vimos en el artículo XIII de la serie de DataTables. Sólo te he puesto el código para que veas que no hay novedades aquí y para que lo tengas a mano para copiarlo en tu localhost.

El script secundario que nos interesa ahora es crud_editor_02.php, que es el invocado desde el objeto del editor para ocuparse de añadir nuevos registros, o editar o eliminar. Su listado es el siguiente:

En primer lugar, este script, cuando es invocado, recibe datos de los registros con los que vamos a trabajar por POST, en lugar de GET, como hace el objeto DataTables. Esto es lógico. Cuando pulsas, por ejemplo, el botón de añadir un nuevo registro, se te abre un formulario con todos los campos en blanco. Los rellenas y pulsas el botón de grabar. En este formulario puede haber muchos campos o, incluso, como ya veremos en artículos posteriores, campos de tipo fichero. Todo ese paquete de información debe ser pasado por POST. Cuando pulsas el botón de edición, la situación es similar. Cuando pulsas el botón de eliminación, en realidad sólo vamos a necesitar que pasen los id de los registros a eliminar, pero el editor pasa todos los datos, así que también pasan por POST. En la línea 13 del script ves como los recuperamos.

La forma en que llegan los datos a este script secundario es cómo una matriz. El primer elemento tiene la clave action, y el valor create, edit o remove, según la operación que estemos haciendo. El segundo elemento tiene la clave data y es, a su vez, una matriz con los datos de todos los registros afectados, a razón de un elemento de esta matriz por registro, siendo la clave de dicho elemento el id del registro. Por ejemplo, en caso de eliminación de dos registros, la matriz que llega por post tendrá un aspecto similar al siguiente:

En el supesto de editar dos registros de dos personas, de las que digamos que queremos conservar todos sus datos, excepto la ciudad, ya que ambos los trasladamos a Brisbane, la matriz enviada a este script tendría un aspecto así:

Y ahora supongamos que agregamos un nuevo miembro de personal. La matriz rtecibida podría ser similar a la que aparece a continuación:

Además, este script debe devolver, por ajax, un objeto JSON que indique cómo quedan los datos, para que el objeto editor pueda renderizar los cambios en tiempo real en la tabla HTML. Así, en caso de una eliminación, se devolverá un obeto JSON similar al siguiente:

Cómo ves, se trata de un objeto JSON sin contenido. Como es una eliminación, el objeto editor en el script primarip debe reemplazar el registro o registros que se hubieran seleccionado por, exactamente, eso: nada, un conjunto de datos vacío.

Si se trata de una edición como la que hemos visto en el ejemplo de más arriba, donde mudábamos a dos personas a Brisbane, el objeto JSON devuelto al editor tendría un aspecto cómo el siguiente:

Por último, en el caso de un nuevo registro, el objeto JSON devuelto tendrá un aspecto parecido al que ves a continuación.

Al recibir estos datos en el formato JSON correcto, el editor puede, cómo hemos comentado, actualizar la tabla HTML en tiempo real.

Sin embargo, este nuevo script no sólo debe recibir los datos por POST y generar el JSON a devolver. Además, en el camino, debe efectuar la correspondiente consulta de creación, edición o eliminación. Si ves el código con detalle, podrás identificar los procesos que lleva a cabo el script.

En el próximo artículo seguiremos profundizando en las capacidades del editor de DataTables. Los scripts y la base de datos de esste artículo te los puedes descargar en este enlace.