add_menu_page, add_submenu_page

El add_menu_page() és la funció fonamental de WordPress per afegir un nou element de menú de primer nivell (o menú pare) al panell d'administració. Aquesta funció connecta un títol, una icona i una funció de PHP amb un lloc concret del menú lateral.

Sintaxis add_menu_page()

La funció accepta set paràmetres, tots ells essencials per definir el nou menú:

add_menu_page( 
    $page_title, 
    $menu_title, 
    $capability, 
    $menu_slug, 
    $callback, 
    $icon_url, 
    $position 
);

$capability (Permisos)

Aquest paràmetre és de seguretat. Defineix qui pot veure el menú. Has d'especificar una de les capacitats de WordPress.

$menu_slug (Identificador únic)

Aquest slug es converteix en una part de l'URL de la vostra pàgina:

wp-admin/admin.php?page=**el-meu-plugin-config**

$callback (Funció de contingut)

Aquesta funció és el cor de la teva pàgina d'administració. Quan l'usuari clica al menú, WordPress executa aquesta funció i la sortida (l'HTML, el formulari, etc.) és el que es mostra a la pantalla.

$icon_url (Icona)

Hi ha tres opcions per definir la icona:

$position (Posició)

Aquest número controla on apareixerà l'element de menú a la barra lateral, permetent-te ordenar-lo respecte als menús natius de WordPress:

Si utilitzes un número ja ocupat, el teu menú es col·locarà just sota l'element natiu corresponent. Per exemple, usar 60 el posarà just a sota d'Apariència.

Exemple

Així és com utilitzaries l'acció admin_menu per registrar el teu menú:

function el_meu_plugin_registrar_menu() {
    add_menu_page(
        'Títol de la Pestanya',       // $page_title
        'El Meu Menú',                // $menu_title
        'manage_options',             // $capability (Només Administradors)
        'plugin-propi-slug',          // $menu_slug
        'la_meva_funcio_de_contingut', // $callback (Funció que mostrarà l'HTML)
        'dashicons-star-filled',      // $icon_url
        51                            // $position (Just sota 'Publicacions', que és 5)
    );
}
// Enganxar la funció a l'acció admin_menu
add_action( 'admin_menu', 'el_meu_plugin_registrar_menu' );

// La funció que genera l'HTML de la pàgina
function la_meva_funcio_de_contingut() {
    echo '<div class="wrap"><h1>Benvingut al meu Plugin!</h1></div>';
}

Sintaxis add_submenu_page()

El add_submenu_page() és la funció de WordPress que s'utilitza per crear un element de menú fill o submenú dins d'un menú de primer nivell ja existent al panell d'administració. Això és perfecte per organitzar les opcions del teu plugin, ja sigui sota un menú natiu de WordPress (com ara Eines o Configuració) o sota un menú pare que hagis creat tu mateix amb add_menu_page().

Aquesta funció requereix vuit paràmetres, amb l'addició crucial del slug del menú pare:

add_submenu_page( 
    $parent_slug, 
    $page_title, 
    $menu_title, 
    $capability, 
    $menu_slug, 
    $callback, 
    $position 
);

Exemple

Si el teu menú principal es diu bp-configuracio (creat amb add_menu_page), així és com li afegiries un submenú d'importació:

// Funció que s'executa amb el hook 'admin_menu'
function bp_afegir_submenus() {

    // 1. REGISTRAR UN SUBMENÚ SOTA UN MENÚ PROPI
    add_submenu_page(
        'bp-configuracio',          // $parent_slug: El menú pare que hem creat
        'Importar Configuració',    // $page_title
        'Importar / Exportar',      // $menu_title
        'manage_options',           // $capability
        'bp-importar-exportar',     // $menu_slug: Únic per a la nova pàgina
        'bp_pagina_importacio'      // $callback
    );

    // 2. REGISTRAR UN SUBMENÚ SOTA UN MENÚ NADIU DE WORDPRESS (EXEMPLE: EINES)
    add_submenu_page(
        'tools.php',                // $parent_slug: El slug del menú natiu Eines
        'Eina de Neteja del Banner',
        'Neteja Banner',
        'manage_options',
        'bp-eina-neteja',
        'bp_pagina_eina_neteja'
    );
}
add_action( 'admin_menu', 'bp_afegir_submenus' );

// Funció que mostra el contingut de la pàgina d'importació
function bp_pagina_importacio() {
    echo '<div class="wrap"><h1>Pàgina d\'Importació</h1><p>Aquí anirà el formulari d\'importació de dades.</p></div>';
}

Slugs dels menús natius:

Per adjuntar submenús a les seccions existents de WordPress, utilitza els seus slugs de fitxer (o URL):

Aquesta tècnica manté la interfície d'administració organitzada i evita sobrecarregar la barra lateral amb massa entrades de primer nivell.