Este documento explica cómo utilizar el personalizador de WordPress para previsualizar configuraciones en un sitio. Describe los cuatro objetos principales que componen el personalizador (paneles, secciones, controles y ajustes), y cómo añadirlos y asociarlos entre sí utilizando funciones como add_panel(), add_section(), add_setting() y add_control(). También cubre temas como tipos de controles, validaciones, soporte para múltiples idiomas y cómo extender los objetos de personalización de forma personalizada.

1. SÁCALE PARTIDO
AL PERSONALIZADOR
Pablo López
@desarrollowp

2. ¿QUÉ ES?
Es un framework para previsualizar configuraciones en
nuestro sitio (v 3.4)

3. ¿PARA QUÉ SE UTILIZA?
En el personalizador encontramos por defecto opciones de
configuración como:
- Identidad del sitio (título, descripción, logo…)
- Gestión de Menús
- Gestión de Widgets
- Portada
Muchos temas y plugins utilizan el personalizador para
ofrecer al usuario opciones de configuración propias:
- Colores y estilos
- API keys
- Layouts
- Claims

4. ¿DE QUÉ CONSTA?
4 Objetos: Panels, Sections, Controls y Settings

5. PANELS
Los Panels son elementos contenedores de Sections. Un
nivel adicional de jerarquía

6. SECTIONS
Las Sections son contenedores (UI) para Controls

7. CONTROLS
Son elementos (UI) para establecer datos. Inputs de
diferentes tipos

8. SETTINGS
Es la asociación del Control con el dato que se almacena
en BBDD.

9. UN POCO DE CÓDIGO…
Necesitamos crear una función en el archivo functions.php
de nuestro tema o en nuestro plugin, y añadirla al hook
‘customize_register’
function themeslug_customize_register( $wp_customize ) {
// Do stuff with $wp_customize, the WP_Customize_Manager object.
}
add_action( 'customize_register', 'themeslug_customize_register' );
Importante: Es recomendable el uso de prefijos para
cualquier ID de los objetos que vamos a crear a
continuación para evitar conflictos

10. MÉTODOS
Para cada objeto: add_, get_ y remove_
$wp_customize->add_panel();
$wp_customize->get_panel();
$wp_customize->remove_panel();
$wp_customize->add_section();
$wp_customize->get_section();
$wp_customize->remove_section();
$wp_customize->add_setting();
$wp_customize->get_setting();
$wp_customize->remove_setting();
$wp_customize->add_control();
$wp_customize->get_control();
$wp_customize->remove_control();

11. PRIORIDAD
Podremos establecer el orden de nuestros elementos
teniendo en cuenta que por defecto:

12. THEME_MODS VS OPTIONS
¿Opciones del tema u Opciones generales?

13. AÑADIENDO UN PANEL
Usando el método add_panel
$wp_customize->add_panel( 'panel_id', array(
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed
'title' => __( 'Título Panel', 'your_textdomain' ),
'description' => __( 'Descripción Panel', 'your_textdomain' ),
) );

14. AÑADIENDO UN SECTION
Usando el método add_section
$wp_customize->add_section( 'section_id', array(
'panel' => 'panel_id', // Not typically needed.
'priority' => 160,
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
'title' => __( 'Título Section', 'your_textdomain' ),
'description' => __( 'Descripción Section', 'your_textdomain' ),
) );

15. AÑADIENDO UN SETTING
Usando el método add_setting. Estableceremos el nombre
y el tipo de dato que guardaremos en BBDD. Podremos
establecer un valor por defecto y además validar y
sanitizar el dato antes de guardarlo
$wp_customize->add_setting( 'setting_id', array(
'type' => 'theme_mod', // or 'option'
'capability' => 'edit_theme_options',
'theme_supports' => '', // Rarely needed.
'default' => '', // Ej: #000000
'transport' => 'refresh', // or postMessage
'sanitize_callback' => '', // Ej: ‘sanitize_hex_color’
'sanitize_js_callback' => '', // Basically to_json.
) );

16. AÑADIENDO UN CONTROL
Usando el método add_control. Al añadir el control lo
asociamos al Setting. También indicamos a que Section
pertenece, así como el tipo, título, descripción, etc…
$wp_customize->add_control( 'setting_id', array(
'type' => 'date',
'priority' => 10, // Within the section.
'section' => 'section_id', // Required, core or custom.
'label' => __( 'Fecha', 'your_textdomain' ),
'description' => __( 'Descripción', 'your_textdomain' ),
'input_attrs' => array(
'class' => 'my-custom-class-for-js',
'style' => 'border: 1px solid #900',
'placeholder' => __( 'dd/mm/yyyy', 'your_textdomain' ),
),
'active_callback' => 'is_front_page',
) );

17. TIPOS DE CONTROLS
Podemos usar los siguientes tipos de controles:
• HTML inputs: text, hidden, number, range, url, tel,
email, search, time, date, datetime, y week
(Dependiendo de la compatibilidad del navegador)
• checkbox
• textarea
• radio (las opciones las pasaremos por el parámetro
choices)
• select (las opciones las pasaremos por el parámetro
choices)
• dropdown-pages
• controles personalizados

