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

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

0 304

Seguimos con nuestro tutorial para la creación de complementos en WordPress. En la anterior entrada te expliqué como es el esqueleto básico de un complemento y viste de qué manera crear tu primer complemento. 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 complemento que crees va a estar adecuadamente organizado en su directorio: wp-content/plugins/mi-plugin-de-ejemplo.
  • Todo plugin debe tener por lo menos un archivo (mi-plugin-de-ejemplo/mi-complemento-de-ejemplo.php) con una cabecera estándar que señalará el nombre del complemento, el autor, la versión, etc. Esta información es la que entonces aparece en el Escritorio de WordPress » Plugins.
  • WordPress ofrece diferentes API para implementar nuevas funcionalidades mediante nuestro complemento. Una API no es más que un conjunto de funciones con una meta concreto. De esta manera, tenemos una API para widgets, otra para opciones, otra para plugins…

En la entrada de hoy vamos a ver una forma de vertebrar y organizar el código para facilitar su mantenimiento y entendimiento, 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 complemento extendía la información de una entrada cualquiera mediante 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 de qué forma agregar 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 semejante a esto:

Problemas

El código precedente, si bien funcional, deja bastante que desear:

  1. Estamos mezclando un montón de conceptos en un mismo fichero. Por poner un 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 ruido de funcionalidades, también estamos mezclando los datos y la lógica de nuestro plugin (incorporar 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 y en toda circunstancia activas, aunque no se necesiten. El archivo incluye funciones que sólo tienen sentido cuando estamos en el Escritorio de WordPress y otras que solo tienen sentido si estamos viendo el front-end. No obstante, toda vez que se carga el plugin, se interpreta y ejecuta todo el contenido del archivo, de tal manera 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 archivo logramos un código fácil de comprender y proseguir, y el coste de cuatro funciones no es elevado.

Pero ahora imagina un plugin que va medrando, 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, precisamos 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 agrada especialmente; si no le conocías y se te da bien el inglés, te recomiendo que le sigas) y que hoy día está mantenido por Devin Vinson y otros desarrolladores. Tal como puedes leer en la propia página de GitHub:

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

Este esqueleto” cumple con las guías de estilo de WordPress, está realmente bien documentado y plantea una estructura de organización de archivos rígida y funcional. Conque 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. No obstante, puede resultar complicado de comprender para un desarrollador WPrincipiante, con lo que hoy solo nos fijaremos en la organización de ficheros que plantea y veremos de qué forma aplicarla a nuestro ejemplo. ¡Pero deja de preocuparte! Prometo que pronto hablaremos de él con más detalle :-)

Nueva Estructura de Directorios

Volvamos a nuestro plugin. Recuerda que estamos partiendo de la próxima situación: en el directorio wp-content/plugins/wprincipiante-ejemplo/ tenemos un único fichero wprincipiante-ejemplo.php, el que 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 resolvemos? ¡Muy simple! Vamos a separarlas a fin de que cada cosa esté en su sitio. Para esto, vamos a crear la próxima estructura de directorios:

  • wprincipiante-ejemplo/admin/. Todo el código que esté alterando el Escritorio de WordPress (es decir, la zona de administración” de nuestro WordPress) va a ir dentro de este subdirectorio.
  • wprincipiante-ejemplo/public/. Parecido al caso anterior, cualquier código que manipule el front-end de WordPress va a deber ubicarse en public.
  • wprincipiante-ejemplo/includes/. Todo lo que no pueda ponerse en alguno de los 2 directorios precedentes deberá ir acá. Por ejemplo, un componente que se utiliza tanto en el front-end como en el Escritorio de WordPress deberá ser parte de includes.

Como ya te puedes imaginar, cada uno de ellos de esto 3 directorios puede contener, por su parte, múltiples directorios que ayuden a organizar todavía mejor el código. Si echamos una ojeada al Plugin Boilerplate, vamos a ver 3 directorios que me semejan bien interesantes para adminpublic:

  • admin/css/public/css/. Contiene las hojas de estilo que se emplean 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 es parte integrante 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 de esta manera, lo único que debes hacer es romper el código en componentes más pequeños y meterlos en el directorio conveniente. Veremos, 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 va a ir en un directorio partials y, como en un caso así 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 terminamos de crear utiliza una variable llamada  dólares americanos val que no está iniciada. 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 y cada una formas, para facilitarnos el trabajo futuro, agregamos un comentario al comienzo 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 administra la meta box en sí. Si bien hay múltiples formas de hacerlo (las vamos a ver en futuras entradas), el día de hoy optaremos por una solución fácil y conceptualmente adecuada. En concreto, crearemos un archivo con una única función: administrar la meta box. ¿Qué quiere decir eso? Puesto que, esencialmente, que este archivo 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, logramos un fichero que cumple un único acometido y que tiene perfecto sentido de forma aislada. Además de esto, como hemos separado el código HTML de la meta box de su gestión, ahora tenemos un código considerablemente más entendible (¡imagina que follón si la plantilla HTML hubiese sido un poco más grande!).

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

¡Perfecto! Ya tenemos todo el código con perfección distribuido. Si ahora echas un vistazo al archivo primordial de nuestro complemento (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 vas a ver que nada marcha. Esto es debido a que WordPress sólo lee el fichero principal e ignora el resto. Te corresponde a ti, pues, incluir el resto ficheros según se necesiten:

Los 5 trucos para redactar buen código

Como puedes ver, crear plugins es un trabajo muy entretenido, en especial si deseas hacerlo bien”. Para completar la lección de el día de hoy me agradaría compartir contigo 5 consejos que ojalá alguien me hubiese dado cuando comencé Si consigues hacerlos tuyos y aplicarlos en tu cada día, vas a tener una base considerablemente más sólida y el resultado de tus proyectos será interminablemente mejor de lo que imaginas.

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

¿Qué prefieres? ¿Esto?

¿O esto?

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

Relacionado con esto, te recomiendo que escribas tu código en inglés. Creo que la mayor parte de programadores de alrededor del planeta son más o menos diestros con el idioma de Shakespeare, con lo que redactar y compartir tu trabajo en inglés hace que este pueda llegar a más gente. De hecho, es bastante probable que tarde o bien temprano trabajes con gente de otros países, así que vale 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 el día de hoy trataba precisamente de esto y el Complemento Boilerplate que he presentado es un buen ejemplo de ello. Simplemente recuerda las siguientes reglas y todo va a 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 poner un ejemplo, los de vistas (views/ y views/partials/), pero asimismo puedes crear directorios para los archivos JavaScript (js/) o bien 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 utilizando clases. Siempre que crees una clase PHP, hazlo en su propio fichero (el que, 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 (es decir, el código PHP que recupera, procesa y guarda datos).
  6. Carga las cosas cuando sea preciso. 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 planeta conoce y que, por desgracia, casi siempre y en toda circunstancia olvidamos. Es normal, en el momento en que te pones a trabajar en un proyecto nuevo quieres que las cosas funcionen lo ya antes posible… para entonces ya, si eso, preocuparte de la seguridad y la eficiencia.

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

  1. Siempre que vayas a pintar algo por pantalla, cerciórate de que está apropiadamente 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 aguardando que el usuario te introduzca un número, asegúrate de transformar 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 contrastar formularios y URLs. Toda vez que recojas información de un formulario, debes comprobar que esa información realmente viene del formulario y que no es cosa que ha generado un agente externo malicioso. Esto se consigue por medio de los nonces, un número de seguridad que solo puede utilizarse una vez. Te invito a que leas más sobre ellos en el Codex.

Truco #4. Comenta el código

Los proyectos funcionan merced 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 resumen, no sirven de nada”. ¿Para qué exactamente escribir código? Si partimos de la base que nuestro código es limpio y entendible, ¿qué aportan?

En mi opinión, los comentarios atrapan las intenciones del desarrollador (esto es, nuestras intenciones). Cuando escribes un fragmento de código se supone que estás procurando solucionar 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é procurabas resolver y de qué forma pensabas que podías solucionarlo. Con esta idea en la cabeza vas a ver que, de pronto, tu código (y el de los demás) es mucho más simple de entender, pues vas a poder recuperarlo en cualquier instante y comprender por qué las cosas son como son… recobrarás el contexto. Y eso siempre y en toda circunstancia mola, ¿no?

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

e procura ir un tanto más allá:

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

Una de las cosas que hemos aprendido durante estas 2 entradas es de qué forma usar los filtros y acciones de WordPress. Mas ¿sabías que puedes crear tus propios filtros y acciones? Es decir, que puedes preparar el código de tu plugin (o tema) a fin de que otras personas lo extiendan.

Para ello, lo único que debes hacer es definir exactamente en qué momento un complemento puede ser extendido (por servirnos de un ejemplo, cuando se activa, o cuando vas a alterar algo del front-end) y incorporar allí el código de extensión con las funciones do_action o apply_filters de WordPress. Usando este mecanismo, serás capaz de agregar mismo nuevas funcionalidades en tu plugin, enganchándote a esos puntos de extensión desde el propio complemento o bien 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 una parte de este tutorial. Específicamente, hemos visto la importancia que tiene la estructura del código y de qué manera puede ayudarnos a sostener el código limpio, ordenado y entendible. Además de esto, hemos visto cinco trucos que debemos aplicar en el momento de escribir código. Te invito a 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 Complemento Boilerplate y otro esqueleto en el que estoy trabajando.

Imagen destacada de James j8246.

SIMILAR ARTICLES

NO COMMENTS

Leave a Reply