Creando un Sistema de Mensajes Personalizado de WordPress, Parte 4

Spanish (Español) translation by Rodney Martinez (you can also view the original English article)

En esta serie, hemos echado un vistazo a cómo podemos implementar un sistema que nos permite por medio de la programación, definir mensajes personalizados que se muestren una página de administración dada en el back-end de WordPress.

Si ha seguido junto con las serie hasta ahora, entonces sabrá:

Que hemos establecido un base para el plugin que es utilizado a través de esta serie, e incluso desarrollarlo un poco más.
Hemos definido y utilizado un hook personalizado que podemos usar para representar la configuración de los mensajes.
Hemos agregado soporte para los mensajes de éxito, advertencia y error que pueden ser reproducidos en la parte de arriba de una página configurada.

Como mencione en el tutorial anterior:

Si ha leído algunos de mis tutoriales anteriores, entonces sabe que no soy un fanático de tener código duplicado. No soy un fanático de tener una clase que haga mis cosas. Y, lamentablemente, eso es exactamente lo que vamos hacer aquí:

Y vamos a abordar eso en éste tutorial final. Al final, tendremos una refactorizada solución completa que usa algunos principios de la programación orientada a objetos como herencia. Además, tendremos algunos métodos que podremos usar mediante la programación o que pueden estar registrados con el sistema hook de WordPress.

Empezando con el final

En este punto debería de saber exactamente lo que necesita en su ambiente de desarrollo local. Específicamente, deberá tener lo siguiente:

PHP 5.6.25 y MySQL 5.6.28
Apache o Nginx
WordPress 4.6.1
Su IDE o editor de texto de su preferencia

Además, recomiendo la versión más reciente del código fuente ya que éste le permitirá ir a través de todos los cambios que vamos a hacer. Si no lo tiene, está bien, pero le recomiendo leer los tutoriales anteriores antes de continuar.

In el tutorial anterior

Como puede recordar (o haber comprobado de parte de los comentarios anteriores) el tutorial anterior nos dejo con una sola clase que estaba haciendo demasiado trabajo.

Una forma para estar seguro de esto es que si fuera a describir lo que la clase está haciendo, entonces no podría dar una sola respuesta. En cambio, tendría que decir que ésta clase era responsable por controlar los mensajes de éxito, los mensajes de advertencia, los mensajes de errores y reproducirlos todos de forma independiente uno de otro.

Y aunque podría ser el caso de que éste fuera "un administrador de mensajes personalizados", usted no lo describiría, necesariamente, sólo cómo la clase que era. Eso es lo que esperamos resolver en éste tutorial.

En el Tutorial Final

Específicamente, vamos a ver y hacer lo siguiente:

quitar la configuración anterior de la clase mensajes
añadir una nueva y más genérica configuración de la clase mensajes
añadir una configuraciones de la clase mensajes con la cual comunicar
introducir los métodos que podemos usar independientemente de WordPress
simplificar cómo WordPress reproduce los mensajes

Hemos recortado nuestro trabajo recortado para nosotros, así que vamos a continuar y a empezar con todo lo anterior.

Refactorizando Nuestro Trabajo

Cuando se trata de refactorizar nuestro trabajo, éste nos ayuda a saber con exactitud qué es lo que queremos hacer. En nuestro caso, reconocemos que tenemos mucho código duplicado que podría ser condensado.

Además, tenemos tres diferentes tipos de mensajes gestionados en, exactamente, la misma forma que ahorramos cómo son reproducidos. Y en esa instancia, es un problema de los atributos de la clase HTML.

De este modo, podemos generalizar ese código para enfocarnos en un type específico, y podemos consolidar muchos métodos para añadir mensajes de éxito o extraer mensajes de error por medio de generalizar un método para reconocer este type dicho.

En última instancia, haremos eso. Pero primero, hagamos algunos quehaceres domésticos.

1. Quitar las configuraciones anteriores de Messenger

En los tutoriales anteiores, hemos estado trabajando con clases llamadas Settings_Messenger. Hasta este punto, ha servido a su propósito, sin embargo, vamos a refactorizar esta clase a través de lo que queda de este tutorial.

Cuando ocurre este tipo de refactorización, es muy fácil querer eliminar la clase y volver empezar. Hay momentos en los cuales esto es apropiado, pero éste no es uno de ellos. En vez de eso, vamos a ocupar esa clase y refactorizar lo que ya está ahí.

Todo eso para decir, no elimine el archivo y empiece con uno nuevo. Al contrario, supervise lo que vamos haciendo a través de este tutorial.

2. Una Nueva Configuración de la Clase Messenger

Primero, vamos a introducir una clase Settings_Message. Esto representa cualquier tipo de configuración de mensaje con el cual vamos a escribir. Eso significa que gestionaremos los mensajes de éxito, los mensajes de error y los mensajes de advertencia.

Para hacer esto, definiremos la clase, introduciremos una sola propiedad y, después, la instanciaremos en el constructor. Revise este código, y explicaré un poco más abajo:

<?php

class Settings_Message {

    private $messages;

