Creación de Plugins en WordPress (I)

Creación de Plugins en WordPress (I)

0 338

Hará más o menos dos años que 3 compañeros (y amigos) míos decidimos probar suerte y tirar adelante una idea de negocio chulísima. Por cierto motivo, decidimos que la montaríamos encima de WordPress, aunque por aquel entonces no teníamos clarísimo de qué manera funcionaba WordPress y de qué manera podíamos extenderlo… Todavía de esta manera, fuimos bastante audaces y nos tiramos a la piscina Como puedes imaginar, los primeros meses fueron moviditos”; tuvimos que adquirir un montón de conocimientos en escaso tiempo para poder iniciar cuanto antes con el desarrollo. ¿Qué hicimos? Lo mismo que tú ahora: buscar y leer recursos y tutoriales en internet y escribir mucho, muchísimo código de prueba

Después de dos años trabajando únicamente en el ecosistema de WordPress y de haber desarrollado múltiples plugins, he pensado que sería una buena idea compartir mi experiencia contigo y enseñarte cómo crear complementos en WordPress. Durante esta y próximas entradas, te explicaré todo lo que necesitas saber para redactar buenos plugins, es decir, plugins que sean funcionales, extensibles y mantenibles. En cierto modo, pues, intentaré crear el tutorial que me hubiese agradado tener cuando comencé. Como verás, habrá poca teoría y mucha práctica… de tal modo que los conocimientos que vas a deber adquirir irán apareciendo a medida que los precisemos. ¡Espero que te guste!

En la entrada de hoy vas a aprender 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 carpetita en el directorio wp-content/plugins/ y incorporar un archivo con el código fuente. Por servirnos de un ejemplo, crearemos un plugin que se llame wprincipiante-ejemplo. Para ello, crea la carpetita wp-content/plugins/wprincipiante-ejemplo/ y añade un nuevo archivo dentro llamado wprincipiante-ejemplo.php con el próximo contenido:

