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

En los primeros dos artículos de esta serie, escribí acerca de lo que son las páginas de bienvenida y como ayudan a los productos a mejorar la experiencia de los usuarios a través de conectar los puntos, después escribí sobre WordPress Transients API que destine a usar mientras construía la página de bienvenida.

El código de una página de bienvenida para su plugin WordPress puede ser un proceso complicado.

Plantilla de Página de Bienvenida Boilerplate de WP

Voy a crear una plantilla de página de bienvenida para WordPress en el formulario de un plugin que podría ser utilizado dentro de su producto WordPress. El formulario final de éste plugin está alojado en GitHub en WP-Welcome-Page-Boilerplate-For-TutsPlus.

En este punto, estoy asumiendo que tiene la siguiente configuración:

• una máquina local o un servidor web
• un panel de control de un sitio web de demostración de WordPress

Arquitectura Plugin

Voy a crear un plugin sencillo que mostrará una página de bienvenida cuando un usuario instale y active el plugin. Vamos a analizar la arquitectura del plugin:

• WP-Welcome-Page-Boilerplate: es la carpeta que contiene nuestro plugin.
• WP-Welcome-Page-Boilerplate/welcome: es la carpeta para lo relacionado a la página de bienvenida.
• WP-Welcome-Page-Boilerplate/welcome/img: es la carpeta para las imágenes.
  
• wp-welcome-page-boilerplate.php: El archivo principal del plugin en la raíz. Este archivo es responsable de definir las constantes globales y la necesidad de inicializar el archivo, por ejemplo, welcome-inti.php.
• welcome-init.php: El archivo inicializador que es responsable de tres cosas: añadir un transient cuando el plugin se activará, eliminándolo cuando el plugin sea desactivado y, finalmente, añadiendo el archivo lógico, por ejemplo, welcome-logic.php.
  
• welcome-logic.php: El archivo lógico que es responsable por la seguridad de la redirección de la página de bienvenidad, creando el sub-menú de la página de bienvenida y añadiendo el archivo vista de la página de bienvenida, por ejemplo, welcome-logic.php.
  
• welcome-view.php: el archivo vista que es responsable por mostrar la página de bienvenida y es creado con PHP y HTML.
• Hay carpetas opcionales para las imágenes y CSS, y éstas están nombradas de acuerdo a su propósito. 

Puede ver la siguiente captura de pantalla para verificar la arquitectura.

Flujo de trabajo del Plugin

El pllugin funciona de la siguiente manera:

• Añada un transient a la activación del plugin.
• Elimina un transient en la desactivación del plugin.
• Segura redirección a la página de bienvenida.

Archivo base estándar del Plugin

Vamos a comenzar nuestro análisis con los contenidos del archivo base, el cual es wp-welcome-page-boilerplate.php. Aquí está el código completo:

1

<?php

2

3

/**

4

 * Plugin Name: WP Welcome Page Boilerplate

5

 * Plugin URI: https://code.tutsplus.com/articles/building-a-welcome-page-for-your-wordpress-product-introduction--cms-26013

6

 * Description: Welcome page boilerplate for WordPress plugins.

7

 * Version: 1.0.0

8

 * Author: mrahmadawais, WPTie

9

 * Author URI: http://AhmadAwais.com/

10

 * License: GPL-3.0+

11

 * License URI: http://www.gnu.org/licenses/gpl-3.0.html

12

 * Domain Path: /lang

13

 * Text Domain: WPW

14

 */

15

16

if ( ! defined( 'WPINC' ) ) {

17

18

    die;

19

20

}

La sección encabezado PHPDoc del plugin le dice a WordPres que un archivo es un plugin. En un mínimo, un encabezado puede contener solamente el nombre de un Plugin, pero varias piezas pueden —y, por lo general, deben— ser incluidas. Puede leer los requerimientos del encabezado en el Manual de Desarrollo de Plugin en WordPress. 

El siguiente conjunto de código realiza una revisión de seguridad. Si alguien trata de acceder a este archivo directamente, éste ejecuta el ABSPATH, que termina el script si tiene acceso desde afuera de WordPress.

Después de eso, el código luce así:

1

// Plugin version.

2

if ( ! defined( 'WPW_VERSION' ) ) {

3

4

    define( 'WPW_VERSION', '1.0.0' );

5

6

}

7

8

// Plugin folder name.

9

if ( ! defined( 'WPW_NAME' ) ) {

10

11

    define( 'WPW_NAME', trim( dirname( plugin_basename( __FILE__ ) ), '/' ) );

12

13

}

14

15

// Plugin directory, including the folder.

16

if ( ! defined( 'WPW_DIR' ) ) {

17

18

    define( 'WPW_DIR', WP_PLUGIN_DIR . '/' . WPW_NAME );

19

20

}

21

22

// Plugin url, including the folder.

23

if ( ! defined( 'WPW_URL' ) ) {

24

25

    define( 'WPW_URL', WP_PLUGIN_URL . '/' . WPW_NAME );

26

27

}

28

29

// Plugin root file.

30

if ( ! defined( 'WPW_PLUGIN_FILE' ) ) {

31

32

    define( 'WPW_PLUGIN_FILE', __FILE__ );

33

34

}

He definido algunas constantes globales que definen detalles sobre la versión del plugin, carpeta raíz, URL, y el archivo principal del plugin.

