Créer le panneau d'administration d'un plugin wordpress

Tous les plugins devraient idéalement posséder un panneau d'administration. Créer ce panneau d'administration n'est pas très complexe, c'est donc un peu pénible de la part des auteurs de plugin de demander à leurs utilisateurs d'éditer eux-mêmes le code PHP (Ce qui n'est généralement pas une bonne idée).

Cette section a pour vocation à vous apprendre à créer votre panneau d'administration.

Où stocker les variables ?

La première des choses à se demander lorsque l'on construit un panneau d'administration est où allons nous stocker les variables. Par chance, Wordpress rend cela plus simple avec les options. Tout ce que nous avons à faire pour le moment est de stocker nos propres variables d'administration dans la base de données existante Wordpress.

Nous devons donc créer des variables uniques pour les options d'administration. Nous les définissons comme attributs de la classe principale wp_jschat.

class wp_jschat
{
    var $adminOptionsName = 'wp_jschatAdminOptions';
    function wp_jschat()
    {
        
    }
}

Nous ajoutons donc un attribut $adminOptions à notre classe principale wp_jschat, et lui donnons comme valeur la chaîne unique 'wp_jschatOptions'.

Définissons les options par défaut

Il faut maintenant initialiser les options par défaut de l'administration, pour lorsqu'un utilisateur du plugin active celui-ci.

Note : afin d'assurer la compatibilité future de ce plugin si vous décidez par la suite d'ajouter des options. La technique est de fournir une méthode dédiée pour appeler les options d'administration, voici cette méthode dans le cadre de notre plugin :

function getAdminOptions() 
{
    $wp_jschatAdminOptions = array(
            'enabled' => 'true',
            'exclude_ips' => ''
        );
    $wp_jschatOptions = get_option($this->adminOptionsName);
    if (!empty($wp_jschatOptions))
    {
        foreach ($wp_jschatOptions as $key => $option)
            $wp_jschatAdminOptions[$key] = $option;
    }
    update_option($this->adminOptionsName, $wp_jschatAdminOptions);
    return $wp_jschatAdminOptions;
}

Cette fonction :

• assigne les valeurs par défaut aux options d'administration,
• tente de trouver les options préalables qui ont pu être stockées dans la base de données,
• si les options existent dans la base de données, les valeurs par défaut sont écrasées par celles de la base,
• les options sont stockées dans la base,
• les options sont renvoyées pour être utilisées.

Initialisation des options d'administration

La fonction getAdminOptions() peut être appelée n'importe quand pour connaître les options d'administration. Cette fonction doit néanmoins être appelée pour récupérer ces données. Ajoutons donc cette fonction dans notre classe wp_jschat :

function init() 
{
    $this->getAdminOptions();
}

Une action wordpress est également requise afin d'appeler cette fonction :

add_action('activate_wp_jschat/wp_jschat.php',  array(&$inst_wp_jschat, 'init'));

Cette action n'est par exactement comme les précédentes, mais elle est simple à comprendre. Voici ce qu'elle fait :

• elle s'exécute lorsque le plugin est activé,
• vous indiquez l'adresse vers le fichier PHP principal , qui est wp_jschat/wp_jschat.php,
• vous passez la référence à l'instance de la classe $inst_wp_jschat, et appellez la méthode init()

Désormais, à chaque fois que le plugin est activé, la fonction init() du plugin wp_jschat est appelée.

So anytime the plugin is activated, the init function is called for the Devlounge Plugin Series plugin.

Comment fonctionne le panneau d'administration

Avant de débuter à coder, il est préférable de décrire un peu le comportement du panneau d'administration Wordpress. Voici la marche à suivre :

• vérifier si les données de formulaire ont été soumises,
• afficher une information de sortie si des données de formulaire sont soumises,
• afficher les options d'administration.

Un chose peut paraître confuse, c'est l'utilisation de la méthode wordpress _e(). La méthode _e() permet à wordpress de chercher une version localisée de votre texte en vue de l'internationalisation de votre plugin. Il est important de recourir à cette méthode dans la mesure ou vous souhaitez déployer votre plugin dans plusieurs langages. Cette méthode fonctionne comme beaucoup de fonctions de fonctions d'autres CMS (comme eZPublish), c'est à dire qu'au lieu de passer du texte, on y passe une variable d'identification du texte, par exemple :

_e('Mettre à jour', 'wpjschat');
//est équivalent à :
echo 'Mettre à jour';

cependant, vous gardez la possibilité d'internationaliser ce texte par la suite grâce aux fichiers de langues .po, dont nous étudierons dans la suite de ce tutoriel le fonctionnement.

Installer le panneau d'administration Wordpress

