Alejandro Carantoña

En la primerísima entrada de este blog mencionaba que había decidido poner en el aire esta página web con la infraestructura mínima que la permitiese funcionar, para luego ir alimentándola poco a poco.

Después de haber creado las páginas generales sobre sobretítulos, es decir, sobre las traducciones de ópera que he hecho, y sobre uno de los grupos en los que estoy, creo que el siguiente paso es empezar a alimentar esos apartados.

Afortunadamente, el editor Gutenberg que viene de serie con las nuevas versiones de WordPress convierte la tarea de mantener esas páginas actualizadas un juego de niños. Simplemente necesito crear una página, insertar un bloque que recupere automáticamente las entradas del blog etiquetadas como «Sobretítulos» y ya está: la página se actualizará sola cada vez que yo publique una entrada del blog.

Pero ahora vienen curvas: ¿cómo ordenar y categorizar otros elementos, que no son entradas ni páginas, en WordPress?

El reto: Crear un repertorio

En versiones anteriores de esta página, había hecho el repertorio de óperas que he sobretitulado de la forma más pesada imaginable, es decir, de una en una. Escribía una entrada con su título y, en el cuerpo. anotaba los detalles copiando la plantilla de una a otra. Al final estaba todo ahí, pero no había manera de ver el índice por compositores, por ejemplo, o filtrarlas por teatros… Esto es lo que quiero conseguir ahora.

Qué queremos conseguir

• Crear entradas de WordPress que incluyan, además de título, texto y una imagen principal, el compositor, el teatro para el que hice el encargo y las lenguas en las que está disponible.
• Mostrar en una página de la web todo el repertorio de óperas ordenado por compositores, óperas y que se puedan filtrar por lenguas de origen y destino.

Empiezo a investigar

Hace un tiempo hice un curso sobre creación de los mal llamados temas (plantillas) en WordPress, un proceso que consta de dos pasos: crear el tema en sí (dar formato, color, orden, etc. a cada elemento de la página web) y añadirle funcionalidades, normalmente mediante plugins. Los plugins sirven para extender o completar las prestaciones que ofrece WordPress sin tocar su código, que como bien dicen jamás debe ser modificado a mano.

Un plugin, en principio, sirve para mi propósito, que no deja de ser guardar y mostrar un tipo de entrada que, por sí mismo, no existe en WordPress.

Vamos a ello…

Creando el plugin Repertoire

Así llamaré al plugin. Lo primero que hago es conectarme con la carpeta de mi servidor desde donde sirvo esta página web, irme a wp-content/plugins y crear la carpeta «repertoire»; dentro de ella, el archivo vacío «repertoire.php».

(Si no sabes por qué esta carpeta, por qué este archivo… Pasea por la documentación de WordPress para entender cómo se organiza.)

Lo primero de todo es registrarlo. Es decir, que WordPress pueda entender que existe un nuevo plugin. Esta información se incluye en el encabezamiento del archivo PHP como si fuese un comentario. Puedo poner algo así:

/*
* Plugin name: Repertoire
* Description: Un plugin para construir un repertorio de óperas que me permita mostrarlas por compositor e idiomas disponibles.
* Version: 1.0
* Author: Alejandro Carantoña
* Author URI: https://alexcarantona.com
*/

Solo el nombre es imprescindible. El resto es opcional. Guardo, refresco y…

Ya tengo un plugin en mi panel de control, que no hace absolutamente nada. Ahora, habrá que empezar a añadirle funcionalidades.

Daré el día por bueno si consigo crearle un panel de control en el menú de administración, donde podré añadir una ópera con esa información que quiero: el nombre del compositor, los idiomas disponibles, etc.

Creando el panel de control del plugin

Lo que viene ahora es muy fácil e intuitivo cuando uno se acostumbra, pero rarísimo al principio. WordPress incluye una tonelada de funciones, acciones, filtros, etc. que nos permiten intervenir en su funcionamiento normal, y añadirle pasos o modificar los que está dando.

En este caso, quiero que cuando esté cargando los menús de administración tenga en cuenta que yo quiero incluir el de mi plugin. Esto se hace llamando la siguiente función, un hook o gancho de WordPress, en el mismo archivo php que creé antes:

add_action( 'admin_menu', 'repertoire_admin_page');

Aquí es donde le digo que cuando realice la acción admin_menu incluya la ejecución de repertoire_admin_page, que es otra función, creada por mí, que será la que genere el menú deseado. Y esa función, siempre en el mismo archivo php, dice así:

function repertoire_admin_page() {
    add_menu_page(
        'Repertoire', // El título de la página del menú
        'Repertoire', // El nombre que aparecerá en el menú de la izquierda
        'manage_options', // Los permisos que debe tener el usuario
        'repertoire', // Lo que aparecerá en las url
        'repertoire_admin_html', // La función que devuelve el HTML (más sobre esto abajo)
        'dashicons-playlist-audio', // El icono que se verá en el menú. Puede ser una imagen o, como aquí, un icono de WordPress
    );
}

Como puedes ver, mi función simplemente envuelve add_menu_page, que es la función incluida en WordPress para crear una página de administración. En el extracto de código incluyo, como comentario, a qué corresponde cada uno de los argumentos de la función. Puedes añadir otro más, que no he puesto, que es un número para indicar en qué posición del menú izquierdo aparecerá tu plugin. Si no lo incluyes, saldrá el último.

Solo nos queda una cosa por hacer, que es incluir el html que se verá cuando entremos en el panel de control. Esto se controla mediante el quinto argumento que ves ahí, que he señalado en negrita.

Es la llamada a una función que a su vez devuelve el html del panel de control. Voy a hacer una versión mínima solo para ver que funciona.

function repertoire_admin_html() {
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <p>Aquí empieza mi repertorio</p>
    <?php
}

Le pongo la clase «wrap» al contenedor por sugerencia de WordPress. Luego, utilizo su mismo ejemplo: esc_html (que limpia y sanea el texto que contiene) y la función get_admin_page_title() para recuperar el nombre que le he puesto a mi panel de control previamente.

Guardo, vuelvo al panel de control de Plugins, actualizo y…

Podemos dar el día por bueno. En próximas batallas, tocará añadir aquí la forma de añadir una ópera y guardarla. Te dejo, de momento, el código completo de repertoire.php hasta este punto:

<?php 
/*
* Plugin name: Repertoire
* Description: Un plugin para construir un repertorio de óperas que me permita mostrarlas por compositor e idiomas disponibles.
* Version: 1.0
* Author: Alejandro Carantoña
* Author URI: https://alexcarantona.com
*/

/** Creando el menú */ 

function repertoire_admin_html() {
    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <p>Aquí empieza mi repertorio</p>
    <?php
}

function repertoire_admin_page() {
    add_menu_page(
        'Repertoire', // El título
        'Repertoire', // El nombre que aparecerá en el menú de la izquierda
        'manage_options', // Los permisos que debe tener el usuario para poder acceder. Este es el que permite manejar la configuración, panel de control, etc.
        'repertoire', // Lo que aparecerá en las url
        'repertoire_admin_html', // La función que devuelve el HTML
        'dashicons-playlist-audio', // El icono que se verá en el menú
    );
}

add_action( 'admin_menu', 'repertoire_admin_page');

Y si tienes ganas y paciencia, la guía de WordPress para crear plugins en inglés, de donde he ido extrayendo la receta.

Sigue leyendo esta receta aquí.