La API de configuración de WordPress, Parte 6 Páginas de menú

En la Parte 3 de esta serie, examinamos las diversas funciones del menú que proporciona la API de WordPress. Si ha estado siguiendo esto, entonces sabe que ya hemos configurado una página de configuración para nuestro tema usando el add_theme_page función. Aunque la introducción de menús y submenús no son parte explícita de la API de configuración, desempeñan un papel en la creación de funcionalidades, complementos y / o temas personalizados..

En este artículo, vamos a presentar un nuevo menú al panel de WordPress que hará que nuestras opciones de tema estén disponibles en cualquier otro lugar que no sea solo bajo las opciones de "Apariencia"..

Antes de empezar: En este artículo se supone que estás familiarizado con la API de configuración y las opciones de tema. Si eres un desarrollador de WordPress principiante o incluso intermedio, te recomiendo que te pongas al día con el resto de la serie antes de sumergirte en esta publicación..

Una mirada a la API

Debido a que ya hemos examinado cada una de las funciones del menú, no necesitamos volver a usar cada una de las funciones que WordPress tiene disponibles. En su lugar, analizaremos los que vamos a utilizar y luego analizaremos un ejemplo práctico de cómo usarlos en nuestro propio trabajo..

Antes de ver cada función, detallamos lo que planeamos lograr en la siguiente fase de esta serie:

Introduzca un menú de nivel superior para nuestras opciones de tema
Agregue un elemento de submenú que se vinculará a la pestaña "Opciones de visualización"
Agregue un elemento de submenú que se vinculará a la pestaña "Opciones sociales"

Relativamente simple, ¿verdad? Para hacer esto, aprovecharemos las siguientes dos funciones:

add_menu_page que se utiliza para introducir elementos de menú de nivel superior
add_submenu_page que se utiliza para introducir elementos de submenú a los menús de nivel superior.

Vamos a echar un vistazo a los parámetros y el uso de cada función a medida que los implementamos en nuestro tema.

Tenga en cuenta que el resto de este artículo se basa en esta versión del entorno de pruebas de WordPress. Si está siguiendo junto con el repositorio, asegúrese de verificarlo.

El menú de nivel superior

Lo primero que queremos hacer es introducir un menú de nivel superior. Este menú aparecerá directamente debajo del menú "Configuración" en el panel de WordPress y tendrá dos propósitos. El menú debe:

Exponer las opciones del tema al panel de WordPress
Mostrar una página de opciones predeterminadas para las opciones de tema

La función toma los siguientes siete argumentos, los primeros cinco son necesarios, los últimos dos no son:

Título de la página Es el texto que se representará en la barra de título del navegador.
menu_title es el texto que se mostrará para el elemento de menú
capacidad se refiere al rol que debe tener el usuario para acceder a este menú
menu_slug Es un valor único que identifica este menú. También es como los submenús se registran con este menú..
nombre de la función que se llama cuando se hace clic en el menú para mostrar la página de opciones.
icon_url es la ruta al icono que desea mostrar junto a su elemento de menú.
posición es donde se debe agregar el menú en relación con los otros menús en el Panel de WordPress.

En nuestro trabajo, nos centraremos solo en los primeros cinco parámetros. Discuto el posicionamiento del menú en la conclusión de este artículo..

Para empezar, vamos a necesitar introducir una llamada al add_menu_page función. De acuerdo con el Códice de WordPress, los menús de administración se pueden agregar usando el admin_menu gancho. Anteriormente en esta serie, escribimos una función que agrega nuestras opciones de tema al menú "Apariencia". Específicamente, escribimos sandbox_example_theme_menu:

function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // El título que se mostrará en la ventana del navegador para esta página. 'Sandbox Theme', // El texto que se mostrará para este elemento de menú 'administrador', // cual el tipo de usuarios puede ver este elemento de menú 'sandbox_theme_options', // La ID única, es decir, el slug, para este elemento de menú 'sandbox_theme_display' // El nombre de la función a la que llamar cuando se muestra la página de este menú);  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Note en el código de arriba que esta función fue registrada con el admin_menu gancho, también. Siempre debe esforzarse por mantener sus funciones lógicamente consistentes. Dado que ya tenemos una función que registra un menú, que está registrada con el enlace apropiado, y como estamos introduciendo una funcionalidad similar, agregaremos nuestras nuevas funciones de menú a esta función.

