add_submenu_page()

Définition : add_submenu_page() insère une page sous un menu existant dans l’administration WordPress. Elle organise plusieurs écrans d’une extension sans multiplier les entrées de premier niveau dans la barre latérale.

Terminologie

Terme officiel : add_submenu_page()

Autres appellations : Sous-menu d’administration

À quoi cela sert

Cette fonction permet de construire une navigation cohérente pour un plugin à plusieurs fonctionnalités, par exemple un tableau général et une page Rapports. Le parent peut être un menu WordPress standard ou un menu déclaré par le plugin.

Comment cela fonctionne

Elle reçoit notamment le slug du parent, le titre, le libellé, la capacité et le slug de sous-page. Son callback doit vérifier les droits indépendamment du filtrage initial de visibilité.

Dans quel contexte l’utiliser

À utiliser lorsqu’un module dispose de plusieurs écrans logiquement regroupés sous un menu central déjà défini.

Exemple concret

Un espace ATOOLPHA comprend une page d’accueil et un écran supplémentaire « Rapports ».

Exemple de code commenté

<?php
add_action( 'admin_menu', function () {
    add_submenu_page(
        'atoolpha-centre', 'Rapports ATOOLPHA', 'Rapports',
        'manage_options', 'atoolpha-rapports',
        function () {
            if ( ! current_user_can( 'manage_options' ) ) {
                wp_die( 'Accès refusé.' );
            }
            echo '<div class="wrap"><h1>Rapports</h1></div>';
        }
    );
} );
// Prérequis : add_menu_page('...','...',...,'atoolpha-centre',...).

Explication pas à pas de l’exemple

Le slug du parent relie la sous-page au menu existant. La page Rapports apparaît dans sa navigation, et son callback affiche un titre. Le parent doit être créé dans le même chargement de l’administration.

Résultat attendu

Un utilisateur autorisé voit l’entrée Rapports sous Centre ATOOLPHA et peut accéder à son écran.

Précautions et limites

Ne pas réutiliser les slugs d’autres plugins. Définir les capacités par écran et contrôler également les actions de modification ou d’export exposées dans les sous-pages.