La API de configuración de WordPress, Parte 3 Todo sobre los menús

En este punto, hemos aprendido por qué la configuración de la API es importante, hemos aprendido todo acerca de las secciones, los campos y la configuración, e incluso hemos configurado un tema de Sandbox que estamos utilizando para desarrollar la funcionalidad a medida que exploramos la API..

En este artículo, veremos cómo podemos interactuar con el sistema de menú de WordPress. Es importante tener en cuenta que esto no es en realidad una parte de la API de configuración, pero está tan estrechamente relacionado que debemos familiarizarnos con cómo usarlo..

A medida que nuestros temas y / o complementos se vuelven más complejos, necesitamos conocer todas las formas en que podemos incluirlos en el Panel de WordPress. En este artículo, vamos a echar un vistazo a las diversas funciones del menú de WordPress, cuándo usarlas, cuándo evitarlas y las situaciones a las que cada función se presta mejor..

Comprender los tipos de menú

WordPress proporciona cuatro formas diferentes de incluir nuestros propios menús. A continuación, veremos cada menú, los parámetros que cada uno acepta y ejemplos de código para usarlos en los proyectos. Nuestro objetivo es desarrollar una comprensión clara de cómo funciona la API, ya que puede sentar las bases de nuestro trabajo futuro..

Menús de nivel superior

Las páginas del menú se refieren a los elementos del menú que ve cuando inicia sesión por primera vez en WordPress. Es decir, son las opciones disponibles en el menú de la izquierda que pueden contener una lista de páginas del submenú.

Para introducir su propia página de menú en el Panel de WordPress, use la función add_menu_page.

Veremos un ejemplo práctico en un momento, pero primero revisemos la función: acepta siete argumentos (cinco requeridos, dos opcionales):

Título de la página se refiere al texto que aparece en la parte superior de la ventana del navegador cada vez que se muestra la página del menú de nivel superior.
Título del menú Es el texto que aparece en el menú actual. Es mejor mantener esto un poco corto, de lo contrario se ajustará al elemento del menú y se verá un poco fuera del resto de elementos del menú.
Capacidad Se refiere a qué usuarios tienen acceso al menú. Esto es simplemente un valor de cadena que representa uno de los roles disponibles.
Barra de menú es un identificador único que usted proporciona. Identifica este menú en el contexto de WordPress y también hace referencia a la página que muestra las opciones asociadas con este menú. También proporciona un gancho con el que los elementos del submenú pueden registrarse ellos mismos..
Llamar de vuelta es la función que define el contenido que se muestra en la página que corresponde a este menú. Esto puede ser HTML en línea o referirse a un archivo externo.
URL del icono es la ruta al icono que desea que aparezca junto al elemento del menú en el menú de WordPress. Puedes usar uno de los íconos existentes de WordPress o usar uno de los tuyos. Este argumento es opcional.
Posición define la posición en la que este menú residirá en la lista de elementos del menú de WordPress. De manera predeterminada, el menú aparece en la parte inferior del menú, pero una posición personalizada colocará su menú arriba (o debajo) de cualquiera de los elementos existentes del menú de WordPress..

Echemos un vistazo a un ejemplo. Localice functions.php en el entorno de pruebas de WordPress y agregue las siguientes dos funciones:

función sandbox_create_menu_page ()  add_action ('admin_menu', 'sandbox_create_menu_page'); función sandbox_menu_page_display ()

Tenga en cuenta que estamos utilizando el enlace admin_menu para registrar nuestro elemento de menú. Esta función en particular se activa justo después de que el menú de administración básica está en su lugar, por lo que desea registrar su menú aquí para que WordPress lo muestre mientras muestra el resto de los menús..

A continuación, vamos a configurar el elemento de menú básico. Para mantener la coherencia con los artículos anteriores de esta serie, esto es lo que planeamos hacer:

Agregar un nuevo menú a la parte inferior del menú de WordPress
Le daremos el nombre de nuestro tema (es decir, "Sandbox")
Estará disponible para todos los usuarios.
No incluirá un icono.

Bastante fácil, ¿verdad? Sigamos adelante y añadamos nuestro menú. Nuevamente, no simplemente copie y pegue este código. Léalo, anote los comentarios y asegúrese de que comprende perfectamente lo que estamos haciendo:

function sandbox_create_menu_page () add_menu_page ('Opciones de Sandbox', // El título que se mostrará en la página correspondiente de este menú 'Sandbox', // El texto que se mostrará para este elemento de menú real 'administrador', // Qué tipo Los usuarios pueden ver este menú 'sandbox', // La ID única, es decir, la barra, para este elemento de menú 'sandbox_menu_page_display', // El nombre de la función a la que llamar cuando se renderiza el menú para esta página "); // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page');

Ahora, actualice el menú de administración de WordPress y debería ver un nuevo elemento de menú. Al hacer clic en él, debería aparecer una página en blanco..

Obviamente, esto no es muy funcional. Apaguemos la función de devolución de llamada que definimos anteriormente para mostrar alguna cosa en la pantalla:

function sandbox_menu_page_display () // Crear un encabezado en el contenedor de "ajuste" de WordPress predeterminado $ html = ''; $ html. = 'Salvadera
'; $ html. = '
'; // Enviar el marcado al navegador echo $ html;  // finalizar sandbox_menu_page_display

La versión final de tu código debería verse así:

/ ** * Agrega un nuevo menú de nivel superior a la parte inferior del menú de administración de WordPress. * / function sandbox_create_menu_page () add_menu_page ('Opciones de Sandbox', // El título que se mostrará en la página correspondiente de este menú 'Sandbox', // El texto que se mostrará para este elemento de menú real 'administrador', // ¿Qué tipo de usuarios pueden ver este menú 'sandbox', // La ID única, es decir, el slug, para este elemento de menú 'sandbox_menu_page_display', // El nombre de la función a la que llamar cuando se renderiza el menú para esta página ") ; // finalizar sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_menu_page'); / ** * Representa la visualización básica de la página del menú para el tema. * / function sandbox_menu_page_display () // Crear un encabezado en el WordPress predeterminado » envolver 'container $ html =''; $ html. = 'Salvadera
'; $ html. = '
'; // Enviar el marcado al navegador echo $ html;  // finalizar sandbox_menu_page_display

Aparte de cómo usar realmente la función add_menu_page, quizás la eliminación más sutil es que, en WordPress, cada elemento del menú tiene una página de menú correspondiente. Vamos a ver esto más a fondo a lo largo de la serie, pero es importante tenerlo en cuenta ahora a medida que comenzamos a explorar cada uno de los distintos tipos de menús..

Aunque esto es en gran parte incompleto, lo añadiremos a lo largo del resto de este artículo y del resto del tutorial..

Una nota sobre el posicionamiento: Muchos desarrolladores consideran que usar el argumento de posición como mala etiqueta, ya que mezcla la experiencia de usuario predeterminada con WordPress. Además, si define una posición y otro tema, complemento o función utiliza la misma posición, se puede sobrescribir uno de los elementos del menú.

Submenús

Los submenús son como los menús, con la excepción de que pertenecen a otro menú: tienen un padre. Entonces, obviamente, no puede crear un submenú sin crear primero un elemento de menú. Por supuesto, como vimos en el artículo anterior, los elementos del submenú pueden introducirse en los elementos de menú existentes, no solo en los elementos de menú personalizados..

En este artículo, presentaremos una página de submenú en nuestro propio elemento de menú personalizado. Pero antes de hacer eso, echemos un vistazo a la función add_submenu_page y los parámetros que acepta:

Babosa de los padres se refiere a la ID del elemento del menú principal al que pertenecerá este submenú. En nuestro caso, utilizaremos la barra de menú que definimos anteriormente..
Título de la página es el texto que aparecerá en el título del navegador cuando la página sea renderizada.
Título del menú es el texto que aparecerá como el elemento del menú real en el menú de WordPress.
Capacidad, al igual que con el menú principal, se refiere a qué tipos de usuarios tienen acceso a este menú en particular.
Barra de menú es el identificador único para este elemento de menú. Es lo que se usa para definir este menú en particular dentro del contexto de WordPress.
Llamar de vuelta es la función que se utiliza para representar la página de este menú en la pantalla.

Si desea agregar un elemento de menú a uno de los menús existentes, consulte la tabla en el artículo anterior.

Comencemos registrando un submenú para el menú existente arriba. Queremos hacer lo siguiente:

Registre un submenú que se agregará al menú que acabamos de crear.
Se mostrará el texto 'Opciones'
Estará disponible para todos los usuarios.
No incluirá un icono.

Echa un vistazo al siguiente código: lo añadiremos directamente debajo de nuestra llamada a add_menu_page:

add_submenu_page ('sandbox', // Registre este submenú con el menú definido anteriormente 'Opciones de Sandbox', // El texto que se muestra en el navegador cuando este elemento de menú está activo 'Opciones', // El texto para este elemento de menú ' administrador ', // ¿Qué tipo de usuarios pueden ver este menú' sandbox_options ', // La ID única - el slug - para este elemento de menú' sandbox_options_display '// La función utilizada para mostrar el menú de esta página en la pantalla);

No olvide definir la devolución de llamada, incluso si está vacía. Es decir, no olvide agregar esta función a su archivo (agregaremos más momentáneamente):

función sandbox_options_display ()  // finalizar sandbox_options_display

Cuando actualice su navegador, debería ver ahora dos Submenú de elementos directamente debajo del menú "Caja de arena". Observe que WordPress crea un elemento de submenú por sí mismo; es un elemento de submenú que corresponde al elemento de menú y la función de devolución de llamada definida. La segunda es la nueva opción de submenú que acabamos de definir, aunque no presenta contenido.

Para arreglar eso, sigamos adelante e introduzcamos una página básica. Actualice la función de devolución de llamada del submenú para verse así:

function sandbox_options_display () // Crear un encabezado en el contenedor de "ajuste" de WordPress predeterminado $ html = ''; $ html. = 'Opciones de caja de arena
'; $ html. = '
'; // Enviar el marcado al navegador echo $ html;  // finalizar sandbox_options_display

Actualice su navegador una vez más y debería ver un título de página básico al seleccionar el nuevo Opciones elemento de submenú.

Aunque esto no es necesario, tenga en cuenta que en realidad puede tener el elemento del menú principal y el Opciones El elemento del menú se refiere al mismo contenido: simplemente actualice la devolución de llamada en la función ad_menu_page a la sandbox_options_display función que acabamos de definir.

Páginas de Complementos

Si está desarrollando un complemento de WordPress, existen diferentes formas en que su producto puede interactuar con la plataforma..

Específicamente, tu plugin ...

Puede trabajar en segundo plano y no requiere menú..
Puede usar ambas funciones o una de las mencionadas anteriormente para crear un menú personalizado
Puede incluirse en uno de los menús de WordPress existentes.

Para facilitar que los desarrolladores de complementos incluyan sus opciones en los menús existentes de WordPress, la API de WordPress ofrece la siguiente función: add_plugins_page.

Pero espera. Si has estado siguiendo los ejemplos anteriores, es probable que hayas notado que no parece haber una diferencia perceptible entre add_plugins_page y add_submenu_page. Tienes razón. add_plugins_page ofrece la misma funcionalidad que add_submenu_page, pero hay dos diferencias principales:

El complemento se proporciona específicamente para su uso en el desarrollo de complementos.
La función agrega la opción de menú de complementos directamente a WordPress ' Complementos menú.

Aunque ciertamente puedes usar add_submenu_page para lograr el mismo objetivo, siempre soy un fanático del uso de funciones destinadas a un caso de uso específico, incluso si hay otra función de API que haga lo mismo. Cuando haces esto, estás demostrando que estás usando la API como los desarrolladores pretenden y estás haciendo que tu código sea un poco más cohesivo a medida que tu base de código esté más alineada con la forma en que interactúa con la plataforma central..

El desarrollo de complementos está fuera del alcance de esta serie en particular, pero no es completamente irrelevante. Aunque no se realizarán modificaciones a nuestro tema de Sandbox, quiero proporcionar un ejemplo simple que muestre cómo usar esta función en particular.

Primero, revisemos los argumentos que acepta add_plugins_page:

Título de la página es el texto que aparecerá en el título del navegador cuando se represente la página de opciones del complemento.
Título del menú es el texto que aparecerá como elemento del menú del complemento en el menú de WordPress.
Capacidad al igual que con el menú principal, se refiere a qué tipos de usuarios tienen acceso a este menú en particular.
Barra de menú es el identificador único para este elemento de menú. Es lo que usó para definir este menú en particular dentro del contexto de WordPress.
Llamar de vuelta es la función que se utiliza para representar la página de este menú en la pantalla.

Aquí hay un ejemplo simple que demuestra exactamente cómo usarlo. Tenga en cuenta que puede incluir esto en su archivo functions.php pero es no parte del tema de Sandbox en el que estamos trabajando y se debe usar en el contexto de un complemento, en lugar de.

Primero, configure la llamada a la función API: observe que esto utiliza el enlace admin_menu:

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

A continuación, configure la función que representará la pantalla del complemento:

function sandbox_plugin_display () // Crear un encabezado en el contenedor de "ajuste" de WordPress predeterminado $ html = ''; $ html. = 'Opciones de Sandbox Plugin
'; $ html. = 'Actualmente no hay opciones. Esto es sólo para fines de demostración.
'; $ html. = '
'; // Enviar el marcado al navegador echo $ html;  // end sandbox_plugin_display

Actualice su Panel de WordPress, pase el cursor sobre el Complementos menú y usted debe notar un nuevo elemento de menú. No esta mal eh?

La versión final del código debería verse así:

/ ** * Esta función introduce una opción de menú de un solo tema en el menú 'Complementos' de WordPress. * / function sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // El título que se mostrará en la ventana del navegador para esta página. 'Sandbox Plugin', // El texto que se mostrará para este elemento de menú 'administrador', / / ¿Qué tipo de usuarios pueden ver este elemento de menú 'sandbox_plugin_options', // La ID única, es decir, la barra - para este elemento de menú 'sandbox_plugin_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_plugin_menu'); / ** * Representa una página simple para mostrar para el menú de tema definido anteriormente. * / function sandbox_plugin_display () // Crear un encabezado en el contenedor de "ajuste" de WordPress predeterminado $ html = ''; $ html. = 'Opciones de Sandbox Plugin
'; $ html. = 'Actualmente no hay opciones. Esto es sólo para fines de demostración.
'; $ html. = '
'; // Enviar el marcado al navegador echo $ html;  // end sandbox_plugin_display

De nuevo, esta función no será parte de nuestro tema de Sandbox porque está más orientada hacia el desarrollo de complementos; Sin embargo, vale la pena cubrir para aquellos de ustedes que aprovecharán la API de configuración en su esfuerzo de desarrollo de complementos..

Páginas temáticas

Al igual que con los complementos, WordPress proporciona una función de API para introducir menús específicamente para temas. Es muy similar a la función de menú del complemento, ya que proporciona otra manera de introducir un submenú a los menús existentes. La principal diferencia es que el submenú se agrega a la Apariencia menú.

Al igual que con el ejemplo del complemento anterior en este artículo, analizaremos cómo podemos usar esta función, pero no la incluiremos en nuestro tema de Sandbox. Esto tiene el único fin de demostrar cómo usar la función en caso de que decida ir por este camino en su trabajo personal..

Primero, revisaremos los argumentos que acepta add_theme_page. Notará que son como las que se requieren para el menú del complemento y muy similares a las funciones del submenú que describimos anteriormente:

add_theme_page acepta los siguientes argumentos:

Título de la página es el texto que aparecerá en el título del navegador cuando se represente la página de opciones del tema.
Título del menú es el texto que aparecerá como elemento del menú del tema en el menú de WordPress.
Capacidad al igual que con el menú principal, se refiere a qué tipos de usuarios tienen acceso a este menú en particular.
Barra de menú es el identificador único para este elemento de menú. Es lo que usó para definir este menú en particular dentro del contexto de WordPress.
Llamar de vuelta es la función que se utiliza para representar la página de este menú en la pantalla.

Al igual que con las otras funciones, crearemos un par de funciones de ejemplo que muestran cómo incluir esto en su proyecto. Tenga en cuenta que la llamada a add_theme_page se puede agregar a functions.php y, a diferencia de las llamadas a add_plugin_page, debería reside aquí cuando desarrolles tu tema.

Primero, la llamada para configurar el elemento del menú:

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, la barra - para este elemento de menú 'sandbox_theme_display' // El nombre de la función a la que llamar cuando se muestra la página para este menú);  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

A continuación, configuraremos una función para renderizar la página de opciones:

function sandbox_theme_display () // Crear un encabezado en el contenedor de "ajuste" de WordPress predeterminado $ html = ''; $ html. = 'Opciones de tema de sandbox
'; $ html. = 'Actualmente no hay opciones. Esto es sólo para fines de demostración.
'; $ html. = '
'; // Enviar el marcado al navegador echo $ html;  // finaliza sandbox_theme_display

Ahora actualice el Panel de WordPress, pase el cursor sobre la Apariencia menú y debería ver su nuevo elemento de menú. Sencillo!

La versión final del código debería verse así:

/ ** * Esta función introduce una opción de menú de un solo tema en el menú 'Aspecto' * de WordPress. * / 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', / / ¿Qué tipo de usuarios pueden ver este elemento de menú 'sandbox_theme_options', // La ID única, es decir, la barra - para este elemento de menú 'sandbox_theme_display' // El nombre de la función a la que llamar cuando se muestra la página para este menú) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu'); / ** * Representa una página simple para mostrar para el menú de tema definido anteriormente. * / function sandbox_theme_display () // Crear un encabezado en el contenedor de "ajuste" de WordPress predeterminado $ html = ''; $ html. = 'Opciones de tema de sandbox
'; $ html. = 'Actualmente no hay opciones. Esto es sólo para fines de demostración.
'; $ html. = '
'; // Enviar el marcado al navegador echo $ html;  // finaliza sandbox_theme_display

Para aquellos de ustedes que estén interesados en hacer un desarrollo más avanzado de temas, probablemente hayan considerado las diversas formas de implementar múltiples páginas de opciones para su tema..

Por un lado, podemos agregar varios submenús a un menú de nivel superior, pero hay es Una alternativa: la navegación por pestañas. Esto se presta bien cuando desea introducir opciones al Apariencia menú y no agregar otro elemento de menú al Panel de WordPress. Discutiremos esto en mayor profundidad en el próximo artículo..

Cuándo usar cada función

Hemos examinado cada una de las cuatro formas principales de introducir nuestras propias páginas de opciones en WordPress. Aunque estas funciones no son específicamente parte de la API de configuración, es importante discutirlas porque trabajan en estrecha colaboración con ellas..

Pero conocer estas funciones es solo la mitad. Como desarrollador responsable de la integración y la organización de las configuraciones, es importante saber cuándo usar cada una de las diversas funciones en su contexto adecuado..

Aunque no hay una respuesta mágica para cuándo usar cada función, aquí hay algunas pautas a tener en cuenta al trabajar en sus funciones personalizadas, complementos y / o tema:

Menús de nivel superior se puede agregar cuando hay un submenú que puede agruparse lógicamente con estas opciones. Esto se presta para cuando tiene una importante colección de configuraciones que no se ajustan de forma lógica en ninguno de los menús de WordPress existentes.
Submenús pertenezca siempre a un menú de nivel superior, ya sea personalizado o preexistente. Siempre deben agruparse en el menú de nivel superior que sea más lógico. Si WordPress ofrece un menú que puede servir como padre para su submenú, entonces utilícelo; no contamine el menú con un menú redundante de nivel superior.
Menús de Plugin debe usarse cuando tenga opciones simples de una página para su complemento. Si tiene varias páginas de opciones, considere crear un menú de nivel superior o considere usar la navegación con pestañas que exploraremos en el próximo artículo.
Menús Temáticos debe usarse cuando está desarrollando su propio tema que ofrece su propio conjunto de opciones personalizadas. Si las opciones pueden vivir en una sola página, considere usar la función API de WordPress. Si tiene más opciones, considere usar la navegación con pestañas. Tenga en cuenta que muchos desarrolladores de temas a menudo elevan sus opciones de tema al menú de nivel superior y eso también está bien.

Una palabra sobre menús personalizados: Aunque WordPress nos brinda la posibilidad de agregar nuestros propios menús de nivel superior, agregarlos a cualquier menú existente, y en general nos brinda la capacidad de hacer lo que queremos con la configuración predeterminada, una parte de la comunidad no ve con buenos ojos esto. Creen que la funcionalidad personalizada no debe interferir con ciertos menús principales. Aunque en última instancia depende de usted, implemente su trabajo con discernimiento; es probable que pocas cosas que haga sean más importantes que la funcionalidad principal de WordPress, así que no coloque su trabajo por encima de eso..

¿Qué pasa después??

En el siguiente artículo, aplicaremos un poco de lo que hemos aprendido sobre los menús y comenzaremos a introducir páginas de opciones para nuestro tema de Sandbox..

Además de agregar páginas de menú, también analizaremos la navegación con pestañas y cómo podemos implementarla para que funcione junto con nuestras propias páginas de menú..

Mientras tanto, revisa los artículos anteriores de esta serie y no olvides revisar la versión actual de la Configuración de WordPress en GitHub..

Recursos Relacionados

Cubrimos bastantes recursos en este artículo. Aquí hay un resumen de todo lo que usamos:

add_menu_page
add_submenu_page
add_plugins_page
add_theme_page
Configuración de WordPress Sandbox

Código