Tarjetas flotantes de temas

[denvergeeks]

	Resumen	Muestra tarjetas de tema altamente personalizables como herramientas emergentes al pasar el ratón sobre los enlaces de temas
	Vista previa	Léase de 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 temas en Discourse

Instala este componente de tema

Tarjetas de vista previa emergentes ricas para enlaces de temas internos en temas, respuestas, listas de temas, la página de inicio de categorías, Categorías de documentación, tableros Kanban y temas sugeridos.

Cuando los usuarios pasan el ratón por encima de un enlace a un tema (o tocan en dispositivos móviles), aparece una tarjeta con la miniatura del tema, el título, el extracto, la categoría, las etiquetas y estadísticas clave.

Características

• Tarjetas emergentes para enlaces de temas internos en:
  • Cuerpo del tema (publicación original)
  • Respuestas
  • Listas de temas estándar (/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 de escritorio con densidad y colocación de miniaturas configurables
  • Vista previa de 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/ventanas emergentes)
  • Publicador original
  • Fecha de publicación
  • Vistas, respuestas, me gusta, última actividad
• Opción de exclusión por usuario mediante un campo de usuario personalizado
• Modo de depuración solo para administradores para resolución segura de problemas

Configuración

Diseño y tiempo

• 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 emergente, en milisegundos (predeterminado: 300).

• enable_on_mobile
  Cuando está activado, tocar un enlace a un tema interno compatible muestra una hoja de vista previa en móviles.

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

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

Densidad

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

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

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

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
  Para diseños de escritorio left y right, controla el ancho de la miniatura como porcentaje del ancho de la tarjeta emergente.

Campos por ventana gráfica

Para cada bloque a continuación, 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 (CSS line-clamp).

• show_op / show_op_mobile
  Muestra el avatar y el 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 emergentes

• 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 de temas estándar, 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 vistas de Categorías de documentación (cuando corresponda).

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

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

---

Opción de exclusión por usuario

Puedes permitir que usuarios individuales desactiven las tarjetas emergentes mediante un campo de usuario personalizado. Esto utiliza el mecanismo estándar de configuración de temas y el acceso a datos del usuario actual descrito 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 del 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 emergentes para ese usuario.

Configuración para este comportamiento

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

• debug_mode
  Cuando está activado, 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 emergentes 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 a un tema relevante.

Verás mensajes similares a:

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

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

• tu enlace objetivo sea un enlace a un tema interno (/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

[chapoi]

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