Contents
Introducción
Este tutorial explica, paso a paso y con todo lujo de detalles, cómo crear un panel de bienvenida personalizado en el área de administración de WordPress usando PHP y JavaScript. El resultado será un panel que aparece en el Escritorio (Dashboard), es estético, accesible, seguro y puede ser descartado por cada usuario (persistencia por usuario). Incluiré el código necesario para un plugin independiente, la lógica PHP, el JavaScript para la interacción y algo de CSS para el estilo.
Concepto y flujo de funcionamiento
- Crear un widget para el Dashboard con wp_add_dashboard_widget.
- Mostrar el contenido HTML del panel, con un botón para cerrar (dismiss).
- Comprobar si el usuario ya ha descartado el panel usando get_user_meta.
- Al pulsar cerrar, enviar una petición AJAX segura a admin-ajax.php para guardar la preferencia usando update_user_meta.
- Ocultar el panel en la interfaz inmediatamente con JavaScript y asegurar persistencia para posteriores visitas.
Estructura propuesta del plugin
Archivo único (suficiente para comenzar):
- wp-admin-welcome-panel.php (archivo principal del plugin)
- assets/js/welcome-panel.js (archivo JS encolado)
- assets/css/welcome-panel.css (estilos)
Archivo principal (plugin) — Código completo
Guarda el siguiente código como wp-admin-welcome-panel.php en la carpeta /wp-content/plugins/wp-admin-welcome-panel/ o como prefieras.
. esc_html__( Has descartado el panel de bienvenida., wp-admin-welcome-panel ) .
return
}
// Nonce para la petición AJAX
nonce = wp_create_nonce( wpap_dismiss_welcome_nonce )
?>
admin_url( admin-ajax.php ),
nonce => wp_create_nonce( wpap_dismiss_welcome_nonce ),
i18n => array(
dismiss_success => __( Panel descartado., wp-admin-welcome-panel ),
dismiss_error => __( No se pudo descartar. Inténtalo de nuevo., wp-admin-welcome-panel ),
),
)
)
}
/
Handler AJAX para marcar el panel como descartado (para usuarios logueados)
/
add_action( wp_ajax_wpap_dismiss_welcome, wpap_ajax_dismiss_welcome )
function wpap_ajax_dismiss_welcome() {
// Verificar nonce
nonce = isset( _POST[nonce] ) ? sanitize_text_field( wp_unslash( _POST[nonce] ) ) :
if ( ! wp_verify_nonce( nonce, wpap_dismiss_welcome_nonce ) ) {
wp_send_json_error( array( message => __( Nonce inválido, wp-admin-welcome-panel ) ), 403 )
}
// Requerir usuario logueado
if ( ! is_user_logged_in() ) {
wp_send_json_error( array( message => __( No autorizado, wp-admin-welcome-panel ) ), 401 )
}
user_id = get_current_user_id()
// Guardar la preferencia
updated = update_user_meta( user_id, wpap_welcome_dismissed, 1 )
if ( updated ) {
wp_send_json_success( array( message => __( Guardado, wp-admin-welcome-panel ) ) )
} else {
// Si no se pudo actualizar (o ya estaba)
wp_send_json_success( array( message => __( No fue necesario actualizar, wp-admin-welcome-panel ) ) )
}
}
Notas sobre el archivo PHP
- Usamos wp_add_dashboard_widget para agregar el panel al Dashboard.
- Comprobamos el user meta wpap_welcome_dismissed para decidir si mostrar el panel.
- Encolamos los assets solo en la pantalla del dashboard comprobando hook === index.php.
- La petición AJAX está protegida con wp_verify_nonce y requiere usuario autenticado.
- Usamos update_user_meta para persistencia por usuario.
Archivo JavaScript — welcome-panel.js
Coloca este archivo en assets/js/welcome-panel.js. Maneja la interacción y la petición AJAX.
jQuery( document ).ready( function( ) {
var panel = ( #wpap-welcome-panel )
var dismiss = ( #wpap-welcome-dismiss )
if ( ! panel.length ) {
return
}
dismiss.on( click, function( e ) {
e.preventDefault()
var nonce = ( this ).data( nonce ) ( wpap_welcome_vars wpap_welcome_vars.nonce )
if ( ! nonce ) {
alert( wpap_welcome_vars.i18n.dismiss_error )
return
}
// Petición AJAX para guardar la preferencia
.post(
wpap_welcome_vars.ajax_url,
{
action: wpap_dismiss_welcome,
nonce: nonce
},
function( response ) {
if ( response response.success ) {
// Ocultar panel con animación simple
panel.slideUp( 250 )
} else {
alert( wpap_welcome_vars.i18n.dismiss_error )
}
}
).fail( function() {
alert( wpap_welcome_vars.i18n.dismiss_error )
} )
} )
} )
Detalles del JS
- Usamos jQuery (incluido en admin) para simplicidad.
- Leemos el nonce provisto por wp_localize_script y hacemos una llamada POST a admin-ajax.php con action = wpap_dismiss_welcome.
- Al recibir éxito, ocultamos el panel en el cliente con slideUp para una buena experiencia de usuario.
Archivo CSS — welcome-panel.css
Coloca este archivo en assets/css/welcome-panel.css para estilizar el panel.
#wpap-welcome-panel {
background: #ffffff
border: 1px solid #e5e5e5
padding: 16px
border-radius: 4px
box-shadow: 0 1px 2px rgba(0,0,0,0.04)
}
#wpap-welcome-panel .wpap-welcome-header {
display: flex
justify-content: space-between
align-items: center
margin-bottom: 12px
}
#wpap-welcome-panel .wpap-welcome-header h3 {
margin: 0
font-size: 16px
}
#wpap-welcome-panel .wpap-dismiss-button {
background: #f7f7f7
border: 1px solid #ddd
padding: 6px 10px
border-radius: 3px
cursor: pointer
}
#wpap-welcome-panel .wpap-dismiss-button:hover {
background: #f1f1f1
}
#wpap-welcome-panel .wpap-welcome-body p {
margin: 0 0 8px
}
#wpap-welcome-panel .wpap-welcome-body ul {
margin: 0 0 8px 20px
}
Explicación de seguridad y buenas prácticas
- Nonces: Se usan para mitigar CSRF. En el ejemplo generamos y verificamos con wp_create_nonce / wp_verify_nonce.
- Capacidades: El AJAX requiere que el usuario esté logueado. Si tu panel se muestra solo a administradores, añade una comprobación adicional con current_user_can(manage_options).
- Escapado: Usa funciones como esc_html__, esc_attr, etc. en el HTML generado por PHP.
- Persistencia: User meta es apropiado para preferencias por usuario. Si quieres una preferencia global, usa update_option o transients.
- Carga selectiva: Encola assets solo en la pantalla necesaria (comprobando el hook) para no ralentizar otras pantallas.
Variantes y mejoras posibles
- Usar la REST API en lugar de admin-ajax.php para peticiones modernas (crear endpoint y usar fetch en lugar de jQuery).
- Crear una página de opciones para que un administrador pueda resetear el panel para todos los usuarios (borrando el meta a nivel de usuarios o usando una opción global con versión).
- Mostrar el panel solo a roles concretos usando current_user_can o get_userdata()->roles.
- Registrar cadenas para traducción y cargar textdomain si publicas el plugin públicamente.
- Agregar animaciones CSS y accesibilidad (aria-attributes, focus management) para una mejor experiencia.
Buenas prácticas adicionales
- Mantén separadas las responsabilidades: HTML en PHP, comportamiento en JS, estilos en CSS.
- Valida y sanea siempre los datos entrantes en AJAX (sanitize_text_field, intval, etc.).
- Evita inline scripts con datos sensibles usa wp_localize_script o wp_add_inline_script de forma controlada.
- Si tu panel contiene enlaces de acciones (por ejemplo configurar tema), asegúrate de verificar capacidades antes de mostrar esos enlaces.
Resumen final
Con los fragmentos anteriores tienes todas las piezas para crear un panel de bienvenida en el administrador de WordPress, completamente funcional, dismissible por usuario y seguro. El patrón mostrado es flexible y puede adaptarse para mostrar cualquier contenido, enlaces rápidos, tutoriales iniciales u ofertas de configuración inicial del sitio.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |