토픽 호버 카드

커스터마이징 테마 컴포넌트
1
:information_source: 요약 내부 주제 링크에 마우스를 올리거나(모바일의 경우 탭) 링크된 주제의 내용을 미리 볼 수 있는 툴팁 스타일의 팝업을 표시합니다.
:eyeglasses: 미리보기 Github Readme
:hammer_and_wrench: 저장소 https://github.com/denvergeeks/discourse-topic-hover-cards
:question: 설치 가이드 테마 또는 테마 컴포넌트 설치 방법
:open_book: 디스코URS 테마를 처음 사용하시나요? 디스코URS 테마 사용 입문가이드

이 테마 컴포넌트 설치

주제, 답변, 주제 목록, 카테고리 홈페이지, 문서 카테고리, 카나반 보드, 추천 주제 등 내부 주제 링크에 대한 풍부한 호버 미리보기 카드입니다. 데스크톱 및/또는 모바일에서 작동하며, 사이트 전체에 적용되고 설정이 가능합니다.

image

image
image1215×707 146 KB

기능

  • 모든 내부 주제 링크에 사이트 전체로 활성화하거나, 다음 영역 중 하나 이상에만 활성화할 수 있습니다:
    • 주제 본문 (원본 게시물)
    • 답변
    • 표준 주제 목록 (/latest, /top, /tags, 카테고리 주제 목록 등)
    • 카테고리 홈페이지 주제 목록 (Categories + Latest, Categories-only 및 관련 레이아웃)
    • 문서 카테고리 (Doc Categories)
    • 카나반 보드 (Kanban Board)
    • 추천 주제 (Suggested Topics)
  • 반응형 레이아웃:
    • 설정 가능한 밀도와 섬네일 배치의 데스크톱 카드
    • 탭하여 열 수 있는 모바일 하단 시트 미리보기
  • 설정 가능한 콘텐츠에는 다음이 포함될 수 있습니다:
    • 섬네일 이미지
    • 주제 제목
    • 발췌문 (Excerpt)
    • 카테고리
    • 태그
    • 최초 작성자 (사용자 이름 및 아바타)
    • 게시 날짜
    • 마지막 활동 날짜
    • 조회수
    • 답변 수
    • 좋아요 수
  • 사용자 필드(커스텀 필드)를 이용한 사용자별 비활성화 옵션
  • 안전한 문제 해결을 위한 관리자 전용 디버그 모드
포함된 모든 설정을 보려면 클릭하세요...

레이아웃 및 타이밍

  • card_width
    데스크톱용 CSS 폭 값, 예: 32rem, 420px, 40vw, clamp(20rem, 40vw, 36rem).

  • card_max_height
    CSS 최대 높이 값, 예: 10rem, 480px, 50vh, min(60vh, 32rem).

  • card_delay_ms
    호버 카드 표시 전 지연 시간(밀리초, 기본값: 300).

  • enable_on_mobile
    활성화 시, 지원되는 내부 주제 링크를 탭하면 화면 하단에 고정된 모바일 미리보기 시트가 표시됩니다.

  • mobile_width_percent
    뷰포트 폭에 대한 모바일 하단 시트 미리보기 폭(퍼센트, 기본값: 100).

  • mobile_thumbnail_height
    모바일 미리보기의 섬네일 높이(픽셀).

밀도 (Density)

  • density
    데스크톱 밀도: default, cozy, 또는 compact.

  • density_mobile
    모바일 밀도: default, cozy, 또는 compact.

이것들은 패딩, 줄 높이, 글꼴 크기를 조정하는 디스코URS의 “Density” 패턴과 유사합니다.

섬네일 및 배치

  • show_thumbnail / show_thumbnail_mobile
    데스크톱과 모바일에서 주제 이미지(있는 경우)를 표시/숨김.

  • thumbnail_placement
    데스크톱에서 섬네일의 위치:

    • top
    • left
    • right
    • bottom
      모바일에서는 섬네일이 항상 카드 상단에 렌더링됩니다.

  • image_size_percent
    렌더링된 호버 카드 크기에 대한 섬네일 크기(퍼센트).

뷰포트별 필드

아래 각 블록마다 데스크톱과 모바일 토글이 모두 있습니다:

  • 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
    발췌문의 줄 수 (CSS line-clamp 사용).

  • show_op / show_op_mobile
    최초 작성자 아바타 + 사용자 이름 표시.

  • 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

