Creación de Plugins en WordPress (I)

Hará aproximadamente un par de años que tres compañeros (y amigos) míos decidimos probar suerte y tirar adelante una idea de negocio muy chula. Por algún motivo, decidimos que la montaríamos encima de WordPress, aunque por aquel entonces no teníamos muy claro cómo funcionaba WordPress y cómo podíamos extenderlo… Aún así, fuimos bastante atrevidos y nos tiramos a la piscina 😛 Como puedes imaginar, los primeros meses fueron «moviditos»; tuvimos que adquirir un montón de conocimientos en poco tiempo para poder empezar cuanto antes con el desarrollo. ¿Que qué hicimos? Lo mismo que tú ahora: buscar y leer recursos y tutoriales en la red y escribir mucho, muchísimo código de prueba 😉

Después de dos años trabajando exclusivamente en el ecosistema de WordPress y de haber desarrollado varios plugins, he pensado que sería una buena idea compartir mi experiencia contigo y enseñarte cómo crear plugins en WordPress. A lo largo de esta y próximas entradas, te explicaré todo lo que necesitas saber para escribir buenos plugins, es decir, plugins que sean funcionales, extensibles y mantenibles. En cierto modo, pues, intentaré crear el tutorial que me hubiera gustado tener cuando yo empecé. Como verás, habrá poca teoría y mucha práctica… de tal forma que los conocimientos que deberás adquirir irán apareciendo a medida que los necesitemos. ¡Espero que te guste!

En la entrada de hoy aprenderás cómo:

1. crear el esqueleto básico de un plugin,
2. cambiar el título de todas las entradas haciendo que muestren un texto fijo y
3. hacer el cambio del paso 2 de forma selectiva (según lo que tú, como autor de una entrada, decidas).

Crear tu primer plugin

Crear un plugin para WordPress es extremadamente sencillo. Lo único que tienes que hacer es crear una nueva carpeta en el directorio wp-content/plugins/ y añadir un fichero con el código fuente. Por ejemplo, vamos a crear un plugin que se llame wprincipiante-ejemplo. Para ello, crea la carpeta wp-content/plugins/wprincipiante-ejemplo/ y añade un nuevo fichero dentro llamado wprincipiante-ejemplo.php con el siguiente contenido:

Si ahora vamos al Escritorio de WordPress » Plugins, veremos que nuestro nuevo plugin Ejemplo de WPrincipiante aparece correctamente listado, con su versión, su autor, su descripción, enlaces a nuestra web… Vamos, que WordPress está usando toda la información que hemos añadido en el comentario inicial de wprincipiante-ejemplo.php.

Cómo añadir alguna funcionalidad al plugin

¡Felicidades! Acabas de crear tu primer plugin, aunque por desgracia no hace absolutamente nada útil. WordPress ofrece diferentes APIs para implementar nuevas funcionalidades. Algunos ejemplos de estas APIs son:

• Plugins API. Es la API más básica que debemos dominar para poder extender WordPress con nuestros plugins.
• Settings API. Ofrece un conjunto de operaciones para crear páginas de configuración de nuestro plugin.
• Options API. Permite almacenar (y recuperar) las opciones de configuración de nuestro plugin.
• Widgets API. Permite crear nuevos widgets que podrán añadirse a una instalación de WordPress y ser visibles desde el front-end.
• y muchas, muchas más otras…

Hace un par de días, mi compañero Antonio te explicaba con muchísimo detalle la API de Plugins. Básicamente, aquí encontramos el concepto de hook. Como nos contaba Toni, los hooks son mecanismos que ofrece WordPress para permitir “enganchar” las acciones de tu plugin a diferentes partes de WordPress.

Tu primer hook

Vamos a añadir un poco de funcionalidad al plugin. Añade el siguiente fragmento de código al final del fichero wprincipiante.php (no vuelvas a incluir la etiqueta <?php; únicamente la añado para que el código tenga resaltado de sintaxis):

Si has activado el plugin y vas a tu blog, verás que todos los títulos de todas tus páginas y entradas incluyen el texto [Exclusiva]. Así, por ejemplo, la entrada ¡Hola mundo! ahora es [Exclusiva] ¡Hola mundo!.

Vamos a analizar paso a paso lo que acabamos de escribir:

• Función add_filter. Es, como te decía, el primer hook que usaremos. Aquí, lo que básicamente le estamos diciendo a WordPress es que «cuando se produzca el evento the_title (es decir, cuando WordPress esté a punto de escribir el título de una entrada o página), ejecute la función wprincipiante_cambiar_titulo.
• Creamos una nueva función. Con la instrucción anterior le hemos dicho a WordPress que cuando se produzca el evento the_title tendrá que llamar a una cierta función. Esta función, sin embargo, no existe por defecto, así que habrá que crearla. Además, le hemos dicho (porque así está documentado) que la función deberá aceptar dos parámetros ($title e $id). Vamos, pues, a crear esta función.
• El cuerpo de la función. Finalmente, sólo nos queda ver y entender el cuerpo de la función wprincipiante_cambiar_titulo, el cual no tiene ningún misterio: simplemente le añade al título la cadena [Exclusiva].

