La API de configuración de WordPress, Parte 8: Validación, desinfección y entrada I

Spanish (Español) translation by Luis Chiabrera (you can also view the original English article)

Hemos llegado al artículo final de la serie. En la última publicación, echamos un vistazo a la introducción de la validación, el saneamiento y un par de elementos de entrada básicos que podemos aprovechar al crear páginas de opciones.

En este artículo, vamos a echar un vistazo al conjunto final de tres opciones y cómo conectarlas a la parte frontal del tema.

Antes de comenzar: al igual que con los últimos, este artículo asume que usted ha estado siguiendo el resto de la serie, tiene instalada una copia de trabajo del código de muestra y ahora está relativamente familiarizado con la API de configuración y las opciones de tema . Si no está seguro acerca de alguno de los anteriores, le recomiendo leer el resto de los artículos antes de sumergirse en este post.

Los tipos de elementos, continuación

casilla de verificación

Anteriormente en esta serie, agregamos casillas de verificación. Podríamos volver atrás y revisarlos, pero mantengámonos coherentes con lo que hemos hecho hasta este momento e introduzcamos nuevas opciones. Una vez que hayamos terminado, puede revisar el código que agregamos al comienzo de la serie para revisar.

Primero, introduzcamos el elemento de la casilla de verificación a la función sandbox_theme_initialize_input_examples:

add_settings_field(
  'Checkbox Element',
	'Checkbox Element',
	'sandbox_checkbox_element_callback',
	'sandbox_theme_input_examples',
	'input_examples_section'
);

A continuación, debemos seguir adelante y definir la devolución de llamada que hemos especificado anteriormente. Agregue la siguiente función a su proyecto:

function sandbox_checkbox_element_callback() {

	$options = get_option( 'sandbox_theme_input_examples' );
	
	$html = '<input type="checkbox" id="checkbox_example" name="sandbox_theme_input_examples[checkbox_example]" />';
	$html .= '<label for="checkbox_example">This is an example of a checkbox</label>';
	
	echo $html;

} // end sandbox_checkbox_element_callback

Volveremos a revisar esta función momentáneamente, pero primero note que he agregado un elemento de etiqueta junto a la casilla de verificación. Las casillas de verificación a menudo tienen un elemento asociado con ellas que también permite hacer clic para activar la casilla de verificación. Esto facilita que los usuarios alternen una opción sin tener que hacer clic con precisión en la casilla de verificación.

Para asociar una etiqueta con una casilla de verificación, debe asignar a la etiqueta for atributo el valor del atributo ID de la casilla de verificación a la que está vinculada. Bastante fácil, ¿verdad?

Ahora, actualice su página de opciones y debería ver el nuevo elemento visible en su página de opciones. Pero, por ahora, en realidad no guarda ni recupera un valor. Primero, introduzcamos un atributo value en la casilla de verificación. Esto es algo arbitrario, pero es una práctica común dar a un elemento marcado un valor de '1'. Vamos a hacer eso ahora:

1	$html = '<input type="checkbox" id="checkbox_example" name="sandbox_theme_input_examples[checkbox_example]" value="1" />';

A continuación, pensemos exactamente qué debe suceder cuando guardamos un valor. Idealmente:

El usuario comprueba el elemento y guarda el valor.
La página se actualiza y la casilla de verificación está marcada.
El usuario verifica el elemento para desactivarlo y guarda el valor.
La página se actualiza y la casilla de verificación no está marcada

Relativamente claro, ¿verdad? En lugar de leer la opción, configurar un condicional y verificar la presencia o ausencia de un valor, podemos aprovechar la función verificada de WordPress.

La función acepta tres argumentos, de los cuales solo se requiere el primero:

El primer valor es uno de los valores para comparar.
El segundo valor para comparar si el primer valor no es verdadero
Si o no se hace eco de check="checked" en el navegador

Así que vamos a actualizar nuestro código para usar esta función:

1	$html = '<input type="checkbox" id="checkbox_example" name="sandbox_theme_input_examples[checkbox_example]" value="1"' . checked( 1, $options['checkbox_example'], false ) . '/>';

Actualice la página y marque la opción, guardar y repetir.

