Personalización del administrador de WordPress: Texto de ayuda

En la Parte 2 de este tutorial, te mostré cómo añadir metaboxes personalizados al escritorio de WordPress, algo que puedes usar para proporcionar texto de ayuda a tus clientes o usuarios.

Pero, ¿qué pasa si deseas proporcionar texto de ayuda en pantallas de edición individuales? En este tutorial, te mostraré cómo hacer precisamente eso.

En este tutorial aprenderás lo siguiente:

1. Añadir un metabox a la pantalla de edición para el texto de ayuda
2. Añadir metaboxes adicionales en diferentes ubicaciones
3. Crear un metabox ficticio para mostrar el texto de ayuda en la parte superior de la pantalla de edición

Para hacer esto voy a crear un plugin, si ya has creado un plugin después de seguir las Partes 1 a 3 de esta serie es posible que prefieras añadir el código de este tutorial a dicho plugin, lo que te proporcionará un plugin con todas tus personalizaciones para el administrador.

Lo que necesitarás para completar este tutorial

Para completar este tutorial necesitarás lo siguiente:

• Una instalación de WordPress
• Acceso a la carpeta de plugins de tu sitio para añadir tu plugin
• Un editor de texto para crear tu plugin

Configuración del plugin

Al principio de mi plugin, estoy añadiendo las siguientes líneas:

1

/*

2

Plugin Name: Wptuts+ Customize the Admin Part 4 - Help Text

3

Plugin URI: https://rachelmccollin.co.uk

4

Description: This plugin supports the tutorial in Wptuts+. It adds help text to the WordPress editing screen.

5

Version: 1.0

6

Author: Rachel McCollin

7

Author URI: http://rachelmccollin.com

8

License: GPLv2

9

*/

1. Añadir un Metabox de Ayuda a la pantalla de edición de las entradas

Para añadir un metabox que contenga texto de ayuda, utiliza la función add_meta_box(), que también usarías si estuvieras creando un metabox para los metadatos de la entrada o en una pantalla de ajustes. Esta función toma algunos parámetros:

1

<?php add_meta_box( $id, $title, $callback, $post_type, $context, $priority, $callback_args ); ?>

Los parámetros son:

• $id - el identificador único del metabox.
• $title - el título del metabox que se mostrará a los usuarios.
• $callback - la función de devolución de llamada que define el contenido del metabox.
• $post_type - el tipo de entrada en cuya pantalla de edición aparecerá el metabox. Deja este espacio en blanco para añadir los metaboxes a las pantallas de edición de todos los tipos de entradas o especifica el tipo de entrada al que deseas dirigirte.
• $context - el lugar de la pantalla de edición en la que deseas que aparezca el metabox, 'normal', 'avanzado' o 'lateral'. El valor predeterminado es 'avanzado' que coloca el metabox en el área principal de la pantalla.
• $priority - dentro del contexto que has definido, la prioridad para este metabox ('high', 'core', 'default' o 'low'). Esto es útil si vas a añadir varios metaboxes.
• $callback_args - argumentos para pasar a la función de devolución de llamada (opcional)

Por lo tanto, para añadir un metabox al área principal de la pantalla de edición solo para las entradas, añado lo siguiente a mi plugin:

1

// Add metabox below editing pane

2

function wptutsplus_metabox_after_title() {

3

	add_meta_box( 'after-title-help', 'Using this Screen', 'wptutsplus_after_title_help_metabox_content', 'post', 'advanced', 'high' );

4

}

5

add_action( 'add_meta_boxes', 'wptutsplus_metabox_after_title' );

Esto añade un metabox vacío, que aún no funcionará porque no he añadido la función de devolución de llamada. Esto es lo siguiente:

1

// callback function to populate metabox

2

function wptutsplus_after_title_help_metabox_content() { ?>

3

	<p>Use this screen to add new articles or edit existing ones. Make sure you click 'Publish' to publish a new article once you've added it, or 'Update' to save any changes.</p>

4

<?php }

Esto añade ahora un metabox a la pantalla de edición de mis entradas, como se muestra en la captura de pantalla:

Como puedes ver, he eliminado algunos de los otros metaboxes que normalmente se ven en la pantalla de edición de las entradas (como extracto y comentarios), pero mi nuevo metabox está debajo del panel de edición y por lo tanto no es muy visible. Es imposible utilizar la función add_meta_box() para añadir un metabox por encima del panel de edición principal sin recurrir a una solución jQuery que mueva el panel de edición principal hacia abajo, y que creo que sería exagerado para este problema. ¿Qué alternativas tengo?

1. En primer lugar, puedo añadir un metabox por encima del metabox 'Publicar', así será más obvio para los usuarios.
2. Alternativamente, puedo hacer trampa y usar el gancho de acción edit_form_after_title para añadir un metabox falso por encima del panel de edición.

Empezaré con la primera opción: añadir un metabox a la derecha encima del metabox 'Publicar'.

2. Añadir un metabox a la derecha de la pantalla de edición

