Nav Button Highlighter 컴포넌트 - 이제 정상 작동

커스터마이징 테마 컴포넌트
1

JavaScript 버전의 관리자 섹션을 안정적으로 유지하는 데 문제가 있어 순수 CSS 컴포넌트로 재구성해야 했습니다. 이는 사이트에서 작동하도록 하려면 CSS 선택자를 직접 편집해야 한다는 것을 의미합니다.

이 컴포넌트의 목적은 사용자가 특정 경로를 따르도록 유도하는 것을 돕기 위한 것입니다.

링크: https://github.com/focallocal/nav-buttons-highlighter

아래는 설치된 상태로, 내 플랫폼의 대부분의 사용자는 수개월 동안 회원이었음에도 불구하고(특히 모바일을 주로 사용하는 사용자) 어디서 찾을지 모르는 카난(Kanban) 보드 플러그인을 강조하고 있는 모습입니다.

데스크톱:

image
image1471×247 31.4 KB

모바일:

image
image763×261 25.8 KB

image
image760×546 27.2 KB

# Nav Buttons Highlighter

사용자가 특정 경로나 기능을 따르도록 유도하기 위해 내비게이션 버튼을 강조하고, 모바일 드롭다운 메뉴를 더 명확하고 눈에 띄게 만드는 Discourse 테마 컴포넌트입니다.

목적

이 컴포넌트는 다음을 도와줍니다:

  • 사용자 유도: 중요한 내비게이션 링크(예: 작업 보드, 문서, 주요 카테고리)를 강조하여
  • 모바일 UX 개선: 드롭다운 내비게이션 버튼을 눈에 띄게 만들어
  • 시각적 위계 구조 생성: 내비게이션 바에

기능

  • 단색과 호버 효과를 가진 깔끔한 버튼 스타일링
  • 관리자 설정 가능 - CSS 편집 불필요
  • 최대 3개의 사용자 지정 내비게이션 버튼 지원
  • 모바일 반응형 - 모바일 드롭다운 버튼 강조 포함
  • 기본적으로 Discourse Kanban 플러그인에 대해 사전 구성됨
  • 쉬운 커스터마이징을 위한 색상 선택기 지원

기본 구성