Si algo de esto parece un poco confuso, revise el artículo anterior en el que cubrimos los significados de cada atributo en un elemento de opción.

Finalmente, actualicemos la parte frontal del tema para marcar esta opción y generar una cadena de texto en función de si la opción ha sido marcada. Recuerde que cuando creamos el elemento, le dimos el valor de '1'. Esto significa que cuando la casilla de verificación esté marcada y serializada, mantendrá un valor de uno. En pocas palabras, necesitamos escribir un condicional que verifique el valor de la opción y luego presente el texto de manera apropiada. En index.php, agregue este bloque de código:

<?php if( $input_examples['checkbox_example'] == '1' ) { ?>
	<p>The checkbox has been checked.</p>
<?php } else { ?>
	<p>The checkbox has not been checked.</p>
<?php } // end if ?>

Ahora, vuelva a la página de configuración, active la casilla de verificación y actualice la página.

Como se mencionó al principio de esta sección, mire hacia atrás en las "Opciones de visualización" que presentamos anteriormente en esta serie y vea si está mucho más claro ahora que hemos examinado cómo introducir y administrar los elementos de las casillas de verificación.

Botones de radio

Los botones de radio son elementos que son útiles en grupos; después de todo, nunca usarás un solo botón de radio. Lo que pasa con los elementos de radio es que proporcionan una manera de permitir a los usuarios elegir una de un conjunto de opciones mutuamente excluyentes.

Por una razón u otra, los botones de opción son a menudo un desafío para los desarrolladores de WordPress. Con suerte, lo haremos lo más fácil posible para incluirlo en nuestros proyectos. Al igual que con el resto de los ejemplos de esta serie, detalle lo que vamos a hacer:

Queremos introducir dos opciones entre las que el usuario debe seleccionar. Les daremos etiquetas muy generales.
La primera opción será un elemento de radio con la etiqueta 'Opción Uno' y tendrá el valor de '1'.
La segunda opción será un elemento de radio con la etiqueta 'Opción Dos' y tendrá el valor de '2'.

Parece lo suficientemente claro: continuemos y agreguemos el elemento de campo a nuestra página de opciones:

add_settings_field(
	'Radio Button Elements',
	'Radio Button Elements',
	'sandbox_radio_element_callback',
	'sandbox_theme_input_examples',
	'input_examples_section'
);

Y vamos a implementar la devolución de llamada del elemento de radio. Primero, especificaremos el código, luego lo revisaremos:

function sandbox_radio_element_callback() {

	$options = get_option( 'sandbox_theme_input_examples' );
	
	$html = '<input type="radio" id="radio_example_one" name="sandbox_theme_input_examples[radio_example]" value="1"' . checked( 1, $options['radio_example'], false ) . '/>';
	$html .= '<label for="radio_example_one">Option One</label>';
	
	$html .= '<input type="radio" id="radio_example_two" name="sandbox_theme_input_examples[radio_example]" value="2"' . checked( 2, $options['radio_example'], false ) . '/>';
	$html .= '<label for="radio_example_two">Option Two</label>';
	
	echo $html;

} // end sandbox_radio_element_callback

Lo primero que se debe tener en cuenta cuando se trabaja con botones de opción es que no siguen los ejemplos típicos de cómo configurar los atributos de ID y name. Observe que el atributo ID es único y no tiene relación con el resto de los atributos en el elemento. También tenga en cuenta que la etiqueta asociada de cada elemento utiliza la ID para su atributo for. Esto une la etiqueta al botón de radio para que los usuarios puedan hacer clic en la etiqueta para seleccionar el elemento de radio.

A continuación, observe que los atributos de name son los mismos para cada elemento de radio, pero los values son diferentes. Esto es lo que hace que los botones de radio sean mutuamente exclusivos: cada elemento de radio debe tener el mismo name pero los valores deben ser únicos.

Finalmente, podemos configurar un condicional en la página de inicio verificando el valor del elemento. En las funciones de su functions.php, agregue el siguiente bloque de código:

<?php if( $input_examples['radio_example'] == 1 ) { ?>
	<p>The first option was selected.</p>
<?php } elseif( $input_examples['radio_example'] == 2 ) { ?>
	<p>The second option was selected.</p>
<?php } // end if  ?>

Cargue la página de inicio de su tema, alterne las opciones y actualice. Debería ver las dos oraciones cambiando según el valor de los elementos de opción.

cuadro de selección

El último elemento que vamos a revisar es el elemento de selección. Este elemento ofrece a los usuarios un menú desplegable de opciones entre las que elegir. Planifiquemos exactamente lo que necesitamos introducir para este elemento:

Definir un elemento de selección. En nuestro ejemplo, lo trataremos como tres opciones por tiempo.
Daremos las opciones para 'Nunca', 'A veces' y 'Siempre'.
Rellenaremos una opción predeterminada que se establecerá cuando se cargue la página.

En este punto de la serie, esto debería ser bastante rutinario. Empecemos, primero, introduciremos el campo de configuración:

add_settings_field(
	'Select Element',
	'Select Element',
	'sandbox_select_element_callback',
	'sandbox_theme_input_examples',
	'input_examples_section'
);

A continuación, vamos a definir la función de devolución de llamada. Revise el código y luego lo discutiremos después del ejemplo:

function sandbox_select_element_callback() {

	$options = get_option( 'sandbox_theme_input_examples' );
	
	$html = '<select id="time_options" name="sandbox_theme_input_examples[time_options]">';
		$html .= '<option value="default">Select a time option...</option>';
		$html .= '<option value="never"' . selected( $options['time_options'], 'never', false) . '>Never</option>';
		$html .= '<option value="sometimes"' . selected( $options['time_options'], 'sometimes', false) . '>Sometimes</option>';
		$html .= '<option value="always"' . selected( $options['time_options'], 'always', false) . '>Always</option>';
	$html .= '</select>';
	
	echo $html;

} // end sandbox_radio_element_callback

Primero, actualice la página de opciones para asegurarse de que aparezca el elemento seleccionado. Suponiendo que sí, revisemos el código anterior.

Al definir el elemento de selección, le asignamos un atributo de ID y un atributo de name, tal como lo hacemos con el resto de los elementos que hemos demostrado. A continuación, cada opción tiene un valor único y un texto que corresponde al valor. Aunque no tiene que hacer esto, normalmente lo encuentro útil cuando trabajo en mis proyectos. Finalmente, hemos aprovechado el ayudante selected que ofrece WordPress. Esto se parece mucho a la función checked que hemos usado en el ejemplo anterior, excepto que está orientada a seleccionar opciones.

El último paso será actualizar el extremo delantero del tema para que compruebe el valor del elemento seleccionado una vez que se haya guardado. Agregue el siguiente bloque de código a su index.php:

<?php if( $input_examples['time_options'] == 'never' ) { ?>
	<p>Never display this. Somewhat ironic to even show this.</p>
<?php } elseif( $input_examples['time_options'] == 'sometimes' ) { ?>
	<p>Sometimes display this.</p>
<?php } elseif( $input_examples['time_options'] == 'always' ) { ?>
	<p>Always display this.</p>
<?php } // end if/else ?>

Vuelva a visitar la página de inicio de su tema, cambie las opciones y luego actualice la página: debería notar la actualización de texto basada en la opción que seleccionó.

Conclusion

Con eso, finalmente llegamos al final de esta serie. La API de configuración es una característica poderosa de WordPress y nos brinda la capacidad de implementar páginas de opciones seguras y bien diseñadas, pero requiere que lo usemos correctamente. Desafortunadamente, esta es probablemente una de las características más ignoradas de la plataforma por muchos desarrolladores.

En última instancia, mi objetivo era guiar a los desarrolladores a través de la API desde el principio para entender por qué es importante, a la configuración, desde las páginas del menú, a la navegación por pestañas, y cómo trabajar con cada uno de los tipos de elementos.

Finalmente, recuerde que puede encontrar el código de ejemplo en GitHub. A medida que continúe trabajando con la API de configuración o encuentre una característica que no esté clara, contribuya. Me encantaría que esta serie y el código de ejemplo sigan proporcionando una fuente de educación para la comunidad de WordPress.