Una guía para principiantes de Titan Framework: Cómo funciona Titan

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

Este es el tercer artículo de la serie y hasta ahora, he discutido la importancia y las características de Titan Framework junto con la configuración básica. En el primer artículo, hablé de la configuración en tres pasos de Titan Framework, que es así:

Configura tu proyecto.
Crear opciones.
Obtener valores.

Le expliqué el primer paso del artículo anterior, en el que aprendimos que Titan Framework es un marco plug and play, es decir, se trata de un complemento, aunque también puede integrarse incrustándolo en su proyecto de desarrollo web. Entonces, continuemos desde donde lo dejé y continuemos con los siguientes dos pasos.

Aquí, explicaré cómo y en qué capacidad trabaja Titan Framework en su proyecto de desarrollo web. Luego pasaré al concepto de crear instancias y opciones desde el cual obtendré los valores guardados en el front-end. ¡Vamos a empezar!

1. Configura tu proyecto

En primer lugar, averigüemos qué necesitará para implementar el tutorial de hoy. Vamos a crear un tema simple de WordPress con el que usaremos Titan Framework para explorar el conjunto de opciones que puede crear. Necesitarás:

Configuración de WordPress local, por ejemplo Yo uso DesktopServer (créeme, es increíble!).
Un tema básico de WordPress: voy a utilizar Neat para ese propósito. He creado una nueva rama llamada Neat: TitanFramework para este tutorial.

Mi configuración

Como voy a usar el tema de Neat WordPress, es importante que explique primero su estructura. Abra la carpeta de temas en su editor de texto donde, dentro del directorio assets, he creado una nueva carpeta llamada admin. Su propósito es manejar todo el código relevante para las opciones de administración. Dentro de él hay otro directorio, titanframework y un archivo PHP, admin-init.php.

Archivo `admin-init.php`

Este archivo PHP manejará toda la actividad relacionada con la administración. Si se desplaza por su código, descubrirá que he usado la función get_template_directory() para incluir cuatro archivos del directorio titanframework. El siguiente código es bastante autoexplicativo, pero explicaré el propósito de cada uno de estos archivos en breve.

Aquí está el código para admin-init.php:

<?php

/**
 * Admin related initializations
 */

/**
 * Titan Framework Required to be installed
 *
 * It adds Titan Framework as a plugin
 *
 * https://www.titanframework.net/get-started/
 */

if ( file_exists( get_template_directory() .'/assets/admin/titanframework/titan-framework-checker.php') ) {
    
    require_once( get_template_directory() .'/assets/admin/titanframework/titan-framework-checker.php' );
    
}

/**
 * Create an options via Titan Framework
 *
 * http://www.titanframework.net/get-started/
 */

// Admin panel options.
if ( file_exists( get_template_directory() .'/assets/admin/titanframework/adminpanel-options-init.php') ) {
    
    require_once( get_template_directory() .'/assets/admin/titanframework/adminpanel-options-init.php' );
    
}

// Metabox options.
if ( file_exists( get_template_directory() .'/assets/admin/titanframework/metabox-options-init.php') ) {
    
    require_once( get_template_directory() .'/assets/admin/titanframework/metabox-options-init.php' );
    
}

// Customizer options.
if ( file_exists( get_template_directory() .'/assets/admin/titanframework/customizer-options-init.php') ) {
    
    require_once( get_template_directory() .'/assets/admin/titanframework/customizer-options-init.php' );
    
}

Directorio llamado `titanframework`

He discutido anteriormente que Titan Framework le ayuda a crear Paneles y pestañas de administración, Metaboxes y secciones y paneles del Personalizador de temas. Así que he creado archivos separados para cada uno de ellos. Obviamente se pueden crear con líneas de código separadas. Discutiré cada uno de estos en mis próximos artículos, pero por ahora, todo lo que necesita entender es para qué sirven estos archivos.

titan-framework-checker.php: es responsable de incluir Titan Framework en tu tema.
adminpanel-options-init.php: contiene el código para crear el panel de administración y las pestañas con un conjunto de opciones.
metabox-options-init.php: contiene el código para crear metaboxes para tipos de publicaciones con un conjunto de opciones en ellas.
customizer-options-init.php: contiene el código para crear paneles y secciones de personalizador de temas con un conjunto de opciones.

Incluyendo el archivo `admin-init.php`

Hasta ahora debes preguntarte por qué he creado tantos archivos nuevos. ¿Por qué no acabo de agregar todo el código en el archivo functions.php? Bueno, no considero que sea un buen enfoque de diseño de arquitectura. Para construir un producto mantenible, necesita definir un buen patrón de diseño.