18. TIPOS DE CONTROLS: EJEMPLOS
$wp_customize->add_control( 'setting_id', array(
'type' => 'range',
'section' => 'section_id',
'label' => __( 'Etiqueta', 'your_textdomain' ),
'input_attrs' => array(
'min' => 0,
'max' => 10,
'step' => 2,
),
) );
$wp_customize->add_control( 'setting_id', array(
'type' => 'radio',
'section' => 'section_id',
'label' => __( 'Etiqueta', 'your_textdomain' ),
'choices' => array(
'on' => __( 'On', 'your_textdomain' ),
'off' => __( 'Off', 'your_textdomain' ),
),
) );
$categories = get_categories();
$cats = array();
foreach($categories as $category) {
$cats[$category->slug] = $category->name;
}
$wp_customize->add_control( 'setting_id', array(
'type' => 'select',
'section' => 'section_id',
'label' => __( 'Etiqueta', 'your_textdomain' ),
'choices' => $cats
) );
$wp_customize->add_control( 'setting_id', array(
'type' => ‘dropdown-pages',
'section' => 'section_id',
'label' => __( 'Etiqueta', 'your_textdomain' ),
) );

19. WP_CUSTOMIZE_COLOR_CONTROL
$wp_customize->add_control( new WP_Customize_Color_Control (
$wp_customize, 'setting_id', array(
'label' => __( 'Etiqueta', 'your_textdomain' ),
'section' => 'section_id', // Required, core or custom.
) );

20. WP_CUSTOMIZE_MEDIA_CONTROL
$wp_customize->add_control( new WP_Customize_Media_Control (
$wp_customize, 'setting_id', array(
'mime_type' => 'image', // image, audio, video, application
'label' => __( 'Etiqueta', 'your_textdomain' ),
'section' => 'section_id', // Required, core or custom.
) );

21. EXTENDIENDO OBJETOS
Podemos crear Panels, Sections, Controls y Settings
personalizados extendiendo las clases asociadas con cada
objeto: WP_Customize_Panel, WP_Customize_Section,
WP_Customize_Control y WP_Customize_Setting:
class WP_New_Menu_Customize_Control extends WP_Customize_Control {
public $type = 'new_menu';
public function render_content() {?>
<button class="button button-primary" id="create-new-menu-submit"
tabindex="0"><?php _e( 'Create Menu', 'your_textdomain' ); ?></button>;
<?php }
}

22. VALIDACIONES
El personalizador nos permite validar y sanitizar nuestras
opciones antes de guardar en base de datos
$wp_customize->add_setting( 'setting_id', array(
'sanitize_callback' => 'absint',
'validate_callback' => 'validate_established_year'
) );
function validate_established_year( $validity, $value ) {
$value = intval( $value );
if ( empty( $value ) || ! is_numeric( $value ) ) {
$validity->add( 'required', __( 'Año no válido', 'your_textdomain' ) );
} elseif ( $value < 1900 ) {
$validity->add( 'year_too_small', __( 'Menor de 1900', 'your_textdomain' ) );
} elseif ( $value > gmdate( 'Y' ) ) {
$validity->add( 'year_too_big', __( 'Mayor que actual', 'your_textdomain' ) );
}
return $validity;
}

23. MULTI-IDIOMA
Tanto WPML como Polylang disponen de la función
icl_get_languages para obtener los idiomas activos de un
sitio
Array (
[es] => Array (
[id] => 2
[active] => 1
[native_name] => Español
[missing] => 1
[translated_name] =>
[language_code] => es
[country_flag_url] => http://wcs16.com/wp-content/plugins/polylang/flags/es.png
[url] => http://wcsantander16.com/es/
)
)

24. MULTI-IDIOMA
function themeslug_customize_register( $wp_customize ) {
$langs = (function_exists('icl_get_languages')) ? icl_get_languages('skip_missing=N') :
array( 'es' => array( 'language_code' => ‘es’));
$wp_customize->add_section( 'section_id', array(
'title' => __( 'Título Section', 'your_textdomain' ),
'description' => __( 'Descripción Section', 'your_textdomain' ),
) );
foreach($langs as $lang) {
$wp_customize->add_setting( 'setting_id_' . $lang['language_code'], array(
'type' => 'theme_mod',
'capability' => 'edit_theme_options',
) );
$wp_customize->add_control( 'setting_id_' . $lang['language_code'], array(
'type' => 'text',
'section' => 'section_id',
'label' => __( 'Título', 'your_textdomain' ) . " " . $lang['native_name'],
) );
}
}
add_action( 'customize_register', 'themeslug_customize_register' );

25. MULTI-IDIOMA

26. ¡ESTO ES TODO AMIG@S!
Pablo López Mestre
@desarrollowp
desarrollowp.com
WP Manager en VASS digital
¡Gracias por vuestra asistencia!