Creación de Plugins en WordPress (II): Organización y Trucos

Publicada en WordPress.

Esta entrada forma parte del siguiente tutorial

  1. Creación de Plugins en WordPress (I)
  2. Creación de Plugins en WordPress (II): Organización y Trucos

Seguimos con nuestro tutorial para la creación de plugins en WordPress. En la anterior entrada te expliqué cual es el esqueleto básico de un plugin y viste cómo crear tu primer plugin. Para refrescarte un poco la memoria, esto es lo más importante que debes tener en mente:

  • Los plugins se meten dentro del directorio wp-content/plugins. Cada plugin que crees estará correctamente organizado dentro de su propio directorio: wp-content/plugins/mi-plugin-de-ejemplo.
  • Todo plugin debe tener como mínimo un fichero (mi-plugin-de-ejemplo/mi-plugin-de-ejemplo.php) con una cabecera estándar que indicará el nombre del plugin, el autor, la versión, etc. Esta información es la que luego aparece en el Escritorio de WordPress » Plugins.
  • WordPress ofrece diferentes API para implementar nuevas funcionalidades a través de nuestro plugin. Una API no es más que un conjunto de funciones con un objetivo concreto. Así, tenemos una API para widgets, otra para opciones, otra para plugins…

En la entrada de hoy veremos una forma de estructurar y organizar el código para facilitar su mantenimiento y comprensión, y te explicaré 5 trucos para escribir mejor código.

Nuestro código de ejemplo

¿Recuerdas el ejemplo que creamos hace un par de semanas? Nuestro primer plugin extendía la información de una entrada cualquiera a través de lo que llamamos una «Extensión del título», un pequeño campo de texto que, en caso de tener algún valor, debería añadirse al título de la entrada. También vimos cómo añadir al editor de entradas una meta box que nos permitiera modificar la «Extensión del título» de esa entrada.

Si seguiste los pasos que te di, deberías tener algo parecido a esto:

Problemas

El código anterior, aunque funcional, deja bastante que desear:

  1. Estamos mezclando un montón de conceptos en un mismo fichero. Por ejemplo, lo mismo tenemos código para cambiar el título de una entrada en el front-end, como código que añade elementos gráficos a la página de edición de entradas, como una función que controla qué se guarda en la base de datos.
  2. No sólo estamos haciendo un barullo de funcionalidades, también estamos mezclando los datos y la lógica de nuestro plugin (añadir una meta box o acceder a la base de datos) con la interfaz de usuario (el código HTML que pinta la meta box).
  3. Las diferentes funcionalidades están siempre activas, aunque no se necesiten. El fichero incluye funciones que sólo tienen sentido cuando estamos en el Escritorio de WordPress y otras que sólo tienen sentido si estamos viendo el front-end. No obstante, cada vez que se carga el plugin, se interpreta y ejecuta todo el contenido del fichero, de tal forma que se establecen hooks que pueden no ser necesarios en un momento determinado.

Cuando el código que manejamos es pequeño (como el del ejemplo), estos problemillas no pasan de ser eso, «problemillas». De hecho, simplemente con añadir algún comentario con gracia en nuestro fichero conseguimos un código fácil de entender y seguir, y el coste de cuatro funciones no es elevado.

Pero ahora imagina un plugin que va creciendo, en el que añadimos ficheros JavaScript, hojas de estilo, más funcionalidades, páginas de configuración… Está claro que en ese caso necesitamos orden, necesitamos una forma de organizar nuestro código tal que cada cosa tenga su lugar y un motivo para estar allí y no en otro lado.

Organizando mejor el código

Hace ya unos meses encontré un proyecto en GitHub llamado The Plugin Boilerplate. Este proyecto fue creado originalmente por Tom McFarlin (un desarrollador WordPress cuya forma de trabajar me gusta especialmente; si no le conocías y se te da bien el inglés, te recomiendo que le sigas) y que actualmente está mantenido por Devin Vinson y otros desarrolladores. Tal y como puedes leer en la propia página de GitHub:

WordPress Plugin Boilerplate es una base estandarizada, bien organizada y orientada a objetos pensada para la creación de plugins.

Este «esqueleto» cumple con las guías de estilo de WordPress, está muy bien documentado y propone una estructura de organización de ficheros rígida y funcional. Así que si quieres aprender a crear buenos plugins, partir de esta base es un fantástico ejercicio de aprendizaje y mejora.