호버 카드가 나타나는 위치

  • enable_on_topics
    원본 게시물 내의 주제 링크.

  • enable_on_replies
    답변 내의 주제 링크.

  • enable_on_topic_lists
    표준 주제 목록 내의 주제 링크, 예: /latest, /top, 카테고리 주제 목록.

  • enable_on_category_homepage_topic_lists
    카테고리 홈페이지의 “최신 주제” 또는 동등한 목록 내의 주제 링크:

    • Categories + Latest Topics
    • Categories-only
    • 홈페이가 어떻게 구성되었는지에 따라 / 또는 /categories에서 렌더링되는 관련 변형.

  • enable_on_doc_categories
    문서 카테고리 뷰 내의 주제 링크 (해당 시).

  • enable_on_kanban_boards
    카나반 스타일 보드 레이아웃에서 렌더링되는 주제 링크 (해당 시).

  • enable_on_suggested_topic_links
    “추천 주제” 섹션 내의 링크.

사용자별 비활성화 (Opt-out)

커스텀 사용자 필드를 사용하여 개별 사용자가 호버 카드를 비활성화할 수 있습니다. 이는 개발자 가이드에 설명된 표준 테마 설정 메커니즘과 현재 사용자 데이터 접근을 사용합니다.

  • user_preference_field_name
    현재 사용자의 비활성화를 감지하는 데 사용되는 키. 이것은 다음일 수 있습니다:
    • 직접적인 커스텀 필드 키, 예: disable_topic_hover_cards
    • 숫자 ID, 예: 1
    • user_field_X 키, 예: user_field_1

매칭 방식

  1. 컴포넌트는 먼저 현재 사용자의 custom_fields와 user_fields에서 다음을 확인합니다:
    • 설정된 user_preference_field_name
    • 적절한 경우 1과 user_field_1 사이로 변환된 동일한 값
  2. 매칭이 발견되지 않고 현재 사용자가 스태프(관리자/모더레이터)이며 resolve_user_field_id_for_admins가 활성화되어 있으면, 컴포넌트는 다음을 호출합니다:
    • /admin/config/user-fields.json
      설정된 값(필드 이름 또는 user_field_X)을 숫자 ID로 매핑하기 위해.
  3. 숫자 ID를 사용하여 다음을 확인합니다:
    • user_fields[id]
    • user_fields['user_field_' + id]
    • custom_fields[id]
    • custom_fields['user_field_' + id]

해당 위치의 어떤 참(truthy) 값(예: 1, true, yes, on, checked)도 해당 사용자에게 호버 카드를 비활성화합니다.

이 동작에 대한 설정

  • resolve_user_field_id_for_admins
    활성화(권장) 시, 관리자는 필드를 이름 또는 user_field_X로 설정할 수 있으며, 컴포넌트는 숫자 ID를 자동으로 해석하고 매칭합니다.

  • debug_mode
    활성화 시, 스태프를 위해 브라우저 콘솔에 상세한 감지 정보를 기록합니다:

    • 어떤 키가 확인되었는지
    • 매칭이 어디서 발견되었는지 (현재 사용자 vs 전체 사용자 기록)
    • 해석된 숫자 사용자 필드 ID (있는 경우)

디버깅

호버 카드가 예상되는 위치에 나타나지 않는 경우, 내장된 디버그 모드를 사용하세요:

  1. 이 컴포넌트의 설정에서 debug_mode를 활성화합니다.
  2. 브라우저 개발자 콘솔을 엽니다.
  3. 관련 주제 링크에 마우스를 올리거나 탭합니다.

다음과 유사한 메시지를 볼 수 있습니다:

  • Hover cards initialized – 초기화와 활성화된 위치를 확인합니다.
  • Resolved admin user-field mapping – 설정된 사용자 필드 이름/키가 숫자 ID로 매핑되었음을 확인합니다 (스태프용).
  • No disable field match found anywhere – 현재 사용자에게 호버 카드가 억제되지 않음을 확인합니다.

카드가 어디에 나타나야 하는지 디버깅하려면 다음을 확인하세요:

  • 대상 링크가 topicIdFromHref()가 파싱할 수 있는 내부 주제 링크(/t/...)인지
  • 관련 위치 플래그가 활성화되어 있는지:
    • 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

추가 예정인 설정 및 기능:

  • 제외 태그 (Excluded Tags)
  • 포함 태그 (Included Tags)
  • 제외 클래스 (Excluded Classes)
  • 포함 클래스 (Included Classes)
  • OneBoxes 등을 기본적으로 제외
  • 제안??
6개의 좋아요
2

작동하는 미리보기 링크나 스크린샷을 추가해서 이 기능이 어떤 모습인지 보여줄 수 있을까요?

9개의 좋아요