Agrega la siguiente llamada a add_menu_page directamente debajo de la llamada anterior:

add_menu_page ('Sandbox Theme', // El valor utilizado para rellenar la barra de título del navegador cuando la página del menú está activa 'Sandbox Theme', // El texto del menú en la barra lateral del administrador 'administrador', // ¿Qué roles son posibles? para acceder al menú 'sandbox_theme_menu', // La ID utilizada para vincular los elementos del submenú a este menú 'sandbox_theme_display' // La función de devolución de llamada utilizada para representar este menú);

Como puede ver, estamos registrando un menú que mostrará "Sandbox Theme" en la barra de título del navegador y en el elemento del menú. Estamos exponiendo el menú solo a los administradores y le hemos dado al menú el ID único de "sandbox_theme_parent_menu". Volveremos a utilizar este parámetro en la siguiente sección..

Hay una cosa importante que debemos aclarar: note que hemos pasado 'sandbox_theme_display'como la función a llamar cuando se hace clic en este elemento del menú. Recuerde que en la Parte 3 introdujimos esta función (y la refinamos en la Parte 5). Específicamente, es responsable de representar nuestra página de opciones de tema con pestañas.

Al pasar este nombre de función existente a la add_menu_page Estamos aprovechando el código que ya hemos escrito y estamos mostrando una página de opciones predeterminadas para el elemento del menú..

En este punto, estamos listos para comenzar a agregar submenús, pero antes de seguir adelante, asegúrese de que su función se vea exactamente como esta:

function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', 'Sandbox Theme', 'administrador', 'sandbox_theme_options', 'sandbox_theme_display'); add_menu_page ('Sandbox Theme', 'Sandbox Theme', 'administrador', 'sandbox_theme_menu', 'sandbox_theme_display');  // end sandbox_example_theme_menu

Añadir los submenús

Los submenús son muy similares a los menús, excepto que "pertenecen" a un menú existente. La API para registrar submenús también es relativamente similar. La función acepta seis argumentos, los primeros cinco son requeridos, el último es opcional:

parent_slug se refiere a la ID única del elemento del menú principal. En nuestro caso, "sandbox_theme_menu".
Título de la página es el texto que se representará en la barra de herramientas del navegador cuando este elemento del submenú esté activo
menu_title es el texto para este elemento del submenú real en el panel de control
capacidad es el rol que un usuario debe tener para acceder a este elemento del menú
menu_slug es la ID única para este elemento de menú en particular
nombre de la función que se llama cuando se hace clic en el menú para mostrar la página de opciones

La función es sencilla. Tenemos dos elementos de menú para presentar: uno para "Opciones de visualización" y otro para "Opciones sociales".

Opciones de pantalla

Primero, introduzcamos un elemento del submenú para las opciones de visualización. Agregue el siguiente bloque de código directamente debajo de add_menu_page Llamada que hemos definido anteriormente:

add_submenu_page ('sandbox_theme_menu', // El ID de la página del menú de nivel superior al que pertenece este elemento del submenú 'Opciones de visualización', // El valor utilizado para completar la barra de título del navegador cuando la página del menú está activa 'Opciones de visualización', // La etiqueta de este elemento del submenú se muestra en el menú 'administrador', // ¿Qué roles pueden acceder a este elemento del submenú 'sandbox_theme_display_options', // La ID utilizada para representar este elemento del submenú 'sandbox_theme_display' // La función de devolución de llamada utilizada para representar las opciones para este elemento del submenú);

Cada uno de los parámetros anteriores debe ser claro, con la excepción del nombre de la función que pasamos como argumento final. Observe que es el mismo nombre de función que proporcionamos en el add_menu_page llamada. Pero esto tiene sentido, ¿verdad? Después de todo, las "Opciones de pantalla" son la pestaña predeterminada que se muestra cuando se seleccionan las opciones del tema, por lo que tendría sentido que se representara cuando se selecciona el menú de nivel superior y cuando se selecciona el elemento de menú "Opciones de pantalla".

En este punto, hay una característica importante de WordPress para resaltar: tenga en cuenta que una vez que haya agregado su primer elemento de submenú, WordPress realmente representará dos elementos de submenú al menú de nivel superior: un elemento que duplica la función del nivel superior menú y un elemento que corresponde al elemento del submenú que acaba de definir. Menciono esto porque, en mi experiencia, he visto a los desarrolladores confundirse en cuanto a cómo (y por qué) sucede esto. En resumen, WordPress está haciendo esto, no hay nada de malo en tu código..

Opciones sociales

Agregar un elemento de menú para las opciones sociales es casi exactamente como agregar un elemento de menú para las opciones de visualización. Por supuesto, solo queremos cambiar los valores de la barra de título, el elemento del menú y la página que se muestra cada vez que se selecciona el menú. En primer lugar, vamos a configurar nuestra llamada a la add_submenu_page función. Debe tener un aspecto como este:

add_submenu_page ('sandbox_theme', 'Opciones sociales', 'Opciones sociales', 'administrador', 'sandbox_theme_social_options', 'sandbox_theme_display');

Guarde su código, actualice su panel de control y verá el elemento de menú "Opciones sociales" ahora disponible en el menú "Tema de Sandbox"; sin embargo, observe que al hacer clic en el nuevo elemento del submenú solo se muestran las "Opciones de pantalla". Desde que hemos pasado el "sandbox_theme_display"como el nombre de la función, eso es lo que deberíamos esperar, ¿no? Así que ahora nos enfrentamos a un pequeño desafío: ¿Cómo seleccionamos la pestaña" Opciones sociales "al hacer clic en el elemento del submenú??

Refactorizando la funcionalidad de nuestra pestaña

Hay un par de opciones diferentes que tenemos para vincular el nuevo elemento del submenú a la pestaña adecuada en la página de opciones del tema:

Podemos definir una nueva función que represente las opciones sociales. Esto requeriría que realicemos algún trabajo adicional para introducir una nueva función, configurar la funcionalidad de tabulación para que no rompamos la experiencia de la página existente y duplicar un poco de código.
Podemos refactorizar lo existente. sandbox_theme_display función para aceptar un parámetro opcional y luego usar una función anónima en el add_submenu_page llamar para pasarle un parámetro.

En última instancia, cualquiera de estas opciones depende de usted; sin embargo, prefiero refactorizar mi función existente a duplicar el código, así que eso es lo que haré durante el resto de este artículo.

Primero, comencemos refactorizando nuestra sandbox_theme_display función. Hagamos que acepte un argumento opcional que se utilizará para indicar qué pestaña queremos seleccionar. Localiza la siguiente firma en tu funciones.php expediente:

function sandbox_theme_display () / * Consolidado para esta parte del artículo. * / // finaliza sandbox_theme_display

Actualice la firma para que acepte un solo argumento y la establezca en nula cuando no esté definida:

function sandbox_theme_display ($ active_tab = null) / * Consolidado para esta parte del artículo. * / // finaliza sandbox_theme_display

Si es nuevo en PHP, puede leer sobre los argumentos predeterminados en esta página.

Recuerde del artículo anterior que nuestra función de visualización realmente está buscando un valor de cadena de consulta para establecer. Todavía queremos mantener esa funcionalidad, pero debemos tener en cuenta el hecho de que el parámetro también se puede pasar a la función. Para realizar esta refactorización, primero ubique la siguiente línea de código en el sandbox_theme_display función:

$ active_tab = isset ($ _GET ['tab'])? $ _GET ['tab']: 'display_options';

Tenga en cuenta que esta línea de código en particular solo está relacionada con los parámetros de la cadena de consulta. Para tener en cuenta el nuevo parámetro opcional, debemos introducir una lógica que primero verifique si el parámetro de la cadena de consulta está activado, si no, verificará si el argumento de la función está configurado para mostrar las opciones sociales y, si no, entonces se predeterminará a las opciones de visualización. Reemplace la línea de código anterior con el siguiente condicional:

if (isset ($ _GET ['tab'])) $ active_tab = $ _GET ['tab'];  else if ($ active_tab == 'social_options') $ active_tab = 'social_options';  else $ active_tab = 'display_options';  // termina si / else

La versión final de la función debería verse así:

function sandbox_theme_display ($ active_tab = ") ?>

Opciones de tema de sandbox

"> Opciones de visualización"> Opciones sociales

Todavía no hemos terminado. Aunque hemos realizado el trabajo necesario para mostrar las opciones sociales si se ha pasado el parámetro adecuado, no hemos llamado a la función usando un parámetro. Para hacer esto, necesitamos refactorizar el add_submenu_page Funcionar desde arriba. Actualmente, la llamada a la función se ve así:

add_submenu_page ('sandbox_theme', 'Opciones sociales', 'Opciones sociales', 'administrador', 'sandbox_theme_social_options', 'sandbox_theme_display');

Necesitamos actualizar el parámetro final para que llame a la función de visualización y pase el valor adecuado para representar las opciones sociales. Para ello, crearemos una función anónima:

add_submenu_page ('sandbox_theme_menu', 'Opciones sociales', 'Opciones sociales', 'administrador', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("social_options");'));

Si eres nuevo en PHP, asegúrate de leer en el create_function Característica y funciones anónimas. Aunque están fuera del alcance de este artículo, pueden ser poderosos (y útiles) cuando se usan en el contexto adecuado..

La versión final de la sandbox_example_theme_menu La función debe ser la siguiente:

function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // El título que se mostrará en la ventana del navegador para esta página. 'Sandbox Theme', // El texto que se mostrará para este elemento de menú 'administrador', // cual el tipo de usuarios puede ver este elemento de menú 'sandbox_theme_options', // La ID única, es decir, el slug, para este elemento de menú 'sandbox_theme_display' // El nombre de la función a la que llamar cuando se muestra la página de este menú); add_menu_page ('Sandbox Theme', // El valor utilizado para rellenar la barra de título del navegador cuando la página del menú está activa 'Sandbox Theme', // El texto del menú en la barra lateral del administrador 'administrador', // ¿Qué roles son posibles? para acceder al menú 'sandbox_theme_menu', // La ID utilizada para vincular los elementos del submenú a este menú 'sandbox_theme_display' // La función de devolución de llamada utilizada para representar este menú); add_submenu_page ('sandbox_theme_menu', // El ID de la página del menú de nivel superior al que pertenece este elemento del submenú 'Opciones de visualización', // El valor utilizado para completar la barra de título del navegador cuando la página del menú está activa 'Opciones de visualización', // La etiqueta de este elemento del submenú se muestra en el menú 'administrador', // ¿Qué roles pueden acceder a este elemento del submenú 'sandbox_theme_display_options', // La ID utilizada para representar este elemento del submenú 'sandbox_theme_display' // La función de devolución de llamada utilizada para representar las opciones para este elemento del submenú); add_submenu_page ('sandbox_theme_menu', 'Opciones sociales', 'Opciones sociales', 'administrador', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("social_options");'));  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Conclusión

En este punto, nuestro tema ahora tiene su propio elemento de menú de nivel superior con cada una de las pestañas de configuración accesibles a través de los elementos del submenú. Aunque esto es útil, creo que es importante tener en cuenta que hay algunas opiniones mixtas sobre la introducción de menús en el Panel de WordPress. Aunque pueden hacer que su trabajo sea más prominente y accesible, también pueden interferir con los menús existentes de WordPress u otros trabajos de terceros. especialmente Si intenta colocar sus menús en algún lugar utilizando el parámetro de posición. Aunque no hay ningún derecho absoluto o absoluto cuando se trata de introducir menús, piense detenidamente dónde expone sus menús. Si un menú de WordPress existente tiene sentido, registre su trabajo como un submenú.

En la próxima publicación, comenzaremos a ver los diversos elementos de entrada que podemos usar para introducir opciones en nuestro tema de WordPress, así como también cómo validar y sanear los datos antes de serializarlos..

Fuentes relacionadas

add_menu_page
add_submenu_page
create_function
funciones anonimas
Configuración de WordPress Sandbox 0.5

Código