Bitácora de Gesbit

Otra de las cosas que me preocupan en Gesbit es la documentación que pueda y aun deba incorporar. Me estoy esforzando últimamente en preparar una documentación del código fuente que se muestre bien y sea realmente útil. La idea es que cualquier persona pueda adentrarse en el código fuente de Gesbit y comprenderlo más o menos perfectamente. Por supuesto, no he empezado ahora, y de hecho he dedicado mucho tiempo a la documentación, pero, es una tarea de nunca acabar.

Efectivamente, los cambios en el código fuente de Gesbit (que son constantes) implican cambios en la documentación del mismo, y, además, no todos los comentarios a modo de documentación que incluye el código es "consistente" como para presentarlo luego en el HTML que puede generar una herramienta como PHPDoc, que es la que uso para generar la documentación de Gesbit a partir de su código fuente. Quiere decirse que a veces esta no se presenta adecuadamente.

Esto es lo que me he propuesto cambiar, y en esto es en lo que estoy trabajando, si bien es una tarea un tanto más ingrata que cuando estás arreglando algún problema o añadiendo alguna funcionalidad o mejorando alguna existente. Sin embargo, ¿quién duda de que es importante? Porque además cada "script" en Gesbit tiene una razón de ser, se requiere allí donde es necesario únicamente (por alguna razón), en definitiva, es preciso comprender todo esto si se quiere uno adentrar en Gesbit a esos niveles.

Es una tarea más ingrata que otras, pues, como digo, está sujeta a cambios, que, a veces, echan a perder párrafos y más párrafos que dejan con los cambios de tener sentido. Aunque también es agradable darte cuenta de que tienes el sistema de Gesbit en la cabeza, que, funcione mejor o peor, está paso por paso, casi línea por línea de código metido en tu cabeza, como quien lleva más de un año trabajando sobre el mismo, claro está. Pues bien, lo agradable estriba en tratar de sacarlo de tu cabeza y explicárselo a otros mediante la documentación.

Y todavía no hablamos de la documentación para desarrolladores de temas y plugins para Gesbit, así como la relativa a la traducción del mismo a otros idiomas. Esta documentación habrá de separarse del código fuente, propiamente, aunque, a decir verdad, la idea es que al menos los desarrolladores de plugins para Gesbit puedan también conocer el sistema de Gesbit, más allá de los recursos que se les ofrece para llevar a cabo plugins para el mismo. Pues no sé, por ejemplo, tengo pendiente una especie de tutorial acerca de las "convenciones" usadas en Gesbit.

Total, que hay tarea por delante. Mucha tarea, a decir verdad. Pero, que, vamos poco a poco haciéndola. Debería ser cuestión de tiempo. Y mientras quede cierta ilusión seguiré adelante, desde luego, aunque sea con algo como la documentación de Gesbit y alrededor de Gesbit, que no es lo que más me agrada, como ya he dicho, pero, que, considero muy necesaria, realmente. Pienso, por ejemplo, en las capacidades de los nuevos entornos para trabajar con PHP. Efectivamente, estos entornos hacen buen uso de la documentación del código fuente, facilitando la tarea de desarrollar un determinado proyecto, en este caso Gesbit.

Una de las cuestiones a las que le ha dado y aun le daré más vueltas en Gesbit es la "autocarga" de clases, es decir, la implementación que se hace de la función "autoload" de PHP. Si eres lector de esta bitácora desde sus orígenes sabes que es así, y, efectivamente, sigo dándole vueltas al asunto y haciendo los cambios que me parecen más oportunos y elegantes, lo que, por supuesto, no quiere decir que sean así, sólo que a mí me lo parecen. ¡Pero funciona! ;)

Como sabes, las principales clases PHP utilizadas en Gesbit se "autocargan" cuando son necesarias, puesto que Gesbit tiene "controlado" qué directorios contienen las clases utilizadas, y así puede recorrer dichos directorios y requerir los archivos precisos. Esto es así desde un principio. Hace poco que los plugins también podían beneficiarse de esta "autocarga" de clases, y, hace menos aún, también los temas de Gesbit pueden hacerlo del mismo modo.

La implementación respecto de los plugins no era muy curiosa, para qué nos vamos a engañar. Añadí una función en el mismo "script" "autoload.php", de modo que se "juntaban" los directorios para classes de Gesbit, con los directorios correspondientes a los plugins instalados, siempre que existiesen. Ya aquí se echa de ver qué fallaba: se añadían todos los directorios, de todos los plugins, tanto activos como inactivos.

