Timber by EMSIEN-3 LTD
Tags Posts tagged with "organizacin"

organizacin

0 360

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

  • Los complementos se meten en el directorio wp-content/plugins. Cada complemento que crees va a estar adecuadamente organizado en su propio directorio: wp-content/plugins/mi-complemento-de-ejemplo.
  • Todo complemento debe tener como mínimo un archivo (mi-complemento-de-ejemplo/mi-complemento-de-ejemplo.php) con una cabecera estándar que señalará el nombre del complemento, el creador, 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 por medio de nuestro plugin. 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 plugin extendía la información de una entrada cualquiera por medio 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. Asimismo vimos de qué manera agregar al editor de entradas una meta box que nos permitiera modificar la Extensión del título” de esa entrada.

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

Problemas

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

  1. Estamos mezclando un montón de conceptos en un mismo fichero. Por servirnos de un ejemplo, lo mismo tenemos código para mudar el título de una entrada en el front-end, como código que agrega 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 solo estamos haciendo un estruendo de funcionalidades, también estamos mezclando los datos y la lógica de nuestro plugin (agregar una meta box o bien 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 todo momento activas, si bien no se precisen. El fichero incluye funciones que solo tienen sentido cuando estamos en el Escritorio de WordPress y otras que solo tienen sentido si estamos viendo el front-end. No obstante, cada vez que se carga el complemento, se interpreta y ejecuta todo el contenido del fichero, de tal forma que se establecen hooks que pueden no ser precisos 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”. En verdad, sencillamente con agregar algún comentario con gracia en nuestro fichero logramos un código fácil de comprender y continuar, y el coste de 4 funciones no es elevado.

Pero ahora imagina un complemento que va creciendo, en el que añadimos archivos JavaScript, hojas de estilo, más funcionalidades, páginas de configuración… No hay duda de que en un caso así precisamos 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 prosigas) 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 complementos.

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

Como puedes imaginarte, el Complemento Boilerplate es excelente para crear plugins de gran extensión partiendo de una base sólida y bien pensada. Sin embargo, puede resultar complicado de entender para un desarrollador WPrincipiante, conque hoy solo nos vamos a fijar en la organización de archivos que plantea y vamos a ver cómo aplicarla a nuestro ejemplo. ¡Mas deja de preocuparte! Prometo que pronto hablaremos de él con más detalle :-)

Nueva Estructura de Directorios

Volvamos a nuestro plugin. Recuerda que partimos de la siguiente situación: dentro del directorio wp-content/plugins/wprincipiante-ejemplo/ tenemos un único archivo wprincipiante-ejemplo.php, el que contiene todo el código de nuestro complemento. Como acabamos de ver, esto produce una serie de inconvenientes que podemos resumir en estamos mezclando demasiadas cosas”. ¿De qué forma lo resolvemos? ¡Muy fácil! Vamos a separarlas para que cada cosa esté en su lugar. 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 en este subdirectorio.
  • wprincipiante-ejemplo/public/. Semejante al caso precedente, cualquier código que manipule el front-end de WordPress va a deber situarse en public.
  • wprincipiante-ejemplo/includes/. Todo lo que no pueda ponerse en alguno de los 2 directorios precedentes deberá ir acá. Por poner un 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 tres directorios puede contener, a su vez, múltiples directorios que ayuden a organizar aún mejor el código. Si echamos una ojeada al Complemento Boilerplate, vamos a ver 3 directorios que me parecen muy interesantes para adminpublic:

  • admin/css/public/css/. Contiene las hojas de estilo que se utilizan en el Escritorio o en el front-end.
  • admin/js/ y public/js/. Equivalente a los directorios precedentes, mas 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 forma, lo único que tienes que hacer es romper el código en componentes más pequeños y meterlos en el directorio conveniente. Veremos, paso a paso, de qué forma 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 este caso se trata de un componente que forma parte del Escritorio de WordPress, va a deber ir en admin/partials/. Este es el fichero que debes meter allí:

Fíjate que la plantilla que terminamos de crear utiliza una variable llamada $ val que no está iniciada. Aunque pueda parecer un fallo, no se trata de ningún inconveniente, en tanto que nos encargaremos de darle un valor cuando vayamos a emplear la plantilla. De todas y cada una maneras, para facilitarnos el trabajo futuro, agregamos un comentario al comienzo del fichero que nos recuerda que esta plantilla precisa esa variable, el tipo que debe tener y qué valor” se supone que contiene.

