Menús de administración
Es bastante corriente que nuestros plugins necesiten algún tipo de configuración global, más allá de la información que podemos manipular por medio de post types y meta boxes. Para estos casos, generalmente necesitamos crear alguna pantalla de administración propia de nuestro plugin, donde el usuario pueda configurar las opciones que definan su funcionamiento.
Con este fin es que WordPress nos ofrece tres tipos de herramientas: menús de administración, Options API y Settings API. Cada una consiste en un conjunto de funciones que nos permiten definir cómo se van a manejar las configuraciones internas de nuestro plugin. En este capítulo vamos a ver la primera, los menús de administración.
Los menús de administración son esas secciones que vemos en la barra lateral de navegación en nuestro panel de administración. Cada uno de ellos tiene un link principal, y además pueden tener un segundo nivel de links, que vemos cuando estamos navegando un menú o cuando pasamos el mouse por encima del link principal. Estos links secundarios son lo que llamamos sub-menús.
Por último tenemos las páginas de opciones, que son aquellos links que vemos ubicados debajo del menú Settings (o Configuración).
Agregar un menú
Para agregar un menú usamos la función add_menu_page(), y la asignamos como acción al evento admin_menu. Con este ejemplo de código podemos crear un menú y asociarle una interfaz muy básica.
<?php
add_action( 'admin_menu', 'portfolio_menu_page' );
function portfolio_add_menu_page() {
add_menu_page(
__( 'Portfolio Settings', 'portfolio' ), // Texto del título que aparece en la página de opciones.
__( 'Portfolio', 'portfolio' ), // Texto que aparece en el link principal del menú.
'manage_options', // Permiso que debe tener el usuario para ver el menú.
'portfolio-settings', // Slug, string que permite identificar internamente el menú.
'portfolio_menu_page', // Nombre de la función que imprime el HTML de la página de opciones.
'dashicons-art', // Icono del menú. Podemos usar Dashicons o una URL.
10 // Posición en la que aparece el menú en la barra de navegación.
);
}
function portfolio_menu_page(){
_e( 'Set Portfolio options here.', 'portfolio' );
}
Cuando guardemos nuestro código y actualicemos el navegador, vamos a ver que contamos con un nuevo menú de administración. Haciendo click en el link del menú, vamos a ver el texto que imprimimos dentro de nuestra función callback.
Agregar una página de opciones
También podemos, en lugar de crear un nuevo menú para nuestra página de opciones, ubicar un link debajo de Settings. Esto es lo que hacen muchos desarrolladores de plugins para que la barra de navegación no se vea tan larga.
El procedimiento es muy similar a agregar un menú, pero usando la función add_options_page(). Simplemente reemplazamos el código anterior por este:
<?php
add_action( 'admin_menu', 'portfolio_menu_page', 999 );
function portfolio_add_menu_page() {
add_options_page(
__( 'Portfolio Settings', 'portfolio' ), // Texto del título que aparece en la página de opciones.
__( 'Portfolio', 'portfolio' ), // Texto que aparece en el link principal del menú.
'manage_options', // Permiso que debe tener el usuario para ver el menú.
'portfolio-settings', // Slug, string que permite identificar internamente el menú.
'portfolio_menu_page' // Nombre de la función que imprime el HTML de la página de opciones.
);
}
function portfolio_menu_page(){
_e( 'Set Portfolio options here.', 'portfolio' );
}
Cuando actualicemos el navegador después de guardar, la ubicación de nuestro link va a haber cambiado, pero vamos a seguir viendo la misma página. Algo que no podemos definir desde add_options_page() es un ícono, ya que los sub-menús y links de páginas de opciones no tienen ninguno. Tampoco se puede definir, desde add_options_page(), la posición en la que va a aparecer el link, aunque para esto podemos modificar las prioridades de add_action() hasta que el link se vea donde pretendemos. En el ejemplo hay una prioridad alta (999) para que aparezca lo más cerca posible del final de la lista.
Agregar un sub-menú
Una tercera alternativa, más ordenada, es ubicar el link a nuestra página de opciones dentro del menú que se creó automáticamente para nuestro post type. Como ya vimos al agregar un menú principal, todo menú cuenta con un slug o palabra clave para que pueda ser reconocido internamente, y para agregar un sub-menú necesitamos conocer el slug del menú principal.
En el caso de los post types, el nombre del slug es un poco más rebuscado que el de los que venimos definiendo, pero es fácilmente reconocible: edit.php?post_type={nombre_del_post_type}. En nuestro caso, como nuestro post type se llama project, el slug del menú va a ser edit.php?post_type=project. Teniendo esto en cuenta, la forma de registrar un sub-menú es prácticamente igual al ejemplo anterior, pero usando la función add_submenu_page().
<?php
add_action( 'admin_menu', 'portfolio_menu_page', 999 );
function portfolio_add_menu_page() {
add_submenu_page(
'edit.php?post_type=project', // Slug del menú principal.
__( 'Portfolio Settings', 'portfolio' ), // Texto del título que aparece en la página de opciones.
__( 'Portfolio Settings', 'portfolio' ), // Texto que aparece en el link principal del menú.
'manage_options', // Permiso que debe tener el usuario para ver el menú.
'portfolio-settings', // Slug, string que permite identificar internamente el menú.
'portfolio_menu_page' // Nombre de la función que imprime el HTML de la página de opciones.
);
}
function portfolio_menu_page(){
_e( 'Set Portfolio options here.', 'portfolio' );
}
Al refrescar el browser puede verse que el link cambió nuevamente de ubicación, y ahora está en el último lugar del menú de Projects.
Algo importante a tener en cuenta es que, si estamos mirando la página de administración que acabamos de crear, al cambiar el link de lugar y actualizar el navegador, WordPress puede mostrar un error. Esto no es porque hayamos hecho algo mal, sino porque al cambiar la ubicación del link también puede cambiar la URL que se le asigna, pero con volver a la página principal del panel de administración vamos a poder ver el link en su nueva ubicación, y acceder a él desde su nueva URL sin problemas.