Para añadir un metabox en la parte superior derecha de la pantalla utilizo la función add_meta_box() de la misma manera que antes, con algunos de los parámetros cambiados. También usaré una función de devolución de llamada diferente para rellenar el metabox con contenido diferente.

En tu plugin, añade lo siguiente:

1

// Add help text to right of screen in a metabox

2

function wptutsplus_metabox_top_right() {

3

	add_meta_box( 'after-title-help', 'Publishing and Saving Changes', 'wptutsplus_top_right_help_metabox_content', 'post', 'side', 'high' );

4

}

5

// callback function to populate metabox

6

function wptutsplus_top_right_help_metabox_content() { ?>

7

	<p>Make sure you click 'Publish' below to publish a new article once you've added it, or 'Update' to save any changes.</p>

8

<?php }

9

add_action( 'add_meta_boxes', 'wptutsplus_metabox_top_right' );

Esto añade un pequeño metabox con instrucciones breves, si añado mucho más texto, desplazaría los metaboxes que hay bajo él demasiado lejos en la pantalla. Puedes ver el resultado en la captura de pantalla:

Nota: He comentado la función para el metabox del área principal de la pantalla antes de añadir este nuevo metabox, por lo que no se puede ver en la captura de pantalla.

3. Añadir un metabox 'falso' por encima del panel de edición

De manera que añadir un pequeño metabox en la parte superior derecha de la pantalla es bastante simple, pero ¿qué pasa si quiero un metabox en la parte superior izquierda, por encima del panel de edición?

Para hacer esto, no se utiliza la función add_meta_box(), sino que se utiliza el gancho edit_form_after_title, que inserta el contenido después del título de la entrada y antes del panel de edición. Adjuntaré una función a ese gancho para definir el marcado que se añadirá a la pantalla, y usaré clases en mi marcado para replicar el aspecto del metabox.

En tu plugin, añade lo siguiente:

1

function wptutsplus_text_after_title( $post_type ) { ?>

2

	<div class="after-title-help postbox">

3

		<h3>Using this screen</h3>

4

		<div class="inside">

5

			<p>Use this screen to add new articles or edit existing ones. Make sure you click 'Publish' to publish a new article once you've added it, or 'Update' to save any changes.</p>

6

		</div><!-- .inside -->

7

	</div><!-- .postbox -->

8

<?php }

9

add_action( 'edit_form_after_title', 'wptutsplus_text_after_title' );

Esto añade algo de marcado a la pantalla de edición que se parece mucho a un metabox, porque incluí las clases .postbox e .inside:

Sin embargo, existe un problema con este marcado, aparecerá en la pantalla de edición para todos y cada uno de los tipos de entrada. Como no estoy usando la función add_meta_box(), no tengo el lujo del parámetro $post_type. Así que en lugar de usar esto, realizaré una comprobación de la página de edición en la que estamos antes de generar el marcado.

Como estoy en el backend de WordPress, no puedo usar las etiquetas condicionales estándar que usaría en un archivo de plantilla para comprobar mi ubicación, pero puedo usar la función get_current_screen() para identificar en qué pantalla de edición estoy.

La función get_current_screen() devuelve una matriz, que incluirá el tipo de entrada de la pantalla actual, entre otras cosas. Puedo usar esto para comprobar si el tipo de entrada que se está editando es 'post'.

Dentro de la función, encima del otro contenido, añade lo siguiente:

1

$screen = get_current_screen();

2

$edit_post_type = $screen->post_type;

3

4

if ( $edit_post_type != 'post' )

5

	return;

6

?>

Ahora la función completa tendrá este aspecto:

1

// Add fake metabox above editing pane

2

function wptutsplus_text_after_title( $post_type ) {

3

	$screen = get_current_screen();

4

	$edit_post_type = $screen->post_type;

5

	if ( $edit_post_type != 'post' )

6

		return;

7

	?>

8

	<div class="after-title-help postbox">

9

		<h3>Using this screen</h3>

10

		<div class="inside">

11

			<p>Use this screen to add new articles or edit existing ones. Make sure you click 'Publish' to publish a new article once you've added it, or 'Update' to save any changes.</p>

12

		</div><!-- .inside -->

13

	</div><!-- .postbox -->

14

<?php }

15

add_action( 'edit_form_after_title', 'wptutsplus_text_after_title' );

Esto garantizará que el metabox 'falso' solo se mostrará en la pantalla de edición de las entradas, pero no en la pantalla de edición de otros tipos de entradas. A continuación, puedes repetir esta función para diferentes tipos de entradas (como 'page' y 'attachment', así como tus propios tipos de entradas personalizadas), para mostrar texto de ayuda distinto en ellos.

Resumen

Añadir texto de ayuda a pantallas de edición individuales puede ser muy útil para los usuarios que no quieran volver contínuamente al panel para obtener ayuda.

En este tutorial, has aprendido a crear metaboxes para añadir texto de ayuda en las pantallas de edición, así como a usar el enlace de edit_form_after_title para añadir texto de ayuda inmediatamente encima del panel de edición.