Ajouter des fonctionnalités dans le tableau de bord (add_menu_page(), add_submenu_page(), add_option_page())

Lorsqu'un thème ou une extension utilise des tables personnalisées ou encore des options personnalisées (dans la table wp_options), il y a fort à parier qu'une interface de gestion sera nécessaire pour gérer les données de ces tables. Une telle interface fera partie du tableau de bord.

▼Publicité

Le code nécessaire sera entré :

  • pour un thème : dans functions.php
  • pour une extension : dans la classe de l'extension

Ajouter une option dans le menu du tableau de bord

Le « hook » admin_menu permet de personnaliser le menu du tableau de bord WordPress. Dans la fonction associée à ce « hook », vous pouvez ajouter une option de menu à l'aide des fonctions WordPress suivantes. 

  • add_menu_page() : ajouter une option dans le menu principal.
  • add_submenu_page() : ajouter une option sous une option de menu existante. Par exemple, nous pourrions créer une option de menu avec add_menu_page() puis ajouter des sous-options à ce menu à l'aide de add_submenu_page().
  • add_option_page() : ajouter une option de menu sous le menu « Réglages ».
  • etc.

Attention : si vous tentez d'appeler ces fonctions en dehors du « hook » admin_menu, vous obtiendrez un message d'erreur.

Voici un extrait de code permettant d'ajouter une option de menu principal (le menu « Mon thème » dans l'image présentée). 

Ajout d'une option dans le menu principal

WordPress (PHP)

add_action( "admin_menu", "montheme_ajouter_menu_tableau_de_bord" );

function montheme_ajouter_menu_tableau_de_bord() {

   add_menu_page( 

      __( "Mon thème - Configuration", "montheme" ), // texte de la balise <title>

      __( "Mon thème", "montheme" ),  // titre de l'option de menu

      "manage_options", // droits requis pour voir l'option de menu

      "montheme_menu_admin", // slug

      "montheme_creer_page_configuration" // fonction de rappel pour créer la page

   );

}

 

function montheme_creer_page_configuration() {

   global $title;   // titre de la page du menu, tel que spécifié dans la fonction add_menu_page

   ?>

   <div class="wrap">

      <h2><?php echo $title; ?></h2>   

      ...

   </div>

   <?php

}

Le premier paramètre de add_menu_page() permet de spécifier le texte de la balise <title> (titre d'entête) de la page de configuration (dans l'exemple : Mon thème - Configuration). Le titre d'entête apparaît dans la barre de titre du navigateur et non dans la page elle-même. Une variable nommée $title contiendra ce titre et permettra, si nous le désirons, de l'afficher en haut de notre page (titre de contenu). Remarquez l'utilisation de __() pour permettre l'affichage dans une autre langue, selon les configurations de wp_config.php

Le second paramètre est le titre de l'option de menu, tel qu'il apparaîtra dans la zone gauche du tableau de bord.

Lorsqu'on ajoute une option de menu dans le tableau de bord, il faut spécifier quels droits sont nécessaires pour pouvoir accéder à cette page (dans l'exemple : manage_options. Consultez la liste des droits existants pour connaître toutes les possibilités. Notez cependant que si votre option de menu doit permettre la gestion d'options, il faudra avoir minimalement les droits manage_options pour y parvenir.

Remarquez que l'identifiant (slug) du menu (dans l'exemple : montheme_menu_admin) sera utilisé dans l'URL de la page donc visible pour les administrateurs (ex : http://mondomaine.com/wp-admin/admin.php?page=montheme_menu_admin). Assurez-vous que cet identifiant soit acceptable !

Le dernier paramètre est le nom de la fonction de rappel qui se chargera d'afficher le contenu dans la page du tableau de bord qui sera lancée par notre nouvelle option de menu. Cette page contiendra vraisemblablement un formulaire permettant de gérer les données personnalisées. Il peut s'agir d'un formulaire monté de toutes pièces pour interagir avec nos tables personnalisées. Ça peut également être un formulaire géré par le « WordPress Settings API » pour gérer les options du thème ou de l'extension.

Dans la page de l'option de menu, notez la présence de la division dont la classe est "wrap". Cette division est utilisée pour formater les autres pages du tableau de bord alors nous l'utiliserons également afin que l'apparence de notre page soit conforme au reste du tableau de bord.

Icône et position

Il aurait été possible d'ajouter deux paramètres supplémentaires : l'URL de l'icône devant représenter le menu ainsi que la position du nouveau menu. Si ces paramètres sont omis, le menu utilisera l'icône par défaut et sera placé dans le bas complètement du menu WordPress.

