개발자 레퍼런스

테마 API 레퍼런스

TubePress 테마 API 레퍼런스: 튜브 사이트 테마를 만들거나 사용자 지정할 때 사용할 수 있는 모든 전역 템플릿 변수, 헬퍼 함수, 클래스를 다룹니다.

이 페이지는 테마가 사용할 수 있는 모든 것에 대한 완전한 참조입니다: 모든 템플릿에 주입되는 전역 변수, 각 템플릿에 특정한 변수, 그리고 테마 코드에서 사용 가능한 헬퍼 클래스. 테마를 빌드하거나 커스터마이징하는 경우, 이 페이지를 테마 개발과 함께 열어 두세요.

모든 템플릿은 ThemeRenderer::render($template, $data)에 의해 렌더링됩니다. 렌더러는 $_ 접두사가 붙은 전역 변수 세트를 주입하고, 템플릿별 $data를 병합한 다음, theme.template_data 필터를 실행하고, 템플릿을 $content로 버퍼링한 후 layout.php를 로드합니다.

전역 변수

이것들은 모든 템플릿과 layout.php에서 사용 가능합니다.

사이트

변수	타입	설명
`$_template`	string	현재 템플릿 이름 (예: `'home'`, `'video'`)
`$_siteName`	string	설정에서 가져온 사이트 이름
`$_siteDescription`	string	사이트 설명
`$_siteUrl`	string	사이트 URL
`$_videosPerRow`	int	그리드 열 수 (4, 5 또는 6)
`$_user`	array\\|null	로그인한 사용자, 또는 null
`$_footerPages`	array	푸터에 표시되도록 설정된 정적 페이지
`$_registrationEnabled`	bool	회원가입 토글
`$_ctrEnabled`	bool	CTR 랭킹 토글

외관

변수	타입	설명
`$_siteLogo`	string	`/uploads/branding/` 내 로고 파일명
`$_siteFavicon`	string	파비콘 파일명
`$_siteBackground`	string	배경 이미지 파일명
`$_siteBackgroundMode`	string	`'cover'`, `'contain'` 또는 `'repeat'`
`$_colorOverrides`	string	CSS 사용자 정의 속성이 포함된 `<style>` 블록
`$_menuSearch`	bool	검색창 표시
`$_menuItems`	array	탐색 항목 (`key`, `label`, `url`, `enabled`, `templates`)

로케일

변수	타입	설명
`$_locale`	string	현재 로케일 코드 (예: `'en'`)
`$_direction`	string	`'ltr'` 또는 `'rtl'`
`$_isRtl`	bool	오른쪽에서 왼쪽으로 쓰는 언어
`$_availableLangs`	array	사용 가능한 언어
`$_langPrefix`	string	URL 접두사 (예: `'/fr'` 또는 `''`)

동영상 카드 설정

변수	타입	설명
`$_cardShowDuration`	bool	재생 시간 배지 표시
`$_cardShowTitle`	bool	동영상 제목 표시
`$_cardMetaLeft`	string	왼쪽 메타: `'views'`, `'likes'`, `'time'`, `'none'`
`$_cardMetaRight`	string	오른쪽 메타 (동일한 옵션)
`$_cardGridGap`	int	픽셀 단위 그리드 간격
`$_cardBorderRadius`	int	픽셀 단위 카드 테두리 반경
`$_cardThumbnailHover`	bool	썸네일 호버 효과
`$_cardTitleLines`	int	제목 줄 수 (1 또는 2)

시청 페이지 설정

변수	타입	설명
`$_watchShowViews`	bool	조회수 표시
`$_watchShowDuration`	bool	재생 시간 표시
`$_watchShowDate`	bool	게시 날짜 표시
`$_watchShowLikes`	bool	좋아요 / 싫어요 표시
`$_watchShowFavorites`	bool	즐겨찾기 버튼 표시
`$_watchShowPornstars`	bool	출연자 표시
`$_watchShowChannels`	bool	채널 표시
`$_watchShowCategories`	bool	카테고리 표시
`$_watchShowTags`	bool	태그 표시
`$_commentsEnabled`	bool	댓글 활성화

이것들은 설정이지 마법이 아닙니다. 모든 $_card* 및 $_watch* 값은 관리자 외관 화면에서 직접 가져오므로, 사이트 소유자는 코드를 건드리지 않고도 테마를 재스타일링할 수 있습니다 — 하드코딩 대신 이 변수들을 읽기만 한다면요.

템플릿별 변수

전역 변수 외에도, 각 템플릿은 자체 데이터를 받습니다.

home.php

변수	타입
`$videos`	배열 — 동영상 행
`$pagination`	Pagination 객체
`$sort`	문자열 — 현재 정렬 키

video.php

