=== 그누보드 샘플 테마 Readme ===
Version: 1.0.0
Maker: temhamarket
Homepage: https://market.temha.io/

해당 코드는 템하마켓에서 제공하는 그누보드용 샘플 템플릿입니다.
이 문서는 테마 설치 및 사용 방법에 대한 가이드입니다.

---

### 목차

1. 테마 정보 및 라이선스
2. 요구 사양 (제작 환경)
3. 설치 방법
   - 3.1. 기본 설치 방법 (신규 그누보드)
   - 3.2. 수동 설치 방법 (기존 그누보드)
   - 3.3. 템플릿하우스 에디터 연동 설치
4. 주요 기능 및 커스터마이징
   - 4.1. 페이지 구조 (page.php)
   - 4.2. 게시판 스킨 설정
   - 4.3. 신규 페이지 제작 가이드
   - 4.4. 헤더 및 푸터 설정
   - 4.5. 콘텐츠 동적 삽입 (문의폼/최신글)
   - 4.6. 템플릿하우스 에디터 연동
   - 4.7. 게시판 비주얼 처리 방법
5. 주의사항 및 추가 안내
6. 문의 및 지원

---

### 1. 테마 정보 및 라이선스

* **테마명**: 샘플 (sample)
* **제작자**: temhamarket
* **제작자 URI**: https://market.temha.io/
* **버전**: 1.0.0
* **라이선스**: MIT

---

### 2. 요구 사양 (제작 환경)

* **언어 (Language)**: PHP 5.2.17 이상
* **데이터베이스 (DB)**: MySQL 8.0.31 이상
* **그누보드 버전**: 5.5.9 이상 최신 버전
* **템플릿하우스 에디터**: 템플릿하우스 에디터 계정 필요 (선택사항)

---

### 3. 설치 방법

#### 3.1. 기본 설치 방법 (신규 그누보드)

처음 그누보드를 설치하는 경우 아래 순서대로 진행하세요.

1. 다운로드한 그누보드 원본 코드를 서버의 `/www/` 경로에 업로드합니다.
2. `/www/` 경로에 `data` 폴더를 생성하고, 웹브라우저에서 사이트에 접속하여 그누보드를 설치합니다.
3. 설치된 사이트에 관리자 계정으로 로그인 후, 관리자 페이지 (`/adm`)로 이동합니다.
4. 좌측 메뉴의 [테마 설정]에서 'sample' 테마를 찾아 적용합니다.
5. 사이트 구조에 맞게 페이지 및 게시판을 생성하고 커스터마이징합니다.

#### 3.2. 수동 설치 방법 (기존 그누보드)