Ajouter un sous-menu à l'aide de add_submenu_page()

Si vous souhaitez ajouter une option sous un menu existant, vous utiliserez add_submenu_page. Les paramètres sont très semblables à ceux de add_menu_page. Cependant, vous devrez ajouter un paramètre au tout début de la liste : le « slug » du menu parent.

Ex :

WordPress (PHP)

add_submenu_page( 

   "montheme_menu_admin",  // slug du menu parent

   __( "Mon thème - Mon sous-menu - Configuration", "montheme" ),  // texte de la balise <title>

   __( "Mon sous-menu", "montheme" ),  // titre de l'option de sous-menu

   "manage_options",  // droits requis pour voir l'option de menu

   "montheme_sousmenu_admin", // slug

   "montheme_sousmenu_creer_page_configuration"  // fonction de rappel pour créer la page

);

Attention : si vous désirez ajouter un menu qui contiendra des sous-menu, il est d'usage de faire en sorte que pour le premier sous-menu, la fonction add_submenu_page utilise le même identifiant (slug) comme premier paramètre (parent_slug) et comme 5e paramètre (menu_slug). Seul le titre de l'option de menu différera afin de ne pas laisser croire qu'il s'agit d'un mauvais fonctionnement.

Autrement dit, le add_menu_page() et le premier add_submenu_page() définieront tous deux la même option de menu. De cette façon, un clic sur l'option du menu principal affichera la même page que lors d'un clic sur le premier sous-menu.

Vous pouvez observer ce comportement dans les options de menu présentes par défaut dans le tableau de bord. Sous l'option de menu Nouvelles, on retrouve le sous-menu « Toutes les nouvelles ». Ces deux options de menu mènent vers la même page.

Voici donc le code permettant d'ajouter les sous-menus Configuration et Mon sous-menu sous l'option de menu Mon thème.

Ex :

WordPress (PHP)

add_menu_page( 

   __( "Mon thème - Configuration", "montheme" ),  // texte de la balise <title>

   __( "Mon thème", "montheme" ),   // titre de l'option de menu

   "manage_options", // droits requis pour voir l'option de menu

   "montheme_menu_admin", // slug

   "montheme_creer_page_configuration" // fonction de rappel pour créer la page

);

// première option du sous-menu : redéfinit les mêmes critères que le menu

add_submenu_page( 

   "montheme_menu_admin",  // slug du menu parent

   __( "Mon thème - Configuration", "montheme" ),  // texte de la balise <title> - même que dans add_menu_page()

   __( "Configuration", "montheme" ),   // titre de l'option de sous-menu

   "manage_options",  // droits requis pour voir l'option de menu

   "montheme_menu_admin", // réutiliser le slug du menu parent

   "montheme_creer_page_configuration"  // fonction de rappel pour créer la page - même que dans add_menu_page()

);

// seconde option du sous-menu

add_submenu_page( 

   "montheme_menu_admin",   // slug du menu parent

   __( "Mon thème - Mon sous-menu - Configuration", "montheme" ),  // texte de la balise <title>

   __( "Mon sous-menu", "montheme" ),   // titre de l'option de sous-menu

   "manage_options",  // droits requis pour voir l'option de menu

   "montheme_sousmenu_admin", // slug

   "montheme_sousmenu_creer_page_configuration"  // fonction de rappel pour créer la page

);

Et voici le résultat obtenu par ce code :

Menu personnalisé avec sous-menus

Notez que pour le texte de la balise <title> et le nom de la fonction de rappel, s'ils ne sont pas identiques dans add_menu_page() et dans le premier add_submenu_page(), ce seront les valeurs dans le add_submenu_page() qui seront utilisées.

Pour plus d'information

« Administration Menus ». Codex WordPress. http://codex.wordpress.org/Administration_Menus

« Create a Simple WordPress Admin Panel – Part ICreate a Simple WordPress Admin Panel – Part I ». Colorlabs. http://colorlabsproject.com/tutorials/create-a-simple-wordpress-admin-panel/

« Plugin API/Action Reference/admin menu ». Codex WordPress. http://codex.wordpress.org/Plugin_API/Action_Reference/admin_menu

« Function Reference/add menu page ». Codex WordPress. http://codex.wordpress.org/Function_Reference/add_menu_page

Merci de partager ! Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInPin on PinterestShare on StumbleUponEmail this to someone
Catégories