Creando un Sistema Personalizado de Mensajería Para WordPress, Parte 2

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

Si apenas te estás poniendo al corriente con esta serie en particular, estamos en el proceso se construir nuestro propio sistema personalizado de mensajería que se engancha a WordPress, permitiéndonos sacar ventaja de algunas APIs existentes, pero también permitiendonos un poco más de control.

Del tutorial previo:

Pero como vimos en cómo crear páginas personalizadas de administración, también es posible implementar un sistema que nos permita establecer nuestros propios mensajes personalizados de manera programática, su tipo y cuándo y dónde mostrarlos en la página de administración.

Aunque no es requerido leer la serie que precede a esta, recomiendo altamente leer el tutorial anterior. Cada uno de estos se contruye sobre los fundamentos del tutorial anterior (y continuaremos haciéndolo para el resto de la serie).

Dicho eso, todo el propósito de esta serie es dar una introducción sobre cómo sacamos ventaja de la API de WordPress y la programación orientada a objetos para crear un sistema de mensajes personalizados que podemos usar en todo el trabajo que podríamos estar haciendo para un cliente.

Pero antes de comenzar, hay algunos cuantos prerrequisitos que deberías tener en orden.

Antes de Que Comiences

Lee el artículo previo
Instala PHP 5.6.25 y MySQL 5.6.28.
Instala Apache o Ngnix
Configura WordPress 4.6.1
Ten listo tu IDE o editor favorito.

Si estás buscando una solución todo en uno, revisa MAMP y si estás interesado en cómo todo esto encaja, entonces revisa estos artículos.

Nuestro Mapa

En caso de que no hayas podido leer el tutorial previo, el mapa que hemos establecido para este tutorial es como sigue:

En este tutorial, vamos a establecer el trabajo preparatorio para apenas el mínimo de nuestro complemento y lo que necesitamos para comenzar.
En esta segunda pieza, vamos a llevar un poco más allá el complemento agregando una página muy básica de administración de WordPress. También estaremos haciendo una llamada al gancho personalizado que usaremos y lo conectaremos en el lado del servidor. También comenzaremos el trabajo previo para nuestros Ajustes de Mensajería.
En este tutorial, comenzaremos implementando nuestras Configuraciones de Mensajero agregando soporte para errores y mensajes de éxito así como cubrir algunos puntos sobre seguridad.
Terminaremos atando todo de manera conjunta, viéndolo en acción y habilitando de manera pública el complemento para que lo descargues.

Obviamente, hemos logrado el número uno. Así que en este tutorial, nos vamos a enfocar especialmente en agregar una página básica de administración y configurando un gancho personalizado que nos permitirá sacar ventaja de nuestro mensajero personalizado.

Volviendo al Trabajo

Con todo eso cubierto, regresemos al desarrollo. Recuerda qué, en este punto, deberíamos tener los fundamentos de este complemento establecidos de manera que podamos activarlo y navegar a Ajustes y después Tuts+ Custom Message Example para ver una página genérica de administración.

Si nos has seguido hasta ahora, el código de la página es extremadamente simple (y veremos un poco después en el tutorial), también:

<div class="wrap">

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

    <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 -->

Estoy reiterando esto porque aquí es donde vamos a comenzar a implementar nuestro propio mensajero personalizado.

Para hacer esto, vamos a necesitar introducir lo siguiente:

un gancho que definamos
una función que esté registrada con ese gancho
mostrar algo cuando la función sea disparada

Definiendo un Gancho Personalizado

Definir un gancho personalizado suena más intimidante de lo que en realidad es. La mayoría de nosotros está familiarizado con hacer llamadas a add_action y add_filter, pero ¿cómo podemos usar estas funciones para hacer una llamada a nuestros propios ganchos?

Fácil: Usamos do_action y definimos nuestra acción que registraremos con WordPress. Por ejemplo, toma el código de arriba y, justo abajo de la etiqueta h1, hagamos lo siguiente:

<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 -->

Nada mal, ¿verdad? Ahora necesitamos registrar una función que se disparará siempre que ese gancho sea llamado. Antes de que hagamos eso, quiero asegurarme de que estamos todos en la misma página sobre lo que do_action realmente hace.

Aquí esta lo que el documento de desarrollador dice sobre do_action:

Esta función invoca a todas las funciones atadas a la acción de gancho $tag. Es posible crear nuevos ganchos de acción simplemente llamando a esta función, especificando el nombre de nuestro nuevo gancho usando el parámetro $tag.

Si la definición no está clara, quizá su implementación ayudará. Así que echemos un vistazo a eso ahora.

2. Registrar una Función

Justo como hacemos con cualquier otro tipo de función, necesitamos registrar una función que se disparará siempre que nuestro gancho tutsplus_settings_messages es disparado. Pero ya que estamos trabajando con programación orientada a objetos, vamos a necesitar diseñar una clase que defina a esta función.