이미 그누보드가 설치된 사이트에 테마만 적용하는 경우 아래 순서대로 파일을 업로드하세요.
(참고: https://sir.kr/manual/yc5/67)

1. **테마 업로드**: 다운로드한 테마 폴더 내의 `/theme/sample` 폴더를 서버의 `/www/theme/` 경로에 업로드합니다.
2. **extend 업로드**: `/extend/` 폴더 내의 `temha.extend.php` 파일을 서버의 `/www/extend/` 경로에 업로드합니다.
3. **기타 파일 업로드**:
   * `/page.php` 파일을 서버의 `/www/` 경로에 업로드합니다.

※ 코드 설명 및 유지보수에 대한 별도 문의는 받지 않습니다.

#### 3.3. 템플릿하우스 에디터 연동 설치

템플릿하우스 에디터와 연동하여 사용하려면 아래 과정을 추가로 진행하세요.

**1단계: 템플릿하우스 에디터에서 프로젝트 생성**
- 템플릿하우스 에디터에 접속하여 새 프로젝트를 생성합니다.
- 프로젝트명은 사이트의 목적에 맞게 설정해주세요.

**2단계: 페이지 및 블록 구성**
- 메인 페이지 생성 (헤더, 푸터 블록 포함)
- 서브 페이지들 생성 (회사소개, 서비스 등)
- 게시판용 비주얼 페이지 생성 (필요시)

**3단계: FTP 설정 및 내보내기**
- 내보내기 버튼을 클릭하여 FTP 설정 창을 엽니다.
- Root 폴더 경로를 `/www/theme/sample/temha`로 설정합니다.
- 내보내기를 실행합니다.

**4단계: 그누보드에서 테마 적용**
- 그누보드 관리자 페이지에서 테마 설정으로 이동합니다.
- 업로드된 테마를 선택하고 적용합니다.

---

### 4. 주요 기능 및 커스터마이징

#### 4.1. 페이지 구조 (page.php)

`page.php`는 `http://도메인/page.php?id=페이지ID` 형태의 URL로 독립적인 페이지를 생성하는 역할을 합니다. `id` 값에 해당하는 `skin.php` 파일을 동적으로 불러옵니다.

* **동작 구조**:
```php
<?php
include_once('./_common.php');
$id = isset($_GET['id']) ? preg_replace('/[^a-z0-9_]/i', '', $_GET['id']) : '';
$skin_path = "{$pages_skin_path}/{$id}.skin.php"; // 예: /theme/sample/skin/pages/basic/about.skin.php
// ... (중략)
include_once($skin_path);
// ...
?>
```

* **HTML 연동**: 페이지 스킨 파일 (`*.skin.php`)은 자체 제작 에디터로 만든 HTML 파일을 불러와 `<main>` 태그 영역만 파싱하여 출력하는 구조입니다.

* **페이지별 타이틀 설정**: `$title_array` 배열을 통해 페이지별로 다른 타이틀을 설정할 수 있습니다.
  ```php
  $title_array = array(
      'about' => '회사소개',
      'contact' => '문의하기',
      'service' => '서비스'
  );
  ```

#### 4.2. 게시판 스킨 설정

관리자 페이지에서 게시판 생성 시, 목적에 맞는 테마 스킨을 선택하여 사용할 수 있습니다.

* **샘플용 템플릿에선 그누보드 기본 게시판 스킨을 사용합니다**:
  - **게시판 스킨**: basic (board 폴더)
  - **최신글 스킨**: temha_basic (latest 폴더)

* **스킨 설정 방법**:
  1. 관리자 페이지 → 게시판 관리 → 게시판 생성/수정
  2. 스킨 선택에서 원하는 스킨 선택
  3. 최신글 스킨도 함께 설정
  4. 추가로 필요한 최신글 스킨이 있다면 직접 생성하여 적용할 수 있습니다.

* **템플릿하우스와 그누보드 연동 프로세스**:
  1. 템플릿하우스에서 HTML 코드를 그누보드 스킨 파일에 삽입
  2. 그누보드 스킨 파일에서 데이터 처리 로직 구현
  3. 템플릿하우스에서 HTML 코드 삭제하고 주석으로 마킹
  4. 그누보드에서 주석 위치에 처리된 블록 치환

#### 4.3. 신규 페이지 제작 가이드

PHP 페이지는 `/temha/` 폴더에 위치한 HTML 파일을 불러와 내용을 표시하는 방식으로 제작합니다.

1. **HTML 파일 작성**:
   * 위치: `/theme/sample/temha/페이지명.html`
   * 이 위치에 페이지의 실제 디자인 내용을 HTML로 작성합니다.

2. **PHP 스킨 파일 작성**:
   * 위치: `/theme/sample/skin/pages/basic/페이지명.skin.php`
   * 아래 코드를 사용하여 HTML 파일의 `<main>` 영역을 불러옵니다.

```php
<?php
if (!defined("_GNUBOARD_")) exit;

// 1. 불러올 HTML 파일 경로 지정
$file_path_main = G5_THEME_PATH . '/temha/about.html';
if (!file_exists($file_path_main)) {
    die("파일을 찾을 수 없습니다: " . $file_path_main);
}
$html = file_get_contents($file_path_main);

// 2. <main> 태그 영역만 추출
preg_match('/(<main class="th-layout-main">.*?<\/main>)/s', $html, $block);
$content = isset($block[1]) ? $block[1] : "내용을 찾을 수 없습니다.";

// 3. 추출한 내용 출력
echo $content;
?>
```

#### 4.4. 헤더 및 푸터 설정

헤더와 푸터는 모든 페이지에 공통으로 적용되며, `main.html` 파일에서 `<header>`와 `<footer>` 태그를 각각 추출하여 구성합니다.

* **헤더 파일**: `/theme/sample/head.php`
* **푸터 파일**: `/theme/sample/tail.php`
* **공통 리소스 관리**: `/theme/sample/head.sub.php`
  * 이 파일에서 모든 페이지에 필요한 공통 CSS, JS 파일, 메타 태그, 파비콘 등을 관리합니다.
  * 특히 `<base href="...">` 태그를 이용해 리소스의 상대경로 문제를 해결합니다.

**head.sub.php 주요 기능**:
1. `<base href>`로 모든 상대경로의 기준 URL을 임시 지정 (404 오류 방지)
2. `<meta>` 태그를 통한 웹페이지 정보 설정
3. 테마 전용 파비콘과 CSS 파일 로드
4. JavaScript를 통한 경로 처리 및 `<base>` 태그 제거
5. 로그인 메뉴 토글 기능

#### 4.5. 콘텐츠 동적 삽입 (게시판)

HTML 파일 내에 특정 주석 마커(`<!--마커명-->`)를 삽입하면, PHP가 해당 위치에 최신글 목록을 동적으로 삽입합니다.

* **사용 방법**:
  1. HTML 파일에 마커 삽입: `<!--board-latest-->`
  2. PHP 파일 (예: index.php)에서 `latest()` 함수로 콘텐츠를 생성합니다.
  3. `str_replace()` 함수를 사용해 마커를 생성된 HTML 콘텐츠로 치환합니다.

* **예시 코드**:
```php
// 최신글 HTML 생성
ob_start();
echo latest('theme/temha_basic', 'notice', 4, 23);
$latest_html = ob_get_clean();

// $content의 마커를 실제 HTML로 치환
$content = str_replace('<!--board-latest-->', $latest_html, $content);
```

* **주의**: 주석 마커의 이름을 임의로 변경하거나 삭제하면 콘텐츠가 표시되지 않습니다.

#### 4.6. 템플릿하우스 에디터 연동

이 테마는 템플릿하우스에서 자체 제작한 에디터와의 연동을 위해 특별히 설계되었습니다.

* **에디터 연동 방식**:
  * 에디터에서 제작한 HTML 페이지는 FTP를 통해 `/theme/sample/temha/` 폴더에 업로드됩니다.
  * `/theme/sample/skin/pages/basic/*.skin.php` 또는 `/theme/sample/index.php`는 해당 HTML 파일을 불러와 `<main>` 태그 기준으로 파싱하여 출력합니다.
  * HTML에는 CSS, JS, 이미지 등의 리소스가 포함되며 `/temha/resources/` 하위에 위치합니다.
  * 파비콘을 업로드할 경우 `/temha/resources/` 하위에 업로드하세요.
  * 리소스의 경로 문제를 방지하기 위해 `/theme/sample/head.sub.php` 내 `<base href="...">` 선언을 통해 상대경로를 일괄 처리합니다.

* **에디터 사용 시 주의사항**:
  * 게시판 및 문의폼 블록에 사용된 `<article class="board_blank">` 요소는 에디터에서 영역 보호를 위한 용도입니다.
  * 해당 페이지 내에서 이 요소를 제거하는 코드(`preg_replace`)를 삭제하면 숨겨진 레이아웃이 그대로 출력될 수 있으니 주의해 주세요.
  * CSS/JS 수정 시에는 FTP로 연동되므로 에디터에서 직접 수정이 불가능합니다.

#### 4.7. 게시판 비주얼 처리 방법

게시판 상단에 비주얼 섹션을 추가하는 방법은 두 가지가 있습니다.

**방법 1: 템플릿하우스 에디터의 비주얼 블록을 파싱하여 노출하는 방법**

* **장점**: 디자인 변경이 자주 발생하는 경우, 유지보수가 용이함
* **단점**: 파일 I/O 오버헤드, 복잡한 로직 구현 제한
* **사용 시나리오**: 디자인이 자주 변경되거나, 템플릿하우스에서 관리하고 싶은 경우

* **구현 과정**:
  1. 템플릿하우스에서 별도 페이지 생성 (예: board_visual.html)
  2. 비주얼 블록을 해당 페이지에 배치
  3. 내보내기 후 그누보드에서 HTML 파일 파싱
  4. 태그를 추적하여 정확한 블록 추출
  5. 추출된 HTML을 게시판 상단에 출력

**방법 2: HTML 구조를 하드 코딩하여 노출하는 방법**

* **장점**: 빠른 구현, 복잡한 로직 자유롭게 구현 가능
* **단점**: 디자인 변경 시 코드 수정 필요, 유지보수 복잡
* **사용 시나리오**: 빠른 구현이 필요한 경우, 복잡한 로직이 필요한 경우, 일회성 사용

* **구현 과정**:
  1. 템플릿하우스에서 블록의 HTML 코드 복사
  2. PHP 파일에 직접 HTML 코드 작성
  3. 그누보드 상수(G5_THEME_URL 등)를 사용하여 경로 처리

* **주의사항**:
  - 이미지 경로는 G5_THEME_URL 상수를 사용하여 절대경로로 설정
  - CSS 클래스명과 ID는 템플릿하우스와 동일하게 유지, 해당 블록의 CSS, JS는 해당 비주얼 블록에 있는 것을 사용

---

### 5. 주의사항 및 추가 안내

* **`G5_TEMHA_RESOUCES` 상수**: 테마의 CSS, JS 등 리소스 경로를 담고 있는 핵심 상수입니다. `extend/temha.extend.php` 파일이 누락되면 화면이 깨질 수 있습니다.

* **`board_blank` 클래스**: 게시판 블록에 포함된 `<article class="board_blank">` 요소는 에디터 영역 보호용입니다. 관련 제거 코드를 삭제하면 숨겨진 레이아웃이 노출될 수 있으니 주의 바랍니다.

* **메인 및 서브 페이지에 게시판 또는 동적 데이터 요소를 중간에 삽입하려면**, 해당 페이지에 관련 함수를 추가한 후, 버퍼 함수를 사용해 생성된 HTML을 주석 마커 위치에 삽입하는 방식으로 구현해야 합니다.

* **리소스 경로 처리**: 템플릿하우스 에디터와 연동 시 발생하는 상대경로 문제는 `base` 태그를 통해 해결합니다. 이는 404 오류를 방지하고 올바른 리소스 로딩을 보장합니다.

* **반응형 디자인**: 템플릿하우스에서 제작한 반응형 디자인이 그누보드에서도 정상적으로 작동하도록 설정되어 있습니다. 다양한 디바이스에서 테스트해보세요.

* 코드 설명 및 유지보수에 대한 개별 문의는 받지 않습니다.

---

### 6. 문의 및 지원

테마 관련 문의 및 업데이트 정보는 아래 공식 사이트에서 확인해 주세요.

* **템하마켓**: https://market.temha.io/
* **템플릿하우스 에디터**: 템플릿하우스 에디터를 통한 디자인 수정 및 연동 지원
* **그누보드 커뮤니티**: https://sir.kr/ - 그누보드 관련 기술 문의