Si ahora vamos al Escritorio de WordPress » Plugins, veremos que nuestro nuevo plugin Ejemplo de WPrincipiante aparece adecuadamente listado, con su versión, su autor, su descripción, enlaces a nuestra web… Vamos, que WordPress está utilizando 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 completamente nada útil. WordPress ofrece diferentes APIs para incorporar 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 complemento.
  • Options API. Deja guardar (y recuperar) las opciones de configuración de nuestro plugin.
  • Widgets API. Deja crear nuevos widgets que van a poder 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 mucho detalle la API de Plugins. Esencialmente, acá hallamos 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 incorporar un poco de funcionalidad al complemento. Añade el próximo fragmento de código al final del fichero wprincipiante.php (no vuelvas a incluir la etiqueta <>; únicamente la agrego para que el código tenga destacado de sintaxis):

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

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

  • Función add_filter. Es, como te afirmaba, el primer hook que usaremos. Acá, lo que básicamente le estamos diciendo a WordPress es que cuando se produzca el acontecimiento the_title (o sea, cuando WordPress esté a punto de redactar 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, conque habrá que crearla. Por si fuera poco, le hemos dicho (pues así está documentado) que la función deberá admitir 2 parámetros ( dólares americanos title y también $ id). Vamos, pues, a crear esta función.
  • El cuerpo de la función. Finalmente, solo nos queda ver y comprender el cuerpo de la función wprincipiante_cambiar_titulo, el cual no tiene ningún misterio: simplemente le agrega al título la cadena [Exclusiva].

Tipos de hooks: filtros y acciones

Recordemos que existen 2 géneros de hooks:

Extender la información de las entradas

De instante, 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 de qué manera emplear ciertos recursos más de los que nos ofrece WordPress para hacer un complemento más potente. Específicamente, vamos a:

  1. Modificar el editor de entradas. Añadiremos una nueva caja de edición en las entradas de WordPress donde vamos a poder precisar un texto cualquiera. Este texto va a ser concreto de cada entrada (como lo son el título o bien 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 dejará guardar 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 guardada en dos.

Por ejemplo, pongamos que tenemos 2 entradas en WordPress:

  • ¡Hola Planeta!
  • Bienvenidos a mi blog

Nuestro objetivo es que el creador de una entrada pueda añadir el texto que desee al título (por servirnos de un ejemplo, WordPress mola” en la primera entrada) a fin de que, en el momento en que un visitante acceda al weblog, vea lo siguiente:

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

¿Comenzamos?

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:

Captura de pantalla del editor de entradas por defecto de WordPress.
Captura de pantalla del editor de entradas por defecto de WordPress.

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

Veamos de qué manera puedes crear tu propia meta box. Para ello, va a bastar con realizar una búsqueda rápida en el Codex de WordPress para hallar 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, sencillamente hay que añadir el próximo código:

Permíteme que te explique qué acabamos de hacer :-)

Para comenzar, 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 pues la documentación nos dice que la función add_meta_box debe llamarse desde la acción add_meta_boxes, conque (a) detallamos un nuevo hook y (b) creamos la función socia (wprincipiante_add_meta_boxes).

La documentación también nos afirma que para crear una meta box hay que invocar la función add_meta_box con tres parámetros: dólares americanos id, dólares americanos title y dólares americanos callback. Si miras la documentación vas a saber qué es cada factor. El interesante ahora 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 asimismo vacía. Ve a la página de edición de entradas y lo verás:

Nueva meta box
Nueva meta box Extensión del Título” vacía.

Si deseas incorporarle contenido, simplemente define el cuerpo de la función wprincipiante_print_extension_titulo_meta_box y escribe:

para lograr esto:

Nueva meta box
Nueva meta box Extensión del Título” con un campo de texto que el usuario puede rellenar.

Guardar el nuevo valor

Usando la meta box que acabamos de crear podemos especificar qué texto va a haber que agregar en el título de una entrada cualquiera. Sin embargo, ya antes vamos a deber guardar este campo en la base de datos y hacerlo permanente.

WordPress nos permite añadir cualquier género de información adicional a una entrada dada por medio de lo que se conoce como campos personalizados. Lo que debemos hacer, puesto que, es emplear las funciones que nos permiten manipular estos campos personalizados en el instante en el que la entrada se va a guardar:

Como puedes ver, estamos siguiendo el mismo patrón una y otra vez durante todo el tutorial de hoy. De esta forma, empleamos las acciones y filtros que nos ofrece WordPress para lograr manipular lo que deseamos cuando deseamos. En este caso, hemos creado una nueva función (wprincipiante_save_extension_titulo) que se ejecuta en el momento en que WordPress 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. Esencialmente, miramos que no estemos guardando una copia automática y, puesto que la función que creamos sirve para guardar el texto de la extensión de título, verificamos 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 y cuando recojamos valores de los usuarios, habrá que pasarlos por una función de estas. Por poner un ejemplo, si aguardamos un número entero, hay que revisar que ciertamente nos ha pasado un entero.

  • Para recobrar el valor, accedemos a un array de PHP llamado $ _REQUEST. Este array contiene los valores que se hayan enviado al guardar la entrada y, concretamente, el del campo 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, toda 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 agregas un texto a ese campo y la guardas, verás que el campo aparecerá vacío, tal y como si no se hubiese guardado apropiadamente. ¿Por qué ocurre eso, si te acabo de decir que sí lo hemos guardado? Sigue leyendo y lo comprenderá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 que 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. Es de esta forma como deberíamos haberlo hecho:

Para recuperar el valor del campo personalizado, simplemente utilizamos la función get_post_meta con el identificador de la entrada y el nombre del campo en cuestión. Entonces, va a bastar con redactar el valor donde toque (en un caso así, dentro del atributo value value de la etiqueta input).

Fíjate que el echo no es de manera directa del valor  dólares americanos 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 servirnos de un 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 por el hecho de que 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 utilizamos la función esc_attr, este es el resultado:

el cual marcha con perfección (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 alteraba el título de nuestras entradas. Mejoraremos esa función para que use el nuevo valor:

Como ves, volvemos a recobrar el valor utilizando la llamada que ya conocemos, verificamos que ese valor verdaderamente exista para la entrada en cuestión y, si existe, lo añadimos al título.

¡Y eso es todo! Ya hemos hecho un complemento 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 emplearlos según los necesitemos. De todas y cada una formas, el código que hemos escrito hoy se puede prosperar muchísimo: estamos mezclando funcionalidades del complemento (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 archivo, todas las funciones son públicas… En la próxima entrada te voy a explicar de qué manera debes organizar el código y compartiré mis 5 trucos para redactar buen código.

¡Nos vemos la semana que viene!

Imagen destacada de mi portátil

NO COMMENTS

Leave a Reply