Tipos de hooks: filtros y acciones

Recordemos que existen dos tipos de hooks:

• Acciones. Una acción es una función PHP que se ejecuta cuando se produce un cierto evento en WordPress. Ejemplos de eventos son guardar una entrada, modificar la base de datos o enviar la etiqueta head del HTML. Aquí encontrarás la lista con (prácticamente) todas las acciones disponibles en WordPress.
• Filtros. Un filtro es parecido a una acción, pero con una diferencia: reciben un valor de entrada, lo procesan de alguna forma para modificarlo y devuelven el nuevo valor. El ejemplo que acabamos de programar es, precisamente, un filtro. El código que hemos escrito en el plugin toma como valor de entrada el título de una entrada o página cualquiera, lo modifica añadiéndole un pequeño texto y devuelve la versión modificada del título. Aquí tienes la lista con los filtros disponibles.

Extender la información de las entradas

De momento, todo lo que te he explicado ya estaba más o menos cubierto en la anterior entrada de WPrincipiante. Con esto ya tienes las nociones básicas para hacer prácticamente cualquier cosa en WordPress. Vamos a ver cómo ir un paso más allá y descubramos cómo usar algunos recursos más de los que nos ofrece WordPress para hacer un plugin más potente. En concreto, vamos a:

1. Modificar el editor de entradas. Añadiremos una nueva caja de edición en las entradas de WordPress donde podremos especificar un texto cualquiera. Este texto será específico de cada entrada (como lo son el título o el contenido) y será una «Extensión del título».
2. Guardar el nuevo campo. Modificaremos la información que WordPress almacena de una entrada y le añadiremos un campo adicional que nos permitirá almacenar y recuperar esa «extensión del título».
3. Modificar el título con ese campo. Haremos que los títulos de cada entrada incluyan la extensión almacenada en 2.

Por ejemplo, imaginemos que tenemos dos entradas en WordPress:

• ¡Hola Mundo!
• Bienvenidos a mi blog

Nuestro objetivo es que el autor de una entrada pueda añadir el texto que quiera al título (por ejemplo, «WordPress mola» en la primera entrada) para que, cuando un visitante acceda al blog, vea lo siguiente:

• ¡Hola mundo! WordPress mola
• Bienvenidos a mi blog

¿Empezamos?

Nelio Forms

Un plugin de contacto fantástico que usa el editor de bloques. En su simplicidad está la potencia del plugin. Me encanta, es muy versátil y funciona de maravilla para mí.

Wajari Velasquez

WordPress.org

Descarga gratis

Versión premium

Añadir la caja de edición (meta box) en el editor de entradas

Por defecto, esta es la apariencia que tiene el editor de entradas de WordPress:

Lo mínimo que cualquier entrada nos exige es un título y un contenido, y eso son las dos primeros campos de texto grandes que vemos. Alrededor de esos dos elementos tenemos un montón de cajitas: Publicar, Imagen Destacada, Etiquetas, Extracto, Categorías… Estas cajas se llaman meta boxes y nos permiten añadir información adicional a nuestra entrada (por ejemplo, una imagen destacada, una lista de etiquetas o las categorías a las que pertenece).

Veamos cómo puedes crear tu propia meta box. Para ello, bastará con realizar una búsqueda rápida en el Codex de WordPress para encontrar una función llamada add_meta_box, la cual tiene todos los números de ser la que necesitamos:

Vamos a invocar esta operación para crear nuestra nueva meta box. Para ello, simplemente hay que añadir el siguiente código:

Permíteme que te explique qué acabamos de hacer 🙂

Para empezar, fíjate que estamos llamando a la función add_meta_box desde una función (wprincipiante_add_meta_boxes) vinculada a una acción (add_meta_boxes). ¿Por qué todo este follón? Bueno, básicamente porque la documentación nos dice que la función add_meta_box debe llamarse desde la acción add_meta_boxes, así que (a) especificamos un nuevo hook y (b) creamos la función asociada (wprincipiante_add_meta_boxes).

La documentación también nos dice que para crear una meta box hay que invocar la función add_meta_box con tres parámetros: $id, $title y $callback. Si miras la documentación sabrás qué es cada parámetro. El interesante ahora mismo es el tercero, el cual indica el nombre de la función que dibuja el contenido de la cajita. En nuestro ejemplo, la función es wprincipiante_print_extension_titulo_meta_box, y como la hemos dejado vacía, la meta box aparece también vacía. Ve a la página de edición de entradas y lo verás:

Si quieres añadirle contenido, simplemente define el cuerpo de la función wprincipiante_print_extension_titulo_meta_box y escribe:

para conseguir esto:

Guardar el nuevo valor

