Tarjetas emergentes de temas

[denvergeeks]

	Resumen	Muestra emergencias estilo tooltip al pasar el ratón (o al tocar en móviles) sobre enlaces internos a temas, mostrando una vista previa rápida del contenido del tema enlazado.
	Vista previa	Lectura en GitHub
	Repositorio	https://github.com/denvergeeks/discourse-topic-hover-cards
	Guía de instalación	Cómo instalar un tema o un componente de tema
	¿Nuevo en los temas de Discourse?	Guía para principiantes sobre el uso de los temas de Discourse

Instalar este componente de tema

Tarjetas de vista previa ricas al pasar el ratón para enlaces internos a temas en todo el sitio: en temas, respuestas, listas de temas, páginas de inicio de categorías, categorías de documentación, tableros Kanban y temas sugeridos. Para escritorio y/o móviles. Disponible en todo el sitio y altamente configurable.

Características

• Se puede activar en todo el sitio para todos los enlaces internos a temas, o solo en uno o más de los siguientes ámbitos:
  • Cuerpo del tema (publicación original)
  • Respuestas
  • Listas estándar de temas (/latest, /top, /tags, listas de temas por categoría, etc.)
  • Listas de temas en la página de inicio de categorías (Categorías + Últimos, Solo categorías y diseños relacionados)
  • Vistas de categorías de documentación
  • Vistas de tableros estilo Kanban
  • Temas sugeridos
• Diseño adaptable:
  • Tarjeta para escritorio con densidad configurable y colocación de miniaturas
  • Vista previa tipo hoja inferior en móviles con apertura al tocar
• Contenido configurable:
  • Imagen de miniatura
  • Insignia de categoría
  • Etiquetas
  • Título
  • Extracto (limpio de imágenes y lightboxes)
  • Publicador original
  • Fecha de publicación
  • Vistas, respuestas, me gusta, última actividad
• Opción de exclusión por usuario mediante un campo personalizado de usuario
• Modo de depuración solo para administradores para solución de problemas segura

Configuración

Diseño y temporización

• card_width
  Cualquier valor de ancho CSS (para escritorio), por ejemplo: 32rem, 420px, 40vw, clamp(20rem, 40vw, 36rem).

• card_max_height
  Cualquier valor de altura máxima CSS, por ejemplo: 10rem, 480px, 50vh, min(60vh, 32rem).

• card_delay_ms
  Retraso antes de mostrar la tarjeta al pasar el ratón, en milisegundos (valor predeterminado: 300).

• enable_on_mobile
  Al activarlo, al tocar un enlace interno a tema compatible se muestra una hoja de vista previa móvil fijada en la parte inferior de la pantalla.

• mobile_width_percent
  Ancho de la vista previa tipo hoja inferior móvil como porcentaje del ancho de la ventana gráfica (valor predeterminado: 100).

• mobile_thumbnail_height
  Altura de la miniatura en píxeles para la vista previa móvil.

Densidad

• density
  Densidad para escritorio: default, cozy o compact.

• density_mobile
  Densidad para móviles: default, cozy o compact.

Estos valores son paralelos a los patrones de “Densidad” de Discourse y simplemente ajustan el relleno y la altura de línea.

Miniatura y colocación

• show_thumbnail / show_thumbnail_mobile
  Mostrar/ocultar la imagen del tema (si existe) en escritorio y móviles.

• thumbnail_placement
  Cómo se coloca la miniatura en escritorio:

  • top
  • left
  • right
  • bottom
    En móviles, la miniatura siempre se renderiza en la parte superior de la tarjeta.

• image_size_percent
  Controla el tamaño de la miniatura como porcentaje del tamaño renderizado de la tarjeta al pasar el ratón.

Campos por ventana gráfica

Para cada bloque siguiente, tienes interruptores tanto para escritorio como para móviles:

• show_category / show_category_mobile

• show_tags / show_tags_mobile

• show_title / show_title_mobile

• show_excerpt / show_excerpt_mobile

• excerpt_length / excerpt_length_mobile
  Número de líneas para el extracto (usa line-clamp de CSS).

• show_op / show_op_mobile
  Muestra el avatar y nombre de usuario del publicador original.

• show_publish_date / show_publish_date_mobile

• show_views / show_views_mobile

• show_reply_count / show_reply_count_mobile

• show_likes / show_likes_mobile

• show_activity / show_activity_mobile

Dónde aparecen las tarjetas al pasar el ratón

• enable_on_topics
  Enlaces a temas en la publicación original.

• enable_on_replies
  Enlaces a temas en las respuestas.

• enable_on_topic_lists
  Enlaces a temas en listas estándar de temas, por ejemplo: /latest, /top, listas de temas por categoría.

• enable_on_category_homepage_topic_lists
  Enlaces a temas en las listas de “últimos temas” o equivalentes en la página de inicio de categorías:

  • Categorías + Últimos temas
  • Solo categorías
  • Variantes relacionadas renderizadas en / o /categories, según cómo esté configurada tu página de inicio.

• enable_on_doc_categories
  Enlaces a temas en las vistas de categorías de documentación (cuando sea aplicable).

• enable_on_kanban_boards
  Enlaces a temas renderizados en diseños de tableros estilo Kanban (cuando sea aplicable).

• enable_on_suggested_topic_links
  Enlaces en la sección de “Temas sugeridos”.

---

Exclusión por usuario

Puedes permitir que usuarios individuales desactiven las tarjetas al pasar el ratón mediante un campo personalizado de usuario. Esto utiliza el mecanismo estándar de configuración de temas y el acceso a datos del usuario actual descritos en las guías para desarrolladores.

• user_preference_field_name
  La clave utilizada para detectar la exclusión en el usuario actual. Puede ser:
  • una clave de campo personalizado directa, por ejemplo: disable_topic_hover_cards
  • un ID numérico, por ejemplo: 1
  • una clave user_field_X, por ejemplo: user_field_1

Cómo funciona la coincidencia

1. El componente primero verifica los custom_fields y user_fields del usuario actual para:
   • el user_preference_field_name configurado
   • el mismo valor convertido entre 1 y user_field_1 cuando corresponda
2. Si no se encuentra ninguna coincidencia y el usuario actual es personal (administrador/moderador) y
   resolve_user_field_id_for_admins está activado, el componente llama a:
   • /admin/config/user-fields.json
     para mapear el valor configurado (nombre de campo o user_field_X) a su ID numérico.
3. Con el ID numérico, verifica:
   • user_fields[id]
   • user_fields['user_field_' + id]
   • custom_fields[id]
   • custom_fields['user_field_' + id]

Cualquier valor verdadero en esas posiciones (por ejemplo: 1, true, yes, on, checked) desactiva las tarjetas al pasar el ratón para ese usuario.

Configuración para este comportamiento

• resolve_user_field_id_for_admins
  Al activarlo (recomendado), los administradores pueden configurar el campo por nombre o user_field_X, y el componente resolverá y coincidirá automáticamente el ID numérico.

• debug_mode
  Al activarlo, registra información detallada de detección en la consola del navegador para el personal, incluyendo:

  • qué claves se verificaron
  • dónde se encontró una coincidencia (usuario actual vs registro completo de usuario)
  • el ID numérico del campo de usuario resuelto, si existe

---

Depuración

Si las tarjetas al pasar el ratón no aparecen donde esperas, utiliza el modo de depuración integrado:

1. Activa debug_mode en la configuración de este componente.
2. Abre la consola de desarrollador del navegador.
3. Pasa el ratón o toca un enlace relevante a un tema.

Verás mensajes similares a:

• Hover cards initialized – confirma la inicialización y las ubicaciones activadas.
• Resolved admin user-field mapping – confirma el mapeo del nombre/clave del campo de usuario configurado a un ID numérico (para personal).
• No disable field match found anywhere – confirma que las tarjetas al pasar el ratón no están siendo suprimidas para el usuario actual.

Para depurar dónde debería aparecer la tarjeta, verifica que:

• tu enlace de destino sea un enlace interno a tema (/t/...) que topicIdFromHref() pueda analizar
• la bandera de ubicación relevante esté activada:
  • enable_on_topics
  • enable_on_replies
  • enable_on_topic_lists
  • enable_on_category_homepage_topic_lists
  • enable_on_doc_categories
  • enable_on_kanban_boards
  • enable_on_suggested_topic_links

Configuraciones y características planificadas aún no añadidas:

• Etiquetas excluidas
• Etiquetas incluidas
• Clases excluidas
• Clases incluidas
• Excluir OneBoxes y otros por defecto
• Sugerencias??

[chapoi]

¿Podrías agregar un enlace de vista previa funcional o algunas capturas de pantalla para mostrar cómo se ve?