Afin de respecter le style du tableau de bord, les message, que ce soit un message d'information, de succès, d'avertissement ou d'erreur, devront y être affichés à l'aide d'une des techniques présentées ici.
L'apparence du message sera régi à l'aide de balises HTML et de classes CSS précises.
Le texte du message doit être placé dans une balise <div> dont la classe est notice. À l'intérieur de cette division, on ajoutera également des marques de paragraphes <p>.
De plus, pour ajouter une bande de couleur qui indique le niveau du message, on ajoutera une des classes CSS suivantes :
À ces classes, on peut ajouter la classe is-dismissible pour que le message d'erreur soit accompagné d'un X permettant de le faire disparaître.
echo '<div class="notice notice-error"><p>';
_e( "Oups ! Un problème a été rencontré.", "mon-domaine-de-localisation" );
echo '</p></div>';
Parfois, le message doit être affiché sur-le-champ, là où WordPress est rendu dans la construction de la page. À ce moment, il est possible de faire directement un echo pour afficher le message.
Notez qu'avec cette approche, il est tout de même possible que le message soit affiché en haut de la page. Ce sera le cas, par exemple, si le code qui génère le message est exécuté au début du chargement de la page.
Voici un exemple où un message d'erreur est affiché lorsque la fonction de rappel du hook after_switch_theme est appelée.
dbDelta( $sql );
$erreur_sql = $wpdb->last_error;
if ('' != $erreur_sql) {
echo '<div class="notice notice-error is-dismissible"><p>';
_e( "Un problème a empêché la création des tables requises dans la base de données.", "mon-domaine-de-localisation" );
echo '</p></div>';
}
La plupart du temps, les messages affichés dans le tableau de bord utiliseront le hook admin_notices.
La fonction de rappel associée à ce hook devra afficher le code HTML du message.
Le hook admin_notices et sa fonction de rappel seront utilisés comme suit :
/**
* Affiche un message de remerciement pour l'installation de l'extension.
* @author Christiane Lagacé <christiane.lagace@hotmail.com>
*
* Utilisation : add_action( 'admin_notices', 'monprefixe_message_merci_installation' );
*/
function monprefixe_message_merci_installation() {
echo '<div class="notice notice-info is-dismissible"><p>';
_e( "Merci d'avoir installé l'extension XYZ !", 'mon-domaine-de-localisation' );
echo '</p></div>';
}
add_action( 'admin_notices', 'monprefixe_message_merci_installation' );
Lors du chargement d'une page du tableau de bord, les messages configurés dans le hook admin_notices apparaîtront là où se trouve la balise <hr class="wp-header-end">, qui devrait normalement être définie dans le haut de la page.
<div class="wrap">
<h1 class="wp-heading-inline"><?php echo $title; ?></h1>
...
<hr class="wp-header-end">
...
</div>
En cas d'absence de cette balise, le message sera placé immédiatement sous le titre de contenu (défini avec <h1>, <h2>, ...), à condition que ce titre fasse partie de la division <div class="wrap">.
Dans le cas où la page ne contiendrait pas de balise <hr class="wp-header-end"> ni de balise de titre (ce qui n'est pas souhaitable), le message serait affiché tout en haut de la page.
Dans l'exemple précédent, le message sera toujours affiché, sur toutes les pages du tableau de bord.
Dans le cas où le message doit être affiché seulement dans certaines conditions ou sur seulement certaines pages, la fonction de rappel devra se charger de vérifier si les conditions sont remplies, par exemple en utilisant des variables de session.
Pour travailler avec des variables de session, il faudra d'abord activer ce mécanisme puisque par défaut, WordPress ne le fait pas.
Ceci sera fait directement dans le fichier functions.php (et non dans un sous-fichier) ou encore, si vous êtes en train de développer une extension, dans un fichier de l'extension.
/**
* Active les variables de session.
* @author Christiane Lagacé <christiane.lagace@hotmail.com>
*
* Utilisation : add_action( 'init', 'monprefixe_session_start', 1 );
*/
function monprefixe_session_start() {
if ( ! session_id() ) {
@session_start();
}
}
add_action( 'init', 'monprefixe_session_start', 1 );
Ensuite, le code initialisera la variable de session lorsqu'une condition donnée est rencontrée. Ici, on souhaite affiche un message d'erreur lorsque la création d'une table a échoué.
dbDelta( $sql );
$erreur_sql = $wpdb->last_error;
if ('' != $erreur_sql) {
$_SESSION['monprefixe_erreur_creation_table'] = true;
}
Finalement, la fonction de rappel du hook admin_notices affichera le message mais seulement si la variable de session existe.
/**
* Affiche un message indiquant que l'item a été ajouté avec succès, seulement si la variable de session existe.
* @author Christiane Lagacé <christiane.lagace@hotmail.com>
*
* Utilisation : add_action( 'admin_notices', 'monprefixe_message_ajout_item_reussi' );
*/
function monprefixe_message_ajout_item_reussi() {
if ( isset( $_SESSION['monprefixe_erreur_creation_table'] ) && $_SESSION['monprefixe_erreur_creation_table'] == true ) {
echo '<div class="notice notice-error is-dismissible"><p>';
_e( "Un problème a empêché la création des tables requises dans la base de données.", "mon-domaine-de-localisation" );
echo '</p></div>';
// supprime la variable de session pour ne pas que le message soit affiché à nouveau
$_SESSION['monprefixe_erreur_creation_table'] = null;
}
}
add_action( 'admin_notices', 'monprefixe_message_ajout_item_reussi' );
Ici, dû au moment où l'erreur est survenue, le résultat sera exactement le même que si on avait écrit le message d'erreur directement lorsque l'erreur a été rencontrée.
J'ai tenté d'illustrer ce processus comme suit :
Il est possible d'affiche un message en tout temps mais seulement sur une page donnée, par exemple sur la page qui liste les items de notre thème personnalisé ou de notre extension.
Pour cela, on utilisera la variable globale $pagenow. pour s'assurer qu'on est sur la page admin.php.
On doit également vérifier la valeur du paramètre page dans l'URL. Ce paramètre correspond au slug utilisé dans add_menu_page() ou add_submenu_page().
/**
* Affiche un message indiquant que l'item a été ajouté avec succès, seulement sur la page qui liste les items.
* @author Christiane Lagacé <christiane.lagace@hotmail.com>
*
* Utilisation : add_action( 'admin_notices', 'monprefixe_message_ajout_item_reussi' );
*/
function monprefixe_message_ajout_item_reussi() {
global $pagenow;
if ( $pagenow == 'admin.php' && $_GET['page'] == 'monprefixe_gestion' ) {
echo '<div class="notice notice-info is-dismissible"><p>';
_e( "Pour afficher cette liste côté site Web, veuillez utiliser le shortcode [monprefixelisteitems].", "mon-domaine-de-localisation" );
echo '</p></div>';
}
}
add_action( 'admin_notices', 'monprefixe_message_ajout_item_reussi' );
« Plugin API/Action Reference/admin notices ». Codex WordPress. https://codex.wordpress.org/Plugin_API/Action_Reference/admin_notices
« Complete Guide to WordPress Admin Notices ». Digging Into WordPress. https://digwp.com/2016/05/wordpress-admin-notices/
▼Publicité
