Construyendo una Página de Bienvenida para su Producto WordPress: Código Parte 2

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

En mi publicación anterior de esta serie, empece construyendo una página de bienvenida para un plugin de WordPress. Discutimos la arquitectura del plugin y como funciona. Después escribí el código para su base y los archivos inicializadores donde añadimos los bloques de códigos para agregar y eliminar un plugin basado en la activación y desactivación temporal.

En este artículo final, abordaremos lo que queda de los archivos plugin junto con la implementación práctica de un plugin. Para el final de éste artículo, usted estará sumamente consciente del proceso de código de su primera página de bienvenida para un plugin WordPress.

La Lógica para la Redirección de la Página de Bienvenida

El archivo welcome-init.php, define todo lo relevante al código que inicializa los procesos para nuestra página de bienvenida. Éste comienza con agregar y eliminar los transient por medio de las funciones set_transient() (en la activación del plugin) y delete_transient() (en la desactivación del plugin).

Habiendo dicho eso, ahora necesitamos una forma de redireccionar al usuario a nuestra página de bienvenida. Para conseguir la lógica del plugin, he creado un archivo separado al que llame; welcome-logic.php.

Vamos a examinar el código para este archivo:

<?php

/**
 * Welcome Logic
 *
 * @since 1.0.0
 * @package WPW
 */

if ( ! defined( 'WPINC' ) ) {

    die;

}

/**
 * Welcome page redirect.
 *
 * Only happens once and if the site is not a network or multisite.
 *
 * @since 1.0.0
 */
function wpw_safe_welcome_redirect() {

    // Bail if no activation redirect transient is present.
    if ( ! get_transient( '_welcome_redirect_wpw' ) ) {

        return;

    }

  // Delete the redirect transient.
  delete_transient( '_welcome_redirect_wpw' );

  // Bail if activating from network or bulk sites.
  if ( is_network_admin() || isset( $_GET['activate-multi'] ) ) {

    return;

  }

  // Redirect to Welcome Page.
  // Redirects to `your-domain.com/wp-admin/plugin.php?page=wpw_welcome_page`.
  wp_safe_redirect( add_query_arg( array( 'page' => 'wpw_welcome_page' ), admin_url( 'plugins.php' ) ) );

}

add_action( 'admin_init', 'wpw_safe_welcome_redirect' );

Así es que, como hasta ahora sabe, me gusta seguir el estilo de código y la documentación estándar de WordPress, por lo cual hay mucha documentación, aunque algunas de esas documentaciones fueron agregadas para su comprensión.

Hay un archivo llamado DocBlock, el cual es utilizado para dar una perspectiva que está contenida en el archivo. El código comienza con una verificación ABSPATH, que determina la operación del plugin si alguien trata de acceder directamente al archivo del plugin. Después de eso, escribí el código de rutina para una redirección segura.

Luego, definí una función llamada: wpw_sage_welcome_redirect() para controlar de forma segura la redirección hacia la página de bienvenida. Dentro de éste, realice algunas comprobaciones con la condición if, las cuales supervisan el método de redirección. Si ha revisado los artículos anteriores, entonces sabe que definí el transient: _welcome_redirect_wpw, y ajuste su valor a true. Usaré la misma clave para realizar estas comprobaciones. Para obtener una mejor comprehensión del código, usted debe revisar los artículos anteriores en detalle.

Vamos a comenzar con lo que está pasando en la función wpw_safe_welcome_redirect().

Paso #1: Garantice si Ningún Transient está Presente

Yo revise si existe una activación de un transient de redirección, por ejemplo, _welcome_redirect_wpw, por medio de la función get_transient(). Esta función es utilizada para obtener el valor de un transient. Si el transient no existe, entonces no tiene valor, o ha expirado, luego devuelve el valor que será falso.

Por lo tanto, si el valor extraído no es igual a true, entonces no necesitamos redireccionar al usuario hacia una página de bienvenida. Por otra parte, si el valor extraído es true y la activación del transiente extraído está presente, entonces vamos a continuar.

Paso #2: Eliminar el Transient de Redirección

Si el transient _welcome_redirect_wpw devuelve true, eso significa dos cosas: primero que éste está presente en la base de datos, y segundo, que no tenemos redireccionado al usuario hacia la página de bienvenida. Así que vamos a eliminar este transient y a redireccionar al usuario hacia nuestra página de bienvenida.

Paso #3: Garantice si la Activación será desde la red o de un sitio masivo.

Entonces tenemos que verificar otra condición que confirma que una redirección segura hacia una página de bienvenida ocurre solamente para un sitio que no está en una red o en múlti-sitios. No deseamos que la página de bienvenida redireccione si el plugin está siendo activado desde una red.

Paso #4: Redirección Segura hacia la Página de Bienvenida

