Descifrando el Personalizador de temas: Parte I de prácticas

Después leer los artículos anteriores de esta serie, supongo que entiendes los componentes del Personalizador de temas y cómo añadirlos, eliminarlos y configurarlos.

Parece que hay muchas cosas que averiguar, y sería un buen ejercicio poner todo lo que hemos aprendido en acción.

En este artículo, voy a cubrir algunas de las cosas más importantes sobre el Personalizador de temas a través de varios ejemplos. Esto debería dar lugar a una mayor comprensión de las características que si nos limitásemos simplemente a leer un artículo que no incluyese nada de código.

Antes de empezar

• Asegúrate de que ya has leído la parte anterior que cubre los detalles de los componentes en el Personalizador de temas. Por supuesto, vuelve a consultarlo si no recuerdas algo.
• El Personalizador de temas se vincula con la estructura del tema, por supuesto, por lo que la mejor manera de integrarlo en tu tema consiste en implementarlo correctamente mientras estás desarrollando tu tema; sin embargo, en un artículo limitado como este, no vamos a crear un nuevo tema para hacerlo, voy a utilizar TwentyEleven y lo modificaré para demostrar las explicaciones.

Añadir una nueva sección

Abre el archivo functions.php, y escribe el siguiente código dentro de él:

1

function wptuts_theme_customizer( $wp_customize ) {

2

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

3

		'title' => 'WPTuts+', // The title of section

4

		'description' => 'Settings of WPTuts section', // The description of section

5

	) );

6

7

	// The latter code snippets go here.

8

}

9

add_action( 'customize_register', 'wptuts_theme_customizer', 11 );

En primer lugar, la función wptuts_theme_customizer se enganchará a la acción customize_register, una importante acción que se utiliza para registrar nuevas opciones en el personalizador de temas. Ten en cuenta que esta función tiene un parámetro $wp_customize, como se mencionó antes, se trata de una variable global y una instancia de la clase WP_Customize_Manager que administra todos los demás componentes del Personalizador de temas.

Para añadir una nueva sección, $wp_customize tiene un método denominado add_section. Como se puede ver, nuestra sección "our news section" tiene el id wptuts, esto es algo importante a recordar más adelante.

Los atributos title y description indican qué mostrar al representar un componente.

Ten en cuenta que la nueva sección nunca se mostrará en la barra de menús de la página del Personalizador de temas hasta que tengas al menos un ajuste y un control.

Configurar las opciones

Dentro de la función wptuts_theme_customizer, añade el siguiente código:

1

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

2

	'default' => 'Hello world',

3

	// Let everything else default

4

) );

A continuación, para integrar esta configuración en nuestra sección, tenemos que crear un nuevo control que conecte la nueva sección y el nuevo ajuste:

1

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

2

	// wptuts_welcome_text is a id of setting that this control handles

3

	'label' => 'Welcome text',

4

	// 'type' =>, // Default is "text", define the content type of setting rendering.

5

	'section' => 'wptuts', // id of section to which the setting belongs

6

	// Let everything else default

7

) );

Con el ID wptuts_welcome_text, el nuevo control asociaría el ajuste que tiene este ID con la sección correspondiente. Y los resultados serán:

Lo primero que debes tener en cuenta es que no es necesario declarar el ID del nuevo control, es el mismo que el ID del ajuste. También podemos hacer lo siguiente:

1

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

2

	'label' => 'Welcome text',

3

	'settings' => 'wptuts_welcome_text',

4

	'section' => 'wptuts',

5

) );

Funciona igual que la primera vez que lo usamos. Esencialmente, si no pasamos el valor de la propiedad settings, el control usará su ID como identificador del ajuste que controla.

Este punto nos permite saber que cada ajuste puede ser utilizado por muchos controles diferentes. Esto también significa que cada ajuste se puede mostrar muchas veces en numerosas secciones (aunque esto parece innecesario). Por ejemplo, reemplaza nuestro control por:

1

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

2

	'label' => 'Welcome text',

3

	'settings' => 'wptuts_welcome_text',

4

	'section' => 'wptuts',

5

) );

6

7

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

8

	'label' => 'Welcome text',

9

	'settings' => 'wptuts_welcome_text',

