WordPress: Añadir un menú de administración

Habrás notado que existen multitud de temas o plugins que añaden páginas de opciones accesibles desde el menú de administración de tu sitio web de WordPress. Tú también puedes añadir fácilmente los apartados que desees gracias a las funciones que nos ofrece este CMS.

Si estás desarrollando un tema o un pequeño plugin, es probable que necesites dar al usuario la posibilidad de hacer algunas configuraciones en este. Para ello hay varias opciones. Se pueden incluir estas opciones en apartados de configuración ya existentes, agrupados en alguna página como la de ‘Ajustes > Generales’. Pero si deseas que estas opciones salten más a la vista, o si es una configuración más extensa, es probable que desees crear una página nueva para estas.

Nivel en el menú de administración

En primer lugar, debemos elegir el lugar donde queremos que se muestren nuestras opciones. Podemos añadir las opciones a una página ya existente, pero esto lo trataremos en otro artículo donde explicaremos cómo, ya que en este nos centraremos en añadir una nueva página. Por lo tanto, nos quedan dos opciones: crear una opción de menú de primer nivel, o añadirla como submenú.

Para esto disponemos principalmente de dos funciones que explicaremos a continuación. Estas son add_menu_pageadd_submenu_page.

Añadir menú de primer nivel

Podemos añadir un menú de primer nivel al menú de administración, como en la siguiente imagen:

Imagen de un menú de administración de primer nivel

Para conseguir esto, debemos utilizar la función add_menu_page(). Si consultamos la documentación oficial, podemos observar el listado de los parámetros que recibe, algunos obligatorios (*) y otros opcionales, y son los siguientes:

  • $page_title*: texto que aparecerá en la etiqueta <title> cuando visitemos la página.
  • $menu_title*: texto que aparecerá en el menú para este apartado.
  • $capability*: permiso que necesita el usuario para poder ver esta opción de menú.
  • $menu_slug*: nombre para poder hacer referencia a este menú de manera única.
  • $function: nombre de la función que mostrará el contenido de esta página de menú. Es opcional, pero obviamente debería existir si queremos que nuestra página muestre algo.
  • $icon_url: también opcional, permite establecer el icono que deseemos al menú. Se puede establecer después con CSS o mediante un SVG codificado, pero la opción más fácil es establecer uno de los que nos facilita el core de WordPress. Puedes ver cuáles en este enlace: WordPress Dashicons.
  • $position: este parámetro opcional establece la posición del menú. Anteriormente existía el problema de que si se establecía una posición ya ocupada, se sobrescribía un menú con otro. A partir de WordPress 4.4, no hay que preocuparse por esto. Para ver las posiciones de menú originales y saber dónde colocar el tuyo, visita este enlace: WordPress Menu Structure.

Ya conocidos todos los parámetros, podríamos utilizar la función del siguiente modo:

Ahora bien, no basta con añadir la llamada a la función en nuestro archivo functions.php o uno de los archivos de nuestro plugin, sino que debemos utilizar un hook de WordPress. Para esta situación, utilizaremos la acción admin_menu, que existe precisamente para este propósito y se ejecuta después de que se establezca el menú básico del panel de administración:

Fíjate en que antes de declarar la función register_toplevel_menu comprobamos que no exista ya. De este modo añadimos soporte para child themes, o prevenimos que provoque un error fatal si colisiona con otra función ya definida con el mismo nombre.

Con esto, nuestro menú ya aparece si cargamos el panel de WordPress, justo debajo de la opción ‘Medios’ debido a la posición que le hemos dado. Pero aún falta un detalle que hemos olvidado. Al registrar el menú, hemos indicado la función que mostrará el contenido de esta página, pero esta función no existe. Si accedemos a la página veremos que no se muestra nada, o en todo caso se muestra un error de PHP si lo permite la configuración de nuestro servidor.

Por lo tanto, debemos añadir la función que muestra el contenido. Para ello basta con añadir el siguiente código a nuestro archivo:

Añadir un submenú

Además de añadir un menú de primer nivel como en el ejemplo anterior, también podemos añadir un submenú dentro de un menú de administración ya existente. Podríamos elegir tanto uno definido por WordPress como uno creado por nosotros mismos.

Imagen de un sub menú de administración

La función que utilizaremos para este caso es similar a la anterior, aunque con algunas diferencias. La lista de parámetros es la siguiente:

  • $parent_slug*: identificador del menú ‘padre’ de esta página. Puede ser un identificador que hemos añadido a una página de menú creada anteriormente, o el nombre de uno de los archivos de páginas de administración de WordPress, como por ejemplo ‘options-general.php’.
  • $page_title*: texto a mostrar en la etiqueta <title> cuando estemos en la página.
  • $menu_title*: texto mostrado en el menú.
  • $capability*: permiso necesario del usuario para ver el menú.
  • $menu_slug*: identificador único para hacer referencia a este menú.
  • $function: función que muestra el contenido de la página.

De este modo, un ejemplo para invocar a la función sería el siguiente:

Pero al igual que hemos hecho antes, debemos incluir esto mediante una acción, y definir también la función que mostrará el contenido de la página. De este modo, poniendo todo junto nos quedaría el siguiente código:

Alias para añadir un submenú

A la hora de añadir un submenú, existen varios envoltorios de esta función. Estos sirven para añadir el submenú directamente bajo el apartado del menú de administración que deseemos.

Aunque podemos hacer lo mismo con la función descrita anteriormente, de esta manera nos ahorramos el primer parámetro, es decir, el menú ‘padre’, y añadimos un poco más de semántica a nuestro código.

Las funciones en concreto son:

Determina dónde mostrar tu menú

Es importante que determines bien el uso que tendrá tu página dentro del ecosistema de WordPress. En primer lugar, analiza si merece la pena dedicar una página completa a tus opciones, ya que si son pocas, es preferible agregarlas bajo otras opciones similares del núcleo de WordPress.

Y si vas a crear una página, piensa si es necesario que sea de nivel superior. Seguro que te has enfrentado a instalaciones de WordPress con un menú lleno de innumerables opciones y te has vuelto loco para dar con una página en concreto, así que intenta evitarle esto al usuario si no es necesario.

Enlaces