Tour UI
Proporciona una interfaz de usuario para gestionar el módulo Tour del núcleo de Drupal, permitiendo a los administradores crear, editar y eliminar tours guiados a través de una interfaz de administración intuitiva.
tour_ui
Instalar
composer require 'drupal/tour_ui:^2.0'
Overview
Tour UI extiende el módulo Tour del núcleo de Drupal proporcionando una interfaz administrativa completa para gestionar tours guiados. Sin este módulo, los tours deben crearse escribiendo manualmente archivos de configuración YAML, lo que requiere conocimientos técnicos y acceso al sistema de archivos.
Con Tour UI, los administradores del sitio pueden crear tours guiados interactivos directamente a través de la interfaz de administración de Drupal. Los tours consisten en una serie de consejos (tooltips) que guían a los usuarios a través de páginas o características específicas del sitio. Cada consejo puede posicionarse en relación con cualquier elemento DOM y puede contener texto formateado con HTML.
El módulo incluye tours integrados para su propia interfaz, demostrando cómo usar las características de creación de tours. También proporciona funcionalidad de autocompletado para encontrar rutas y nombres de módulos, facilitando la configuración de dónde deben aparecer los tours.
Features
- Operaciones CRUD completas para tours a través de la interfaz de administración: crear, ver, editar y eliminar tours sin escribir código
- Gestionar consejos de tour con funcionalidad de agregar, editar, eliminar y reordenar mediante arrastrar y soltar
- Función de autocompletado de rutas que busca en la tabla de enrutamiento para ayudar a encontrar los nombres de ruta correctos para orientar los tours
- Autocompletado de nombres de módulos para especificar a qué módulo pertenece la configuración del tour
- Soporte para parámetros de ruta que permite orientar tours a páginas específicas (por ejemplo, un nodo específico)
- Múltiples opciones de posicionamiento para tooltips incluyendo auto, arriba, abajo, izquierda, derecha y sus variantes de inicio/fin
- Tours autodocumentados integrados que demuestran cómo usar Tour UI
- Plugin de consejo de texto extendido con configuración basada en formularios para crear contenido de tooltip enriquecido
- Sistema de peso para consejos que controla el orden en que aparecen los pasos del tour
Use Cases
Incorporación de Nuevos Administradores del Sitio
Crea un tour guiado para la interfaz de administración de Drupal para ayudar a los nuevos administradores a aprender dónde encontrar configuraciones comunes. Por ejemplo, crea un tour para la ruta /admin/config que recorra cada categoría de configuración, explicando qué contiene cada sección y cuándo podrían necesitar usarla.
Capacitación de Editores de Contenido
Construye tours para flujos de trabajo de creación de contenido. Crea un tour en la ruta node/add/article que guíe a los editores de contenido a través de cada campo, explicando las mejores prácticas para títulos, contenido del cuerpo, imágenes y términos de taxonomía.
Documentación de Módulos
Al desarrollar módulos personalizados, usa Tour UI para crear documentación interactiva. Crea tours que expliquen páginas de administración personalizadas, opciones de configuración y flujos de trabajo específicos de tu módulo.
Anuncios de Características
Después de desplegar nuevas características, crea tours temporales para destacar los cambios. Por ejemplo, después de rediseñar un panel de control, crea un tour que señale los nuevos elementos y explique su propósito.
Guía para Formularios Complejos
Para formularios con muchos campos u opciones complejas, crea tours que expliquen cada sección. Esto es particularmente útil para formularios de configuración donde configuraciones incorrectas podrían causar problemas.
Tips
- Usa la página /devel/routes del módulo Devel para encontrar fácilmente nombres de rutas para orientar tours
- Al crear tours para sitios de producción, exporta la configuración a un módulo personalizado en lugar de dejarla en tour_ui - Tour UI está pensado como una herramienta de desarrollo
- Los parámetros de ruta (como - node:2) permiten orientar páginas de contenido específicas, pero ten en cuenta que esta característica tiene limitaciones documentadas en el issue #2978327
- Los consejos aparecen en orden basándose en su peso - los pesos más bajos aparecen primero en la secuencia del tour
- El campo selector acepta cualquier selector CSS válido, facilitando apuntar a elementos específicos en la página
- Los selectores vacíos hacen que el tooltip aparezca centrado en la pantalla, útil para consejos introductorios o de resumen
- Considera la ventana gráfica del usuario al elegir posiciones de consejos - 'auto' intentará encontrar la mejor posición automáticamente
- HTML está soportado en el contenido del cuerpo del consejo, permitiendo texto formateado, enlaces e incluso imágenes en el contenido de tu tour
Technical Details
Admin Pages 7
/admin/config/user-interface/tour
La página principal de gestión de tours que lista todos los tours disponibles en el sistema. Muestra una tabla con el ID del tour, etiqueta, rutas (páginas donde aparece el tour), número de consejos y operaciones. Desde esta página puedes agregar nuevos tours o editar/eliminar los existentes.
/admin/config/user-interface/tour/add
Formulario para crear un nuevo tour guiado. Especifica el nombre del tour, el módulo al que pertenece y las rutas donde debe aparecer. Después de crear el tour, puedes agregar consejos individuales (pasos del tour).
/admin/config/user-interface/tour/manage/{tour}
Formulario para editar un tour existente. Modifica la configuración del tour y gestiona los consejos del tour. Los consejos pueden reordenarse usando arrastrar y soltar, y se pueden agregar nuevos consejos usando el selector de tipo de consejo.
/admin/config/user-interface/tour/manage/{tour}/tip/add/{type}
Formulario para agregar un nuevo consejo (paso del tour) a un tour. Los campos del formulario varían según el tipo de consejo seleccionado. El tipo de consejo Texto es el más común y permite crear tooltips con contenido formateado.
/admin/config/user-interface/tour/manage/{tour}/tip/edit/{tip}
Formulario para editar un consejo de tour existente. Los mismos campos que el formulario de agregar consejo, pero pre-poblados con los valores actuales del consejo.
/admin/config/user-interface/tour/manage/{tour}/tip/delete/{tip}
Formulario de confirmación para eliminar un consejo del tour. Muestra los nombres del tour y del consejo y solicita confirmación antes de la eliminación.
/admin/config/user-interface/tour/manage/{tour}/delete
Formulario de confirmación para eliminar un tour completo incluyendo todos sus consejos.
Permisos 1
Hooks 4
hook_entity_type_alter
Altera el tipo de entidad Tour para agregar clases de formulario personalizadas, manejador de acceso, constructor de listas y plantillas de enlaces para la interfaz de administración de Tour UI.
hook_tour_tips_info_alter
Altera las definiciones de plugins de consejos de tour para reemplazar el plugin de texto del núcleo con una versión extendida que incluye configuración basada en formularios.
hook_module_implements_alter
Asegura que el hook entity_type_alter de tour_ui se ejecute antes que otros módulos para que sus alteraciones tengan precedencia.
hook_help
Proporciona texto de ayuda para el módulo Tour UI en la página de ayuda.
Troubleshooting 6
Verifica que el nombre de la ruta sea correcto usando la página /devel/routes del módulo Devel. También asegúrate de que el usuario tenga el permiso 'access tour' del módulo Tour del núcleo.
Revisa los valores de peso en la página de edición del tour. Los pesos más bajos aparecen primero. Usa arrastrar y soltar para reordenar los consejos y guarda el tour.
El elemento puede no estar visible cuando se carga el tour, o el selector CSS puede coincidir con múltiples elementos. Intenta usar un selector más específico como un ID en lugar de una clase.
Esto ocurre cuando un plugin de consejo no implementa getConfiguration(). Esto puede suceder con plugins de consejos personalizados que no son compatibles con Tour UI.
Escribe al menos un carácter para activar el autocompletado. El módulo debe estar habilitado para aparecer en las sugerencias.
Debes escribir al menos 4 caracteres antes de que se active la búsqueda de rutas. La búsqueda coincide tanto con nombres de rutas como con patrones de rutas.
Security Notes 3
- El permiso 'Administer tour' está marcado como 'restrict access' y solo debe otorgarse a administradores de confianza
- El contenido del cuerpo del consejo de tour acepta HTML, que potencialmente podría usarse para XSS si a usuarios no confiables se les otorga el permiso de administrar tour - solo se permiten etiquetas HTML confiables (usando Xss::getAdminTagList())
- Tour UI es principalmente una herramienta de desarrollo y puede que no necesite estar habilitada en sitios de producción una vez que los tours se hayan creado y exportado a la configuración del módulo