Plantilla estándar del personalizador de temas de WordPress

Actualización: este artículo ha sido editado el 19 de febrero de 2013 para reflejar los cambios realizados en Theme Customizer Boilerplate.

Esperamos que hayas leído y disfrutado las dos primeras publicaciones de la serie Theme Customizer: Introducción al personalizador de temas de WordPress e interacción con el personalizador de temas. Ahora es el momento de pasar al plato principal y comenzar a ensamblar el modelo estándar del Personalizador de temas que podrá usar en sus temas. Esta publicación contiene algunos bloques largos de código, así que preste atención a los comentarios en línea.

Nota: Si prefiere usar el texto estándar de inmediato, puede descargarlo de Github y cambiar los campos en la matriz $ options enganchándose al gancho de filtro ‘thsp_cbp_options_array’.

Lo que estamos creando

Estructura de directorios de plantilla del personalizador de temas

Estructura de directorios de plantilla del personalizador de temas

  • customizer.php – Este es el archivo de plantilla principal del Personalizador de temas, el que agrega secciones, configuraciones y controles usando datos de la matriz de opciones
  • controles personalizados.php – Clases de controles personalizados y un gancho de acción que le permite agregar sus propios controles personalizados
  • helpers.php – Funciones de ayuda, utilizadas para recuperar opciones de tema, opciones predeterminadas, etc.
  • options.php – Opciones de muestra y un gancho de filtro que le permite editar la matriz de opciones y usar sus propios campos
  • customizer-controls.css – CSS básico para control personalizado de radio reemplazado por imagen

La idea es poder copiar estos archivos a un subdirectorio en su directorio de temas, incluir el archivo customizer.php de su functions.php y cambiar lo que quiera, incluyendo y especialmente la matriz de opciones, usando los ganchos de Theme Customizer Boilerplate (explicado en la Parte 4). Actualizar: Anteriormente, solo editarías options.php, pero el uso de ganchos hace que las cosas sean mucho más limpias.

Ahora usemos un ejemplo real: agregaremos un control de texto a una nueva sección del Personalizador de temas. La matriz se coloca en una función auxiliar y se le aplica un filtro cuando se devuelve. De esta manera, puede agregar más opciones desde un tema o complemento secundario. Aquí está:

/**
 * Helper function that holds array of theme options.
 *
 * @return	array	$options	Array of theme options
 * @uses	thsp_get_theme_customizer_fields()	defined in customizer/helpers.php
 */
function thsp_get_theme_customizer_fields() {

	/*
	 * Using helper function to get default required capability
	 */
	$required_capability = thsp_settings_page_capability();
	
	$options = array(

		
		// Section ID
		'new_customizer_section' => array(
		
			/*
			 * We're checking if this is an existing section
			 * or a new one that needs to be registered
			 */
			'existing_section' => false,
			/*
			 * Section related arguments
			 * Codex - http://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_section
			 */
			'args' => array(
				'title' => __( 'New Section Title', 'my_theme_textdomain' ),
				'description' => __( 'New section description', 'my_theme_textdomain' ),
				'priority' => 10
			),
			
			/* 
			 * 'fields' array contains all the fields that need to be
			 * added to this section
			 */
			'fields' => array(
				
				/*
				 * ==========
				 * ==========
				 * Text field
				 * ==========
				 * ==========
				 */
				// Field ID
				'new_text_field' => array(
					/*
					 * Setting related arguments
					 * Codex - http://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting
					 */
					'setting_args' => array(
						'default' => __( 'Default text value', 'my_theme_textdomain' ),
						'type' => 'option',
						'capability' => $required_capability,
						'transport' => 'refresh',
						'sanitize_callback' => 'thsp_sanitize_cb',
					),					
					/*
					 * Control related arguments
					 * Codex - http://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_control
					 */
					'control_args' => array(
						'label' => __( 'New text control label', 'my_theme_textdomain' ),
						'type' => 'text', // Text field control
						'priority' => 1
					)
				)				

			)
			
		),

	);
	
	/* 
	 * 'thsp_customizer_options' filter hook will allow you to 
	 * add/remove some of these options from a child theme
	 */
	return apply_filters( 'thsp_customizer_options', $options );
	
}

Actualizar: La matriz sigue siendo la misma, pero ahora también puede pasar la matriz de opciones a un gancho de filtro; consulte la Parte 4 para obtener más detalles.

