Descifrando el personalizador de temas: Componentes

En la primera parte de esta serie, presenté la funcionalidad del Personalizador de temas y mostré las razones por las que resulta tan útil. Ya sabemos que el Personalizador de temas tiene 4 componentes principales: Ajustes, Secciones, Controles y el componente que controla a todos estos, el Administrador, cuya importante variable es $wp_customize. También conocemos la forma de invocar esta variable para usarla más adelante. En este tutorial, mi plan es profundizar en estos componentes, averiguar sus propiedades y explicar cómo registrarlos o eliminarlos y la forma de configurarlos como desees.

Administrador

Como se explicó en la primera parte, este es un importante componente cuya tarea principal consiste en gestionar los demás. Inicializa todas las cosas necesarias, las configura e integra los componentes predeterminados en el Personalizador de temas. Como se trata de una instancia de la clase WP_Class_Customize_Manager (ubicada en wp-includes/wp-class-customize-manager.php ), tiene algunos útiles métodos:

Obtener todas las secciones, ajustes o listas de controles:

1

2

$wp_customize->sections(); // return an array with the id is the id of section/setting/control,

3

$wp_customize->settings(); // and the value is Section/Setting/Control object.

4

$wp_customize->controls(); //

Para obtener un componente, podríamos usar lo siguiente:

1

2

$wp_customize->get_section( 'id' );

3

$wp_customize->get_setting( 'id' ); // Remember to pass the id as argument.

4

$wp_customize->get_control( 'id' );

Y para eliminar componentes:

1

2

$wp_customize->remove_section( 'id' );

3

$wp_customize->remove_setting( 'id' ); // Remember to pass the id as argument.

4

$wp_customize->remove_control( 'id' );

El Administrador también tiene algunos otros importantes métodos, entre los que se incluyen los siguientes:

1

2

$wp_customize->add_section( 'id', array() ); // The first argument is the id of component

3

$wp_customize->add_setting( 'id', array() ); // The second one is an array of property-value pairs

4

$wp_customize->add_control( 'id', array() ); // passing to component object.

Nos centraremos en estos métodos en las siguientes secciones.

Sección

Como su nombre indica, este componente clasifica todos los ajustes en grupos. Cada sección puede contener uno o varios ajustes. Este es el componente más sencillo. Algunos métodos que funcionan con secciones son add_section, get_section y remove_section:

1

2

$wp_customize->add_section( 'id', array(

3

	'title' => '',

4

	'description' => '',

5

	'priority' => ''

6

) );

• id: un nombre de identidad único, que se usará luego con los Ajustes y los Controles.
• title: el título de la sección que se muestra en el menú.
• description: una breve descripción sobre esta sección.
• priority: la secuencia o el orden en el que se muestran las secciones en el menú, cuanto menor sea el número, más alta aparecerá.

Advierte que cada sección es una instancia de la clase WP_Class_Customize_Section (ubicada en wp-includes/class-wp-customize-section.php), por lo que si utilizas get_section, ese método devolverá un objeto que es una instancia de esa clase.

Para conseguir que un ajuste esté disponible, simplemente usa get_section, este método devuelve un objeto de ajuste.

1

2

$wp_customize->get_section( 'id' );

Y el último método remove_section, sencillamente elimina cualquier sección que queramos eliminar:

1

2

$wp_customize->remove_section( 'id' );

Por ejemplo, si quisiera añadir una nueva sección para usarla más adelante, los que usaría sería el siguiente código:

1

2

$wp_customize->add_section( 'wp_tuts', array(

3

	'title' => 'WpTuts',

4

	'description' => 'An example for Theme Customizer',

5

) );

Ajuste

Estos son componentes que controlan las opciones, cada uno gestiona una opción específica. Están dentro de las secciones y bajo la clase WP_Customize_Setting (ubicada en wp-includes/class-wp-customize-setting.php). La tarea principal de este componente es definir la forma en que se almacena un ajuste y dónde. El código siguiente muestra la sintaxis de este método:

1

2

$wp_customize->add_setting( 'id', array(

3

	'default' => '',

4

	'theme-supports' => '',

5

	'type' => '', // Default is "theme_mod"

6

	'capability' => '', // Default is "edit_theme_options"

7

	'sanitize_callback' => '',

8

	'sanitize_js_callback => '',

9

	'transport' => '', // Default is "refresh"

10

) );

• default: el valor predeterminado del campo de entrada del ajuste.
• theme-supports: comprueba si el tema actual admite la función de tema en cuestión, si no es así, este ajuste ya no está disponible.
• type: define el tipo de ajuste, ya sea theme_mod u option, el valor predeterminado es theme_mod.
  • Los ajustes theme_mod solo están disponibles en el tema actual, son todos ajustes que mantienen el tema actual y son especiales para cada tema. Para obtener el valor de un ajuste específico, puedes usar la función get_theme_mod con un argumento del nombre de un ajuste concreto. Ten en cuenta que la función get_theme_mod cambiará el lugar desde el cual se obtienen los datos cada vez que cambiemos de tema, también significa que la función depende del tema que usemos. Digamos, por ejemplo, cuando usamos Twenty Eleven, la función get_theme_mod obtiene datos de la opción theme_mods_twentyeleven, y la opción theme_mods_twentyten si usamos el tema Twenty Ten.
  • Por otro lado, los ajustes option estarán disponibles en todas partes, como sabes, es la opción que solemos usar. Para obtener el valor, utilizamos la función get_option, que presumiblemente ya conoces.
