[Tutorial] Crear un plugin WordPress desde cero: Carrusel Responsive

Este tutorial explica cómo hacer un plugin WordPress desde cero y paso a paso.

El plugin que crearemos permitirá insertar en cualquier página o entrada de nuestra web un carrusel de Custom Posts responsive y animado. La inserción del carrusel se hará vía shortcode.

Durante el proceso vamos a utilizar funciones del core de WordPress para:

  • Crear Custom Post Types.
  • Añadir shortcodes personalizados.
  • Registrar y encolar estilos y scripts propios y de terceros.

Además, también haremos uso de otros recursos:

  • Veremos una introducción a Piklist, un plugin que agiliza el desarrollo WordPress y que nos permite crear campos personalizados (custom fields) y vincularlos a Custom Post Types de una manera muy sencilla.
  • Incorporaremos a nuestro código Slick, un plugin jQuery para la generación de carruseles animados.

El código correspondiente a esta guía lo encontraréis en este repositorio GitHub, donde también hay un breve manual de usuario del plugin.

PRERREQUISITOS

  • Una instalación de WordPress convenientemente actualizada.
  • Tener instalado y activado el plugin Piklist.

PASO 1: CREAR LA ESTRUCTURA DE UN PLUGIN WORDPRESS

Un plugin nos permite añadir características, servicios o funcionalidades personalizadas a WordPress.

Lo primero que debemos hacer es crear la carpeta que contendrá los ficheros del plugin dentro de la ruta wp-content/plugins/ de nuestro WordPress.

En nuestro caso, llamaremos al nuevo plugin “Netireki – Carousel Custom Posts” y a la carpeta que lo contendrá “ntrk-carousel-cposts”:

WordPress FilesystemTree
Estructura de directorios básica

A continuación crearemos el fichero principal del plugin dentro de la carpeta que acabamos de crear. Nombraremos a ese fichero igual que la carpeta: ntrk-carousel-cposts.php

Las primeras líneas de este fichero PHP deben contener las cabeceras de archivo, que permite a WordPress reconocer al plugin y presentarlo en la pantalla de gestión de plugins del panel de administración.

Este es el aspecto inicial de nuestra cabecera:

Solo con hacer esto ya podemos ver nuestro plugin en el panel de administración de plugins de WordPress:

Netireki Plugin - Custom Posts Carousel
Plugin básico desactivado

Si quisiéramos que nuestro plugin sea publicado en el repositorio de plugins de WordPress, y por tanto que fuese accesible e instalable desde el panel de administración de WordPress, deberíamos incluir un fichero readme.txt junto al fichero principal.

Puedes encontrar más información acerca de este fichero en el Codex de WordPress. También puedes generarlo automáticamente en la página GenerateWP.

Para este plugin he creado uno muy sencillito que seguramente no nos permitiría publicar el plugin en el repositorio WordPress.

PASO 2: CREAR EL CUSTOM POST TYPE PARA EL CARRUSEL

En el paso 1 hemos generado la estructura básica de un plugin WordPress. En este segundo paso, vamos a empezar a darle funcionalidad.

Primeramente crearemos un Custom Post Type llamado ‘ntrk_carousel_cpost‘, que nos permitirá gestionar los diferentes carruseles como si fuesen entradas de WordPress. Para ello podemos ayudarnos del generador de Custom Posts de GenerateWP y copiar el código generado en nuestro fichero ‘ntrk-carousel-cposts.php‘:

En este momento, si activamos el plugin desde el panel de administración de WordPress, podremos observar cómo se ha añadido un nuevo elemento en el menú con el nombre ‘NETIREKI – Carousels‘.

Menu ntrk-carousel-cposts
Entrada del plugin en el menú lateral de WordPress

Si tratamos de crear un nuevo carrusel, veremos que solo podemos rellenar el campo Título. Esto sucede porque así se lo hemos indicado a WordPress con el argumento ‘supports‘ que hemos enviado al registrar nuestro Custom Post Type (‘supports’ => array(‘title’)).

Para poder añadir diapositivas a nuestro carrusel, debemos crear una estructura de campos personalizados para las entradas del nuevo Custom Post Type que acabamos de crear.

PASO 3: CREAR LOS CAMPOS PERSONALIZADOS DEL CARRUSEL

En los pasos 1 y 2 hemos construido la estructura básica de un plugin WordPress y generado el Custom Post Type que dará soporte a nuestros carruseles. En este tercer paso vamos a añadir campos personalizados a los carruseles para poder añadirles diapositivas con una imagen y un texto descriptivo.

Utilizaremos las funciones que nos provee Piklist, un plugin gratuito que agiliza el desarrollo de temas o plugins simplificando tareas complejas de WordPress para hacer más en menos tiempo.

