Mise à jour: cet article a été modifié le 19 février 2013, pour refléter les modifications apportées à la plaque de cuisson du personnalisateur de thème.

J’espère que vous avez lu et apprécié les deux premiers articles de la série Theme Customizer – Introduction à WordPress Theme Customizer et Interagir avec Theme Customizer. Il est maintenant temps de passer au cours principal et de commencer à assembler le modèle standard du personnalisateur de thème que vous pourrez utiliser dans vos thèmes. Cet article contient quelques longs blocs de code, alors faites attention aux commentaires en ligne.

Remarque: Si vous préférez simplement utiliser le passe-partout tout de suite, vous pouvez le télécharger depuis Github et modifier les champs dans le tableau $ options en vous connectant au hook de filtre ‘thsp_cbp_options_array’.

Ce que nous créons

Structure du répertoire Boilerplate du personnalisateur de thème

  • customizer.php – Il s’agit du fichier standard du personnalisateur de thème principal, celui qui ajoute des sections, des paramètres et des contrôles à l’aide des données du tableau d’options
  • custom-controls.php – Classes de contrôles personnalisés et un crochet d’action qui vous permet d’ajouter vos propres contrôles personnalisés
  • helpers.php – Fonctions d’assistance, utilisées pour récupérer les options de thème, les options par défaut, etc.
  • options.php – Exemples d’options et un crochet de filtre qui vous permet de modifier le tableau d’options et d’utiliser vos propres champs
  • customizer-controls.css – CSS de base pour le contrôle personnalisé de la radio remplacé par l’image

L’idée générale est de pouvoir copier ces fichiers dans un sous-répertoire de votre répertoire de thème, d’inclure le fichier customizer.php de votre functions.php et de changer tout ce que vous voulez, y compris et surtout le tableau d’options, en utilisant les hooks Boilerplate de Theme Customizer (expliqué dans la partie 4). Mettre à jour: Auparavant, vous éditiez simplement options.php, mais l’utilisation de hooks rend les choses beaucoup plus propres.

Utilisons maintenant un exemple réel – nous ajouterons un contrôle de texte à une nouvelle section de personnalisation de thème. Le tableau est placé dans une fonction d’assistance et un filtre lui est appliqué lorsqu’il est renvoyé. De cette façon, vous pouvez ajouter plus d’options à partir d’un thème enfant ou d’un plugin. C’est ici:

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

Mettre à jour: Le tableau reste le même, mais maintenant vous pouvez également passer le tableau d’options à un hook de filtre, voir la partie 4 pour plus de détails.

Cela semble compliqué à première vue, je sais, mais laissez-moi vous expliquer.

le $ options tableau se compose de section (s) (une seule dans ce cas – new_customizer_section), chaque section a ses arguments, champs et une valeur booléenne (existing_section) pour indiquer s’il s’agit d’une nouvelle section, ou nous ajoutons simplement des champs à un existant une. Le tableau d’arguments est identique à ce à quoi vous passeriez $ wp_customize-> add_section méthode. Le tableau des champs est légèrement plus complexe.

Mettre à jour: Le tableau de choix dans les arguments de contrôle est maintenant un tableau multidimensionnel.

Chaque champ se compose d’un paramètre de personnalisation et d’un contrôle de personnalisation. C’est pourquoi nous avons des tableaux setting_args et control_args. Ils sont presque exactement les mêmes que les tableaux d’arguments auxquels vous passeriez $ wp_customize-> add_setting et $ wp_customize-> add_control méthodes. La seule différence est le tableau ‘choice’ dans les arguments de contrôle, $ wp_customize-> add_control nécessite qu’il s’agisse d’un simple tableau de paires clé => valeur et nous utilisons un tableau multidimensionnel à la place.

De cette façon, il est possible de transmettre plus de données à chacun des choix, donc si vous chargez, par exemple, des polices Google dans votre thème, vous pourrez avoir des chaînes qui vous permettront de charger la police correcte dans le tableau de choix. . Vous pouvez voir un exemple de ceci thème utilisant Customizer Boilerplate.

Donc, si vous connaissez déjà ces trois méthodes, tout est très familier.

L’ajout d’un contrôle de case à cocher est presque identique, il vous suffit de changer ‘type’ en ‘checkbox’ dans le tableau ‘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
    )
),              

Les commandes de radio et de sélection sont presque les mêmes, il vous suffit de spécifier les choix donnés:

/*
 * ===========
 * ===========
 * 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
    )
)

Et enfin, deux types de contrôle complexes intégrés à WordPress – téléchargement de fichiers et téléchargement d’images:

/*
 * ===========
 * ===========
 * 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
    )
)

Notez que j’ai utilisé ‘type’ => ‘option’ dans la définition des arguments pour tous ces champs. Cela permettra à toutes les valeurs d’être stockées en une seule valeur dans votre base de données. L’alternative est ‘type’ => ‘theme_mod’ mais pour l’instant, restons avec «option».

Utilisation de la matrice d’options pour ajouter des sections, des paramètres et des commandes de personnalisation

Si vous ne savez pas comment interagir avec WordPress Theme Customizer, allez vérifier, car c’est ce que nous allons faire maintenant. La seule différence est qu’au lieu d’ajouter des sections, des paramètres et des contrôles un par un, nous automatiserons le processus à l’aide du tableau sérialisé que nous avons créé. Allons-y simplement:

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

Parcourir toutes les sections, ajouter celles qui n’existent pas déjà, puis parcourir tous les champs de chaque section, ajouter un paramètre et un contrôle pour chacune. C’est tout ce qui se passe ici.

Rappelez-vous que nous avons utilisé ‘type’ => ‘option’ pour tous les paramètres? C’est pourquoi nous avons maintenant “My_theme_options[$thsp_field_key]” pour les paramètres et les sections. Cela stockera toutes les valeurs dans un tableau sérialisé que vous pouvez récupérer en utilisant get_option (‘mes_options_thème’). Ou vous pouvez simplement utiliser les fonctions d’assistance définies dans helpers.php pour récupérer les valeurs actuelles et les valeurs par défaut pour tous les champs:

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

Il n’y a qu’une seule chose que je devrais mentionner – la fonction de rappel de nettoyage que nous avons spécifiée dans le tableau ‘setting_args’. La fonction est définie dans extend.php et exécute simplement les données via wp_kses_post fonction:

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

Où aller d’ici?

Pour le moment, vous pouvez utiliser cette Boilerplate de personnalisation de thème dans vos thèmes, tout ce que vous avez à faire est de le télécharger depuis Github, de le copier dans le répertoire de votre thème et d’inclure le fichier principal de functions.php, qui est 100% fonctionnel et suffisant pour la plupart thèmes.

Puisque votre thème n’est pas «comme la plupart des thèmes», la semaine prochaine, nous verrons comment étendre le passe-partout en utilisant son filtre et ses crochets d’action.

Je serais ravi d’entendre comment vous pensez que ce passe-partout pourrait être amélioré ou élargi, alors n’hésitez pas à lire dans les commentaires.

Share: