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

En la Parte 3 de esta serie, examinamos las diversas funciones de menú que ofrece la API de WordPress. Si has estado siguiendo, entonces sabes que ya hemos configurado una página de configuración para nuestro tema utilizando la función add_theme_page. Aunque la introducción de menús y submenús no forma parte explícitamente de la API de configuración, desempeñan un papel en la creación de funcionalidades, plugins y/o temas personalizados.

En este artículo, vamos a introducir un nuevo menú en el panel de control de WordPress que hará que las opciones de nuestro tema estén disponibles en otros lugares además de las opciones de "Apariencia".

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

Un vistazo a la API

Como ya hemos visto cada una de las funciones del menú, no necesitamos repetir cada una de las funciones que WordPress tiene disponibles. En su lugar, echaremos un vistazo a los que vamos a utilizar y luego trabajaremos con un ejemplo práctico de cómo utilizarlos en nuestro propio trabajo.

Antes de ver cada función, vamos a detallar lo que tenemos previsto realizar en la siguiente fase de esta serie:

• Introducir un menú de nivel superior para las opciones de nuestro tema
• Añadir un elemento de submenú que enlazará con la pestaña "Opciones de visualización".
• Añadir un elemento de submenú que enlazará con la pestaña "Opciones sociales".

Relativamente sencillo, ¿verdad? Para ello, aprovecharemos las dos funciones siguientes:

• 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ú en los menús de nivel superior.

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

Observa que el resto de este artículo se basa en esta versión de WordPress Settings Sandbox. Si estás siguiendo el repositorio, asegúrate de comprobarlo.

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 control de WordPress y servirá para dos propósitos. El menú debería:

1. Exponer las opciones del tema al panel de control de WordPress
2. Mostrar una página de opciones por defecto para las opciones del tema

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

1. page_title es el texto que se mostrará en la barra de título del navegador
2. menu_title es el texto que se mostrará para el elemento del menú
3. capability se refiere al rol que el usuario debe tener para acceder a este menú
4. menu_slug es un valor único que identifica este menú. También es la forma en que los submenús se registran en este menú.
5. function_name que se llama cuando se hace clic en el menú para mostrar la página de opciones.
6. icon_url es la ruta del icono que desea mostrar junto a su elemento de menú.
7. position es donde el menú debe ser añadido en relación con los otros menús en el escritorio de WordPress.

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

Para empezar, vamos a necesitar introducir una llamada a la función add_menu_page. Según el Codex de WordPress, los menús de administración pueden añadirse utilizando el gancho admin_menu. Anteriormente en esta serie, escribimos una función que añade nuestras opciones de tema al menú "Apariencia". En concreto, escribimos sandbox_example_theme_menu:

1

function sandbox_example_theme_menu() {

2

3

	add_theme_page(

4

		'Sandbox Theme', 			// The title to be displayed in the browser window for this page.

5

		'Sandbox Theme',			// The text to be displayed for this menu item

6

		'administrator',			// Which type of users can see this menu item

7

		'sandbox_theme_options',	// The unique ID - that is, the slug - for this menu item

8

		'sandbox_theme_display'		// The name of the function to call when rendering this menu's page

9

	);

10

11

} // end sandbox_example_theme_menu

12

add_action( 'admin_menu', 'sandbox_example_theme_menu' );

Observa en el código anterior que esta función se registró también con el gancho admin_menu. Siempre debes esforzarte por mantener la coherencia lógica de tus funciones. Como ya tenemos una función que registra un menú, que se registra con el gancho apropiado, y como estamos introduciendo una funcionalidad similar, vamos a añadir nuestras nuevas funciones de menú a esta función.

Añade la siguiente llamada a add_menu_page directamente debajo de la llamada anterior:

1

add_menu_page(

2

	'Sandbox Theme',		// The value used to populate the browser's title bar when the menu page is active

3

	'Sandbox Theme',		// The text of the menu in the administrator's sidebar

4

	'administrator',		// What roles are able to access the menu

5

	'sandbox_theme_menu',	// The ID used to bind submenu items to this menu 

6

	'sandbox_theme_display'	// The callback function used to render this menu

7

);

Como puedes ver, estamos registrando un menú que mostrará "Sandbox Theme" tanto en la barra de título del navegador como en el elemento del menú. Estamos exponiendo el menú solo a los administradores y le hemos dado 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: Observa que hemos pasado 'sandbox_theme_display' como la función que se llamará cuando se haga clic en este elemento del menú. Recordemos que en la Parte 3 introdujimos esta función (y la refinamos en la Parte 5). Específicamente, es responsable de renderizar nuestra página de opciones de tema con pestañas.

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

En este punto, estamos listos para empezar a añadir submenús, pero antes de seguir adelante, asegúrate de que tu función se vea exactamente así:

1

function sandbox_example_theme_menu() {

2

3

	add_theme_page(

4

		'Sandbox Theme',

5

		'Sandbox Theme',

6

		'administrator',

7

		'sandbox_theme_options',

8

		'sandbox_theme_display'

9

	);

10

11

	add_menu_page(

12

		'Sandbox Theme',

13

		'Sandbox Theme',

14

		'administrator',

15

		'sandbox_theme_menu',

16

		'sandbox_theme_display'

17

	);

18

19

} // end sandbox_example_theme_menu

Añadir los submenús

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

1. parent_slug se refiere al ID único del elemento de menú padre. En nuestro caso, "sandbox_theme_menu".
2. page_title es el texto que se mostrará en la barra de herramientas del navegador cuando este elemento del submenú esté activo
3. menu_title es el texto de este elemento del submenú en el panel de control
4. capability es el rol que debe tener un usuario para acceder a este elemento del menú
5. menu_slug es el ID único de este elemento de menú en particular
6. function_name que se llama cuando se hace clic en el menú para mostrar la página de opciones

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

Opciones de visualización

En primer lugar, vamos a introducir un elemento de submenú para las opciones de visualización. Añade el siguiente bloque de código directamente debajo de la llamada add_menu_page que hemos definido anteriormente:

1

add_submenu_page(

2

	'sandbox_theme_menu',				// The ID of the top-level menu page to which this submenu item belongs

3

	'Display Options',					// The value used to populate the browser's title bar when the menu page is active

4

	'Display Options',					// The label of this submenu item displayed in the menu

5

	'administrator',					// What roles are able to access this submenu item

6

	'sandbox_theme_display_options',	// The ID used to represent this submenu item

7

	'sandbox_theme_display'				// The callback function used to render the options for this submenu item

8

);

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

En este punto, hay una característica importante de WordPress a destacar: Ten en cuenta que una vez que hayas añadido tu primer elemento de submenú, WordPress mostrará dos elementos de submenú en el menú de nivel superior: un elemento que duplica la función del menú de nivel superior y un elemento que corresponde al elemento de submenú que acabas de definir. Traigo esto a colación porque, en mi experiencia, he visto que los desarrolladores se confunden en cuanto a cómo (y por qué) sucede esto. El resumen es que WordPress está haciendo esto, no hay nada malo en tu código.

Opciones Sociales

Añadir un elemento de menú para las opciones sociales es casi exactamente igual que añadir 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 de menú y la página que se muestra cuando se selecciona el menú. Primero, vamos a configurar nuestra llamada a la función add_submenu_page. Debería verse así: Debería verse como esto:

1

add_submenu_page(

2

	'sandbox_theme',

3

	'Social Options',

4

	'Social Options',

5

	'administrator',

6

	'sandbox_theme_social_options',

7

	'sandbox_theme_display'

8

);

Guarda tu código, actualiza tu escritorio, y deberías ver el ítem de menú "Opciones Sociales" ahora disponible bajo el menú "Sandbox Theme"; sin embargo, nota que al hacer clic en el nuevo ítem de submenú solo se muestran las "Opciones de Visualización". Dado que hemos pasado "sandbox_theme_display" como nombre de la función, eso es lo que deberíamos esperar, ¿verdad? Así que ahora nos enfrentamos a un pequeño reto: ¿Cómo seleccionamos la pestaña "Opciones sociales" al hacer clic en el elemento del submenú?

Refactorización de nuestra funcionalidad de pestañas

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 muestre las opciones sociales. Esto requeriría que hiciéramos algo de trabajo adicional para introducir una nueva función, configurar la funcionalidad de tabulación para no romper la experiencia de la página existente, y duplicar un poco de código.
• Podemos refactorizar la función existente sandbox_theme_display para que acepte un parámetro opcional y luego utilizar una función anónima en la llamada add_submenu_page para pasarle un parámetro.

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

En primer lugar, vamos a empezar a refactorizar nuestra función sandbox_theme_display. Hagamos que acepte un argumento opcional que servirá para indicar qué pestaña queremos seleccionar. Localiza la siguiente firma en tu archivo functions.php:

1

function sandbox_theme_display() {

2

	/* Consolidated for this part of the article. */

3

} // end sandbox_theme_display

Actualiza la firma para que acepte un único argumento y lo ponga a cero cuando no esté definido:

1

function sandbox_theme_display( $active_tab = null ) {

2

	/* Consolidated for this part of the article. */

3

} // end sandbox_theme_display

Si eres nuevo en PHP, puedes leer sobre los argumentos por defecto en esta página.

Recuerda del último artículo que nuestra función de visualización en realidad está buscando un valor de cadena de consulta para ser establecido. Todavía queremos mantener esa funcionalidad, pero tenemos que tener en cuenta el hecho de que el parámetro puede ser pasado a la función, también. Para realizar esta refactorización, primero localiza la siguiente línea de código en la función sandbox_theme_display:

1

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

Observa que esta línea de código en particular solo se ocupa de los parámetros de la cadena de consulta. Para tener en cuenta el nuevo parámetro opcional, tenemos que introducir una lógica que primero compruebe si el parámetro de la cadena de consulta está marcado, si no es así, comprobará si el argumento de la función está configurado para mostrar las opciones sociales y, si no es así, entonces se mostrará por defecto las opciones de visualización. Sustituye la línea de código anterior por la siguiente condicional:

1

if( isset( $_GET[ 'tab' ] ) ) {

2

	$active_tab = $_GET[ 'tab' ];

3

} else if( $active_tab == 'social_options' ) {

4

	$active_tab = 'social_options';

5

} else {

6

	$active_tab = 'display_options';

7

} // end if/else

La versión final de la función debería tener este aspecto:

1

function sandbox_theme_display( $active_tab = '' ) {

2

?>

3

	<!-- Create a header in the default WordPress 'wrap' container -->

4

	<div class="wrap">

5

6

		<div id="icon-themes" class="icon32"></div>

7

		<h2>Sandbox Theme Options</h2>

8

		<?php settings_errors(); ?>

9

10

		<?php if( isset( $_GET[ 'tab' ] ) ) {

11

			$active_tab = $_GET[ 'tab' ];

12

		} else if( $active_tab == 'social_options' ) {

13

			$active_tab = 'social_options';

14

		} else {

15

			$active_tab = 'display_options';

16

		} // end if/else ?>

17

18

		<h2 class="nav-tab-wrapper">

19

			<a href="?page=sandbox_theme_options&tab=display_options" class="nav-tab <?php echo $active_tab == 'display_options' ? 'nav-tab-active' : ''; ?>">Display Options</a>

20

			<a href="?page=sandbox_theme_options&tab=social_options" class="nav-tab <?php echo $active_tab == 'social_options' ? 'nav-tab-active' : ''; ?>">Social Options</a>

21

		</h2>

22

23

		<form method="post" action="options.php">

24

			<?php

25

26

				if( $active_tab == 'display_options' ) {

27

					settings_fields( 'sandbox_theme_display_options' );

28

					do_settings_sections( 'sandbox_theme_display_options' );

29

				} else {

30

					settings_fields( 'sandbox_theme_social_options' );

31

					do_settings_sections( 'sandbox_theme_social_options' );

32

				} // end if/else

33

34

				submit_button();

35

36

			?>

37

		</form>

38

39

	</div><!-- /.wrap -->

40

<?php

41

} // end sandbox_theme_display