Lo primero es registrar nuestro plugin con Piklist. Esto es tan sencillo como modificar la cabecera del fichero principal de nuestro plugin y añadir una línea:

A continuación, adaptamos a Piklist la estructura de directorios de nuestro plugin :

ntrk-carousel-cposts
    |-parts
        |-meta-boxes
            |-ntrk-carousel-metabox.php

Cada carrusel estará formado por varias diapositivas, y cada diapositiva constará a su vez de una imagen y un texto descriptivo. En el fichero ntrk-carousel-metabox.php vamos a usar funciones de Piklist para implementar esta estructura de carrusel:

En la cabecera del fichero (las líneas comentadas), indicamos el título del metabox, así como el tipo de post para el que se mostrará. En nuestro caso, se visualizará en las entradas de tipo ‘ntrk_carousel_cpost‘ que creamos en el paso 2.

Este metabox contiene un grupo de campos (‘type’ => ‘group’) que además serán repetitivos (‘add_more’ => true), lo que permitirá añadir al carrusel cuantas diapositivas se quiera.

Más abajo se definen los dos campos que conforman cada grupo. Por un lado la imagen (‘type’ => ‘file’), y por otro el texto descriptivo (‘type’ =>’textarea’).

Como se puede observar, el código escrito con Piklist es bastante fácil de comprender. Piklist cuenta con una completa documentación para profundizar en sus características y potencial.

Si en este momento creamos un nuevo carrusel, veremos que la página de edición contiene los campos necesarios para añadir las diapositivas:

Nuevo carrusel ntrk-carousel-cposts
Entrada básica de diapostivas de un Carrusel

AVANZADO: En el código disponible en GitHub también se crean campos de configuración para enviar a Slick. Aquí podemos ver un ejemplo de un carrusel configurado con los campos extendidos:

Nuevo carrusel completo ntrk-carousel-cposts
Versión avanzada del editor de Carruseles

PASO 4: CREAR EL SHORTCODE QUE MOSTRARÁ EL CARRUSEL

En los pasos anteriores hemos configurado la estructura del plugin, hemos creado un Custom Post Type y le hemos vinculado campos personalizados crear carruseles con varias diapositivas. Hasta el momento, nuestro plugin solo es capaz de almacenar en el modelo de datos nativo de WordPress toda la información necesaria para construir un carrusel.

En este punto vamos a crear un shortcode que al insertarlo en una página o entrada visualice un carrusel concreto con la información que hemos guardado.

Los shortcodes actúan a modo de macros. Nos permiten encapsular varias líneas de código en un “alias” o “atajo” al que se pueden pasar parámetros.

El objetivo es crear un código con el formato [ntrk-carousel-cpost id=$id] que muestre el carrusel con identificador $id. Para hacerlo podríamos usar Piklist, que tiene funciones para crear shortcodes, pero vamos a utilizar directamente el core de WordPress.

Lo primero es crear una función que contenga toda la lógica de nuestro shortcode, y vincularla al código con el que queremos que sea llamado.

En el fichero principal del plugin (ntrk-carousel-cposts.php) añadiremos una función llamada ntrk_carousel_shortcode(), y la vincularemos al código “ntrk-carousel-cpost” a través de la función del core de WordPress “add_shortcode”:

La variable $atts contendrá el identificador del carrusel que pasamos como parámetro en la llamada del shortcode.

A continuación, dentro de la función realizamos la consulta o query a la base de datos para recuperar el carrusel con el identificador dado:

Con esta primera query solo se muestra el título del carrusel, un dato sin mucho interés para la funcionalidad del plugin. Necesitamos recuperar los datos de las diapositivas, que se encuentran almacenados en los custom fields creados en el paso 3:

La variable $html sirve para ir almacenando el código HTML que generamos, y retornarlo al final de la función.

  • Al inicio de bucle ‘while‘ recuperamos los metadatos del carrusel agrupados en el campo ‘slides‘.
  • Aplicamos un unserialize sobre los datos agrupados.
  • Recorremos el array de slides y vamos mostrando la imagen y el texto descriptivo de cada diapositiva ($slide).

Este shortcode ya mostraría las imágenes y los textos de cada diapositiva, pero sin el comportamiento de un carrusel animado y responsive:

Carrusel incompleto ntrk-carousel-cposts
Información de diapositivas sin formato de Carrusel

Para convertir esto en un carrusel, hay que incorporar a nuestro proyecto el plugin de jQuery Slick.

PASO 5: USANDO SLICK PARA CONSTRUIR EL CARRUSEL

En este paso incorporaremos Slick a nuestro plugin de WordPress, y le enviaremos los datos de configuración necesarios para que el HTML que devuelve el shortcode creado en el punto 4 se convierta en un carrusel animado y responsive.

