El Welcome Wizard: clase y pasos
Cómo crear un asistente de bienvenida que aparece automáticamente cuando el plugin se activa por primera vez.
includes/class-wizard.phpcon la clase PHP del Welcome Wizard. No se modifica ningún otro archivo.
¿Qué es un Welcome Wizard?
Cuando instalás un plugin en WordPress, lo habitual es que aparezca una pantalla de bienvenida. Esa pantalla se llama Welcome Wizard (asistente de bienvenida) y tiene un objetivo simple:
En nuestro caso, el wizard va a tener tres pasos:
Bienvenida
Presentación del plugin y qué hace.
Requisitos
Verifica que LearnPress y Divi estén activos.
Listo
Confirmación y enlace al Dashboard.
Lo importante es que este wizard aparece solo, automáticamente, en el momento en que activás el plugin — sin que el usuario tenga que buscarlo en ningún menú.
Cómo funciona la redirección automática
Para que el wizard aparezca solo, usamos un truco clásico de WordPress. Es un proceso de cuatro pasos que ocurre en fracciones de segundo:
WordPress ejecuta la función
dlms_on_activation() que ya escribimos en la lección anterior.
add_option('dlms_show_wizard', '1') — es como dejar una nota que dice «muestra el wizard la próxima vez».
Se dispara el hook
admin_init. Nuestro método maybe_redirect() detecta la bandera y borra la opción para que no redirija nunca más.
wp_safe_redirect() lleva al usuario a la URL del wizard. La pantalla aparece sola, sin que el usuario haga nada.
Archivo que se completa hoy
Dentro de la carpeta del plugin, completamos este archivo:
├── divi-lms-helper.php
└── includes/
├── class-wizard.php <– ESTA LECCIÓN
├── class-shortcodes.php <– Lección 5.3
├── class-admin-page.php <– Lección 5.5
└── class-assets.php <– Lección 5.4
En la lección 5.1 este archivo existía como «esqueleto» vacío, solo para que PHP no diera error al cargarlo. Hoy lo completamos con el código real del wizard.
La clase DLMS_Wizard y sus métodos
Toda la lógica del wizard vive en una clase PHP llamada DLMS_Wizard. Una clase es simplemente un contenedor que agrupa funciones relacionadas bajo un mismo nombre. En WordPress, este patrón es muy común para mantener el código organizado.
La clase tiene cuatro métodos (funciones). Cada uno hace una cosa concreta:
| Método | Hook de WP | ¿Qué hace? |
|---|---|---|
__construct() |
— | Se ejecuta al crear la clase. Conecta los otros métodos a los hooks de WordPress. |
register_page() |
admin_menu |
Registra la página del wizard en el Dashboard de WP (visible solo para administradores). |
maybe_redirect() |
admin_init |
Revisa si la opción dlms_show_wizard existe. Si sí, borra la opción y redirige al wizard. |
inline_styles() |
admin_head |
Agrega CSS solo en la página del wizard (para no cargar estilos innecesarios en todo el admin). |
render() |
— | Dibuja el contenido HTML del wizard. Lee el parámetro ?step= de la URL para saber qué paso mostrar. |
Al final del archivo, una línea simple instancia la clase: new DLMS_Wizard(); — esto hace que el constructor se ejecute y todos los hooks queden registrados.
El código del wizard
Este es el contenido completo de class-wizard.php. Está dividido en bloques comentados para que sea fácil de seguir:
/**
* Divi LMS Helper — Welcome Wizard
* Asistente de bienvenida al activar el plugin.
*/
if ( ! defined( ‘ABSPATH’ ) ) { exit; }
class DLMS_Wizard {
// ── Constructor: conectar los hooks de WordPress ──────────────
public function __construct() {
add_action( ‘admin_menu’, [ $this, ‘register_page’ ] );
add_action( ‘admin_init’, [ $this, ‘maybe_redirect’ ] );
add_action( ‘admin_head’, [ $this, ‘inline_styles’ ] );
}
// ── Registrar la página del wizard en el Dashboard ─────────────
public function register_page() {
add_dashboard_page(
‘Bienvenido a Divi LMS Helper’, // Título de la pestaña
‘Divi LMS Helper’, // Título en el menú
‘manage_options’, // Solo para administradores
‘dlms-wizard’, // Slug (parte de la URL)
[ $this, ‘render’ ] // Función que dibuja el contenido
);
}
// ── Redirigir automáticamente al wizard tras la activación ─────
public function maybe_redirect() {
// Solo redirigir si la opción existe
if ( ! get_option( ‘dlms_show_wizard’ ) ) {
return;
}
// No redirigir durante llamadas AJAX (evita bucles)
if ( wp_doing_ajax() ) {
return;
}
// Borrar la opción para que no redirija la próxima vez
delete_option( ‘dlms_show_wizard’ );
// Ir al wizard
wp_safe_redirect( admin_url( ‘index.php?page=dlms-wizard’ ) );
exit;
}
// ── Estilos del wizard (solo en la página del wizard) ──────────
public function inline_styles() {
$screen = get_current_screen();
if ( ! $screen || ‘dashboard_page_dlms-wizard’ !== $screen->id ) {
return;
}
// … estilos CSS del wizard (ver archivo completo) …
}
// ── Renderizar el wizard por pasos ─────────────────────────────
public function render() {
// Leer el paso desde la URL (?step=1, ?step=2, ?step=3)
$step = isset( $_GET[‘step’] ) ? absint( $_GET[‘step’] ) : 1;
$step = max( 1, min( 3, $step ) ); // Limitar entre 1 y 3
// Dibuja el HTML con el paso correspondiente
}
}
// Instanciar la clase para que sus hooks queden registrados
new DLMS_Wizard();
if ( 1 === $step ), elseif ( 2 === $step ) y else para mostrar el contenido correcto según la URL. El código completo está en el archivo.
absint()? Convierte el valor de ?step= en un número entero positivo. Si alguien escribe ?step=abc o un valor malicioso en la URL, absint() devuelve 0, y max(1, min(3, 0)) lo convierte en 1. Es una forma simple de validar la entrada del usuario.
Resultado: los tres pasos del wizard
Esto es lo que ve el administrador del sitio al activar el plugin por primera vez. La pantalla aparece automáticamente sin que tenga que buscar nada en el menú:
Gracias por activar Divi LMS Helper. Este plugin extiende tu child theme con shortcodes, una pagina de administracion propia y funcionalidades extra para tu sitio LMS.
En el siguiente paso verificaremos que los plugins necesarios esten activos.
El plugin necesita estos componentes para funcionar correctamente:
- [OK] LearnPress — plugin del LMS
- [OK] Divi — constructor de paginas
- [OK] Child theme Divi LMS Child — tema hijo activo
Tu plugin esta configurado y listo para usarse. Puedes explorar las opciones desde el panel de administracion.
¿Por qué add_dashboard_page y no add_menu_page?
WordPress tiene varias funciones para registrar páginas de administración. Para el wizard usamos add_dashboard_page() en lugar de add_menu_page(). La diferencia es importante:
| Función | ¿Aparece en el menú? | URL generada | Uso típico |
|---|---|---|---|
add_menu_page() |
Sí, en el sidebar | admin.php?page=slug |
Páginas de configuración permanentes |
add_dashboard_page() |
No aparece en el menú | index.php?page=slug |
Páginas temporales o wizards que no necesitan menú |
El wizard no necesita aparecer en el menú lateral de WordPress — es una pantalla que se usa una sola vez al activar el plugin. Usar add_dashboard_page() la mantiene accesible (via URL directa) pero sin ocupar espacio en el menú de administración.
Verificacion de la leccion
Pasos para verificar que el wizard funciona
- En WP Admin, ve a Plugins.
- Haz clic en «Desactivar» en Divi LMS Helper.
- Haz clic en «Activar» nuevamente.
- Deberías ser redirigido automáticamente al wizard — Paso 1 con el mensaje de bienvenida.
- Haz clic en «Siguiente» — deberías ver el Paso 2 con los tres [OK] (LearnPress, Divi y el child theme).
- Haz clic en «Siguiente» — deberías ver el Paso 3 con «Todo listo» y el botón «Ir al Dashboard».
- Si volvés a la lista de Plugins sin desactivar y reactivar, el wizard no debe aparecer (la opción ya fue borrada).
DLMS_Wizard en includes/class-wizard.php. El wizard usa el hook admin_init para detectar la opción dlms_show_wizard y redirigir automáticamente. La página tiene tres pasos: Bienvenida, Requisitos (con verificación PHP en tiempo real de LearnPress, Divi y el child theme) y Listo.