Parece complicado a primera vista, lo sé, pero déjame explicarte.

los $ opciones La matriz consta de secciones (solo una en este caso, new_customizer_section), cada sección tiene sus argumentos, campos y un valor booleano (existing_section) para indicar si es una nueva sección, o simplemente estamos agregando algunos campos a una existente. uno. La matriz de argumentos es idéntica a la que pasaría al método $ wp_customize-> add_section. La matriz de campos es un poco más compleja.

Actualizar: La matriz de opciones en los argumentos de control es ahora una matriz multidimensional.

Cada campo consta de una configuración de personalizador y un control de personalizador. Es por eso que tenemos las matrices setting_args y control_args. Son casi exactamente iguales a las matrices de argumentos que pasaría a los métodos $ wp_customize-> add_setting y $ wp_customize-> add_control. La única diferencia es la matriz de ‘opciones’ en los argumentos de control, $ wp_customize-> add_control requiere que sea una matriz de pares clave => valor simple y estamos usando una matriz multidimensional en su lugar.

De esta manera, es posible pasar más datos a cada una de las opciones, por lo que si, por ejemplo, está cargando fuentes de Google en su tema, podrá tener cadenas que le permitan cargar la fuente correcta dentro de la matriz de opciones. . Puede ver un ejemplo de este tema que usa Customizer Boilerplate.

Entonces, si ya conoce esos tres métodos, le resultará muy familiar.

Agregar un control de casilla de verificación es casi lo mismo, solo necesita cambiar ‘tipo’ a ‘casilla de verificación’ en la matriz ‘control_args’:

/*
 * ==============
 * Checkbox field
 * ==============
 */
'new_checkbox_field' => array(
	'setting_args' => array(
		'default' => true,
		'type' => 'option',
		'capability' => $required_capability,
		'transport' => 'refresh',
		'sanitize_callback' => 'thsp_sanitize_cb',
	),					
	'control_args' => array(
		'label' => __( 'New radio control label', 'my_theme_textdomain' ),
		'type' => 'checkbox', // Checkbox field control					
		'priority' => 2
	)
),				

La radio y los controles de selección son casi iguales, solo necesita especificar las opciones dadas:

/*
 * ===========
 * ===========
 * Radio field
 * ===========
 * ===========
 */
'new_radio_field' => array(
	'setting_args' => array(
		'default' => 'option-2',
		'type' => 'option',
		'capability' => $thsp_cbp_capability,
		'transport' => 'refresh',
	),					
	'control_args' => array(
		'label' => __( 'New radio control label', 'my_theme_textdomain' ),
		'type' => 'radio', // Radio control
		'choices' => array(
			'option-1' => array(
				'label' => __( 'Option 1', 'my_theme_textdomain' )
			),
			'option-2' => array(
				'label' => __( 'Option 2', 'my_theme_textdomain' )
			),
			'option-3' => array(
				'label' => __( 'Option 3', 'my_theme_textdomain' )
			)
		),					
		'priority' => 3
	)
),

/*
 * ============
 * ============
 * Select field
 * ============
 * ============
 */
'new_select_field' => array(
	'setting_args' => array(
		'default' => 'option-3',
		'type' => 'option',
		'capability' => $thsp_cbp_capability,
		'transport' => 'refresh',
	),					
	'control_args' => array(
		'label' => __( 'New select field label', 'my_theme_textdomain' ),
		'type' => 'select', // Select control
		'choices' => array(
			'option-1' => array(
				'label' => __( 'Option 1', 'my_theme_textdomain' )
			),
			'option-2' => array(
				'label' => __( 'Option 2', 'my_theme_textdomain' )
			),
			'option-3' => array(
				'label' => __( 'Option 3', 'my_theme_textdomain' )
			)
		),					
		'priority' => 4
	)
)

Y finalmente, dos tipos de control complejos que están integrados en WordPress: carga de archivos y carga de imágenes:

/*
 * ===========
 * ===========
 * File Upload
 * ===========
 * ===========
 */
'new_file_upload_field' => array(
	'setting_args' => array(
		'default' => '',
		'type' => 'option',
		'capability' => $thsp_cbp_capability,
		'transport' => 'refresh',
	),					
	'control_args' => array(
		'label' => __( 'File upload', 'my_theme_textdomain' ),
		'type' => 'upload', // File upload field control
		'priority' => 5
	)
),