Usando la meta box que acabamos de crear podemos especificar qué texto habrá que añadir en el título de una entrada cualquiera. Sin embargo, antes deberemos guardar este campo en la base de datos y hacerlo permanente.

WordPress nos permite añadir cualquier tipo de información adicional a una entrada dada a través de lo que se conoce como «campos personalizados«. Lo que tenemos que hacer, pues, es usar las funciones que nos permiten manipular estos campos personalizados en el momento en el que la entrada se va a guardar:

Como puedes ver, estamos siguiendo el mismo patrón una y otra vez a lo largo de todo el tutorial de hoy. Así, usamos las acciones y filtros que nos ofrece WordPress para conseguir manipular lo que queremos cuando queremos. En este caso, hemos creado una nueva función (wprincipiante_save_extension_titulo) que se ejecuta en el momento en que WordPress va a guardar una entrada en la base de datos (acción save_post). El código de esta función no tiene ningún secreto:

Añadimos algunas comprobaciones de rigor. Básicamente, miramos que no estemos guardando una copia automática y, ya que la función que estamos creando sirve para guardar el texto de la extensión de título, comprobamos que efectivamente ese texto está definido.

A continuación, cogemos el valor en cuestión y lo pasamos por una función sanitize. Esto es algo importante: siempre que recojamos valores de los usuarios, habrá que pasarlos por una función de estas. Por ejemplo, si esperamos un número entero, hay que comprobar que efectivamente nos ha pasado un entero.

• Para recuperar el valor, accedemos a un array de PHP llamado $_REQUEST. Este array contiene los valores que se hayan enviado al guardar la entrada y, en concreto, el del campo <input type="text"> que hemos añadido en nuestra meta box. Para acceder a ese valor, basta con usar el nombre del campo (wprincipiante-extension-titulo) como índice del array.
• Finalmente, guardamos el valor en un campo personalizado que hemos decidido llamar _wprincipiante_ejemplo_extension_titulo usando la función update_post_meta.
• Ahora, cada vez que editemos y guardemos una entrada, el valor que hayamos introducido en el campo de nuestra meta box se guardará en el campo personalizado _wprincipiante_ejemplo_extension_titulo de la entrada en cuestión.

Ahora bien, si editas una entrada, le añades un texto a ese campo y la guardas, verás que el campo aparecerá vacío, como si no se hubiera guardado correctamente. ¿Por qué pasa eso, si te acabo de decir que sí lo hemos guardado? Sigue leyendo y lo entenderás 😉

Usar el nuevo campo en el front-end y en el back-end

Fijémonos un segundo en la función encargada de pintar el campo de texto, la cual hemos definido antes:

Cada vez que pintamos el campo de texto input, éste está vacío. Si queremos que muestre el valor del campo personalizado _wprincipiante_ejemplo_extension_titulo, tendremos que recuperar ese valor de la base de datos. Así es como deberíamos haberlo hecho:

Para recuperar el valor del campo personalizado, simplemente usamos la función get_post_meta con el identificador de la entrada y el nombre del campo en cuestión. Luego, bastará con escribir el valor donde toque (en este caso, dentro del atributo value value de la etiqueta input).

Fíjate que el echo no es directamente del valor $val, sino que lo pasamos por una función llamada esc_attr. Esta función se encarga de escapar los caracteres que podrían romper el HTML resultante. Por ejemplo, si el valor del campo personalizado fuera:

• Este es mi «texto» favorito

y lo escribiéramos por pantalla directamente, nos quedaría el siguiente value:

que, como puedes ver, se rompe porque hay demasiadas comillas dobles (parece que el valor del atributo value sólo es «Este es mi» y lo que viene después es… quién sabe, algo mal formateado).

En cambio, si usamos la función esc_attr, este es el resultado:

el cual funciona perfectamente (porque las comillas dobles se han sustituido por ").

Finalmente, sólo nos queda usar esta cadena de texto en el front-end. Ya habíamos definido una función (wprincipiante_cambiar_titulo) que modificaba el título de nuestras entradas. Vamos a mejorar esa función para que use el nuevo valor:

Como ves, volvemos a recuperar el valor usando la llamada que ya conocemos, comprobamos que ese valor realmente exista para la entrada en cuestión y, si existe, lo añadimos al título.

¡Y eso es todo! Ya hemos hecho un plugin bastante completito en muy poco tiempo. Interesante, ¿verdad?

Resumiendo

Crear plugins no es excesivamente complicado. Hay que controlar el conjunto de filtros y acciones que nos ofrece WordPress y usarlos según los necesitemos. De todas formas, el código que hemos escrito hoy se puede mejorar muchísimo: estamos mezclando funcionalidades del plugin (código PHP) con la interfaz de usuario (contenido HTML), el código del front-end y del back-end está todo en el mismo fichero, todas las funciones son públicas… En la próxima entrada te explicaré cómo debes organizar el código y compartiré mis cinco trucos para escribir buen código.

¡Nos vemos la semana que viene!

Imagen destacada de mi portátil 😛