• capability: la capacidad necesaria para que el ajuste actual sea mostrado al usuario. Leer más sobre Roles y Capacidades
• sanitize_callback: la función de devolución de llamada que desinfecta la entrada de datos. El Personalizador de temas tiene una función disponible llamada sanitize_hex_color_no_hash que se utiliza para comprobar que la entrada de datos es un color hexadecimal sin hash.
• sanitize_js_callback: la función de devolución de llamada que desinfecta los datos utilizados para Javascript.
• transport: la forma en la que se transportarán los datos, puede ser refresh o postMessage.
  • refresh: cada vez que cambia algo en las opciones de los ajustes, el Personalizador de temas fuerza la recarga del marco de vista previa, por lo que el contenido del marco será totalmente actualizado.
  • postMessage: en lugar de actualizar todo el marco de vista previa cuando algo cambie, los nuevos datos se transportarán instantáneamente al marco de vista previa mediante técnicas de JavaScript.

Así que el motivo por el cual WordPress tiene estas dos maneras de transportar datos (refresh y postMessage), son los cambios que tienen menos impacto en la estructura de la página, o para cambios simples (tal vez añadir /eliminar algo o cambiar el valor de algunas propiedades HTML/CSS). Para estos debemos usar postMessage, ya que se pueden procesar con JavaScript de forma sencilla e instantánea, sin la necesidad de volver a recargar toda la página. Por el contrario, si los nuevos cambios en la configuración afectarán a la estructura de la página, o son difíciles de aplicar con eficacia mediante Javascript, es mejor usar refresh. Hazme saber también tu opinión sobre esto dejando tus comentarios.

A continuación se muestra un sencillo ejemplo de adición de un nuevo ajuste:

1

2

$wp_customize->add_setting( 'blogname', array(

3

	'default' => get_option( 'blogname' ),

4

	'type' => 'option',

5

) );

Al igual que ocurre con las Secciones, para los Ajustes también tenemos get_setting y remove_setting:

1

2

$wp_customize->get_setting( 'id' );

3

$wp_customize->remove_setting( 'id' );

4

// Ex: Get value of setting

5

$wp_customize->get_setting( 'blogname' )->value(); // Return website's name;

Control

Este componente organizará los ajustes de las secciones correspondientes, definirá el tipo de ajustes y, a continuación, representará su contenido. Cada control es una instancia de la clase WP_Class_Customize_Control (ubicada en wp-includes/class-wp-customize-control.php ).

1

2

$wp_customize->add_control( 'id', array(

3

	'label' => '',

4

	'settings' =>  // Default is id property.

5

	'section' => '',

6

	'type' => '', // Default is "text"

7

	'choices' => '', // This is optional, depending on type's value.

8

	'priority' => '', // Default is 10.

9

) );

• id: un identificador único para el control, que también se usará como nombre de la opción del ajuste si no se define el valor de la siguiente propiedad settings.
• label: la etiqueta del ajuste.
• settings: el nombre de la opción del ajuste que se controla. Si se deja en blanco, se utilizará el valor del identificador anterior.
• section: la sección a la que pertenece el ajuste.
• type: se representará el tipo de opción del ajuste. El Personalizador de temas tiene algunos valores predeterminados que puedes utilizar:
  • text: el tipo de opción del ajuste de entrada será un tipo de entrada text. También es el valor predeterminado si no se pasa nada para la propiedad type.
  • checkbox: representación de una opción de ajuste de casilla de verificación o "checkbox".
  • radio: representación de una lista de opciones de ajustes de casilla de verificación. Es necesario pasar una matriz de pares de valor/título para cada entrada de radio como choices.
  • select: representación de una lista de opciones de selección de ajuste. Al igual que la radio, su lista de opciones debe pasarse a través del atributo choices.
  • dropdown-pages: aunque es una lista de selección, se creó para la opción que muestra el listado de páginas del sitio web.
• choices: lista de opciones de ajustes para radio y select.
• priority: se utiliza para especificar el orden en el que se muestra un ajuste. Los números más bajos corresponden a una ejecución más temprana y los ajustes con la misma prioridad se ejecutan en el orden en el que han sido añadidos.

Para obtener y eliminar un control, simplemente haz lo siguiente:

1

2

$wp_customize->get_control( 'id' );

3

$wp_customize->remove_control( 'id' );

4

// Ex: get value of setting that control manage

5

$wp_customize->get_control( 'blogdescription' )->value(); // Get website's description.

Conclusión

En esta serie, tenía la intención de mostrar cada ajuste junto con sus ejemplos en acción. Sin embargo, es difícil explicar todo a fondo debido a la estricta conexión de los componentes. Así que finalmente decidí mostrar la información necesaria para cada componente primero, y proporcionar ejemplos en acción, más adelante, en la siguiente parte. Espero que no te hayas aburrido. Una vez más, estoy deseando escuchar tus comentarios, aprecio verdaderamente todos y cada uno de ellos. ¡Gracias por leerme!