Cada uno de estos contiene una condición if( ! defined() ), que ayuda a evitar cualquier error debido a la redefinición de una constante global. Recomiendo definir las constantes globales con su nombre de paquete como un prefijo. El nombre de paquete en este plugin es WPW, por ejemplo; WordPress Welcome. De éste modo, cada constante tiene un prefijo WPW_.

Las constantes definidas del plugin son:

• WPW_VERSION: Versión del Plugin.
• WPW_NAME: Nombre de la carpeta del Plugin.
• WPW_DIR: Directorio del Plugin.
• WPW_URL: URL del Plugin.
• WPW_PLUGIN_FILE: Raíz del Archivo Plugin.

Una vez que todas éstas constantes están definidas, comenzaremos con el contenido de nuestro archivo de bienvenida.

Finalmente, requiero el inicializador de bienvenida y la lógica.

1

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

2

3

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

4

5

}

6

7

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

8

9

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

10

11

}

Me gusta conservar mi código los más corto posible, y bien documentado. De éste modo, en lugar de añadir cada bloque de código en un solo archivo, prefiero hacer archivos individuales, cada uno sólo con un propósito. Es por eso que tenemos un archivo inicializador que inicializa todo lo relacionado a la página de bienvenida.

La condición require_once() requiere el archivo welcome-init.php, pero antes de requerir un archivo, siempre lo reviso con la función PHP; file_exists() para evitar cualquier error fatal en caso de que el archivo esté eliminado.

El mismo principio aplica para la lógica de la página de bienvenida, que veremos más adelante en la siguiente parte de esta serie.

Usted puede revisar el código final del archivo wp-welcome-page-boilerplate.php en GitHub.

Inicializador de Bienvenida

Para administrar todos los archivos relacionados con la página de bienvenida, creo una carpeta separada llamada; welcome, y agrego el archivo welcome-init.php. El código entero de este archivo controla la inicialización de la página de bienvenida.

Vamos a estudiar el código completo de este archivo:

1

<?php

2

3

/**

4

 * Welcome Page Init

5

 *

6

 * Welcome page initializer.

7

 *

8

 * @since 1.0.0

9

 */

10

11

if ( ! defined( 'WPINC' ) ) {

12

13

    die;

14

15

}

16

17

/**

18

 * Activates the welcome page.

19

 *

20

 * Adds transient to manage the welcome page.

21

 *

22

 * @since 1.0.0

23

 */

24

function wpw_welcome_activate() {

25

26

    // Transient max age is 60 seconds.

27

    set_transient( '_welcome_redirect_wpw', true, 60 );

28

29

}

30

31

register_activation_hook( WPW_PLUGIN_FILE, 'wpw_welcome_activate' );

32

33

/**

34

 * Deactivates welcome page

35

 *

36

 * Deletes the welcome page transient.

37

 *

38

 * @since 1.0.0

39

 */

40

function wpw_welcome_deactivate() {

41

42

  delete_transient( '_welcome_redirect_wpw' );

43

44

}

45

46

register_deactivation_hook( WPW_PLUGIN_FILE, 'wpw_welcome_deactivate' );

El código comienza con una documentación en línea sobre el archivo y una verificación ABSPATH. Ahora necesito una forma de añadir y eliminar el transient cuando el plugin está activado y, respectivamente, desactivado.

Por fortuna, WordPress nos brinda dos hooks para éste propósito exacto.

• register_activation_hook( string $file, callable #function ): Este hook es activado cuando el plugin es activado. Éste, toma el $file principal del plugin y la función callable como parámetros.
• register_deactivation_hook( string $file, callable $function ): Este hook es activado cuando el plugin se desactiva. Éste, toma el $file principal del plugin y la función callable como parámetros.

Así que ahora necesitamos hacer uso de estos hooks. Yo cree un transient para la página de bienvenida. La función set_transient() es llamada dentro de la función personalizada; wpw_welcome_activate(). En el artículo anterior, aprendió que la operación set tome un key y un value y una expiración de tiempo como sus parámetros.

Por lo tanto, la key _welcome_redirect_wpw está ajustado como un valor true durante 60 segundos. Esto define la edad máxima después de que el transient expira.

Después está la activación del hook, y como sabemos, éste hook se ejecuta solamente cuando un plugin está activado. Éste añade nuestro transient a la base de datos. Una vez que el transient está en la base de datos, significa que podemos revisarlo y redireccionar el usuario a nuestra página de bienvenida. ¿Cómo redireccionar al usuario? Bueno, eso es lo que estudiaremos en el siguiente artículo.

Después de eso, escribí el código que se ejecuta tras la desactivación del plugin. Queremos una funcionalidad donde el transient es eliminado cuando un usuario desactiva el plugin. Para hacer eso, llamo a la función delete_transient(), que toma la key: _welcome_redirect_wpw, como su parámetro. Luego, está la función wpw_welcome_deactivate(), que es agregada el hook de desactivación del plugin.

Esta parte es opcional, pero quiero que mis usuarios vean la página de bienvenida siempre que ignore la eliminación de su transient.

Hasta el momento, hemos discutido la parte del código que es necesaria para crear y eliminar un transient. Sin embargo, aún falta el código para nuestra lógica de la página de bienvenida, el cual redireccionaría a los usuarios hacia la página de bienvenida. Abordaremos eso después.

En conclusión

Eso es todo por hoy. Estamos a mitad del camino. El archivo base y el inicializador de nuestra página de bienvenida están listos. Ahora necesitamos crear la lógica y los archivos vista, lo cual es el plan para el siguiente artículo.

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.