WordPress Theme Customizer Boilerplate

Plantilla estándar de personalización de temas de WordPress – WPExplorer

Actualización: este artículo se modificó por última vez el 19 de febrero de 2013 para reflejar los cambios realizados en la bandeja para hornear del Personalizador de temas.

Espero que haya leído y disfrutado los dos primeros artículos 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 curso principal y comenzar a armar la plantilla de personalización de temas estándar que puede usar en sus temas. Este artículo contiene algunos bloques largos de código, así que preste atención a los comentarios en línea.

Notar: Si prefiere usar el texto estándar de inmediato, puede descargarlo de Github y editar los campos en la matriz $ options conectándose al enlace de filtro ‘thsp_cbp_options_array’.

Que creamos

Estructura de directorio estándar del personalizador de temas

Estructura de directorio estándar del personalizador de temas

  • customizer.php – Este es el archivo estándar para el personalizador de temas principal, el que agrega secciones, configuraciones y controles usando datos de la matriz de opciones
  • controles personalizados.php – Clases de control personalizadas 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 de radio personalizado reemplazó la imagen

La idea general es poder copiar estos archivos a un subdirectorio de tu directorio de temas, incluir el archivo customizer.php de tu functions.php y modificar lo que quieras, incluyendo y especialmente las opciones de la tabla d ‘, usando el tema ganchos Boilerplate del personalizador (explicados en la parte 4). Poner al día: Anteriormente, solo editaría options.php, pero el uso de corchetes hace que las cosas sean mucho más limpias.

Ahora usemos un ejemplo real: agregaremos un control de texto a una nueva sección de personalización del tema. 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. Es aquí:

/**
 * 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 );
	
}

Poner al día: 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.

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

los $ opciones La matriz consta de sección (es) (solo una en este caso – new_customizer_section), cada sección tiene sus argumentos, campos y un booleano (existing_section) para indicar si se trata de una nueva sección, o simplemente agregamos campos a una existente. La matriz de argumentos es la misma que pasaría $ wp_customize-> add_section método. La tabla de campos es un poco más compleja.

Poner al día: La matriz de opciones en los argumentos de control ahora es una matriz multidimensional.

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

De esta manera, es posible pasar más datos a cada una de las opciones, por lo que si, por ejemplo, carga fuentes de Google en su tema, puede tener cadenas que le permitirán cargar la fuente correcta en la matriz de opciones. . Puedes ver un ejemplo de esto tema que usa Customizer Boilerplate.

Entonces, si ya está familiarizado con estos tres métodos, todo esto es 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 los mismos, 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 controles complejos 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’ en la definición de argumentos para todos estos campos. Esto permitirá que todos los valores se almacenen como un solo 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 de personalización

Si no sabes cómo interactuar con el Personalizador de temas de WordPress, échale un vistazo, porque eso es lo que haremos ahora. La única diferencia es que en lugar de agregar secciones, parámetros y controles uno por uno, automatizaremos el proceso usando la matriz serializada que creamos. Solo vamonos:

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' );

Recorra todas las secciones, agregue las que aún no existen, luego recorra todos los campos en cada sección, agregando un parámetro y un control para cada una. Eso es todo lo que está pasando aquí.

¿Recuerda que usamos ‘tipo’ => ‘opción’ para todos los parámetros? Es por eso que ahora tenemos “Mis_temas_opciones[$thsp_field_key]” para parámetros y secciones. Esto almacenará todos los valores en una matriz serializada que puede recuperar usando get_option (‘my_options_theme’). O simplemente puede usar las funciones auxiliares definidas en helpers.php para recuperar los valores actuales y predeterminados de 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 limpieza que especificamos en la tabla ‘setting_args’. La función se define en extend.php y simplemente ejecuta los datos a través de wp_kses_post función:

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

A dónde ir desde aquí?

Ahora mismo puede usar este Boilerplate de personalización de temas en sus temas, todo lo que necesita hacer es descargarlo de Github, copiarlo a su directorio de temas e incluir el archivo de funciones principales. Php, que es 100% funcional y suficiente para la mayoría de los temas.

Dado que su tema no es “como la mayoría de los temas”, la próxima semana veremos cómo extender la clave maestra usando su filtro y sus ganchos de acción.

Me encantaría saber cómo crees que esta obra maestra podría mejorarse o ampliarse, así que no dudes en leer los comentarios.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Ir arriba