Como puedes imaginarte, el Plugin Boilerplate es genial para crear plugins de gran envergadura partiendo de una base sólida y bien pensada. Sin embargo, puede resultar complicado de entender para un desarrollador WPrincipiante, así que hoy sólo nos fijaremos en la organización de ficheros que propone y veremos cómo aplicarla a nuestro ejemplo. ¡Pero no te preocupes! Prometo que pronto hablaremos de él con más detalle 🙂

Nueva Estructura de Directorios

Volvamos a nuestro plugin. Recuerda que estamos partiendo de la siguiente situación: dentro del directorio wp-content/plugins/wprincipiante-ejemplo/ tenemos un único fichero wprincipiante-ejemplo.php, el cual contiene todo el código de nuestro plugin. Como acabamos de ver, esto genera una serie de problemas que podemos resumir en «estamos mezclando demasiadas cosas». ¿Cómo lo solucionamos? ¡Muy fácil! Vamos a separarlas para que cada cosa esté en su sitio. Para ello, vamos a crear la siguiente estructura de directorios:

  • wprincipiante-ejemplo/admin/. Todo el código que esté modificando el Escritorio de WordPress (es decir, la zona de «administración» de nuestro WordPress) irá dentro de este subdirectorio.
  • wprincipiante-ejemplo/public/. Parecido al caso anterior, cualquier código que manipule el front-end de WordPress deberá ubicarse en public.
  • wprincipiante-ejemplo/includes/. Todo lo que no pueda ponerse en alguno de los dos directorios anteriores deberá ir aquí. Por ejemplo, un componente que se usa tanto en el front-end como en el Escritorio de WordPress deberá formar parte de includes.

Como ya te puedes imaginar, cada uno de esto tres directorios puede contener, a su vez, múltiples directorios que ayuden a organizar aún mejor el código. Si echamos un vistazo al Plugin Boilerplate, veremos tres directorios que me parecen muy interesantes para adminpublic:

  • admin/css/public/css/. Contiene las hojas de estilo que se usan en el Escritorio o en el front-end.
  • admin/js/ y public/js/. Equivalente a los directorios anteriores, pero para ficheros JavaScript.
  • admin/partials/public/partials/. Sirve para guardar el código que forma parte de la interfaz de usuario (plantillas y demás).

Distribuir el código en la nueva estructura

¿Has creado ya la nueva jerarquía de directorios? Si es así, lo único que tienes que hacer es romper el código en componentes más pequeños y meterlos en el directorio adecuado. Vamos a ver, paso a paso, cómo hacerlo.

Empezaremos con la vista del meta box. Ya hemos dicho que cualquier cosa que forme parte de la interfaz de usuario irá en un directorio partials y, como en este caso se trata de un componente que forma parte del Escritorio de WordPress, deberá ir en admin/partials/. Este es el fichero que tienes que meter allí:

Fíjate que la plantilla que acabamos de crear utiliza una variable llamada $val que no está inicializada. Aunque pueda parecer un error, no se trata de ningún problema, ya que nos encargaremos de darle un valor cuando vayamos a usar la plantilla. De todas formas, para facilitarnos el trabajo futuro, añadimos un comentario al principio del fichero que nos recuerda que esta plantilla necesita esa variable, el tipo que debe tener y qué «valor» se supone que contiene.

Una vez hemos creado la plantilla para mostrar la meta box, ahora necesitamos tener en algún lado el código que gestiona la meta box en sí. Aunque hay varias formas de hacerlo (las veremos en futuras entradas), hoy optaremos por una solución sencilla y conceptualmente correcta. En concreto, crearemos un fichero con una única función: gestionar la meta box. ¿Qué quiere decir eso? Pues, básicamente, que este fichero se encargará de registrar la meta box en WordPress (para que pueda mostrarse en el editor de entradas) y de guardar los valores que introduzca el usuario:

Con esta decisión, conseguimos un fichero que cumple un único acometido y que tiene perfecto sentido de forma aislada. Además, como hemos separado el código HTML de la meta box de su gestión, ahora tenemos un código mucho más comprensible (¡imagina que follón si la plantilla HTML hubiera sido un poco más grande!).

A continuación, tenemos que añadir el código que se encarga de modificar el título que nuestros usuarios ven en el front-end. Como ya puedes imaginar, este fragmento de código irá en public:

¡Perfecto! Ya tenemos todo el código perfectamente distribuido. Si ahora echas un vistazo al fichero principal de nuestro plugin (wprincipiante-ejemplo.php) verás que está vacío. Lógico, ¿no? Sólo hay un problema: si intentas usar el plugin en este estado verás que nada funciona. Esto es debido a que WordPress sólo lee el fichero principal e ignora los demás. Te corresponde a ti, pues, incluir los demás ficheros según se necesiten:

Los 5 trucos para escribir buen código

Como puedes ver, crear plugins es un trabajo muy entretenido, especialmente si quieres hacerlo «bien». Para completar la lección de hoy me gustaría compartir contigo cinco consejos que ojalá alguien me hubiera dado cuando empecé 😉 Si consigues hacerlos tuyos y aplicarlos en tu día a día, tendrás una base mucho más sólida y el resultado de tus proyectos será infinitamente mejor de lo que imaginas.

Truco #1. Sigue las guías de estilo de WordPress

¿Qué prefieres? ¿Esto?

¿O esto?

Detalles tan sencillos como un espaciado e indentación correctos o usar nombres de variables y funciones que sean auto-explicativos puede tener un gran impacto en la calidad final de tu trabajo. Si vas a dedicarte a programar para WordPress, te recomiendo que eches un vistazo a los estándares de programación que tienen para PHP, HTML, JavaScript y CSS. Familiarizarse con ellos te ayudará a escribir mejor código y, además, conseguirás que se integre mucho mejor con el estilo de WordPress, facilitando el trabajo a otros desarrolladores WordPress que, probablemente, también estén siguiendo las mismas guías.

Relacionado con esto, te recomiendo que escribas tu código en inglés. Creo que la mayoría de programadores de alrededor del mundo son más o menos diestros con el idioma de Shakespeare, por lo que escribir y compartir tu trabajo en inglés hace que éste pueda llegar a más gente. De hecho, es bastante probable que tarde o temprano trabajes con gente de otros países, así que merece la pena tener cierta soltura escribiendo tu código y tus comentarios en ese idioma.

Truco #2. Sé ordenado con el código fuente

La entrada de hoy trataba precisamente de esto y el Plugin Boilerplate que he presentado es un buen ejemplo de ello. Simplemente recuerda las siguientes reglas y todo será más fácil:

  1. Utiliza la estructura de directorios que hemos visto: las funcionalidades del front-end van al directorio public/, todas las de administración (esto es, Escritorio de WordPress) a admin/ y todo lo demás en includes/.
  2. Utiliza subdirectorios para clasificar mejor tu código. Hoy hemos visto, por ejemplo, los de vistas (views/ y views/partials/), pero también puedes crear directorios para los ficheros JavaScript (js/) o CSS (css/). Todo esto, obviamente, respetando la estructura del punto 1.
  3. Aunque en nuestros ejemplos no lo hemos visto, es posible programar los plugins usando clases. Siempre que crees una clase PHP, hazlo en su propio fichero (el cual, por cierto, no debe tener nada más).
  4. Cada fichero/clase debería representar una única funcionalidad (por ejemplo, en nuestro ejemplo hemos creado uno para la gestión de la meta box).
  5. Jamás mezcles la capa de presentación (el código HTML) con la lógica de tu plugin (o sea, el código PHP que recupera, procesa y guarda datos).
  6. Carga las cosas cuando sea necesario. Por ejemplo, si estás en el front-end, no cargues cosas del Escritorio (utiliza la función is_admin()).

Truco #3. Tómate la seguridad en serio

Un consejo que todo el mundo conoce y que, por desgracia, casi siempre olvidamos. Es normal, cuando te pones a trabajar en un proyecto nuevo quieres que las cosas funcionen lo antes posible… para luego ya, si eso, preocuparte de la seguridad y la eficiencia.

¡Error! Tienes que tomarte la seguridad en serio. Si sigues estas reglas, podrás garantizar un mínimo de seguridad y robustez en tu plugin:

  1. Siempre que vayas a pintar algo por pantalla, asegúrate de que está correctamente escapado. Para ello, familiarízate con funciones tales como esc_url, esc_attr or esc_html.
  2. Siempre «limpia» (sanitize, en inglés) las entradas del usuario. Si estás esperando que el usuario te introduzca un número, asegúrate de convertir su entrada en un número; si esperas un texto sin código HTML, elimina las posibles etiquetas con strip_tags.
  3. Utiliza nonces para verificar formularios y URLs. Siempre que recojas información de un formulario, debes comprobar que esa información realmente viene del formulario y que no es algo que ha generado un agente externo malicioso. Esto se consigue a través de los nonces, un número de seguridad que sólo puede usarse una vez. Te recomiendo que leas más sobre ellos en el Codex.