¿Cuál es el punto de desordenar su archivo functions.php con tantas líneas de código? Yo mismo lo he experimentado: hacia el final de cualquier proyecto de desarrollo, el código se vuelve tan masivo que se vuelve difícil manejarlo todo en un solo archivo, especialmente cuando se trata de depurar y corregir cualquier error. Siempre es mejor crear archivos separados, así que piensa en estos archivos como módulos.

Incluyamos admin-init.php en nuestro archivo functions.php.

<?php

/**
 * Include admin-init.php
 *
 * File responsible for all admin relevant activity E.g. Settings & Metaboxes etc.
 */

if ( file_exists( get_template_directory() .'/assets/admin/admin-init.php') ) {
    
    require_once( get_template_directory() .'/assets/admin/admin-init.php' );
    
}

Aquí he agregado el archivo admin-init.php a través de las mismas funciones get_template_directory() y require_once().

En este punto, hemos echado un vistazo a la configuración básica de un tema que voy a utilizar para explicar cómo funciona Titan Framework. Hemos completado la configuración e incrustado Titan Framework en nuestro tema de WordPress. Vamos a crear un panel de administración con opciones y obtener los valores para el front-end.

Trabajando con Titan Framework

Para trabajar con Titan Framework, debe seguir un flujo de trabajo determinado que es:

Crea una instancia de Titan Framework por archivo.
Crear paneles / pestañas de administración, cuadros de metaboxes o personalizadores de tema / paneles / secciones.
Crea opciones en ellos.
Obtener los valores.

Permítanme primero escribir la pieza de código que voy a utilizar para este propósito. Este es el código para el archivo adminpanels-options-init.php que está presente dentro del directorio assets/admin/titanframwork/.

<?php

/**
 * Creating admin panel options via Titan Framework.
 *
 * Getting started: http://www.titanframework.net/get-started/
 * Admin Panel: http://www.titanframework.net/admin-panels/
 * Admin Tabs: http://www.titanframework.net/admin-tabs/
 * Options: http://www.titanframework.net/docs/
 * Getting Option Values: http://www.titanframework.net/getting-option-values/
 */

/**
 * `tf_create_options` is the hook used to create options.
 */

add_action( 'tf_create_options', 'aa_options_creating_function' );

function aa_options_creating_function() {

    // Initialize Titan with your theme name.
    $titan = TitanFramework::getInstance( 'neat' );

    /**
     * First Admin panel.
     */

    /**
     * Create admin panel options page called `$aa_panel`.
     *
     * This is a first admin panel and is called by its name i.e. `$aa_panel`.
     */
    $aa_panel = $titan->createAdminPanel( array(
        'name' => 'Neat Options' // Name the options menu
    ) );

    /**
     * Create the options.
     *
     * Now we will create options for our panel that we just created called `$aa_panel`.
     */
    $aa_panel->createOption( array(
        'id' => 'aa_txt', // The ID which will be used to get the value of this option.
        'type' => 'text', // Type of option we are creating.
        'name' => 'My Text Option', // Name of the option which will be displayed in the admin panel.
        'desc' => 'This is our option' // Description of the option which will be displayed in the admin panel.
    ) );

    /**
     * Save button for options.
     *
     * When creating admin panel options, use this code to add an option "Save" button
     * since there is no other way for user to save the options.Your users can now save
     * (and reset) the options we just created.
     */
    $aa_panel->createOption( array(
        'type' => 'save'
    ) );

}

Al principio, he agregado algunos enlaces de ayuda de la documentación de Titan Framework. Ahora voy a explicar este código línea por línea.

Línea 17

Aquí tenemos un gancho llamado tf_create_options, que se usa para crear opciones a través de Titan Framework usando la función aa_options_creating_function().

Lineas 19

Hemos creado una función llamada aa_options_creating_function(), que será responsable de crear estas opciones.

Línea 22

En la línea 22, he creado una instancia para Titan Framework. Crear una instancia es una parte integral de este marco, y debe crearse en cada archivo donde sea necesario para interactuar con Titan Framework. Para hacer que su instancia sea única, puede agregar el nombre de su producto en ella. Por ejemplo, he añadido 'neat' como parámetro.

Consigue una instancia de Titan Framework

Crear una instancia de Titan Framework es bastante simple. Obtenemos una instancia única para evitar cualquier confusión, en caso de que otro complemento use Titan Framework para crear opciones. El autor afirma que:

La función getInstance crea / obtiene una instancia única de Titan Framework específica para "mytheme". Este es el namespace que usaremos para asegurarnos de que nuestra configuración no entre en conflicto con otros complementos que usan Titan Framework. Asegúrese de cambiarlo a su tema o nombre de complemento.