10

	'section' => 'title_tagline',

11

) );

Comprueba los resultados, nuestro ajuste se muestra tanto en la sección Site title & Tagline como en la sección WPTuts.

Cada ajuste puede ser utilizado por múltiples controles.

En segundo lugar, el valor predeterminado de este ajuste se recupera de la opción wptuts_welcome_text del tema actual mediante la función get_theme_mod.

Dado que esta opción de tema no existe, se usará la propiedad predeterminada (default). Así que tenemos un cuadro de texto con el valor "Hola mundo". Para comprobar si funciona o no con el Personalizador de temas, podríamos intentar generar el valor de este ajuste en algún lugar de nuestra plantilla.

Abramos el archivo header.php y antepongamos el siguiente código al final y guardemos:

1

<?php echo get_theme_mod( 'wptuts_welcome_text' ); ?>

Vuelve a la página del Personalizador de temas, actualízala e intenta cambiar algún otro valor de nuestro ajuste, "¡Hola, gracias por leer!", por ejemplo, y comprueba los cambios. Los resultados se muestran al instante en el marco de vista previa, ¡genial!

En tercer lugar, no asignamos ningún valor para el type del ajuste, a continuación, se aplicaría el valor predeterminado para theme_mod, esto explica el motivo por el que usamos la función get_theme_mod para obtener el valor de este ajuste. Puedes cambiar este valor a option y usar get_option para obtener el valor en lugar de get_theme_mod. Intenta añadir los siguientes fragmentos de código al final de la anterior función wptuts_theme_customizer:

1

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

2

		'default' => 'Hello again',

3

		'type' => 'option',

4

	) );

5

6

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

7

		'label' => 'Welcome text again',

8

		'settings' => 'wptuts_welcome_again',

9

		'section' => 'wptuts',

10

	) );

Da salida al valor de wptuts_welcome_again justo después de get_theme_mod( 'wptuts_welcome_text' ) en header.php.

1

<?php

2

echo get_theme_mod( 'wptuts_welcome_text' ) . " ";

3

echo get_option( 'wptuts_welcome_again' );

4

?>

Comprueba el resultado:

Genial, vamos a probar otro ejemplo añadiendo un ajuste más:

1

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

2

		'default' => 0,

3

	) );

4

5

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

6

		'label' => 'Hide footer section',

7

		'type' => 'checkbox',

8

		'section' => 'wptuts',

9

	) );

Sólo añadimos una nueva opción que muestra una casilla de verificación que nos permite elegir si ocultar o no la sección de pie de página. A continuación, abre el archivo footer.php, y busca el siguiente código:

1

<div id="site-generator">

y reemplázalo con:

1

<div id="site-generator" <?php echo ( get_theme_mod( 'wptuts_footer' ) ) ? "style='display:none;'" : "" ?> >

El código anterior comprobará si get_theme_mod('wptuts_footer') devuelve false (o un valor 0), a continuación, muestra el par atributo-valor style='display:none;' que oculta el elemento div que lo contiene, si no, no muestra nada. Finalmente, tenemos una simple opción de casilla de verificación, trata de hacer clic en ella, el contenido de la sección de pie de página se ocultará al instante.

Entonces, ¿qué sucede si ya existía el ID del ajuste que pretendemos usar? Bueno, el ajuste simplemente usará la opción existente sin añadir una nueva entrada de opción. En la siguiente sección, mostraremos una simple demostración de esto.

Usar una opción existente

Ajustes > Comentarios en el panel de administración tiene una opción cuyo título es Avatar por defecto. Llevaré esta opción a la página del Personalizador de temas. Esta opción tiene el ID avatar_default, por tanto:

1

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

2

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

3

		'type' => 'option',

4

	) );

5

6

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

7

		'label' => 'Avatar Default',

8

		'section' => 'wptuts',

9

		'type' => 'radio',

10

		'choices' => array(

11

			'mystery' => 'Mystery Man',

12

			'blank' => 'Blank',

13

			'gravatar_default' => 'Gravatar Logo',

14

			'identicon' => 'Identicon (Generated)',

15

			'wavatar' => 'Wavatar (Generated)',

16

			'monsterid' => 'MonsterID (Generated)',

17

			'retro' => 'Retro (Generated)',

18

		),