Truco #4. Comenta el código

Los proyectos funcionan gracias al código, no a los comentarios, ¿no? Por ello, puede parecer que es mucho mejor centrarse en escribir código que sea inteligible y pasar de perder el tiempo en comentarios que, en fin, «no sirven de nada». ¿Para qué escribir código? Si partimos de la base que nuestro código es limpio y comprensible, ¿qué aportan?

En mi opinión, los comentarios capturan las intenciones del desarrollador (es decir, nuestras intenciones). Cuando escribes un fragmento de código se supone que estás intentando resolver un problema. Describir cuál es ese problema y cómo piensas resolverlo es la función de los códigos. Los comentarios no tienen por qué decir qué hace el código; tienen que explicar qué intentabas resolver y cómo pensabas que podías solucionarlo. Con esta idea en la cabeza verás que, de repente, tu código (y el de los demás) es muchísimo más fácil de entender, porque podrás recuperarlo en cualquier momento y entender por qué las cosas son como son… recuperarás el contexto. Y eso siempre mola, ¿no?

Cuando escribas comentarios, pues, intenta expresar tus intenciones y objetivos. No te quedes en lo superficial:

e intenta ir un poco más allá:

Truco #5. Haz que tu plugin defina sus propios filtros y acciones

Una de las cosas que hemos aprendido a lo largo de estas dos entradas es cómo usar los filtros y acciones de WordPress. Pero ¿sabías que puedes crear tus propios filtros y acciones? Es decir, que puedes preparar el código de tu plugin (o tema) para que otras personas lo extiendan.

Para ello, lo único que tienes que hacer es definir en qué momento un plugin puede ser extendido (por ejemplo, cuando se activa, o cuando vas a modificar algo del front-end) y añadir allí el código de extensión con las funciones do_action o apply_filters de WordPress. Usando este mecanismo, serás capaz de añadir tú mismo nuevas funcionalidades en tu plugin, enganchándote a esos puntos de extensión desde el propio plugin o creando plugins completamente nuevos que extienden y complementan al original.

Conclusión

Hoy hemos dado una pequeña vuelta de tuerca al ejemplo que hicimos en la primera parte de este tutorial. En concreto, hemos visto la importancia que tiene la estructura del código y cómo puede ayudarnos a mantener el código limpio, ordenado y comprensible. Además, hemos visto cinco trucos que debemos aplicar a la hora de escribir código. Te recomiendo que los interiorices y apliques a tus creaciones; tu yo del futuro te lo agradecerá 😉

¡Espero que hayas disfrutado! En la próxima entrada te presentaré con más detalle el Plugin Boilerplate y otro esqueleto en el que estoy trabajando.

Imagen destacada de James j8246.

FlojaNo está malBienMuy bien¡Impecable! (5 votos, promedio: 5,00 de 5)
Cargando…

6 comentarios en «Creación de Plugins en WordPress (II): Organización y Trucos»

  1. Hola. Muy buena la explicacion, muy claro todo. Hay mas ? Porque no se ve ningun boton para continuar

    1. ¡Hola, Marcelo!

      Vaya, parece que no llegué a publicar nada más sobre el tema. Me temo, pues, que no tenemos nada más publicado de momento sobre el tema. Pero sigue atento al blog, porque siempre vamos publicando pequeños trucos y consejos que pueden ayudarte.

      Un saludo,
      David

  2. Hola, como hago para integrar bootstrap al plugin sin que entre en conflicto con la versión de bootstrap que tiene el tema si es que lo tiene. Muy buena la info!!!

Deja un comentario

No publicaremos tu correo electrónico. Los campos obligatorios están marcados con: •

He leído y acepto la Política de privacidad de Nelio Software

Al marcar la casilla de aceptación estás dando tu legítimo consentimiento para que tu información personal se almacene en SiteGround y sea usada por Nelio Software con el propósito único de publicar aquí este comentario. Contáctanos para corregir, limitar, eliminar o acceder a tu información.