Todavía no hemos terminado. Aunque hemos hecho el trabajo necesario para mostrar las opciones sociales si se ha pasado el parámetro adecuado, no hemos llamado realmente a la función utilizando un parámetro. Para ello, tenemos que refactorizar la función add_submenu_page de arriba. Actualmente, la llamada a la función tiene el siguiente aspecto:

1

add_submenu_page(

2

	'sandbox_theme',

3

	'Social Options',

4

	'Social Options',

5

	'administrator',

6

	'sandbox_theme_social_options',

7

	'sandbox_theme_display'

8

);

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

1

add_submenu_page(

2

	'sandbox_theme_menu',

3

	'Social Options',

4

	'Social Options',

5

	'administrator',

6

	'sandbox_theme_social_options',

7

	create_function( null, 'sandbox_theme_display( "social_options" );' )

8

);

Si eres nuevo en PHP, asegúrate de leer sobre la función create_function y las funciones anónimas. Aunque están fuera del alcance de este artículo, pueden ser poderosas (y útiles) cuando se utilizan en el contexto adecuado.

La versión final de la función sandbox_example_theme_menu debería ser la siguiente:

1

function sandbox_example_theme_menu() {

2

3

	add_theme_page(

4

		'Sandbox Theme', 					// The title to be displayed in the browser window for this page.

5

		'Sandbox Theme',					// The text to be displayed for this menu item

6

		'administrator',					// Which type of users can see this menu item

7

		'sandbox_theme_options',			// The unique ID - that is, the slug - for this menu item

8

		'sandbox_theme_display'				// The name of the function to call when rendering this menu's page

9

	);

10

11

	add_menu_page(

12

		'Sandbox Theme',					// The value used to populate the browser's title bar when the menu page is active

13

		'Sandbox Theme',					// The text of the menu in the administrator's sidebar

14

		'administrator',					// What roles are able to access the menu

15

		'sandbox_theme_menu',				// The ID used to bind submenu items to this menu 

16

		'sandbox_theme_display'				// The callback function used to render this menu

17

	);

18

19

	add_submenu_page(

20

		'sandbox_theme_menu',				// The ID of the top-level menu page to which this submenu item belongs

21

		'Display Options',					// The value used to populate the browser's title bar when the menu page is active

22

		'Display Options',					// The label of this submenu item displayed in the menu

23

		'administrator',					// What roles are able to access this submenu item

24

		'sandbox_theme_display_options',	// The ID used to represent this submenu item

25

		'sandbox_theme_display'				// The callback function used to render the options for this submenu item

26

	);

27

28

	add_submenu_page(

29

		'sandbox_theme_menu',

30

		'Social Options',

31

		'Social Options',

32

		'administrator',

33

		'sandbox_theme_social_options',

34

		create_function( null, 'sandbox_theme_display( "social_options" );' )

35

	);

36

37

} // end sandbox_example_theme_menu

38

add_action( 'admin_menu', 'sandbox_example_theme_menu' );

Conclusión

En este punto, nuestro tema tiene ahora su propio elemento de menú de nivel superior con cada una de las pestañas de configuración accesibles a través de elementos de submenú. Aunque esto es útil, creo que es importante señalar que hay algunas opiniones encontradas sobre la introducción de menús en el escritorio de WordPress. Aunque pueden hacer que tu 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 intentas colocar tus menús en algún lugar utilizando el parámetro de posición. Aunque no hay un bien o un mal absolutos a la hora de introducir los menús, piensa bien dónde los expones. Si un menú existente de WordPress tiene sentido, registra tu trabajo como un submenú.

En el próximo post, empezaremos a echar un vistazo a los distintos elementos de entrada que podemos utilizar para introducir opciones en nuestro tema de WordPress, así como la forma de validar y sanear los datos antes de serializarlos.

Fuentes relacionadas

• add_menu_page
• add_submenu_page
• create_function
• funciones anónimas
• Sandbox de configuración de WordPress 0.5