19

	) );

El control anterior define el tipo de contenido del ajuste como radio, y el radio debe tener una lista de opciones. Pasé los valores y títulos de cada opción a través del atributo choices donde la clave es el valor de la opción (se usaría como atributo de valor en la etiqueta HTML), y el valor de la clave es el título que se muestra después del botón de opción.

El resultado:

Intenta cambiar el valor:

o

También se cambia el type en el control que deseas seleccionar. Y tendríamos:

Prueba tú mismo otro tipo de control: dropdown-pages. Verás una selección que contiene todas las páginas y el valor del ajuste será el ID de la página seleccionada al recuperarla.

Crear un nuevo componente de forma segura

Añadir un nuevo componente cuyo ID es un duplicado de otro ya existente puede causar errores graves e incluso afectar a las actividades y los datos de otros componentes.

Así que antes de crear algo nuevo, hay que comprobar si existe o no un componente con el mismo ID.

1

	// Check section

2

	if ( ! in_array( 'section_id_to_check', array_keys( $wp_customize->sections() ) ) ) {

3

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

4

			//

5

		) );

6

	}

7

	// Check setting

8

	if ( ! in_array( 'setting_id_to_check', array_keys( $wp_customize->settings() ) ) ) {

9

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

10

			//

11

		) );

12

	}

13

	// Check control

14

	if ( ! in_array( 'control_id_to_check', array_keys( $wp_customize->controls() ) ) ) {

15

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

16

			//

17

		) );

18

	}

El método $wp_customize->sections() devolverá una matriz que contiene pares ID-objecto de todas las secciones del Personalizador de temas. Mediante el uso de la función array_keys, obtengo una nueva matriz que contiene todos los IDs de la antigua matriz.

A continuación, comprueba si el identificador del componente que queremos añadir está ya en esa nueva matriz o no, y después decide añadir un nuevo componente o no hacer nada.

Crear un grupo de ajustes

Al igual que con la API de Ajustes, al crear una opción de ajustes, esta se escribirá en la tabla option de la base de datos de como una entrada. Si tenemos 10 opciones de ajustes, tendríamos 10 filas de entrada en la tabla option, parece un derroche excesivo. ¿Por qué no ponemos todas nuestras opciones de ajuste en una sola entrada? Hace que la base de datos esté ordenada y sea fácil de administrar. A continuación se muestra un ejemplo:

1

	$wp_customize->add_setting( 'wptuts[number]', array(

2

		'default' => 1,

3

		'type' => 'option',

4

	) );

5

6

	$wp_customize->add_control( 'wptuts[number]', array(

7

		'label' => 'WPTuts+ number',

8

		'section' => 'wptuts',

9

	) );

10

11

	$wp_customize->add_setting( 'wptuts[email]', array(

12

		'default' => 'mail@mail.com',

13

		'type' => 'option',

14

	) );

15

16

	$wp_customize->add_control( 'wptuts[email]', array(

17

		'label' => 'WPTuts+ email',

18

		'section' => 'wptuts',

19

	) );

20

21

	$wp_customize->add_setting( 'wptuts[ads]', array(

22

		'default' => 0,

23

		'type' => 'option',

24

	) );

25

26

	$wp_customize->add_control( 'wptuts[ads]', array(

27

		'label' => 'Display advertise banners',

28

		'type' => 'checkbox',

29

		'section' => 'wptuts',

30

	) );

Como puedes ver, ahora, tenemos un grupo de opciones wptuts que contienen nuestras otras opciones de ajustes. Para obtener el valor de un ajuste en particular, podríamos hacerlo de la siguiente manera:

1

$wptuts = get_option( 'wptuts' ); // array

2

$number = $wptuts['number'];

3

$email = $wptuts['email'];

4

$ads = $wptuts['ads'];

A continuación, utiliza esas variables en cualquier lugar que desees. Parece simple, recomiendo encarecidamente hacerlo de esta manera.

Conclusión

Hemos cubierto bastante, pero no es suficiente. En la siguiente parte, veremos otros factores importantes como la desinfección, los atributos de transporte y los componentes extendidos.

Una vez más, estoy deseando saber de ti, ¡apreciaré cualquier comentario!