변수	타입
`$video`	배열 — 카테고리, 태그, 출연자, 채널이 포함된 전체 동영상
`$categories`, `$tags`, `$performers`	배열
`$comments`	배열
`$similar`	배열 — 유사 동영상
`$recommended`	배열 — 추천 동영상
`$userVote`	string\\|null — `'like'`, `'dislike'` 또는 null
`$isFavorited`	bool

category.php / tag.php / performer.php / channel.php

변수	타입
`$category` / `$tag` / `$performer` / `$channel`	배열 — 해당 엔티티
`$videos`	배열 — 동영상 행
`$pagination`	Pagination 객체
`$sort`	string

목록 템플릿

템플릿	주요 변수
`categories.php`	`$categories` — 각 항목에 `video_count` 있음; CTR 활성화 시, `best_video_thumbnail`
`performers.php`	`$performers` — `video_count`; CTR 활성화 시, `best_video_thumbnail`, `total_ctr`, CTR 기준 정렬; `$pagination`
`channels.php`	출연자와 동일한 구조
`search.php`	`$query`, `$videos`, `$pagination`

헬퍼 클래스

이 정적 헬퍼들은 모든 템플릿에서 사용 가능합니다.

클래스	주요 메서드
`ThemeRenderer`	`::enqueueCSS($url, $priority)`, `::enqueueJS($url, $priority)`, `::partial($name, $data)`, `::bodyClass()`, `::renderCSS()`, `::renderJS()`
`ThemeManager`	`::assetUrl($path)`, `::themePath()`, `::templatePath($t)`, `::active()`, `::info($key)`
`ImpressionTracker`	`::collect($videoId)`, `::flush()`, `::isBot()`
`Format`	`::number($n)`, `::duration($seconds)`, `::timeAgo($datetime)`, `::fileSize($bytes)`
`Pagination`	`->total`, `->page`, `->totalPages`, `->offset`, `->hasPrev()`, `->hasNext()`, `->pages()`, `->prevUrl()`, `->nextUrl()`
`Router`	`::url($path)`, `::csrfField()`, `::csrfToken()`, `::langPrefix()`
`HookSystem`	`::doAction($event, ...$args)`, `::applyFilter($filter, $value, ...$args)`
`Auth`	`::check()`, `::user()`, `::id()`
`Setting`	`::get($key, $default)`
`__($key, $replacements)`	번역 헬퍼
`url($path)`	`Router::url($path)`의 단축키

렌더링 흐름

컨트롤러가 렌더러를 호출합니다. ThemeRenderer::render('home', ['videos' => $videos, …]).
전역 변수가 주입됩니다. $_ 접두사가 붙은 사이트, 외관, 로케일, 카드/시청 변수가 추가됩니다.
플러그인이 데이터를 수정할 수 있습니다. HookSystem::applyFilter('theme.template_data', $data, $templateName)가 실행됩니다.
템플릿이 렌더링됩니다. 템플릿 파일이 $content로 버퍼링됩니다.
레이아웃이 로드됩니다. layout.php가 $content와 모든 변수를 받습니다.
임프레션이 플러시됩니다. ImpressionTracker::flush()가 일괄 임프레션 업데이트를 전송합니다 (CTR).
Cron이 실행됩니다. CronManager::run()이 예정된 작업을 실행합니다.

layout.php 요구 사항

테마의 layout.php는 다음을 모두 수행해야 합니다:

전체 HTML 쉘을 출력합니다 (<!DOCTYPE html> … </html>).
<?= ThemeRenderer::renderCSS() ?>를 <head>에 포함합니다.
<?= $_colorOverrides ?>를 <head>에 포함합니다.
<main> 안에 $content를 출력합니다.
</body> 앞에 <?= ThemeRenderer::renderJS() ?>를 포함합니다.
</body> 앞에 <?php ImpressionTracker::flush(); ?>를 호출합니다 (CTR용).
<head>에 <?php HookSystem::doAction('head.meta'); ?>를 호출합니다.
</body> 앞에 <?php HookSystem::doAction('footer.scripts'); ?>를 호출합니다.

템플릿 폴백

활성 테마에 템플릿이 없는 경우, TubePress는 번들로 제공되는 Simply 테마로 폴백됩니다. 따라서 커스텀 테마는 실제로 변경하려는 템플릿만 재정의하면 됩니다 — 하나의 템플릿부터 시작해서 점차 확장하세요.

다음 단계

테마 개발단계별로 테마를 처음부터 빌드합니다. 훅 & 플러그인훅할 수 있는 액션과 필터. 아키텍처전체 CMS가 어떻게 구성되어 있는지.

여전히 막히셨나요?

대시보드에서 티켓을 열면 저희 팀이 도와드리겠습니다.

라이브 데모 체험하기 → TubePress 다운로드 →