Finalmente, después de todas estas revisiones, yo redireccione al usuario hacia nuestra página de bienvenida. La función wp_safe_redirect( $location ) realiza una redirección local y le dice al servidor acerca de la $location para redireccionar al usuario.

Para definir la ubicación, yo utilice una función add_query_arg() que recupera una consulta string URL modificada. Ocupa un arreglo asociado que tiene un par de key-value junto con la ubicación URL.

En este caso, estoy creando un key llamado page con un value wpw_welcome_page y redireccionandolo hacia el archivo plugins.php por medio de la función admin_url(). Esto significa que estoy redireccionando al usuario hacia una página personalizada dentro del menú Plugin, y el usuario será redireccionado hacia la URL: your-domain.com/wp-admin/plugin.php?page=wpw_welcome_page.

Después, enganche toda la función wpw_safe_welcome_redirect() hacia la admin_init.

Añadiendo un Sub-Menú a la Página de Bienvenida

Hasta el momento, he definido el procedimiento para una redirección segura. La ubicación es una page que existe dentro del menú PLUGINS. Pero aún no he creado la página. Ahora vamos a crear una página de bienvenida dentro del menú Plugins.

El resto del código del archivo welcome-logic.php es:

/**
 * Adds welcome page sub menu.
 *
 * @since 1.0.0
 */
function wpw_welcome_page() {

  global $wpw_sub_menu;

  $wpw_sub_menu = add_submenu_page(
      'plugins.php', // The slug name for the parent menu (or the file name of a standard WordPress admin page).
      __( 'Welcome Page', 'wpw' ), // The text to be displayed in the title tags of the page when the menu is selected.
      __( 'Welcome Page', 'wpw' ), // The text to be used for the menu.
      'read', // The capability required for this menu to be displayed to the user.
      'wpw_welcome_page', // The slug name to refer to this menu by (should be unique for this menu).
      'wpw_welcome_page_content' // The function to be called to output the content for this page.
  );

}

add_action( 'admin_menu', 'wpw_welcome_page' );

/**
 * Welcome page content.
 *
 * @since 1.0.0
 */
function wpw_welcome_page_content() {

    if ( file_exists( WPW_DIR . '/welcome/welcome-view.php') ) {

       require_once( WPW_DIR . '/welcome/welcome-view.php' );

    }
}

Para añadir el sub-menú, he creado una función wpw_welcome_page() dentro, la cual he llamado la función add_submenu_page().

La función add_submenu_page() añade una página dentro de un menú. Éste toma una lista de parámetros:

$parent_slug (Requerido): La indicación o nombre del archivo para el menú principal.
$page_title (Requerido): El texto que va a ser mostrado en los títulos de las etiquetas de la página cuando el menú es seleccionado.
$menu_title (Requerido): El texto que va a ser utilizado en el menú.
$capability (Requerido): La capacidad requerida para este menú que va a ser mostrado al usuario.
$menu_slug (Requerido): El nombre indicador para hacer referencia a este menú (deberá ser único para este menú). Éste es wpw_welcome_page, el mismo que definimos durante la función de redirección segura.
$function (Opcional): La función de devolución a ser llamada para sacar el contenido para esta página.

Definí los valores de estos parámetros y finalmente, agregue la función wpw_welcome_page() como add_action para el admin_menu.

