Creando Páginas de Administración Personalizadas en WordPress, Parte 2

Spanish (Español) translation by Rafael Chavarría (you can also view the original English article)

En el tutorial previo en esta serie, comenzamos trabajando en nuestra página de administración personalizada.

Al final, las metas hacia las que estamos trabajando demostrará cómo podemos usar nuestro propio código así como el de la API de WordPress para crear páginas que son un poco más flexibles de lo que serían disponibles vía una de las APIs estándar.

Esto no quiere decir que deberías dejar de lado o evitar las APIs que WordPress proporciona. De hecho, soy fanático de usarlas tanto como sea posible. Pero cuando un proyecto surge en el cuál necesitas introducir funcionalidad adicional o personalizar la manera en la que algo se desempeña, entonces el desarrollo de dicha funcionalidad será dejado a tu consideración.

Secundariamente, también estamos usando principios tales como el principio de responsabilidad individual para demostrar como podemos tomar una aproximación bien organizada orientada a objetos al código que estamos escribiendo.

Antes de continuar, sin embargo, revisemos lo que hemos cubierto hasta ahora.

Por la Primera Publicación...

Recuerda que proporcionamos una definición del principio de responsabilidad individual:

Junta las cosas que cambian por las mismas razones. Separa aquellas cosas que cambian por diferentes razones.

Y usamos eso para ayudar a guiar la organización de la creación de nuestro actual submenú y página de submenú.

También vimos el código por la primer versión del complemento, lo hicimos disponible para descarga y asentamos el fundamento para el trabajo que vamos a hacer en este tutorial

Si no has revisado el tutorial anterior o al menos revisado el código, recomiendo altamente hacerlo; de otro modo, podrías quedarte preguntándote por qué estamos tomando algunas de las decisiones que estamos haciendo o por qué alguna parte del código está organizada de esa manera.

Dicho eso, continuemos.

Antes de que Comencemos

Como con muchos tutoriales, me gusta asegurarme de que tienes todo listo antes de que procedamos. Para este tutorial, vas a necesitar lo siguiente:

un entorno local de desarrollo
una copia de WordPress instalada y lista para ser usada
una copia de nuestro complemento del tutorial anterior instalada y activada
un IDE con el complemento cargado y listo para edición adicional

Si cualquiera de los anteriores no tiene sentido, por favor revisa el tutorial anterior o esta serie para cómo configurar un entorno local de desarrollo.

En cuanto al código que está por venir, estaremos recorriéndolo paso a paso. Explicaré exactamente lo que estamos haciendo y estaremos proporcionando tanto comentarios del código como comentarios en el tutorial para asegurar que entiendes todo lo que está pasando a lo largo del camino.

Creando la Página de Administración

Mientras continuamos con el complemento en este artículo, esto es lo que vamos a estar haciendo:

Crear el marcado para la página de administración que herede los estilos nativos de WordPress.
Introducir una opción con la cuál el usuario pueda interactuar.
Sanitizar la opción antes de guardarla.
Recoger el valor de la opción e igualarla al valor en la página.

En este tutorial, vamos a enfocarnos en los siguientes dos puntos. En el siguiente artículo, nos enfocaremos en los puntos tres y cuatro.

Para aquellos que están familiarizados con la API de Ajustes, esto parece un exceso. Pero mientras ves a través del recordatorio de este tutorial y esta serie, hay una razón por la que vamos a desglosarlo en piezas más pequeñas como esta.

Con eso asentado como nuestro plan de acción, comencemos.

Marcando la Página

Cuando dejamos está función en particular, el código se veía así:

<?php
class Submenu_Page {

    /**
     * This function renders the contents of the page associated with the Submenu
     * that invokes the render method. In the context of this plugin, this is the
     * Submenu class.
     */
    public function render() {
        echo 'This is the basic submenu page.';
    }
}

Ahora estamos listos para comenzar a crear el diseño de la página. Siempre que estoy trabajando en complementos para clientes, llamo a estas "vistas".

Esto no debe confundirse con el paradigma de modelo-vista-controlador. Pero no los llamo plantillas tampoco porque en WordPress, las plantillas no son usadas para mostrar el contenido de una página en el front-end.

Así que es vistas.

La primera cosa que queremos hacer es crear una carpeta de vistas dentro del directorio de admin de nuestro complemento.

views directory inside the admin directory of the plugin

Una vez que está hecho, podemos nombrar esto tan simple como settings.php o algo más descriptivo. Realmente depende de ti y la complejidad de lo que estés construyendo. Ya que es un complemento simple, me estoy apegando a un nombre simple.

Después, comencemos creando el marcado básico que proporcionará el elemento envoltorio estándar de WordPress junto con el título de la página:

<div class="wrap">

    <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>

    <form method="post" action="<?php echo esc_html( admin_url( 'admin-post.php' ) ); ?>">
    </form>

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

Nota que el título está siendo entregado desde una función que usa los valores pasado a la función add_options_page de cuándo primero comenzamos a trabajar en el complemento. Después, también estamos usando la función admin_url para denotar en donde estaremos publicando las opciones (de las cuáles hablaremos un poco después).