Claro está que eso no significaba nada en cuanto a consumo de recursos se refiere, de ahí que se quedara el asunto tal cual: al fin y al cabo funcionaba como se esperaba. Sin embargo, ayer mismo, cuando me propuse que los temas también pudieran contar con clases PHP "autocargables", el cómo lo hize fue por otros derroteros. Es el caso que no podía hacerlo como con los plugins, porque, cuando se añadían los directorios de estos, no puede saberse el tema "actual" de la bitácora.

Así pues, dejé encargada a la clase "GbThemes" de este asunto, de modo que en su constructor, y, una vez conocido el tema en uso en la bitácora, de añadir a la correspondiente variable global el directorio "pscripts" del tema en cuestión, siempre que existiese, porque ya sabes que es opcional. Ahora bien, ¿por qué no hacer lo propio para los plugins? Efectivamente, dejando a la clase "GbPlugins" esta tarea, para empezar, sólo se añadirán los directorios existentes de los plugins activos.

Y así lo he hecho. Aunque, ya puestos, he añadido una nueva clase a Gesbit, la claes "GbClassDirs", que, precisamente, utilizan ahora tanto la clase "GbThemes" como la clase "GbPlugins" para trabajar con la variable global correspondiente. Esto para abstraer un poco esta variable global, inicializada no de la forma en que suelen las otras variables globales de Gesbit, sino en el propio "script" "autoload.php", la primera vez que se ejecuta la función "__autoload()".

Total, que, como ves, no dejo de darle vueltas al asunto de la "autocarga" de clases PHP en Gesbit. Eso sí, creo que voy mejorando, aunque sea poco a poco. Ahora mismo, tanto Gesbit como los temas y plugins que lo compongan pueden utilizar esta característica para no tener que requerir los archivos de las clases por su cuenta y riesgo, sino que estos se requieran justo en el momento de necesitar una clase cualquiera.

Sigo dándole vueltas al asunto de la clase "GbTheme", de que he venido hablado en las últimas entradas, y, claro, cuantas más vueltas le doy más mejoras se me ocurren. Lo último es que los temas deberán situar la clase "GbTheme" (en caso de usarla) dentro de un subdirectorio "pscripts" en el directorio raíz del propio tema. Como digo, todo esto es opcional, tanto el subdirectorio como la clase "GbTheme" pueden no existir, y no pasará nada. Pero (aquí viene lo bueno) en caso de existir, el directorio "pscripts" será añadido a la variable global "gbClassDirs", lo que significa que las clases que se ubiquen en dicho directorio serán "autocargadas" por Gesbit justo en el momento de necesitarlas.

Quiere decirse que en el directorio "pscripts", los temas podrán situar no sólo la clase "GbTheme", que, tiene un tratamiento especial por parte de Gesbit (ejecuta sus métodos "ActionCallback()" y "PrinterCallback()", por ejemplo, si estos existen), decía, que, cualquier clase que siga la convención de nombres de Gesbit, que se sitúe en el directorio "pscripts", será "autocargada" por Gesbit, lo que significa en pocas palabras que el desarrollador del tema no tendrá que preocuparse de requerir las clases que necesite, sino que podrá usarlas sin preocuparse de nada más. Esto ya se hacía con los plugins, pero, no así con lo temas, que estaban un tanto "marginados".

Es lo que más me gusta de los cambios que últimamente estoy llevando a cabo en Gesbit: que los temas se acercan a lo que "pueden" los plugins para Gesbit. Evidentemente no son la misma cosa, pero, creo que puede resultar curiosa la clase "GbTheme", y de hecho se utiliza ya en los temas incluidos en Gesbit, y creo que también puede resultar útil la "autocarga" de clases que usen los temas mismos, para lo que les sea menester. Otras cosas pueden ocurrirse también en el futuro, basadas, quiero decir, en todo lo que se está haciendo ahora. Aunque sólo sirviera para lo que ahora ya está disponible me daría por satisfecho, pero, me temo que voy a seguir dándole más vueltas. ;-)