Descargamos Slick de su página web y copiamos sus archivos en la carpeta ‘slick‘ que crearemos bajo el directorio principal de nuestro plugin (ntrk-carousel-cposts).

También aprovecharemos para crear la carpeta ‘assets‘ donde generamos sendos ficheros carousel.css y carousel.js que servirán personalizar los estilos y scripts de nuestro plugin.

Filesystem with Slick
Estructura de directorios con Slick

A continuación encolamos los ficheros CSS y JS de Slick para cargarse desde nuestro plugin WordPress. También encolamos sendos ficheros CSS y JS propios de nuestro plugin que crearemos en la ruta ‘assets‘. Para ello utilizamos la acción ‘wp_enqueue_scripts‘ del core de WordPress en nuestro fichero »ntrk-carousel-cposts.php«:

Para inicializar Slick, debemos añadir la siguiente llamada al fichero carousel.js que acabamos de crear:

Y en la función de nuestro shortchode añadimos los atributos data para configurar el carrusel de forma que muestre los puntos de navegación, se inicie automaticamente, visualice 3 diapositivas y las desplace de una en una:

AVANZADO: Si añadimos a nuestro Custom Post Type campos personalizados para que el usuario introduzca los valores de los parámetros de Slick que desee para cada carrusel, podremos recuperarlos en el shortcode y pasárselos al plugin JavaScript fácilmente vía HTML a través del atributo data-slick:

Para finalizar, damos estilos al carrusel editando el fichero carousel.css que hemos creado en el directorio ‘asets‘:

Y ahora sí que ya podemos ver nuestro carrusel en acción:

Carrusel en accion ntrk-carousel-cposts
El plugin en acción

EXTRA 1: MOSTRAR EN LA PÁGINA DE EDICIÓN DEL CARRUSEL SU CÓDIGO SHORTCODE

Puede resultar muy útil mostrar cuál es el shortcode completo de cada carrusel en su propia página de edición, y así facilitar al usuario la copia del mismo y su inserción en cualquier página o entrada.

Para hacer esto, vamos a editar el fichero donde definimos el metabox de los Carruseles (ntrk-carousel-metabox.php) y añadir las siguientes líneas:

Esta porción de código añade un campo personalizado de tipo HTML que muestra el código shortcode cuando el carrusel se haya publicado:

Shortcode en edit page ntrk-carousel-cposts
El código del shortcode en la página de edición de un Carrusel

EXTRA 2: PERSONALIZACIÓN RESPONSIVE

Slick permite configurar el comportamiento responsive del carrusel estableciendo diferentes valores a sus opciones dependiendo del ancho de banda.

Podemos incorporar un nuevo grupo de campos personalizados a nuestro metabox (ntrk-carousel-metabox.php) para permitir al usuario establecer los breakpoints y su configuración:

Y luego recuperarlos en el shortcode para actualizar las opciones de Slick a través del método “slickSetOption”:

EXTRA 3: COMPROBAR DEPENDENCIAS AL ACTIVAR EL PLUGIN

Nuestro nuevo plugin necesita para funcionar que nuestro sitio WordPress tenga instalado y activo el plugin Piklist. Para evitar que el plugin pueda ser instalado y activado sin tener resuelta esta dependencia, podemos utilizar el “Piklist Checker”, el código que el propio Piklist nos provee para notificar al usuario de esta dependencia y ayudarle a resolverla.

En resumen, se trata de añadir la clase ‘Piklist_Checker’ a nuestro plugin (fichero ‘class-piklist-checker.php‘) y agregar la siguiente porción de código al fichero principal (‘ntrk-carousel-cposts.php‘):

POSIBLES MEJORAS

Sin duda la funcionalidad de este plugin es limitada a la hora de configurar un carrusel. Se podrían incluir algunas mejoras, como el paso de parámetros vía shortcode para la configuración del número de diapositivas a mostrar y desplazar.

Sin embargo, el propósito de este artículo era más bien enseñar los fundamentos para construir un plugin de WordPress, y repasar de paso el uso de algunas funcionalidades básicas del core (crear Custom Post Types, encolar estilos y scripts propios y de terceros –Slick-, registrar shortcodes) y servir de introducción a las funciones más básicas que nos ofrece Piklist.

A partir de aquí, queda a tu criterio aprovechar el código que pongo a tu disposición para aprender, o para mejorarlo y evolucionarlo, siempre bajo las condiciones de la licencia MIT con la que lo publico.

También puedes proponer mejoras o correcciones al código escribiendo un comentario a esta entrada. Te invito a ello. ¡Prometo responder con rapidez!

Desarrollo WebWordPress