1. 개요
DX 서브히어로는 DXCMS의 게시판·페이지 상단에 히어로 배너를 자동으로 출력하는 플러그인입니다.• 게시판별, 페이지별로 개별 이미지/배경/스타일 설정 가능
• 전역 기본값 설정으로 미설정 항목 일괄 적용
• styles/ 폴더에 파일 추가만으로 새 스타일 자동 등록
• 홈 페이지(/)에는 출력되지 않음
2. 설치
1. plugins/dx-sub-hero/ 폴더를 DXCMS 설치 경로에 복사2. 관리자 → 플러그인 → DX 서브히어로 활성화
3. DB 테이블이 자동으로 생성됩니다 (sub_hero_settings, sub_hero_items)
4. 관리자 사이드바에 레이아웃 → 서브히어로 메뉴가 자동 등록됩니다
3. 관리자 메뉴
관리자 → 레이아웃 → 서브히어로 또는 /admin/sub-hero 접속3-1. 스타일 선택
전역 기본 스타일을 설정합니다. 항목별 스타일이 지정된 경우 항목 스타일이 우선 적용됩니다.| 스타일 ID | 이름 | 설명 |
| style1 | Classic | 좌하단 제목 + Breadcrumb 경로 |
| style2 | Center | 중앙 정렬 + 구분선 |
| style3 | Minimal | 하단 얇은 바 + 제목/경로 |
| style4 | Split | 좌측 컬러 패널 + 이미지 |
| style5 | Overlay Card | 반투명 글라스 카드 |
| style6 | Blur Band | 블러 밴드 위 텍스트 |
| style7 | Side Line | 좌측 세로 라인 강조 |
| style8 | Bottom Fade | 하단 그라디언트 페이드 + 대형 텍스트 |
| style9 | Neon | 네온 글로우 효과 |
| style10 | Magazine | 잡지형 초대형 타이포그래피 |
3-2. 항목 관리
게시판 또는 페이지별로 히어로를 개별 설정합니다.항목 추가 방법
1. 항목 추가 버튼 클릭2. 타입 선택: 게시판 또는 페이지
3. 키 값 입력 — 게시판: 게시판 키 (예: free, notice) / 페이지: 페이지 SLUG (예: about, contact)
4. 스타일 선택 (비워두면 전역 스타일 적용)
5. 배경 타입 설정 — 이미지 URL / 단색 색상코드 / 그라디언트
6. 활성화 토글 ON 후 저장
우선순위: 항목별 설정 > 전역 설정(기본 이미지)
3-3. 전역 설정
| 설정 항목 | 설명 | 기본값 |
| 플러그인 활성화 | ON/OFF 전체 제어 | ON |
| 제목 표시 | 게시판명/페이지명 출력 여부 | ON |
| Breadcrumb 표시 | 경로 표시 여부 | ON |
| 높이 (PC) | PC 히어로 높이 | 250px |
| 높이 (모바일) | 모바일 히어로 높이 | 160px |
| 오버레이 불투명도 | 배경 위 레이어 투명도 (0~1) | 0.45 |
| 기본 이미지 URL | 항목 미설정 시 표시할 기본 이미지 | 없음 |
높이는 px, vh, % 단위 모두 지원합니다. (예: 300px, 40vh)
4. 동작 방식
| 단계 | 내용 |
| 1 | 페이지 로드 시 dx_bottom 훅 실행 |
| 2 | 현재 페이지 타입 판별 (board / page) |
| 3 | 항목 DB 조회 (type + key_value) |
| 4 | 항목 있음 → 항목 설정 사용 / 항목 없음 → 기본 이미지 사용 |
| 5 | 스타일 파일 로드 (styles/styleN.php) |
| 6 | JS로 히어로 DOM 생성 후 #dx-main 앞에 삽입 |
5. 커스텀 스타일 개발 가이드
styles/ 폴더에 PHP 파일을 추가하면 자동으로 관리자에 등록됩니다.5-1. 파일 구조
<?php
* @name 스타일 이름 ← 관리자 UI에 표시되는 이름
* @desc 스타일 설명 ← 관리자 UI에 표시되는 설명
if (!defined('DX_CMS')) exit('Direct access not allowed.');
function dxsh_style_js() {
return <<<'JS'
// 여기에 순수 JavaScript 코드 작성
JS;
}
5-2. 사용 가능한 변수와 함수
| 이름 | 타입 | 설명 |
| d | object | 히어로 데이터 전체 |
| d.title | string | 제목 (게시판명 또는 페이지명) |
| d.crumbs | array | Breadcrumb 배열 [{label, url}] |
| d.showTitle | boolean | 제목 표시 여부 |
| d.showCrumb | boolean | Breadcrumb 표시 여부 |
| d.heightPc | string | PC 높이 (예: 250px) |
| d.heightMo | string | 모바일 높이 |
| d.opacity | number | 오버레이 불투명도 |
| d.bgType | string | image / color / gradient |
| d.imageUrl | string | 배경 이미지 URL |
| d.bgColor | string | 배경 단색 코드 |
| d.bgGradient | string | 배경 그라디언트 CSS |
| wrap | Element | 히어로 최상위 div#dxsh-wrap |
| bg | Element | 배경 레이어 div#dxsh-bg |
| _el(tag, id) | function | id가 지정된 엘리먼트 생성 |
| _buildCrumb(parent, crumbs, style) | function | Breadcrumb ol 생성 및 삽입 |
5-3. 애니메이션 규칙
render.php가 setTimeout(80ms) 후 아래 ID의 스타일을 자동으로 복원합니다.| ID | 복원되는 스타일 |
| dxsh-title | opacity:1; transform:translateY(0) scale(1) |
| dxsh-crumb | opacity:1; transform:translateY(0) |
| dxsh-extra | opacity:1; transform:translateY(0) |
scaleY 등 별도 transform이 필요한 경우 스타일 파일 내에서 직접 setTimeout으로 처리하세요.
6. DB 테이블 구조
6-1. sub_hero_settings — 전역 설정
| 컬럼 | 타입 | 설명 |
| id | INT | PK |
| active_style | VARCHAR | 전역 스타일 ID (예: style1) |
| is_active | TINYINT | 플러그인 활성화 여부 |
| show_title | TINYINT | 제목 표시 여부 |
| show_breadcrumb | TINYINT | Breadcrumb 표시 여부 |
| height_pc | VARCHAR | PC 높이 (예: 250px) |
| height_mo | VARCHAR | 모바일 높이 |
| overlay_opacity | DECIMAL | 오버레이 불투명도 (0.00~1.00) |
| default_image | TEXT | 기본 배경 이미지 URL |
| updated_at | DATETIME | 마지막 수정일 |
6-2. sub_hero_items — 항목별 설정
| 컬럼 | 타입 | 설명 |
| id | INT | PK |
| type | VARCHAR | board 또는 page |
| key_value | VARCHAR | 게시판 키 또는 페이지 SLUG |
| style | VARCHAR | 항목 전용 스타일 ID (비어있으면 전역 스타일) |
| bg_type | VARCHAR | image / color / gradient |
| image_url | TEXT | 배경 이미지 URL |
| bg_color | VARCHAR | 배경 단색 코드 |
| bg_gradient | TEXT | 배경 그라디언트 CSS |
| is_active | TINYINT | 항목 활성화 여부 |
| updated_at | DATETIME | 마지막 수정일 |
7. FAQ
Q. 특정 게시판에만 히어로를 끄고 싶어요.
해당 게시판 항목을 추가하고 활성화를 OFF로 저장하세요.Q. 홈 페이지에도 히어로가 나와요.
플러그인은 홈(/)에서는 자동으로 출력하지 않습니다. 테마 자체에 히어로가 있는 경우입니다.Q. 이미지를 업로드할 수 없어요.
이미지 URL을 직접 입력하거나, DXCMS 파일 관리자에서 업로드 후 URL을 복사해서 입력하세요.Q. 새 스타일을 추가했는데 목록에 안 나와요.
styles/ 폴더에 .php 파일 형식으로 저장하고, 파일 상단에 @name과 @desc 주석을 반드시 포함해야 합니다.Q. 모바일에서 높이가 적용이 안 돼요.
전역 설정 → 높이 (모바일) 값을 확인하세요. CSS @media(max-width:768px) 기준으로 적용됩니다.라이선스
디자인원엑스 라이선스 참고https://designonex.com/notice/view/1787577858493247