Ahora necesitamos manejar el contenido de la página de bienvenida para lo cual he creado una función llamada: wpw_welcome_page_content() (esta es la función de devolución para add_submenu_page() que requiere el archivo welcome-view.php.

Puede haber notado que he creado una variable global $wpw_sub_menu que contiene el ID de la pantalla de la página para nuestro sub-menu de la página. Usaremos esto en la próxima sección.

Ponga en espera el Style.css personalizado

Justo después de todo esto, he puesto en espera un archivo style.css para los estilos personalizados de los elementos en nuestra página de bienvenida. Dentro del código anterior, ajuste una variable global $wpw_sub_menu que contiene el ID de la pantalla del sub-menu de la página.

Podemos verificar está identificación de pantalla mientras ponemos en espera nuestro archivo de estilos para asegurarnos que está en espera solamente cuando estamos navegando en la página de bienvenida y no en cualquier parte de la admin. Eso es lo que hace el siguiente código.

/**
 * Enqueue Styles.
 *
 * @since 1.0.0
 */
function wpw_styles( $hook ) {

    global $wpw_sub_menu;

    // Add style to the welcome page only.
    if ( $hook != $wpw_sub_menu ) {

      return;

    }

    // Welcome page styles.
    wp_enqueue_style(
      'wpw_style',
      WPW_URL . '/welcome/css/style.css',
      array(),
      WPW_VERSION,
      'all'
    );

}

// Enqueue the styles.
add_action( 'admin_enqueue_scripts', 'wpw_styles' );

La lógica de nuestra página de bienvenida está completa. Usted puede visualizar el código completo para el archivo welcome-logic.php en GitHub.

Vista de la Página de Bienvenida

Ahora que la lógica de nuestra página de bienvenida está completa, usted puede, de hecho, probar el plugin creado, y redireccionarse hacia la página de bienvenida. Lo único que queda por hacer es construir la vista de su página de bienvenida. Esto podría ser cualquier cosa que quisiera, pero quiero dejarle con algo de boilerplate por razones obvias.

La parte HTML y CSS del plugin se encuentra dentro del archivo welcome-view.php. El código es el siguiente:

<?php

/**
 * Welcome Page View
 *
 * @since 1.0.0
 * @package WPW
 */

if ( ! defined( 'WPINC' ) ) {

    die;

}

?>

El archivo comienza como un archivo normal PHP con un DocBlock y después el código para una verificación ABSPATH, para que nadie pueda tener acceso al archivo de forma directa. Después de eso, cree una variable para la versión del plugin y la ruta para nuestra imagen del logo.

Estilos CSS

He añadido una carpeta llamada css y un archivo llamado style.css dentro de éste para crear algunos estilos personalizados para la página de bienvenida. El código luce así: Este es el código utilizado para modificar la clase extra que agregue para nuestro logo (Usted puede agregarla como quiera, yo solamente he escrito sobre el logo de WP para conservar las cosas simples para los propósitos de este tutorial).

/* Logo */
.svg .wp-badge.welcome__logo {
    background: url('../img/logo.png') center 24px no-repeat #0092f9;
    background-size: contain;
    color: #fff;
}

/* Responsive Youtube Video*/
.embed-container {
    height: 0;
    max-width: 100%;
    overflow: hidden;
    padding-bottom: 56.25%;
    position: relative;
}

.embed-container iframe,
.embed-container object,
.embed-container embed {
    top: 0;
    height: 100%;
    left: 0;
    position: absolute;
    width: 100%;
}

Después de eso, está la parte HTML de nuestra página. Hay un vídeo YouTube integrado como un vídeo que es flexible.

La parte HTML de la página de bienvenida es igual a la página de bienvenida de WordPress. Los beneficios de eso es que no tenemos que escribir más código CSS y, además, los usuarios ya están familiarizados con el formato integrado.

Los plugins son extensiones para WordPress. Usted puede extender WordPress por medio de la creación de un plugin, por esta razón es que creo que usted siempre debe usar los estilos y apariencias por defecto que ya están integrados para mantener las cosas más en línea con el panel de control de WordPress. Algunos plugins añaden iconos de color y fondos pesados o todo lo demás, pero al final del día terminan por desconcertar una tranquila experiencia de usuario.

Estoy seguro que los desarrolladores de plugins tienen muy buen conocimiento del lenguaje de programación de HTML. De cualquier forma, aquí está el código.

<div class="wrap about-wrap">

    <h1><?php printf( __( 'WordPress Product &nbsp; %s', 'WPW' ), WPW_VERSION ); ?></h1>

    <div class="about-text">
        <?php printf( __( "WordPress Product's welcome page boilerplate for WordPress plugins.", 'WPW' ), WPW_VERSION ); ?>
    </div>

    <div class="wp-badge welcome__logo"></div>

    <div class="feature-section one-col">
        <h3><?php _e( 'Get Started', 'WPW' ); ?></h3>
        <ul>
            <li><strong><?php _e( 'Step #1:', 'WPW' ); ?></strong> <?php _e( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.', 'WPW' ); ?></li>
            <li><strong><?php _e( 'Step #2:', 'WPW' ); ?></strong> <?php _e( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.', 'WPW' ); ?></li>
            <li><strong><?php _e( 'Step #3:', 'WPW' ); ?></strong> <?php _e( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.', 'WPW' ); ?></li>
        </ul>
     </div>

    <div class="feature-section one-col">
        <h3><?php _e( 'What is Inside?', 'WPW' ); ?></h3>
        <div class="headline-feature feature-video">
            <div class='embed-container'>
                <iframe src='https://www.youtube.com/embed/3RLE_vWJ73c' frameborder='0' allowfullscreen></iframe>
            </div>
        </div>
    </div>

    <div class="feature-section two-col">
        <div class="col">
            <img src="http://placehold.it/600x180/0092F9/fff?text=WELCOME" />
            <h3><?php _e( 'Some Feature', 'WPW' ); ?></h3>
            <p><?php _e( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras sed sapien quam. Sed dapibus est id enim facilisis, at posuere turpis adipiscing. Quisque sit amet dui dui.', 'WPW' ); ?></p>
        </div>
        <div class="col">
            <img src="http://placehold.it/600x180/0092F9/fff?text=WELCOME" />
            <h3><?php _e( 'Some Feature', 'WPW' ); ?></h3>
            <p><?php _e( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras sed sapien quam. Sed dapibus est id enim facilisis, at posuere turpis adipiscing. Quisque sit amet dui dui.', 'WPW' ); ?></p>
        </div>
    </div>

    <div class="feature-section two-col">
        <div class="col">
            <img src="http://placehold.it/600x180/0092F9/fff?text=WELCOME" />
            <h3><?php _e( 'Some Feature', 'WPW' ); ?></h3>
            <p><?php _e( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras sed sapien quam. Sed dapibus est id enim facilisis, at posuere turpis adipiscing. Quisque sit amet dui dui.', 'WPW' ); ?></p>
        </div>

        <div class="col">
            <img src="http://placehold.it/600x180/0092F9/fff?text=WELCOME" />
            <h3><?php _e( 'Some Feature', 'WPW' ); ?></h3>
            <p><?php _e( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras sed sapien quam. Sed dapibus est id enim facilisis, at posuere turpis adipiscing. Quisque sit amet dui dui.', 'WPW' ); ?></p>
        </div>
    </div>

</div>

El código muestra la siguiente composición:

título del plugin, versión, descripción y el logotipo
un breve tutorial de inicio en la forma de pasos
un vídeo tutorial de ayuda por medio de YouTube
una lista de dos columnas de las funciones del plugin

Al momento de escribir este tutorial, usted puede usar las siguientes clases CSS para crear columnas:

.feature-section junto con .one-col: para crear una sola columna.
.feature-section junto con .two-col: para crear dos columnas.
.feature-section junto con .three-col: para crear tres columnas.

Esto completa el desarrollo de nuestro plugin. Ahora vamos a probarlo en un sitio web de muestra.

Implementación Práctica

Para probar el plugin en un sitio web de muestra, puede descargar en instalar el WP-Welcome-Page-Boilerplate-For-TutsPlus desde GitHub.

Después de eso, realizar los siguientes pasos:

Conectarse al panel de control de WordPress.
Ir al menú Plugins y hacer clic en Add New.
Hacer clic en el botón Upload Plugin y agregar el archivo comprimido que ha descargado desde GitHub.
Instale y active el plugin.

¡Voila! ¿Ha sido redireccionado hacia la página de bienvenida?

Una vez que ha terminado, regrese a la página de inicio del panel de control y pase su mouse sobre el menú Plugins. Un sub-menú adicional está agregado, nombrado como Welcome Page. Para recordarle nuevamente, que está es la misma página que creo anteriormente.

Por cierto, la página de bienvenida final luce así.

Aquí está la composición completa de la pantalla de bienvenida.

En conclusión

Así es como usted puede crear una página de bienvenida para su plugin de WordPress. He descrito una implementación muy básica. Sin embargo, usted puede modificarla de acuerdo a sus requerimientos. Le recomendaría descargar la carpeta welcome e incluir el archivo welcome-init.php a su producto (cambiar las constantes globales en los archivos welcome-*.php).

Finalmente, puede recoger todos mis cursos y tutoriales de mi página de perfil y puede seguirme en mi blog y/o dirigirse a mi cuenta en Twitter @mrahmadawais donde escribo acerca de flujos de desarrollo en el contexto de WordPress.

Como siempre, no dude en dejar preguntas o comentarios abajo, intentaré responder cada uno de ellos.

1	<?php
2
3	/**
4	* Welcome Logic
5	*
6	* @since 1.0.0
7	* @package WPW
8	*/
9
10	if ( ! defined( 'WPINC' ) ) {
11
12	die;
13
14	}
15
16	/**
17	* Welcome page redirect.
18	*
19	* Only happens once and if the site is not a network or multisite.
20	*
21	* @since 1.0.0
22	*/
23	function wpw_safe_welcome_redirect() {
24
25	// Bail if no activation redirect transient is present.
26	if ( ! get_transient( '_welcome_redirect_wpw' ) ) {
27
28	return;
29
30	}
31
32	// Delete the redirect transient.
33	delete_transient( '_welcome_redirect_wpw' );
34
35	// Bail if activating from network or bulk sites.
36	if ( is_network_admin() \|\| isset( $_GET['activate-multi'] ) ) {
37
38	return;
39
40	}
41
42	// Redirect to Welcome Page.
43	// Redirects to `your-domain.com/wp-admin/plugin.php?page=wpw_welcome_page`.
44	wp_safe_redirect( add_query_arg( array( 'page' => 'wpw_welcome_page' ), admin_url( 'plugins.php' ) ) );
45
46	}
47
48	add_action( 'admin_init', 'wpw_safe_welcome_redirect' );