    public function __construct() {

        $this->messages = array(
            'success'   => array(),
            'error'     => array(),
            'warning' 	=> array(),
        );
    }
}

Observe que hemos creado un atributo privado; $messages. Cuando la clase es instanciada, entonces creamos un arreglo multidimensional. Cada indice identificado por; success, error o warning, hace referencia a su propio arreglo en el cual estará almacenando los mensajes correspondientes.

A continuación, necesitamos poder agregar un mensaje, obtener un mensaje y conseguir todos los mensajes. Abordare cada uno de éstos con más detalle momentáneamente.

Añadiendo Mensajes

Primero, vamos a ver cómo añadiremos mensajes:

<?php 
public function add_message( $type, $message ) {

    $message = sanitize_text_field( $message );

    if ( in_array( $message, $this->messages[ $type ] ) ) {
        return;
    }

    array_push( $this->messages[ $type ], $message );
}

Este mensaje, primero toma el string recibido y limpia los datos. Luego, revisa para ver si éste arreglo existe en los mensajes de éxito. Si es así, simplemente lo devuelve. Después de todo, no queremos mensajes duplicados.

De lo contrario, añade el mensaje a la colección.

Obteniendo Mensajes

La recuperación de mensajes viene en dos formas:

reproduciendo los mensajes individuales por type
representado los mensajes en la pantalla de la página de administración (completa con la limpieza HTML, etc.).

Recuerde que; hay ocasiones en donde solamente podemos querer mostrar mensajes de advertencia. Otras veces, queremos mostrar todos los mensajes. Ya que hay dos formas de hacer esto, podemos aprovechar uno y después, tomar ventaja del otro en otra función.

¿Suena confuso? Sujetese a mí y le explicaré todo. La primera parte vamos a enfocarnos en como reproducir los mensajes por medio de type (éxitos, errores y advertencias). Aquí está el código para hacer eso (y debería de parecerle familiar):

<?php

public function get_messages( $type ) {

    if ( empty( $this->messages[ $type ] ) ) {
		return;
	}

	$html  = "<div class='notice notice-$type is-dismissible'>";
	$html .= '<ul>';
	foreach ( $this->messages[ $type ] as $message ) {
		$html .= "<li>$message</li>";
	}
	$html .= '</ul>';
	$html .= '</div><!-- .notice-$type -->';

	$allowed_html = array(
		'div' => array(
			'class' => array(),
		),
		'ul' => array(),
		'li' => array(),
	);

	echo wp_kses( $html, $allowed_html );
}

Observe que aquí estamos usando la mayor parte del mismo código del tutorial anterior, sin embargo, hemos generalizado para que luzca en el $type entrante y de forma dinámica aplicarlo al marcado.

Esto nos permite tener una sola función para reproducir nuestros mensajes. Aunque esto no es todo. ¿Qué hay de las ocasiones en las que queremos todos los mensajes? Esto podría ser para reproducir en una página o agarrarlos por medio de programación para otros procesos.

Para hacer esto, podemos introducir otra función:

<?php

public function get_all_messages() {

    foreach ( $this->messages as $type => $message ) {
        $this->get_messages( $type );
    }
}

Este mensaje debería ser lo suficientemente fácil de entender. Simplemente repite el ciclo a través de todos los mensajes que tenemos en nuestra colección y llama a la función get_messages que hemos explicado anteriormente.

Aún los reproduce a todos (que veremos usar uno de ellos en nuestra implementación de un hook personalizado, momentáneamente). Si desea usarlos para otros propósitos, usted podría adjuntar el resultado dentro de un string y devolverlo al que lo invoca, o realizar algunas funciones de forma estructurada.

Eso es todo para una implementación.

3. Las configuraciones de Messenger

Eso es todo para la clase Settings_Message. ¿Pero, cómo nos comunicamos con él? Por supuesto que podemos hablarle directamente pero si hay una clase intermedia, tenemos algunos controles sobre lo que nos está devolviendo sin añadir más responsabilidad para la clase Settings_Message, ¿cierto?

Entre a Settings_Message. Esta clase es responsable por dejarnos leer y escribir ajustes de mensajes. Creo que un caso se podría tomar para que usted pudiera separarlo en dos clases por su responsabilidad debido a los dos; la escritura y la lectura, como messenger que envía y recibe, ese es el propósito de esta clase.

La configuración inicial de la clase es sencilla.

El constructor crea una instancia de la clase Settings_Message, que podemos usar para enviar y recibir mensajes.
Ésta asocia un método con nuestro hook personalizado; tutsplus_settings_messages que definimos en el artículo anterior.

Eche un vistazo al primer par de métodos:

<?php

class Settings_Messenger {

    private $message;

    public function __construct() {
        $this->message = new Settings_Message();
    }

    public function init() {
        add_action( 'tutsplus_settings_messages', array( $this, 'get_all_messages' ) );
    }
}

Recuerde la parte anterior de este tutorial, tenemos el hook definido en nuestra vista, la cual puede encontrarse en settings.php. Por razones de plenitud, está enumerado aquí:

<div class="wrap">

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

	<p class="description">
		We aren't actually going to display options on this page. Instead, we're going
		to use this page to demonstration how to hook into our custom messenger.
	</p><!-- .description -->