Efectivamente, incluso antes de acabar de escribir esta otra entrada ya estaba rondándome por la cabeza. Y es que, ya que contamos con una clase para los temas de Gesbit... ¿por qué no hacer algo similar a lo que se hace con los plugins y sus "ActionCallback()", "PrinterCallback()", etc.? Y dicho y hecho. Ahora mismo los temas para Gesbit que implementan una clase "GbTheme" (que recuerdo es opcional en todo caso) podrán aprovecharse de ella no ya para reutilizar código en el propio tema, pero, para estar al tanto de "Actions" y "Printers" exclusivos para los temas de Gesbit.

Ahora además se clarifica un poco más la entrada enlazada, puesto que, un tema puede usar exactamente el mismo "Printer" que un plugin de cara a añadir archivos CSS y Javascript en dicho tema, como sabes, pasando por "la cola de archivos" de Gesbit, con los beneficios que eso conlleva. Además de un "Printer" para este menester, el primero hasta el momento, los temas cuentan ya con dos acciones: una que Gesbit ejecutará justo antes de añadir cualquiera de los "scripts" que componen un tema, y otra que se ejecutará justo después de añadir cada uno de los "scripts".

Me hace especial ilusión este cambio, porque, hacía tiempo que quería ver en este sentido equiparados a los temas y plugins. Como digo, por el momento no se utiliza sino un "Printer" en los temas incluidos en Gesbit, así como en el tema Kubrick, pero, la imaginación al poder... el caso es que ahora los temas pueden hacer este tipo de cosas, hasta ahora relegadas sólo a los plugins para Gesbit. Estoy contento, ya ves, de que todo se haya desarrollado bien, aunque me he hecho ciertos líos al principio, y bueno, que conste que todavía no está dicho todo... pero, ahora me voy a cenar, que ya es hora, las dos de la madrugada, ¿no te parece? :)

Algunos cambios llevados a cabo en los temas para Gesbit, al hilo de los últimos cambios en los plugins, por cierto. (Julián, antes de nada, que sepas que he actualizado el tema Kubrick en consecuencia, y ahora explico los cambios). Se trata de prescindir del archivo "functions.php", que, como sabes, se incluía justo antes de requerir el archivo "header.php" de los temas, y que, podía usarse para implementar funciones útiles para un tema determinado, así como para añadir archivos CSS y Javascript en el tema, aprovechando la "cola" conque para esto se cuenta Gesbit.

El caso es que buscando hacer lo mismo que con los plugins, es decir, conseguir una traducción de su descripción, para la hora de mostrarlos en el panel de administración, no lo he conseguido, pero, digamos que no me ha disgustado cómo se han desarrollado las cosas. Efectivamente, los temas ya no cuentan con un archivo "functions.php", que, como el mismo nombre indica, además podía causar algún que otro problema, si no se tenía cuidado, por ejemplo, al nombrar los identificadores de las funciones implementadas en el mismo.

Pero, bueno, parece que estoy poniendo el carro delante de los bueyes, como suele decirse. Es el caso que ahora los plugins pueden utilizar una clase de PHP, concretamente, pueden implementar una clase de nombre "GbTheme", en un archivo "gbtheme.class.php" situado en el directorio del tema. Este archivo, en realidad, viene a sustituir al archivo "functions.php", sólo que el mismo implementará, como se ha dicho, una clase de PHP, y no funciones "sueltas".

La clase "GbTheme", como el archivo "functions.php", es opcional, pero, de implementarse, desde los temas podrán usarse los métodos públicos conque cuente, siendo la clase "GbTheme" además una clase estática, a cuyos métodos puede accederse de la forma habitual: "GbTheme::NombreMetodo()". Como decía, la clase "GbTheme" es opcional, pero, todavía puede implementar un método un tanto especial.

Efectivamente, se trata del método "InitializeCallback()", que, si la clase "GbTheme" implementa, Gesbit ejecutará justo después de requerir el archivo de la clase. ¿Recuerdas que una de las funciones, valga la redundancia, del archivo "functions.php" era la de añadir el archivo CSS del tema en la cola de archivos CSS de Gesbit? Si lo recuerdas, en "funtions.php" se implementaba una función, que, luego era llamada desde el propio archivo "functions.php", pues este era requerido justo antes de que Gesbit requisiera a su vez el archivo "header.php" del tema.

Pues bien, había que aprovechar ese momento, precisamente, para que "todo fuera bien". En realidad Gesbit ejecutará ahora el método "Initialize()" en el mismo momento en que antes requería el archivo "functions.php", de modo que, este método se convierte, en definitiva, en el mejor lugar para incluir los archivos CSS y Javascript que necesite el tema, si es que necesita alguno, por supuesto.