En ambos casos, estamos usando la función esc_html para asegurarnos de que ninguna cadena maliciosa pueda ser generada en la página.

Estos son dos ejemplos de, cuándo es posible, usar cualquier función de API que esté disponible para su propósito. Asumiendo que todo ha salido correcto, tu página debería verse así:

Ahora, para enlazar esto a tu complemento, necesitamos revistar la función de arriba. Esto significa que la función debería verse así:

1	<?php
2	public function render() {
3	include_once( 'views/settings.php' );
4	}

¿Suficientemente fácil, verdad? Asumiendo que todo está configurado correctamente, esto es lo que deberías ver:

The first pass at the Tuts Custom Administration Page

No, no hay mucho que ver, pero vamos a cambiar eso.

Agrega una Opción

En este punto, estamos listos para agregar una opción. Para los propósitos de esta publicación, vamos a permitir al usuario ingresar algo en el elemento de texto de entrada. Esto nos permitirá echar un vistazo a cómo sanitizar información y eventualmente mostrarla en el front-end.

Para hacer esto, necesitamos tener una pieza clave de información. Es decir necesitamos saber el nombre del atributo que vamos a llamar el elemento input. Esto es de manera que podamos guardarlo a en la base de datos apropiadamente.

Así que, para propósito de este ejemplo, digamos que este mensaje será usado para mostrar incondicionalmente en la parte superior de cada publicación. No llegaremos al punto en este artículo, pero revisitaremos eso en el siguiente artículo.

En tu vista settings.php, agrega el siguiente código.

<div class="wrap">

    <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>

  <form method="post" action="<?php echo esc_html( admin_url( 'admin-post.php' ) ); ?>">

		<div id="universal-message-container">
			<h2>Universal Message</h2>

			<div class="options">
				<p>
					<label>What message would you like to display above each post?</label>
					<br />
					<input type="text" name="acme-message" value="" />
				</p>
		</div><!-- #universal-message-container -->
	</form>

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

Si vieras la página en este punto, deberías ver exactamente lo que esperas: una etiqueta y una caja de texto.

Asegura la Opción

Normalmente mostraría una captura aquí, pero aún no terminamos. Necesitamos introducir dos cosas más.

Un nonce WordPress
El botón enviar

Hagamos eso ahora. Si no estás familiarizado con los valores nonce, recomiendo que leas este artículo. La versión corta es:

Un nonce es "número usado una vez" para ayudar a proteger URLs y formularios de ciertos tipos de mal uso, malicioso o de otra manera.

En nuestro archivo setings.php, agreguemos el siguiente bloque de código.

1	<?php
2	wp_nonce_field( 'acme-settings-save', 'acme-custom-message' );
3	submit_button();
4	?>

Por último, la versión final de nuestro código debería verse así:

<div class="wrap">

    <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>

	<form method="post" action="<?php echo esc_html( admin_url( 'admin-post.php' ) ); ?>">

		<div id="universal-message-container">
			<h2>Universal Message</h2>

			<div class="options">
				<p>
					<label>What message would you like to display above each post?</label>
					<br />
					<input type="text" name="acme-message" value="" />
				</p>
		</div><!-- #universal-message-container -->

		<?php
			wp_nonce_field( 'acme-settings-save', 'acme-custom-message' );
			submit_button();
		?>

	</form>

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

Y la versión final de la página debería verse así:

The final version of the Tuts Custom Administration Screen

En este punto, estamos listos para guardar las opciones. Ahora en orden para hacer esto, necesitamos verificar un par de cosas.

¿El usuario tiene permiso para guardar opciones?
¿Hay un nonce válido siendo pasado de formulario a formulario?

Además, necesitamos:

Sanitizar la información para asegurarnos de que ningún dato malicioso se meta en la base de datos.
Necesitamos poder jalar esta información de la base de datos y poblarla en el formulario.

Y por último, necesitamos mostrar esto en el front-end del sitio web.

Conclusión

Así que en los siguientes dos artículos vamos a concentrarnos en hacer exactamente eso.

No olvides que puedes descargar el complemento en su estado actual desde esta publicación. Mientras progresamos en la serie, haré la última versión disponible en cada publicación de manera que puedas seguir a la par con el código cubierto en cada tutorial, jugar con el y preparar preguntas que quisieras hacer en los comentarios.

Como nota adicional, si estás buscando otras utilidades para ayudarte a construir tu creciente conjunto de herramientas para WordPress o código para estudiar y volverte mejor versado en WordPress, no olvides ver lo que tenemos disponible en Envato Market.

Recuerda, puedes ver todos mis cursos y tutoriales en mi página de perfil y puedes seguirme en mi blog y/o Twitter en @tommcfarlin en donde hablo sobre varias prácticas de desarrollo de software y cómo podemos emplearlas en WordPress.

Finalmente, no dudes en dejar cualquier pregunta o comentarios en la sección de abajo. Hago lo mejor por participar y contestar cada pregunta o crítica que ofrezcas relacionada con este proyecto.