</div><!-- .wrap -->

Observe, sin embargo, que este hook en particular toma ventaja del método get_all_messages, que revisaremos en un momento. No tiene que usar éste método. En lugar de eso, podría ser utilizado para reproducir los mensajes de éxito o cualquier otros métodos que desee usar.

Añadiendo Mensajes

Crear las funciones para añadir mensajes es sencillo, debido a que estas funciones requieren un tipo y el propio mensaje. Recuerde, la clase Settings_Message se ocupa de la limpieza de la información, de modo que podemos pasarla en los mensajes recibidos.

A continuación verá dónde añadimos mensajes de éxito, advertencia y error.

<?php

public function add_success_message( $message ) {
    $this->add_message( 'success', $message );
}

public function add_warning_message( $message ) {
    $this->add_message( 'warning', $message );
}

public function add_error_message( $message ) {
    $this->add_message( 'error', $message );
}

Es fácil, ¿no es así?

Obteniendo Mensajes

La recuperación de mensajes no muy diferente, excepto que solamente necesitamos proporcionar el tipo de mensajes que queremos recuperar:

<?php

public function get_success_messages() {
    echo $this->get_messages( 'success' );
}

public function get_warning_messages() {
    echo $this->get_messages( 'warning' );
}

public function get_error_messages() {
    echo $this->get_messages( 'error' );
}

Hacerlo y hacerlo, ¿verdad?

¿Pero entiende eso?

Observe que todos los mensajes anteriores hacen referencia a otros dos métodos que aún no hemos abordado. Estos son mensajes privados que nos ayudan a simplificar las llamadas anteriores.

Revise los siguientes métodos privados, tanto los flexibles para añadir como los mensajes para recuperar directo desde la instancia Settings_Message, manteniendo activado el objeto messenger:

<?php

private function add_message( $type, $message ) {
    $this->message->add_message( $type, $message );
}

private function get_messages( $type ) {
    return $this->message->get_messages( $type );
}

Y así terminamos la nueva clase Setting_Messenger. Todo esto es muy sencillo, ¿no es así?

Iniciando el Plugin

Surge la pregunta: ¿Cómo iniciamos el plugin ahora que tenemos todos estos cambios?

Vea toda la función siguiente:

<?php

add_action( 'plugins_loaded', 'tutsplus_custom_messaging_start' );
/**
 * Starts the plugin.
 *
 * @since 1.0.0
 */
function tutsplus_custom_messaging_start() {

    $plugin = new Submenu(
        new Submenu_Page()
    );
    $plugin->init();

    $messenger = new Settings_Messenger();
    $messenger->init();

    $messenger->add_success_message( 'Nice shot kid, that was one in a million!' );
    $messenger->add_warning_message( 'Do not go gently into that good night.' );
    $messenger->add_error_message( 'Danger Will Robinson.' );
}

Y eso es todo.

Algunos puntos que debe observar:

Si no llama a init en el Settings_Messenger, entonces no tendrá que preocuparse sobre mostrar cualquier mensaje las configuraciones de sus páginas.
El código añade los mensajes al Settings_Messenger, pero de hecho, no recupera ningún debido a que estoy usando el método init.
Si desea recuperar los mensajes, entonces puede usar los métodos que hemos explicado anteriormente.

Y eso es todo para la refactorización. Esto no funcionará exactamente fuera de la caja debido a que todavía hay algo de código que se necesita para cargar todos los archivos PHP que son requeridos para conseguir que el plugin esté funcionando, sin embargo, el código anterior está enfocado en la refactorización que es el punto de todo este tutorial.

En conclusión

Para una versión completa de este tutorial y el código abierto completo que hace funcionar fuera de la caja, por favor descargue el código fuente adjunto de esta publicación en la barra lateral de la derecha.

Espero que por encima del curso de este material usted consiga una cantidad de nuevas habilidades para plantear el desarrollo WordPress. Repasando la serie, hemos abordado bastante:

menús personalizados
introducción a la administración de páginas
los varios tipos de mensajes
definiendo y aprovechando los hooks personalizados
y refactorizando el código orientado a objetos

Como siempre, siempre estoy feliz de responder a las preguntas por medio de comentarios y usted, también puede revisar mi blog y seguirme en Twitter. Generalmente, hablo sobre el desarrollo de programas dentro de WordPress. Si está interesado en más sobre el desarrollo en WordPress, entonces no olvide revisar mis series y tutoriales anteriores y los otros materiales de WordPress que tenemos aquí en Envato Tuts+.

Creando un Sistema de Mensajes Personalizado de WordPress, Parte 4

Empezando con el final

In el tutorial anterior

En el Tutorial Final

Refactorizando Nuestro Trabajo

1. Quitar las configuraciones anteriores de Messenger

2. Una Nueva Configuración de la Clase Messenger

Añadiendo Mensajes

Obteniendo Mensajes

3. Las configuraciones de Messenger

Añadiendo Mensajes

Obteniendo Mensajes

¿Pero entiende eso?

Iniciando el Plugin

En conclusión

Recursos.