Y aquí es donde nuestro mensajero de ajustes personalizado entrará en juego primero. Dado eso, no estaremos haciendo demasiado trabajo en términos de agregar mensajes personalizados, pero estaremos usando nuestro gancho personalizado y estaremos generando algo en la página.

Además, estaremos asentando el fundamento de la clase que estaremos mejorando en la siguientes lecciones. Desde aquí, agrega el archivo class-settings-messenger.php al directorio admin en tu complemento (y no te preocupes, todo esto estará disponible para descarga).

<?php

class Settings_Messenger {

    public function init() {

    }
}

Recuerda que no estaremos usando namespaces o autoloaders en este tutorial (aunque los hemos cubierto anteriormente). Nota que estaré proporcionando código para el método init momentariamente.

Por ahora, regresa al archivo bootsrap del complemento, tutsplus-custom-message.php, y agrega el siguiente código a la función principal:

<?php

function tutsplus_custom_messaging_start() {

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

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

Ahora revisitemos la función init en el Settings_Messenger y enganchemoslo a nuestra acción personalizada.

<?php

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

Nota en el código de arriba, el primer argumento que estamos pasando a add_action es el nombre de nuestro gancho personalizado. Lo segundo va a ser el método que generará un mensaje en la página de administración. Solo que no lo hemos escrito aún (así que si intentas ejecutar este código, obtendrás un error).

Pero cambiemos eso.

3. Mostrando un Mensaje Personalizado

Primero, crea la función en la clase Settings_Messenger llamada display_message, e imprimamos simplemente una declaración para ver si se está mostrando en la página personalizada que hemos creado.

<?php

public function display_message() {
    echo 'This is an example message.';
}

Y cuando ejecutes el código, deberías ver algo como esto. Mira detenidamente bajo la etiqueta h1 y deberías ver la sentencia que incluímos arriba.

An example of the message we want to display

Aquí está el problema, sin embargo: El mensaje que estamos mostrando no concuerda con nada del marcado que WordPress usa para mostras mensajes de éxito, advertencias o errores.

Estaremos cubriendo esto a detalle después en la serie, pero continuemos y mostremos un mensaje de éxito. Después de todo, hemos llegado hasta aquí, ¿verdad? Estamos mostrando nuestro propio mensaje a través de un gancho personalizado usando una clase de mensajero que hemos creado.

Hay una cantidad de maneras en las que podemos hacer esto: Podemos usar un archivo de plantilla, podemos usar marcado en la función y sanitizarla ahí, o podemos incluir el archivo en la función. Para los propósitos de este tutorial, voy a crear el marcado en la función y usar wp_kses para sanitizar el código.

Esto no es normalmente como recomendaría hacerlo, pero es una manera en la que se puede lograr, y también nos expone a wp_kses, la cuál es una función que deberíamos estar usando todos cuando generamos información en el navegador.

Usa este código:

<?php

public function display_message() {

    $html = "
        <div class='notice notice-success'>
            <p>You have successfully displayed a custom success message.</p>
        </div><!-- .notice-success -->
    ";

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

    echo wp_kses( $html, $allowed_html );
}

Y esto debería resultar en la siguiente captura:

Nota que el mensaje persiste. No hay un botón de guardar, no hay manera de esconder este mensaje y no hay manera de cambiar este mensaje fuera del código. Pero está bien, porque ese no es el punto de este ejercicio.

Unas cuantas que quiero mencionar, de todas formas:

Los atributos de la clase en el elemento div que ves son tomados directamente desde WordPress. Así que podemos heredar esos estilos.
Algunos mensajes pueden dejarse de lado. Cubriremos esto en un tutorial futuro.
El arreglo $allowed_html pasado a wp_kses es lo que asegura que nada más que los elementos especificados y atributos son generados. Es una manera muy buena, sólida y limpia de sanitizar datos.

Y eso es todo lo que hay que cubrir en este tutorial en particular; sin embargo, solo estamos comenzando.

Conclusión

Mientras progresamos en esta serie, vamos a echar un vistazo a cómo manejar mensajes de éxito, mensajes de error y mensajes de advertencia y cómo introducir la habilidad para dejar de lado mensajes.

También, vamos a poder ver cómo usar datos de entrada del usuario para controlar el tipo de mensaje que se muestra.

Nota que siempre estoy contento de contestar cualquier pregunta a través de los comentarios y también puedes revisar mi blog y seguirme en Twitter. Usualmente hablo sobre desarrollo de software dentro de WordPress y tópicos tangenciales de igual manera.

Hasta el próximo tutorial, descarga los archivos, estudia el código y mira como se ejectua en tu máquina local. En la siguiente parte, continuaremos exactamente en donde nos quedamos.