La Parte 3 de la serie Theme Customizer le presentó el Boilerplate del Theme Customizer, que le permite simplificar el código que maneja las opciones de su tema. Todo lo que necesita hacer es pasar una serie de campos de opciones y la plantilla se encargará de registrar las secciones, la configuración y los controles del Personalizador de temas detrás de escena.
Hasta ahora, el texto estándar le permitía usar campos de texto, casillas de verificación, botones de opción y campos de selección en el Personalizador de temas, este artículo le muestra cómo puede extenderlo.
Nota: Antes de continuar, descargue la última versión de WordPress Theme Customizer Boilerplate desde su repositorio de Github. Le hice algunas mejoras desde el último tutorial y es importante que su código esté actualizado. Eche un vistazo a la publicación anterior para obtener más notas sobre los cambios, pero en pocas palabras, una vez que copie el texto estándar en la carpeta de su tema, no necesita editar sus archivos en absoluto: toda la edición se realiza usando filtros y ganchos de acción.
Conectando con Theme Customizer Boilerplate
Hay varios ganchos de acción y filtro en el Boilerplate del Personalizador de temas de WordPress. Puede conectarse a cualquiera de ellos desde el archivo functions.php de su tema usando add_action y Añadir filtro funciones:
- ‘thsp_cbp_directory_uri’ – El gancho de filtro definido en helpers.php le permite cambiar la ubicación de Customizer Boilerplate en su carpeta de temas. De forma predeterminada, la ruta estándar se ve así: get_template_directory_uri (). ‘/ customizer-boilerplate’ – pero si prefiere moverlo a una ubicación personalizada, este es el gancho que puede ayudarlo.
- ‘thsp_cbp_menu_link_text’ – Enlace de filtro definido en helpers.php, le permite cambiar el enlace de texto del menú. Boilerplate agrega un enlace en Apariencia en el panel de WordPress, lo que permite a los usuarios un fácil acceso al Personalizador de temas. De forma predeterminada, ese enlace dirá «Personalizador de temas» y puede cambiar el texto usando el gancho de filtro ‘thsp_cbp_menu_link_text’.
- ‘thsp_cbp_capability’ – Filtro de gancho definido en helpers.php. Le permite cambiar la capacidad requerida predeterminada utilizada en el método $ wp_customize-> add_setting.
- ‘thsp_cbp_option’ – Filtro de gancho definido en helpers.php. Si está usando ‘opción’ en sus argumentos de configuración, use este gancho para cambiar el nombre de la entrada en la que se almacenarán los valores de configuración de su tema en la tabla wp_options. El valor predeterminado es ‘thsp_cbp_theme_options’, asegúrese de conectar este y cámbielo a algo que tenga el nombre de su tema.
- ‘thsp_cbp_options_array’ – Filtro de gancho definido en options.php, DEBE engancharlo y reemplazar la matriz de opciones predeterminada (que contiene opciones de muestra) con opciones que se utilizan en su tema. Lo repetiré, lo en negrita y lo subrayaré: YDEBE conectarse y reemplazar la matriz de opciones predeterminada con las opciones que se utilizan en su tema.
- ‘thsp_cbp_custom_controls’ – Gancho de acción definido en custom-controls.php, al conectarlo puedes crear tus propios controles personalizados, sigue leyendo para ver un ejemplo de cómo hacerlo.
- ‘tshp_cbp_remove_sections’, ‘tshp_cbp_remove_controls’ y ‘tshp_cbp_remove_settings’ – Filtrar ganchos definidos en customizer.php. Puede pasarles matrices de ID de sección incorporadas (o ID de controles o ID de configuración) para eliminar algunas de las secciones, controles o configuraciones incorporados.
Nota: Si bien estamos en la extensibilidad y creando sus propios ganchos para que otros desarrolladores puedan usarlos para extender su código, es imposible exagerar lo importante que es esto. Después de todo, así es como funciona WordPress (núcleo). Y no pude agradecer a Pippin y sus articulos suficiente para hacer que esta idea se me ocurra.
Controles personalizados
La versión actualizada de Theme Customizer (que acaba de ver, ¿verdad?) Tiene algunos controles más que puede usar: campo de área de texto, campo de número HTML5 y campo de imágenes, que es básicamente una versión elegante de botones de opción.
Estos controles personalizados están definidos en custom-controls.php, no los revisaré todos aquí, pero echemos un vistazo a uno (campo numérico HTML5) para ver cómo funciona todo:
/**
* Creates Customizer control for input[type=number] field
*
* @since Theme_Customizer_Boilerplate 1.0
*/
class CBP_Customizer_Number_Control extends WP_Customize_Control {
public $type = 'number';
public function render_content() {
echo '<label>
<span class="customize-control-title">'. esc_html( $this->label ) .'</span>
<input type="number" '. $this->link() .' value="'. intval( $this->value() ) .'" />
</label>';
}
}
Como puede ver, todo lo que necesita hacer es definir un nuevo control $ type y su función render_content que genera el control en la pantalla Theme Customizer.
Uso de los controles personalizados integrados de Customizer Boilerplate
Es lo mismo que los campos simples cubiertos en el tutorial anterior, lo único que debe tener en cuenta son los ‘tipos’ que debe usar para cada uno:
- Campo numérico – ‘número’
- Campo de área de texto – ‘textarea’
- Imágenes que actúan como botones de opción: ‘images_radio’, aquí hay un ejemplo de este control en una próxima versión gratuita Tema Cazuela:
Conociendo los nombres de estos nuevos tipos de control, agregar uno es fácil. A continuación, le mostramos cómo puede agregar un control de campo numérico a la matriz que contiene todas sus opciones:
/*
* ============
* ============
* Number Field
* ============
* ============
*/
'new_number_field' => array(
'setting_args' => array(
'default' => '',
'type' => 'option',
'capability' => $thsp_cbp_capability,
'transport' => 'refresh',
),
'control_args' => array(
'label' => __( 'Number', 'my_theme_textdomain' ),
'type' => 'number', // Textarea control
'priority' => 8
)
)
Nota: Si no está seguro de dónde agregar esto, consulte la sección «Uso de la matriz de opciones para agregar secciones, configuraciones y controles del personalizador» de la Parte 3 de esta serie. Además, hay una muestra para cada uno de los controles personalizados en el archivo options.php.
Agregar sus propios controles personalizados
Volvamos al gancho de acción ‘thsp_cbp_custom_controls’ que mencioné anteriormente:
/**
* Action hook that allows you to create your own controls
*/
do_action( 'thsp_cbp_custom_controls' );
Es un simple gancho de acción de WordPress que le permite agregar sus propios controles personalizados sin modificar los archivos Boilerplate del Personalizador de temas. ¿Por qué querrías evitar editarlos? Porque si, en cambio, se está conectando con el modelo estándar, cada vez que alguien lo actualiza, puede simplemente tomar la última versión, colocarla en su tema y no perder los cambios que realizó. Piense en editar archivos centrales de WordPress frente a escribir un complemento, editar un tema frente a crear un tema secundario, etc.
Si alguna vez necesita agregar sus propios controles personalizados, así es como puede hacerlo:
function my_theme_add_customizer_boilerplate_control() {
/**
* Creates custom control to use with Theme Customizer Boilerplate
* Use a unique class prefix!
*
* @since Theme_Customizer_Boilerplate 1.0
*/
class CBP_Customizer_My_Control extends WP_Customize_Control {
public $type = 'my_type'; // Change this
public function render_content() {
// Control output goes here
}
}
}
add_action( 'thsp_cbp_custom_controls', 'my_theme_add_customizer_boilerplate_control' );
Asegúrese de prefijar su clase de control personalizada con algo único, para que su nombre no entre en conflicto con otra clase. Usé ‘CBP_’ (Customizer Boilerplate) – dado que estás usando boilerplate en un tema, el nombre de tu tema tiene mucho sentido y debería funcionar bien para ti.
Personalizador de temas: ¿Qué sigue?
Ahora que WordPress Theme Customizer Boilerplate es extensible a través de ganchos, echaremos un vistazo para agregar «opciones de tema condicionales», las que solo aparecerán si un determinado complemento está activo y lo ayudarán a mantener la pantalla Theme Customizer ordenada.
¿Qué opinas sobre Customizer Boilerplate hasta ahora? ¿Planeas usarlo en tus temas? ¿Alguna idea sobre cómo podría mejorarse? Sus comentarios son siempre bienvenidos.