Aquí hay un ejemplo de código para obtener una instancia con Titan.

1	$titan = TitanFramework::getInstance( 'my-theme' );

En el caso de mi tema Neat usaré el parámetro neat en lugar de my-theme para hacer que mi código sea único, es decir,

1	$titan = TitanFramework::getInstance( 'neat' );

Creación de un panel de administración; Líneas 33-35

Estas líneas crearán un panel de administración que he denominado "$aa_panel". Titan Framework ayuda a crear secciones como el panel de administración, las pestañas de administración, las metaboxes y los paneles de personalización de temas dentro de su proyecto. Pero por ahora solo crearé un panel de administración como ejemplo para explicar las cosas.

Estas líneas de código están llamando a nuestra función createAdminPanel() en Titan Framework, que forma una matriz. Esta función agregará una nueva sección en su panel de WordPress llamada Neat Options.

La imagen de arriba es una captura de pantalla del panel de WordPress donde puede encontrar una nueva sección que se agrega en el Panel de administración.

Solo para resumir lo que he hecho hasta ahora: he configurado mi proyecto de desarrollo web y luego le agregué una instancia, después de lo cual creé un Panel de administración.

Justo en este punto, si hago clic en el botón Neat Options, entonces esta sección está vacía. Entonces, ahora crearé opciones dentro de este Panel de administración recién creado.

Creando Opciones en Titan Framework

Se prefieren los temas personalizables de WordPress porque la mayoría de los usuarios finales desean configurar los temas sin escribir una sola línea de código. Esto es posible mediante la adición de opciones flexibles durante el desarrollo del tema.

Podemos agregar dichas opciones en un panel de administración separado, o en forma de metaboxes o también paneles de opciones dentro del personalizador de temas. Las opciones sirven para almacenar los valores que luego se recuperan en el front-end.

Líneas 42–47

Ahora eche un vistazo a estas líneas de código. Se utilizarán para crear opciones dentro de un panel o pestaña de administración. La línea 42 define la función createOption() para el $ aa_panel. Esta función es una vez más una matriz que contiene ciertos parámetros como id, type, name, description, etc. De acuerdo con estas líneas, he creado una opción que es un campo de texto y se llama My Text Option.

Esta es la captura de pantalla que muestra la opción creada dentro del panel Neat Options.

Líneas 56–58

Las dos últimas líneas del código crean otra opción dentro de este panel. Pero su propósito es guardar la configuración. Por ejemplo, en el campo My Text Option, el usuario la llena con John Doe. Esto significa que el usuario desea cambiar la configuración predeterminada, que solo es posible si el usuario guarda la configuración personalizada.

Entonces, de nuevo utilicé la función createOption() y asigné el valor del parámetro "type = save".

Esta es la captura de pantalla final del desarrollo que he hecho hasta ahora.

En este punto, ya tiene configurado Titan Framework, ha creado algunas opciones para obtener resultados dinámicos, y ahora todo lo que queda por hacer es obtener los valores de las opciones que configuró en primer lugar. Del lema de tres pasos, he discutido los dos primeros en los dos artículos anteriores. Entonces, veamos ahora la última y más importante parte de cómo funciona Titan Framework.

Obtención de valores

La creación de opciones se realiza en el back-end, y ahora necesitamos recuperar los valores contra esas opciones, establecidos por un usuario final, para usarlos en el front-end. Podemos recuperar los valores establecidos contra las opciones a través de una función simple, es decir, getOption().

La siguiente es la estructura básica del código para recuperar los valores guardados:

<?php

function myFunction() {

    $titan = TitanFramework::getInstance( 'my-theme' );
    $myTextOption = $titan->getOption( 'my_text_option' );

    // Do stuff here.

}

Entonces, creé una función llamada myFunction donde registré por primera vez una instancia de Titan. Registrar una instancia es un paso importante, ya que obtiene el objeto creado por Titan Framework para su configuración registrada en una variable, es decir, $titan. Puede ver que nuestra instancia es específica de nuestro tema, es decir, my-theme, que se supone que es nuestro nombre de tema o algo único.

Recuperando valores en el front-end

Vamos a usar los valores establecidos contra las opciones en el front-end. He creado una plantilla de página personalizada en blanco. Si se refiere a la carpeta de tema Neat, encontrará un archivo llamado aa_titanframework.php en la raíz. Puedes hacer lo mismo con tu tema también.

Cree un nuevo archivo en su editor de texto y copie y pegue las siguientes líneas de código.

<?php

/* Template Name: Titan Framework */