Dirás, ¿Pero no puede el tema mismo, desde el archivo "header.php", que imprime la cabecera del documento HTML, incluir los archivos CSS y Javascript que necesite? Y la respuesta, por supuesto, es afirmativa. Pero, haciéndolo como se viene diciendo, tal como hace el tema "GbSimple", por ejemplo, he aquí el código fuente:

  public static function InitializeCallback(){
    // Just obtain the theme directory
    $themeDir = Gb::ThemeDirUrl(array('return' => true));
    // And add the theme CSS file into the Gesbit queue
    Gb::IncludeCSSInTheme(new GbCssFile("{$themeDir}styles/main.css"));
  }

Lo que en realidad estamos haciendo es usar las herramientas que nos proporciona Gesbit para añadir archivos CSS y Javascript a nuestros temas, y, haciéndolo así, Gesbit podrá, por ejemplo, evitar el duplicado de código y potenciales problemas. Por ejemplo, supón que haces uso en tu tema de la biblioteca jQuery para Javascript, y supón que algún plugin activo en la bitácora también hace uso de esta biblioteca.

Si el plugin y tu tema incluyen la biblioteca jQuery por su cuenta... se estará incluyendo dos veces. Pero tanto el plugin como el tema cuentan con la posibilidad de utilizar la "cola" de archivos CSS y Javascript que usa el propio Gesbit, de modo que se evitarán este tipo de situaciones. En definitiva, creo que no me ha quedado una entrada demasiado clara, puesto que todo esto me parece más sencillo de lo que acaso haya podido parecer. Tú dirás. :)

Ya tenía yo ganas de meter mano a este asunto que paso a explicar ahora. Seguramente te fijaste que en el panel de administración de Gesbit la descripción de los plugins no se encontraba traducida al idioma usado en la bitácora. Esto era porque se tomaba, directamente, desde el archivo de "información" de cada plugin, y no existía la posibilidad de "pedirle" una descripción "traducida", porque, sólo se trabajaba con los datos de los plugins.

Quiere decirse que el archivo de información que cada plugin de Gesbit tiene, es debidamente utilizado para mostrarla en el panel de administración, donde hay plugins "desactivados" y "activados". Hasta ahora era como si se pensase que todos los plugins estaban "desactivados", cuando, en realidad no es así en todo caso. Ahora se hace de tal modo que los plugins pueden proporcionar una descripción (y más aún) traducida.

Efectivamente, los plugins pueden ahora (de hecho todos los plugins para Gesbit que yo mismo desarrollo así lo hacen ya) implementar un método de nombre "GetPluginDescription()", que será ejecutado por Gesbit cuando sea menester la descripción del plugin, y, siempre que el plugin esté "activado", claro está. En otro caso, la descripción se sigue tomando del archivo de información del plugin.

El método en cuestión es opcional, puesto que la clase "GbPlugin" (de la que descienden todos los plugins para Gesbit) lo implementa, retornando la descripción contenida en el archivo de información del plugin en todo caso. No obstante, como digo, todos basta implementar dicho método para que un plugin muestra su descripción en el lenguaje en uso en la bitácora, lo que agradecerá el usuario.

Y más cambios en relación con el archivo de información de los plugins para Gesbit. Hasta ahora se incluía (más aún, debía incluirse) una opción que indicase si el plugin necesitaba ser "globalizado" o no, esto es, después de activarse, si era o no preciso referenciar en una variable global de PHP el objecto del plugin. Esto se pensaba para los plugins que requerían usar alguno de sus métodos desde el tema en uso en Gesbit.

La idea era ahorrar los supuestos recursos que en teoría consumiría globalizar los plugins, pero, tras algunas pruebas, no se nota apenas diferencia. Por tanto, la "complejidad" que se añadía a la clase "GbPlugins", y la misma obligatoriedad de indicar si era preciso o no globalizar un plugin, se había quedado un poco sin sentido.

Pues bien, los plugins no tienen ya necesidad de indicar si han de ser o no globalizados, sencillamente, Gesbit globalizará todos los plugins activos en un momento dado, es decir, justo después de instanciar los objetos correspondientes. Y eso es todo lo que tenía hoy que decir respecto de los plugins para Gesbit, me parece.