/*
 * ============
 * ============
 * Image Upload
 * ============
 * ============
 */
'new_image_upload_field' => array(
	'setting_args' => array(
		'default' => '',
		'type' => 'option',
		'capability' => $thsp_cbp_capability,
		'transport' => 'refresh',
	),					
	'control_args' => array(
		'label' => __( 'Image upload', 'my_theme_textdomain' ),
		'type' => 'image', // Image upload field control
		'priority' => 6
	)
)

Tenga en cuenta que usé ‘tipo’ => ‘opción’ al establecer argumentos para todos estos campos. Esto permitirá que todos los valores se almacenen como un valor en su base de datos. La alternativa es ‘type’ => ‘theme_mod’ pero por ahora sigamos con ‘opción’.

Uso de la matriz de opciones para agregar secciones, configuraciones y controles del personalizador

Si no está seguro de cómo interactuar con el Personalizador de temas de WordPress, vaya y verifique, porque eso es lo que haremos ahora. La única diferencia es que en lugar de agregar secciones, configuraciones y controles uno a la vez, automatizaremos el proceso usando la matriz serializada que creamos. Saltemos a eso:

function thsp_cbp_customize_register( $wp_customize ) {

	/**
	 * Custom controls
	 */	
	require( dirname(__FILE__) . '/custom-controls.php' );


	/*
	 * Get all the fields using a helper function
	 */
	$thsp_sections = thsp_cbp_get_fields();


	/*
	 * Get name of DB entry under which options will be stored
	 */
	$thsp_cbp_option = thsp_cbp_option();


	/**
	 * Loop through the array and add Customizer sections
	 */
	foreach( $thsp_sections as $thsp_section_key => $thsp_section_value ) {
		
		/**
		 * Adds Customizer section, if needed
		 */
		if( ! $thsp_section_value['existing_section'] ) {
			
			$thsp_section_args = $thsp_section_value['args'];
			
			// Add section
			$wp_customize->add_section(
				$thsp_section_key,
				$thsp_section_args
			);
			
		} // end if
		
		/*
		 * Loop through 'fields' array in each section
		 * and add settings and controls
		 */
		$thsp_section_fields = $thsp_section_value['fields'];
		foreach( $thsp_section_fields as $thsp_field_key => $thsp_field_value ) {

			/*
			 * Check if 'option' or 'theme_mod' is used to store option
			 *
			 * If nothing is set, $wp_customize->add_setting method will default to 'theme_mod'
			 * If 'option' is used as setting type its value will be stored in an entry in
			 * {prefix}_options table. Option name is defined by thsp_cbp_option() function
			 */
			if ( isset( $thsp_field_value['setting_args']['type'] ) && 'option' == $thsp_field_value['setting_args']['type'] ) {
				$setting_control_id = $thsp_cbp_option . '[' . $thsp_field_key . ']';
			} else {
				$setting_control_id = $thsp_field_key;
			}
			
			/*
			 * Add default callback function, if none is defined
			 */
			if ( ! isset( $thsp_field_value['setting_args']['sanitize_cb'] ) ) {
				$thsp_field_value['setting_args']['sanitize_cb'] = 'thsp_cbp_sanitize_cb';
			}

			/**
			 * Adds Customizer settings
			 */
			$wp_customize->add_setting(
				$setting_control_id,
				$thsp_field_value['setting_args']
			);

			/**
			 * Adds Customizer control
			 *
			 * 'section' value must be added to 'control_args' array
			 * so control can get added to current section
			 */
			$thsp_field_value['control_args']['section'] = $thsp_section_key;
			
			/*
			 * $wp_customize->add_control method requires 'choices' to be a simple key => value pair
			 */
			if ( isset( $thsp_field_value['control_args']['choices'] ) ) {
				$thsp_cbp_choices = array();
				foreach( $thsp_field_value['control_args']['choices'] as $thsp_cbp_choice_key => $thsp_cbp_choice_value ) {
					$thsp_cbp_choices[$thsp_cbp_choice_key] = $thsp_cbp_choice_value['label'];
				}
				$thsp_field_value['control_args']['choices'] = $thsp_cbp_choices;		
			}
			
			
			// Check control type
			if ( 'color' == $thsp_field_value['control_args']['type'] ) {
				$wp_customize->add_control(
					new WP_Customize_Color_Control(
						$wp_customize,
						$setting_control_id,
						$thsp_field_value['control_args']
					)
				);
			} elseif ( 'image' == $thsp_field_value['control_args']['type'] ) { 
				$wp_customize->add_control(
					new WP_Customize_Image_Control(
						$wp_customize,
						$setting_control_id,
						$thsp_field_value['control_args']
					)
				);
			} elseif ( 'upload' == $thsp_field_value['control_args']['type'] ) { 
				$wp_customize->add_control(
					new WP_Customize_Upload_Control(
						$wp_customize,
						$setting_control_id,
						$thsp_field_value['control_args']
					)
				);
			} else {
				$wp_customize->add_control(
					$setting_control_id,
					$thsp_field_value['control_args']
				);
			}
				
		} // end foreach
		
	} // end foreach	

}
add_action( 'customize_register', 'thsp_cbp_customize_register' );