get_header();

/**
 * First Admin panel.
 */

// We will initialize $titan only once for every file where we use it.
$titan = TitanFramework::getInstance( 'neat' );

$aa_txt_val = $titan->getOption( 'aa_txt' );

?>

<div class="aa_wrap">
    <h1><?php the_title( ); ?></h1>
    <div class="aa_content">

        <?php

        /**
         * First Admin panel options.
         */

        // Print the value saved in `aa_txt` option.
        echo $aa_txt_val;

        // Let's use this value in HTML.

        ?>

        <h3><?php echo $aa_txt_val; ?></h3>
    </div>
</div>

<?php

//get_sidebar();
get_footer();

?>

Antes de explicar el código mencionado anteriormente, refiérase al código de mi artículo anterior donde creé un Panel de administración y sus opciones, porque también estoy usando los mismos nombres, ID, etc., aquí.

Las primeras cuatro líneas del código son para que WordPress registre esta plantilla de página personalizada, que es bastante estándar, no hay ciencia espacial allí.

Obtención de valores de opción

Obtendré los valores de las opciones que creé en el archivo adminpanel-options-init.php (consulte su código en mi artículo anterior) aquí. Se necesitan dos pasos para lograr esto:

Obtenga una instancia única de Titan Framework y guárdela en una variable.
Obtenga el valor a través de ID utilizando la función getOption().

Línea 12

Siguiendo el primer paso, inicialicé una instancia única contra la variable $titan, solo una vez por cada archivo en el que lo uso. Mi instancia es única, ya que la he nombrado neat, es decir, el nombre del paquete para mi tema, puede nombrarla como única. Es necesario para que si un complemento está utilizando Titan y su tema también lo esté usando, entonces debería haber una manera de diferenciar entre las opciones establecidas por ese complemento y su tema.

1	$titan = TitanFramework::getInstance( 'neat' );

Línea 14

El segundo paso es hacer uso de la ID y obtener el valor guardado para esa opción. El código para esta línea es:

1	$aa_txt_val = $titan->getOption( 'aa_txt' );

Recuperé el valor para aa_txt que se guarda contra la variable $aa_txt_val. El parámetro aa_txt se refiere al ID de la opción que creé dentro de mi primer Panel de administración (consulte mi artículo anterior).

Por lo tanto, hasta ahora he configurado la estructura básica para obtener los valores guardados. Ahora vamos a usar los valores guardados en el front-end.

Líneas 22–35

Estas líneas de código se utilizan para mostrar los valores guardados en el front-end. Echa un vistazo a la línea 29 donde usé el comando echo para obtener la salida. Lo mismo se hace en la línea 35, pero esta vez estoy mostrando la salida para $aa_txt_val en un formato H3 (encabezado 3). Entonces, sea cual sea el valor que el usuario final establezca para esta opción, se mostrará en el front-end.

Resultados

Para mostrar los resultados del código que he explicado anteriormente, siga estos pasos:

Ve a tu panel de WordPress
Crear una nueva página a través de páginas > Agregar nueva.
Nombra la página Titan Framework (opcional, lo sabrías)

La captura de pantalla de arriba muestra la página que he creado. Al mismo tiempo, también puede encontrar el nuevo Menú del panel de administración, es decir, Neat Options, donde creamos las opciones.

Luego, elija la Plantilla de página, es decir, Titan Framework, para esta página antes de publicarla.

El archivo aa_titanframework.php agrega una nueva plantilla de página llamada "Titan Framework" que aparece en la lista desplegable. Elige esa plantilla.

Publicar la página.
A continuación, vaya al menú Neat Options y agregue algún valor a la opción llamada My Text Option.

La imagen muestra que he llenado este campo con la AA-Text-Option y luego hice clic en Guardar cambios.

Vuelva a la página de Titan Framework y vea la página.

La imagen de arriba muestra el resultado final. Esta es la página Titan Framework. El valor de la opción guardada (es decir, AA-Text-Option) para aa_txt se muestra en dos formas diferentes. El primero está en formato de párrafo, mientras que el segundo está en formato h3.

Conclusión

A estas alturas ya debe tener un poco de comprensión de Titan Framework y su funcionamiento. Esta es la configuración básica que debe seguirse cada vez que desarrolle algo con Titan Framework.

Ahora que ya sabe cómo configurarlo, cree algunas opciones y obtenga los valores guardados; Pruébelo y hágamelo saber en caso de cualquier consulta a través de comentarios o comuníquese conmigo en Twitter.

A continuación en esta serie, exploraremos el conjunto de opciones que podemos crear con Titan Framework y cómo usarlas.