Découverte de l'API Customizer

WPTech Nantes 2014

Sommaire

• L'avant-customizer
• Qu'est-ce que le customizer ?
• Utiliser le customizer
• Aller plus loin
• "Decisions, not options"
• Le futur de l'API

L'avant-customizer

L'avant-customizer

C'était ça

L'avant-customizer

De nombreux frameworks d'options différents

• Des interfaces disparates
• Un fourre-tout de paramétrages
• Peu pratique pour les développeurs
• Peu intuitif pour les utilisateurs

Qu'est-ce que le customizer ?

Qu'est-ce que le customizer ?

Une API introduite avec WordPress 3.4 (juin 2012)

Qu'est-ce que le customizer ?

Une base commune pour gérer les options d'un thème

Menu Apparence => Personnaliser

Qu'est-ce que le customizer ?

Idéal pour :

• L'utilisateur : tous les thèmes utilisent la même interface
• Le développeur : un système intégré au core = pérennité, hooks, etc

Qu'est-ce que le customizer ?

WordPress l'utilise pour gérer des réglages par défaut

Qu'est-ce que le customizer ?

Utiliser le customizer

Utiliser le customizer

Un hook : customize_register

function themeslug_customize_register( $wp_customize ) {
   // Toutes les sections, réglages et contrôles seront ici
}
add_action( 'customize_register', 'themeslug_customize_register' );

Utiliser le customizer

Une option de thème

• Un réglage
• Un contrôle

Utiliser le customizer

Créer une section

$wp_customize->add_section( 'themeslug_section_name' , array(
    'title'      => __( 'Section name', 'themeslug' ),
    'description'=> __( 'Section description', 'themeslug' ),
    'priority'   => 30,
) );

$wp_customize->add_section( $section_id, $args );

Utiliser le customizer

Créer un réglage

$wp_customize->add_setting( 'themeslug[option_name]' , array(
    'default'     => '',
    'transport'   => 'refresh', // refresh ou postMessage
    'sanitize_callback' => 'sanitize_text_field'
) );

$wp_customize->add_setting( $setting_id, $args );

Utiliser le customizer

Créer un contrôle

$wp_customize->add_control( 'option_name', array(
    'label' => __( 'Option Name', 'themeslug' ),
    'description' => __( 'Option description', 'themeslug' ),
    'section' => 'themeslug_section_name',
    'settings' => 'themeslug[option_name]',
    'type' => 'text',
    'active_callback' => 'is_front_page'
) );

$wp_customize->add_section( $option_id, $args );

Utiliser le customizer

Utiliser le customizer

Type de contrôles

• text (et dérivés HTML 5 : url, email…)
• textarea (depuis WP 4.0)
• checkbox
• select
• radio
• dropdown-pages

Utiliser le customizer

Les contrôles à choix

$wp_customize->add_control('select_radio', array(
        'label'      => __('Radio options', 'themeslug'),
        'section'    => 'themename_section_name',
        'settings'   => 'themeslug[select_radio]',
        'type'       => 'radio',
        'choices'    => array(
            'value1' => 'Choice 1',
            'value2' => 'Choice 2',
            'value3' => 'Choice 3',
        ),
    ));

Utiliser le customizer

Utilisation de la valeur en front

$theme_options = get_theme_mod( 'themeslug' );
echo $theme_options['option_name'];

get_theme_mod( $options_id, $default );

Aller plus loin

Aller plus loin

Créer un panneau

$wp_customize->add_panel( 'panel_name', array(
    'priority' => 200,
    'title' => __( 'Panel name', 'themeslug' ),
    'description' => __( 'Panel description', 'themeslug' )
) );

Un panneau regroupe des sections

$wp_customize->add_panel( $panel_id, $args );

Aller plus loin

Attribuer une section à un panneau

$wp_customize->add_section( 'themeslug_section_name' , array(
    'title'      => __( 'Section name', 'themeslug' ),
    'description'=> __( 'Section description', 'themeslug' ),
    'priority'   => 30,
    'panel'      => 'panel_name'
) );

Aller plus loin

Aller plus loin

Ajouter des attributs à un contrôle

'input_attrs' => array(
    'min' => 0,
    'max' => 10,
    'step' => 2,
    'class' => 'test-class test',
    'style' => 'color: #0a0',
)

Aller plus loin

Utiliser un contrôle étendu

$wp_customize->add_control(
        new WP_Customize_Color_Control(
            $wp_customize,
            'links_color',
            array(
                'label' => __( 'Links color', 'themeslug' ),
                'section' => 'colors',
                'settings' => 'themeslug[links_color]'
            )
        )
    );

Aller plus loin

Aller plus loin

Les contrôles étendus intégrés à l'API

• WP_Customize_Color_Control()
• WP_Customize_Upload_Control()
• WP_Customize_Image_Control()

Aller plus loin

Créer son propre contrôle étendu

class Theme_Custom_Control extends WP_Customize_Control {
      public function render_content() { ?>
        <label>
        <span class="customize-control-title">
            <?php echo esc_html( $this->label ); ?>
        </span>
        </label>
        <textarea rows="5" <?php $this->link(); ?>>
            <?php echo esc_textarea( $this->value() ); ?>
        </textarea>
    <?php }
}

Aller plus loin

Prévisualiser les changement en direct

Pré-requis :

• Utiliser "transport" => "postMessage"
• Créer un fichier javascript pour gérer les changements
• Insérer ce JS grâce au hook : customize_preview_init

Aller plus loin

Ajouter le JS de prévisualisation

function themeslug_customizer_live_preview() {
    wp_enqueue_script( 'themeslug-customizer',
                        get_template_directory_uri() . '/js/customizer.js', 
                        array( 'jquery', 'customize-preview' ),
                        '1.0', 
                        true );
}
add_action( 'customize_preview_init', 'themeslug_customizer_live_preview' );

Hook : customizer_preview_init

Aller plus loin

Changements en direct

( function( $ ) {

    wp.customize( 'themeslug[links_color]', function( value ) {
	value.bind( function( newval ) {
		$( 'a' ).css( 'color', newval );
	} );
    } );

} )( jQuery );

"Decisions, not options"

Decisions, not options

Ne pas reproduire les même erreurs qu'auparavant

Decisions, not options

Proposez des options pertinentes par rapport à votre thème

Le futur de l'API

Elle sert de base pour des projets en cours

• Edition du contenu depuis le front-end

• Nouvelle gestion des menus

Ressources utiles

• http://codex.wordpress.org/Theme_Customization_API

• http://remyperona.fr/nouveautes-customizer-wordpress-4/

• http://ottopress.com/tag/customizer/

Rémy Perona

Développeur/Intégrateur WP

Me retrouver sur :

• ​http://remyperona.fr
• Twitter : @theloopfr
• Github :  https://github.com/Tabrisrp