Pasando por todas las secciones, agregando las que aún no existen, luego revisando todos los campos en cada sección, agregando una configuración y un control para cada una. Eso es todo lo que está pasando aquí.

¿Recuerda que usamos ‘tipo’ => ‘opción’ para toda la configuración? Es por eso que ahora tenemos “My_theme_options[$thsp_field_key]” tanto para la configuración como para las secciones. Esto almacenará todos los valores como una matriz serializada que puede recuperar usando get_option (‘my_theme_options’). O simplemente puede usar funciones auxiliares definidas en helpers.php para recuperar tanto los valores actuales como los valores predeterminados para todos los campos:

/**
 * Get Option Values
 * 
 * Array that holds all of the options values
 * Option's default value is used if user hasn't specified a value
 *
 * @uses	thsp_get_theme_customizer_defaults()	defined in /customizer/options.php
 * @return	array									Current values for all options
 * @since	Theme_Customizer_Boilerplate 1.0
 */
function thsp_cbp_get_options_values() {

	// Get the option defaults
	$option_defaults = thsp_cbp_get_options_defaults();
	
	// Parse the stored options with the defaults
	$thsp_cbp_options = wp_parse_args( get_option( thsp_cbp_option(), array() ), $option_defaults );
	
	// Return the parsed array
	return $thsp_cbp_options;
	
}


/**
 * Get Option Defaults
 * 
 * Returns an array that holds default values for all options
 * 
 * @uses	thsp_get_theme_customizer_fields()	defined in /customizer/options.php
 * @return	array	$thsp_option_defaults		Default values for all options
 * @since	Theme_Customizer_Boilerplate 1.0
 */
function thsp_cbp_get_options_defaults() {

	// Get the array that holds all theme option fields
	$thsp_sections = thsp_cbp_get_fields();
	
	// Initialize the array to hold the default values for all theme options
	$thsp_option_defaults = array();
	
	// Loop through the option parameters array
	foreach ( $thsp_sections as $thsp_section ) {
	
		$thsp_section_fields = $thsp_section['fields'];
		
		foreach ( $thsp_section_fields as $thsp_field_key => $thsp_field_value ) {

			// Add an associative array key to the defaults array for each option in the parameters array
			if( isset( $thsp_field_value['setting_args']['default'] ) ) {
				$thsp_option_defaults[$thsp_field_key] = $thsp_field_value['setting_args']['default'];
			} else {
				$thsp_option_defaults[$thsp_field_key] = false;
			}
			
		}
		
	}
	
	// Return the defaults array
	return $thsp_option_defaults;
	
}

Solo hay una cosa más que debo mencionar: la función de devolución de llamada de desinfección que especificamos en la matriz ‘setting_args’. La función se define en extend.php y simplemente ejecuta datos a través de la función wp_kses_post:

/**
 * Theme Customizer sanitization callback function
 */
function thsp_sanitize_cb( $input ) {
	
	return wp_kses_post( $input );
	
}

¿A dónde vamos desde aquí?

Por ahora, puede usar este Boilerplate del personalizador de temas en sus temas, todo lo que necesita hacer es descargarlo de Github, copiarlo en el directorio de su tema e incluir el archivo principal de functions.php, que es 100% funcional y lo suficientemente bueno para la mayoría temas.

Dado que su tema no es “como la mayoría de los temas”, la próxima semana veremos cómo extender el texto estándar mediante el uso de su filtro y sus ganchos de acción.

Me encantaría saber cómo cree que se podría mejorar o ampliar este texto estándar, así que dispare en los comentarios.

Publicaciones relacionadas

Botón volver arriba