La première chose que nous devons faire est créer une fonction qui va afficher notre panneau d'administration dans la classe principale. Nous appellerons cette fonction printAdminPage(). Cette partie de code va lire les options que nous avons spécifié précédemment, et vérifier si certaines options ont été soumises.

function printAdminPage() {
    $options = $this->getAdminOptions();
    if (isset($_POST['update_wp_jschatSettings'])) {
        if (isset($_POST['enabled'])) {
            $options['enabled'] = $_POST['enabled'];
        }
        if (isset($_POST['exclude_ips'])) {
            $options['exclude_ips'] = $_POST['exclude_ips'];
        }
        update_option($this->adminOptionsName, $options);
        print '<div class="updated"><p><strong>';
        _e("Paramètres mis à jour", "wpjschat");
        print '</strong></p></div>';
       
    }
    include('php/admin_settings.php'); // include du formulaire HTML
}

Ce code charge les options et s'assure que chaque paramètre est soumis. L'imbrication des if n'est pas forcément nécessaire, mais peut se révéler utile dans le cadre d'un débogage. La première variable POST testée est update_wp_jschatSettings, cette variable correspond à l'attribut name du bouton submit de notre formulaire décrit ci-après.

Note : la fonction distribuée dans le plugin wordpress de chat est plus complexe, elle fait appel à la base de données que nous aborderons dans un prochain cours.

On inclut à la fin de la fonction le formulaire que nous plaçons dans le dossier php de notre plugin Wordpress (cf tutoriel précédent : structure du plugin Wordpress).

Le formulaire d'administration

Le code HTML suivant est nécessaire pour l'administration. Ce code affiche simplement le formulaire et lis les options :

<div class=wrap>
    <div class="icon32" id="icon-edit"><br /></div>
    <h2><?php _e('Javascript Chat pour  Wordpress', 'wpjschat') ?></h2>
    <form method="post" action="<?php echo $_SERVER["REQUEST_URI"]; ?>">
        <div class="postbox " id="postexcerpt">
            <h3><?php _e('Activer le chat', 'wpjschat') ?></h3>
            <div class="inside">
                <p>
                    <label for="devloungeHeader_yes">
                        <input type="radio" name="enabled" value="true" <?php if ($options['enabled'] == "true") {
    print ' checked="checked"';
} ?> />
<?php _e('Oui', 'wpjschat') ?>
                    </label>
                    <label for="devloungeHeader_no">
                        <input type="radio" name="enabled" value="false" <?php if ($options['enabled'] == "false") {
    print ' checked="checked"';
} ?>/>
<?php _e('Non', 'wpjschat') ?>
                    </label>
                </p>
            </div>
        </div>
        <div class="postbox " id="postexcerpt">
            <h3><span><?php _e('IP bannies (séparées par des virgules)', 'wpjschat') ?></span></h3>
            <p>
                <textarea name="exclude_ips" style="width: 80%; height: 100px;"><?php _e(apply_filters('format_to_edit', $options['exclude_ips']), 'wpjschat') ?></textarea>
            </p>

        </div>
        <div class="submit">
            <input type="submit" name="update_wp_jschatSettings" value="<?php _e('Mettre à jour', 'wpjschat') ?>" />
        </div>
</div>
 

Notez que ce code dépend de vos options et de votre manière d'intégrer PHP et HTML.

Définir les actions du panneau d'administration

Maintenant que la méthode printAdminPage est ajoutée, nous devons l'appeler à partir d'une action. Pour cela, nous devons mettre en place une fonction au dessus des actions, afin que celle-ci soit en dehors de la portée de la class.

if (!function_exists("wp_jschat_ap")) 
{
    function wp_jschat_ap() {
        global $inst_wp_jschat;
        if (!isset($inst_wp_jschat)) {
            return;
        }
        if (function_exists('add_options_page')) 
        {
            add_options_page('WP jsChat', 'WP jsChat', 9, basename(__FILE__), array(&$inst_wp_jschat, 'printAdminPage'));
        }
    }
}

• Une fonction wp_jschat_ap est donc créée,
• on teste si l'instance de la classe wp_jschat existe,
• une page d'administration nommée "WP jsChat" est initialisée et notre fonction printAdminPage est référencée.

La fonction add_options_page se présente comme suit :

add_options_page(page_title, menu_title, access_level/capability, file, [function]);

Le troisième paramètre (access_level) est décrit de manière détaillée dans la documentation de Wordpress.

Un action doit maintenant être faite pour appeler la fonction wp_jschat_ap().

add_action('admin_menu', 'wp_jschat_ap');

Conclusion

Apparaît maintenant dans le menu Settings un lien WP jsChat pour gérer les paramètres de notre plugin wp_jschat.