기본적으로 이 컴포넌트는 Discourse Kanban 플러그인(링크)을 파란색(#4285F4)으로 강조하도록 설정되어 있습니다.

설치

  1. Discourse 관리자 콘솔에서 커스터마이즈 → 테마 → 컴포넌트로 이동하여 설치를 클릭합니다.
  2. Git 저장소 링크에서 복사하여 붙여넣습니다:
    https://github.com/focallocal/nav-buttons-highlighter
  3. 설치 후 컴포넌트를 활성 테마에 추가합니다.

커스터마이징 방법

관리자 설정 패널

모든 구성은 간단한 관리자 설정을 통해 수행됩니다 - CSS 편집 불필요!

설정 방법:

  1. 관리자 → 커스터마이즈 → 테마로 이동합니다.
  2. 활성 테마를 클릭합니다.
  3. 포함된 컴포넌트 섹션에서 Nav Buttons Highlighter를 찾습니다.
  4. 설정을 클릭합니다.

사용 가능한 설정:

버튼 1 - Kanban (기본값):

  • Kanban 강조: 켜기/끄기 (기본값: 켜짐)
  • Kanban 색상: 색상 선택기 (기본값: 파란색 #4285F4)
  • Kanban 선택기: CSS 선택자 (기본값: a.kanban-nav)

버튼 2 - 사용자 지정:

  • 버튼 2 강조: 두 번째 버튼 활성화 (기본값: 꺼짐)
  • 버튼 2 색상: 색상 선택기 (기본값: 초록색 #4CAF50)
  • 버튼 2 선택기: CSS 선택자 입력 (예: a[href='/page'])

버튼 3 - 사용자 지정:

  • 버튼 3 강조: 세 번째 버튼 활성화 (기본값: 꺼짐)
  • 버튼 3 색상: 색상 선택기 (기본값: 주황색 #FF5722)
  • 버튼 3 선택기: CSS 선택자 입력

모바일:

  • 모바일 드롭다운 강조: 모바일 Latest 드롭다운 켜기/끄기 (기본값: 켜짐)
  • 모바일 드롭다운 색상: 색상 선택기 (기본값: 파란색 #4285F4)

CSS 선택자 찾기:

다른 내비게이션 링크를 강조하려면 해당 CSS 선택자가 필요합니다:

  1. 브라우저에서 포럼을 엽니다.
  2. 강조하려는 링크를 마우스 오른쪽 버튼으로 클릭합니다.
  3. "요소 검사"를 선택합니다.
  4. <a> 태그를 찾아 다음을 기록합니다:
    • 클래스 이름: class="kanban-nav" → 사용: a.kanban-nav
    • Href 값: href="/c/support" → 사용: a[href="/c/support"]

일반적인 예시:

  • Kanban 플러그인: a.kanban-nav
  • 지원 카테고리: a[href="/c/support"]
  • 문서 태그: a[href="/tags/documentation"]
  • 사용자 정의 페이지: a[href="/my-page"]
  • 두 번째 내비게이션 버튼: #navigation-bar > li:nth-child(2) > a

색상 선택:

16진 색상 코드를 사용합니다(예: 파란색의 경우 #4285F4). 컴포넌트는 자동으로 다음을 생성합니다:

  • 그라디언트 상단의 밝은 색조
  • 하단/그림자용 어두운 색조
  • 호버 및 활성 상태 색상

인기 색상:

  • 파란색: #4285F4 (기본값)
  • 초록색: #4CAF50
  • 빨간색: #F44336
  • 주황색: #FF9800
  • 보라색: #9C27B0

안정적인 CSS 전용 버전

직접 CSS 편집을 선호한다면 이전 버전(2.0.1)을 사용할 수 있습니다:

CSS 전용 버전 설치:

https://github.com/focallocal/nav-buttons-highlighter/tree/stable-v2.0.1

CSS 편집 지침은 해당 브랜치의 README를 참조하세요.

개발

이 저장소에는 다음이 포함되어 있습니다:

  • common/common.scss — 모든 버튼 스타일링 및 상세 커스터마이징 가이드
  • assets/javascripts/discourse/api-initializers/nav-buttons-highlighter.js — 최소 초기화 파일 (Discourse에 필수)
  • about.json — 컴포넌트 메타데이터

문제 해결

Q: 변경 사항이 표시되지 않습니다
A: 편집 후 "저장"을 클릭하고 포럼 페이지를 하드 리프레시합니다 (Ctrl+F5 또는 Cmd+Shift+R).

Q: 여러 버튼을 강조하고 싶습니다
A: 전체 버튼 CSS 블록을 복사하여 기존 CSS 규칙 아래에 붙여넣고, 선택자를 변경하고 필요하면 색상을 변경합니다.

라이선스

MIT — Public Happiness Movement

1개의 좋아요
2

좋네요.

근데 이 기이한 마크다운은 뭔가요?

Customization > Theme component 채널로 옮기라고 플래그를 달았나요?

3

감사합니다 :slightly_smiling_face:

GitHub readme에서 그대로 복사해서 붙여넣었는데, 여기에 마크다운을 사용하려면 토글을 클릭해야 한다는 걸 몰랐습니다. 게시물을 올린 뒤로 계속 수정하고 있습니다.

Theme component 카테고리로 옮기라고 신고(flag)를 하셨나요?

아니요, 먼저 피드백을 받고 모든 것이 괜찮은지 확인하고 싶었습니다.

1개의 좋아요
4

Discourse가 손상된 파일을 캐시하는 기이한 문제를 겪었습니다. about.json 파일이었을 것 같고, 이 파일에 대한 모든 수정이 업데이트나 재설치에 반영되지 않았습니다. 왜 아무런 변경 사항도 빌드되지 않는지 파악하는 데 정말 오랜 시간이 걸렸습니다.

라이브 사이트에서 테스트하는 것 외에 컴포넌트를 테스트하는 더 나은 방법이 있을까요?

앞으로 이 문제를 겪는 사람들을 위해, 설치 시 '500 error’가 표시되고 /logs 섹션에서 about.json 파일이 원인으로 지목되는 경우가 있습니다. 이 문제는 해당 컴포넌트를 위한 새 GitHub 저장소를 다른 이름으로 생성하고, 버전을 한 자리 숫자씩 올린 것(예: 1.01에서 2.0.1로)으로 해결되었습니다. 이렇게 하면 Discourse가 이를 새로운 컴포넌트로 인식하게 됩니다.

테마 컴포넌트 설치/업데이트 시 지속되는 500 오류.
오류는 git import 중 version.rb에서 "invalid byte sequence in UTF-8"였습니다.

근본 원인:

  • Discourse는 import 시 테마 저장소 메타데이터를 캐시합니다.
  • 컴포넌트에 손상된 .discourse-compatibility 파일이나 잘못된 형식의 about.json이 있을 때,
    Discourse는 이 오류 상태를 캐시했습니다.
  • 파일을 수정하고 업데이트를 push해도 캐시는 오류 상태를 유지했습니다.

해결 방법:

  • about.json의 컴포넌트 이름을 변경했습니다(예: “Theme Name” → “Theme Name Fresh”)
  • 주요 버전을 올렸습니다(1.0.0 → 2.0.0)
  • 이는 Discourse가 이를 새로운 컴포넌트로 처리하도록 강제하고 캐시된 오류를 우회하게 했습니다.

예방 조치:

  1. 커밋하기 전에 항상 JSON 파일을 검증하세요(jsonlint 또는 VS Code 검증 사용)
  2. 모든 파일이 BOM이 없는 UTF-8 인코딩을 사용하도록 하세요
  3. 필요하지 않다면 .discourse-compatibility 파일을 삭제하세요(about.json의 minimum_discourse_version만으로도 충분합니다)
  4. 지속되는 import 오류가 발생하면 버전 번호를 올리거나 컴포넌트 이름을 일시적으로 변경해 보세요
5

@Drew-ART Objects type for theme setting 링크를 확인해 보셨나요? 이를 활용하면 네스팅(nesting)을 사용하여 배경색과 패딩 같은 속성을 각 규칙에 추가하는 방식으로 여러 CSS 규칙을 넣을 수 있을 것입니다. SCSS에는 이를 활용할 수 있는 each 루프가 있습니다.

아래 링크가 도움이 될 수 있습니다.

1개의 좋아요
6

@NateDhaliwal 감사합니다. 원래 제 접근 방식이었지만, 위에서 언급한 500 오류에 부딪혀 꽤 오랫동안 해결하지 못해서 CSS만 사용하는 방식으로 돌아가게 되었습니다.

이제 500 오류를 어느 정도 파악했으니, 그 당시 중단했던 시도로 돌아가서 지금은 제대로 로드되는지 확인해 볼 수 있을 것 같습니다. 시도해 보겠습니다.

1개의 좋아요
7

아니요, 아예 작동하지 않습니다.

관리자 설정으로 구성하고, 올바르게 로드되지 않으면 CSS로 폴백되도록 했는데, 제가 파악할 수 없는 어떤 요인이 완전히 작동하지 못하게 막고 있습니다.

9

네, 간단한 텍스트/부울 설정을 사용하여 관리자 섹션을 작동하도록 만들었습니다.

Objects 타입을 SCSS 파싱과 함께 작동시키는 것이 어려웠습니다. 위 브랜치가 작동하지 않은 이유를 설명해 주실 수 있는 분이 계시다면 그 의견을 듣고 싶습니다. 하지만 지금 이 기능을 사용하려는 분들은 이제 컴포넌트 관리자 섹션에서 설정을 사용자 지정할 수 있습니다.

1개의 좋아요
10

좋아요, SCSS 문제를 찾은 것 같습니다.

@NateDhaliwal의 캐러셀 컴포넌트에서 다음 내용을 발견했습니다:
SCSS (common.scss):

@if $pagination-button-color != "" {
  --swiper-pagination-bullet-inactive-color: #{$pagination-button-color};
}

설정 (settings.yml):


pagination_button_color:
  type: string
  default: ""

다른 분들도 같은 문제를 겪고 있다면 참고하세요:

  • #{$var} 구문을 사용해 CSS 커스텀 프로퍼티에 주입합니다.
  • 그런 다음 Swiper 라이브러리가 이 값을 읽을 수 있도록 다른 곳에서 해당 CSS 변수를 사용합니다.

이 방식이 작동하는 이유는 다음과 같습니다:

  1. 설정 변수는 #{}로 보간(interpolation)할 수 있습니다.
  2. CSS 커스텀 프로퍼티는 문자열 값을 허용합니다.
  3. 실제 스타일링은 SCSS 함수가 아닌 CSS 변수를 사용합니다.

곧 이 플러그인을 더 현대적인 버전으로 업데이트하겠습니다.

1개의 좋아요