Una vez hemos creado la plantilla para enseñar la meta box, ahora necesitamos tener en algún lado el código que administra 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 adecuada. Concretamente, crearemos un fichero con una única función: administrar la meta box. ¿Qué quiere decir eso? Puesto que, esencialmente, que este fichero se ocupará 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 archivo 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 administración, ahora tenemos un código mucho más comprensible (¡imagina que follón si la plantilla HTML hubiera sido un tanto más grande!).

A continuación, debemos añadir el código que se hace cargo de alterar 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 perfectamente distribuido. Si ahora echas una ojeada al fichero primordial de nuestro complemento (wprincipiante-ejemplo.php) vas a ver que está vacío. Lógico, ¿no? Sólo hay un problema: si intentas usar el plugin en este estado verás que nada marcha. Esto es debido a que WordPress sólo lee el fichero primordial y también ignora el resto. Te corresponde a ti, pues, incluir los demás ficheros conforme 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 el día de hoy me agradaría compartir contigo cinco consejos que esperemos alguien me hubiese dado cuando comencé Si logras hacerlos tuyos y aplicarlos en tu día a día, tendrás una base considerablemente más sólida y el resultado de tus proyectos va a ser infinitamente mejor de lo que imaginas.

Truco #1. Prosigue 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 enorme impacto en la calidad final de tu trabajo. Si vas a dedicarte a programar para WordPress, te invito a que eches un vistazo 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, por si fuera poco, conseguirás que se integre mucho mejor con el estilo de WordPress, facilitando el trabajo a otros desarrolladores WordPress que, seguramente, 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 parte de programadores de alrededor del mundo son más o menos diestros con el idioma de Shakespeare, por 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 temprano trabajes con gente de otros países, conque 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 Complemento Boilerplate que he presentado es un buen ejemplo de ello. Simplemente recuerda las próximas 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 y cada una de 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 servirnos de un ejemplo, los de vistas (views/ y views/partials/), mas también puedes crear directorios para los archivos 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 complementos usando clases. Siempre que crees una clase PHP, hazlo en su propio fichero (el que, a propósito, no debe tener nada más).
  4. Cada fichero/clase debería representar una única funcionalidad (por poner un ejemplo, en nuestro ejemplo hemos creado uno para la administració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 (esto es, el código PHP que recobra, procesa y guarda datos).
  6. Carga las cosas cuando sea preciso. Por poner un 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, desgraciadamente, casi siempre y en toda circunstancia olvidamos. Es normal, cuando te pones a trabajar en un proyecto nuevo deseas que las cosas funcionen lo ya antes posible… para luego ya, si eso, preocuparte de la seguridad y la eficacia.

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

  1. Siempre que vayas a pintar algo por pantalla, cerciórate de que está adecuadamente escapado. Para esto, familiarízate con funciones 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 transformar su entrada en un número; si esperas un texto sin código HTML, suprime las posibles etiquetas con strip_tags.
  3. Utiliza nonces para contrastar formularios y URLs. Siempre y cuando recojas información de un formulario, debes revisar que esa información realmente viene del formulario y que no es algo que ha generado un agente externo malicioso. Esto se consigue mediante los nonces, un número de seguridad que sólo puede emplearse 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 este motivo, puede parecer que es mucho mejor centrarse en escribir código que sea comprensible y pasar de perder el tiempo en comentarios que, en resumen, no sirven de nada”. ¿Para qué exactamente redactar código? Si partimos de la base que nuestro código es limpio y comprensible, ¿qué aportan?

En mi opinión, los comentarios atrapan las pretensiones del desarrollador (es decir, nuestras intenciones). Cuando escribes un fragmento de código se supone que estás procurando resolver un inconveniente. Describir cuál es ese inconveniente 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 solucionar y cómo pensabas que podías solventarlo. Con esta idea en la cabeza verás que, de súbito, tu código (y el del resto) es mucho más simple de entender, porque podrás recuperarlo en cualquier momento y entender por qué las cosas son como son… recobrarás el contexto. Y eso siempre mola, ¿no?

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

e intenta ir un tanto más allá:

Truco #5. Haz que tu plugin defina sus 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. Pero ¿sabías que puedes crear tus filtros y acciones? O sea, que puedes preparar el código de tu plugin (o bien tema) para que otras personas lo extiendan.

Para ello, lo único que tienes que hacer es definir exactamente en qué instante un complemento puede ser extendido (por poner un ejemplo, cuando se activa, o cuando vas a modificar algo del front-end) y incorporar allí el código de extensión con las funciones do_action o bien 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 complemento 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 de qué forma 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 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.

ARTÍCULOS ALEATORIOS

0 924
WordPress es conocido por su facilidad de instalación. Sin embargo, siempre va bien recordar los pasos a seguir a fin de evitar posibles inconvenientes....