사이트 템플릿
사이트 템플릿을 사용하면 블록 테마에서 WordPress wp_template 및
wp_template_part 소스를 정의할 수 있습니다. Blockstudio
페이지 및 패턴에서 사용하는 것과 동일한 파일 우선 구문을 사용합니다.
사이트 편집기의 템플릿 계층 구조에 따라 WordPress이 선택하는 테마 레이아웃(첫 페이지, 단일 글, 아카이브, 검색, 404 페이지, 헤더, 푸터 및 기타 템플릿 파트)을 제어하려면 사이트 템플릿을 사용하세요.
페이지, 패턴 또는 사이트 템플릿?
| 기능 | 생성 항목 | 적합한 용도 |
|---|---|---|
| 페이지 | 글 또는 사용자 지정 글 유형 항목 | 실제 콘텐츠 페이지, 문서 페이지, 랜딩 페이지 및 라우팅 가능한 콘텐츠 |
| 패턴 | 블록 패턴 | 편집자가 삽입하는 재사용 가능한 섹션 |
| 사이트 템플릿 | wp_template 및 wp_template_part 파일 소스 |
사이트 편집기와 WordPress 템플릿 계층 구조로 제어하는 테마 레이아웃 |
사이트 템플릿은 일반 페이지를 만들지 않습니다. 블록 테마 템플릿을 확인할 때 WordPress이 사용하는 파일 소스를 제공합니다. 사용자가 사이트 편집기에서 템플릿을 사용자 지정하면 WordPress은 해당 사용자 지정을 데이터베이스에 저장하며, 초기화할 때까지 파일 소스보다 우선합니다.
폴더 구조
전체 템플릿은 templates/에, 템플릿 파트는 parts/에 배치하세요:
theme/
templates/
front-page/
template.json
index.php
single/
template.json
index.twig
parts/
header/
part.json
index.php
footer/
part.json
index.php
각 폴더에는 매니페스트와 소스 파일 하나가 있습니다.
| 파일 | 엔진 |
|---|---|
index.php |
HTML와 유사한 블록 마크업이며 그대로 읽습니다(PHP 코드는 실행되지 않음) |
index.blade.php |
Blade |
index.twig |
Twig |
index.html |
HTML와 유사한 블록 마크업 |
소스 파일이 여러 개 있으면 Blockstudio은 다음 순서를 따릅니다:
index.phpindex.blade.phpindex.twigindex.html
WordPress은 .html 파일도 재귀적으로 검색하며, 일반적으로 경로에서 파생된 슬러그 아래에 중첩된 index.html를 표시합니다(예: header/index).
해당 파일이 Blockstudio 매니페스트에 속하면 Blockstudio은 경로에서 파생된 중복 항목을 제거하고 매니페스트에 선언된 slug만 표시합니다.
Blockstudio 매니페스트가 없는 중첩된 기본 .html 템플릿은 변경되지 않습니다.
소스는 기본 WordPress 블록 마크업으로 한 번 컴파일됩니다. 현재 요청이나 현재 글에 의존해서는 안 됩니다. 런타임 동작은 동적 블록 안에 넣으세요.
template.json
template.json은 전체 사이트 편집기 템플릿을 정의합니다.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template",
"postTypes": ["page"]
}
속성
| 속성 | 유형 | 기본값 | 설명 |
|---|---|---|---|
slug / name |
string |
폴더 이름 | WordPress 템플릿 슬러그. front-page, single, archive-product 또는 404과 같은 정확한 계층 슬러그를 사용하세요. |
title |
string |
슬러그에서 가져온 제목 | 사이트 편집기에 표시되는 제목. |
description |
string |
"" |
사이트 편집기에 표시되는 설명. |
postTypes |
string[] |
[] |
사용자 지정 템플릿의 글 유형. 코어 계층 템플릿에서는 생략할 수 있습니다. |
source / template / file |
string |
자동 감지된 색인 파일 | 템플릿 폴더 기준의 선택적 소스 파일 경로. |
status |
string |
"publish" |
템플릿 상태. |
sync |
boolean |
false |
향후 데이터베이스 구체화를 위해 예약됨. 사용자 지정 사항은 v1에서 절대 덮어쓰지 않습니다. |
meta |
object |
{} |
헬퍼 API용 사용자 지정 메타데이터. 알 수 없는 매니페스트 키도 여기에 저장됩니다. |
템플릿 슬러그에는 접두사가 없습니다. WordPress에는 템플릿 계층 구조에 정확한 이름이 필요합니다.
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat
part.json
part.json은 사이트 편집기 템플릿 파트를 정의합니다.
{
"slug": "header",
"title": "Header",
"description": "Main site header",
"area": "header"
}
속성
| 속성 | 유형 | 기본값 | 설명 |
|---|---|---|---|
slug / name |
string |
폴더 이름 | WordPress 템플릿 파트 슬러그. |
title |
string |
슬러그에서 가져온 제목 | 사이트 편집기에 표시되는 제목. |
description |
string |
"" |
사이트 편집기에 표시되는 설명. |
area |
string |
"uncategorized" |
템플릿 파트 영역. 일반적인 값은 header, footer, sidebar입니다. |
source / template / file |
string |
자동 감지된 색인 파일 | 파트 폴더 기준의 선택적 소스 파일 경로. |
status |
string |
"publish" |
템플릿 파트 상태. |
meta |
object |
{} |
헬퍼 API용 사용자 지정 메타데이터. 알 수 없는 매니페스트 키도 여기에 저장됩니다. |
마크업 작성
사이트 템플릿 소스는 페이지 및 패턴과 동일한 파서를 사용합니다:
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<p>This template is compiled from Blockstudio files.</p>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" />
</div>
<main> 요소는 core/group 블록이 되어 <main>로 렌더링됩니다.
core/post-content 블록 태그를 포함한 자식 요소는 내부 블록이 됩니다. 다음을 사용할 수 있습니다:
<h1>,<p>,<ul>,<div>같은 표준 HTML 요소와<main>,<header>,<footer>,<article>,<aside>같은 섹션 구분 요소<block name="namespace/block"><bs:namespace-block>- 구성된 블록 태그 접두사
- Blockstudio 블록 및 컴포넌트
WordPress이 컴파일된 템플릿을 렌더링할 때 템플릿 파트 블록에는 활성 테마 속성이 적용됩니다.
사이트 편집기 사용자 지정
Blockstudio은 파일 소스를 제공합니다. WordPress은 사용자 지정을 관리합니다.
조회 순서:
- 사이트 편집기의 데이터베이스 사용자 지정
- 활성 테마의 기본
.html파일 - Blockstudio 파일 기반 소스
- 상위 테마 또는 플러그인 대체 항목
사용자가 사이트 편집기에서 Blockstudio 파일 기반 템플릿을 저장하면 WordPress은 일반 wp_template 또는 wp_template_part 데이터베이스 항목을 만듭니다.
저장된 항목은 이후 파일 변경 사항보다 우선합니다. 사용자 지정을 초기화하거나 삭제하면 최신 파일 기반 소스가 다시 표시됩니다.
Blockstudio은 사이트 편집기의 수정 내용을 v1 파일에 기록하지 않습니다.
성능
템플릿 검색은 요청별로 캐시되며 파일 감시 메타데이터와 함께 저장됩니다. 매니페스트나 소스 파일을 변경하면 캐시된 컴파일 콘텐츠가 무효화됩니다. 데이터베이스 사용자 지정은 캐시에서 덮어쓰지 않습니다. WordPress이 여전히 이를 먼저 확인합니다.
여러 루트의 파일을 조합하는 런타임 통합 기능은 템플릿과 템플릿 파트에 논리적 검색 소스를 제공할 수 있습니다. 매니페스트와 선택된 소스 템플릿은 하나의 논리 테마 트리를 유지하면서 서로 다른 물리적 루트에 있을 수 있습니다.
PHP API
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();
$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');
$paths = Blockstudio\Site_Templates::get_paths();
정확한 슬러그, 경로 또는 소스 경로만 읽고 컴파일하려면 명시적인 목록을 전달하세요:
$templates = Blockstudio\Site_Templates::templates([
'front-page',
]);
$parts = Blockstudio\Site_Templates::parts([
'header',
]);
$errors = Blockstudio\Site_Templates::selection_errors('templates');
인수를 생략하면 전체 레지스트리 동작이 유지됩니다. 빈 목록을 전달하면 항목이 반환되지 않습니다. 관례적인 슬러그 및 경로 요청은 검색 범위를 일치하는 디렉터리로 좁힙니다. 사용자 지정 매니페스트 슬러그에는 메타데이터 검색이 필요할 수 있지만, 관련 없는 소스는 컴파일되거나 반환되지 않습니다.
템플릿 헬퍼 함수도 사용할 수 있습니다:
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');
훅
사이트 템플릿의 전체 확장 지점은 다음과 같습니다:
| 훅 | 유형 | 설명 |
|---|---|---|
blockstudio/site_templates/template_paths |
필터 | 전체 템플릿 검색 루트를 조정합니다. |
blockstudio/site_templates/part_paths |
필터 | 템플릿 파트 검색 루트를 조정합니다. |
blockstudio/site_templates/paths |
필터 | 두 경로 목록을 templates 및 parts로 조정합니다. |
blockstudio/site_templates/template_candidates |
필터 | 매니페스트의 소스 파일 후보를 조정합니다. |
blockstudio/site_templates/templates |
필터 | 레지스트리 API이 반환하는 템플릿을 조정합니다. |
blockstudio/site_templates/parts |
필터 | 레지스트리 API이 반환하는 템플릿 파트를 조정합니다. |
blockstudio/site_templates/template_content |
필터 | 파싱 전에 컴파일된 전체 템플릿 소스를 조정합니다. |
blockstudio/site_templates/part_content |
필터 | 파싱 전에 컴파일된 템플릿 파트 소스를 조정합니다. |
blockstudio/site_templates/parser |
필터 | 항목 하나에 사용할 Html_Parser 인스턴스를 교체합니다. |
blockstudio/site_templates/source_compiled |
액션 | 선택한 소스를 컴파일하기 직전에 실행됩니다. |
blockstudio/site_templates/discovered |
액션 | 캐시가 없는 검색 및 컴파일이 완료된 후 실행됩니다. |
blockstudio/site_templates/registered |
액션 | 재구축된 레지스트리가 저장된 후 실행됩니다. |
검색 경로 추가 또는 교체:
add_filter('blockstudio/site_templates/template_paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
});
add_filter('blockstudio/site_templates/part_paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
});
add_filter('blockstudio/site_templates/paths', function ($paths) {
return $paths;
});
검색된 데이터 필터링:
add_filter('blockstudio/site_templates/templates', function ($templates) {
return $templates;
});
add_filter('blockstudio/site_templates/parts', function ($parts) {
return $parts;
});
파싱 전 소스 필터링:
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
return $content;
}, 10, 2);
add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
return $content;
}, 10, 2);
소스 후보 또는 파서 변경:
add_filter(
'blockstudio/site_templates/template_candidates',
function ($candidates, $directory, $manifest) {
$candidates[] = $directory . '/template.custom.php';
return $candidates;
},
10,
3
);
add_filter(
'blockstudio/site_templates/parser',
function ($parser, $item) {
return $parser;
},
10,
2
);
discovered 및 registered은 캐시 재구축 수명 주기 액션입니다. 레지스트리 캐시가 적중해 따뜻한 상태일 때는 실행되지 않습니다.