본문으로 건너뛰기

파일로 사이트 편집기 템플릿 및 템플릿 파트 작성하기

블록 테마는 templates/*.html과 parts/*.html에 레이아웃을 정의합니다. 직렬화된 블록 주석으로 가득한 파일로, 예를 들면 <!-- wp:template-part {"slug":"header"} /--> 같은 형식입니다. 이런 내용을 직접 작성하고 싶은 사람은 없으므로, 보통 사이트 편집기에서 만든 다음 내보냅니다. 하지만 두 사람이 같은 템플릿을 수정하거나 검토자가 HTML 주석 안의 이스케이프된 JSON diff를 읽어야 하면 문제가 생깁니다.

Blockstudio을 사용하면 파일 기반 페이지를 작성하듯 같은 템플릿을 만들 수 있습니다. 작은 JSON 매니페스트와 HTML 스타일 마크업으로 작성한 소스 파일이 있는 폴더를 만들고, 일반 요소와 <block> 태그, 직접 만든 Blockstudio 블록을 사용하면 됩니다. Blockstudio은 소스를 네이티브 블록 마크업으로 컴파일해 테마 파일로 WordPress에 전달합니다. 사이트 편집기는 이전과 똑같이 작동합니다. 사용자는 템플릿을 사용자 지정할 수 있고, 초기화하면 파일 버전이 다시 적용됩니다.

이 가이드에서는 헤더와 푸터 파트, 프런트 페이지 및 단일 템플릿, 편집자가 페이지에 선택해 적용할 수 있는 사용자 지정 템플릿을 만들고, WordPress이 이를 어떻게 찾는지 보여줍니다.

폴더 구조

템플릿은 templates/에, 템플릿 파트는 parts/에 둡니다. 각 항목은 매니페스트와 소스 파일 하나가 있는 폴더입니다.

코드
theme/
├── templates/
│   ├── front-page/
│   │   ├── template.json
│   │   └── index.php
│   ├── single/
│   │   ├── template.json
│   │   └── index.php
│   └── page-landing/
│       ├── template.json
│       └── index.php
└── parts/
    ├── header/
    │   ├── part.json
    │   └── index.php
    └── footer/
        ├── part.json
        └── index.html

블록 테마에서 WordPress이 읽는 templates/ 및 parts/ 폴더와 같습니다. Blockstudio은 활성 테마를 먼저 살펴본 다음 부모 테마를 살펴봅니다. template.json 또는 part.json가 있는 폴더는 Blockstudio 소스입니다. 그 옆에 있는 일반 .html 파일은 네이티브 WordPress 템플릿으로 유지됩니다.

소스 파일은 index.php, index.blade.php, index.twig, index.html 순서로 확인됩니다. Twig에는 Timber가 필요하고, Blade에는 해당 렌더러 패키지가 필요합니다. 자세한 내용은 템플릿 엔진을 참조하세요.

1단계: 헤더 파트

모든 파트에는 part.json가 필요합니다. area는 사이트 편집기에 파트가 속한 위치를 알려줍니다:

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Site header with logo and navigation",
  "area": "header"
}

소스는 Blockstudio 페이지 및 패턴과 같은 문법을 사용합니다. <div>은 그룹 블록이 되고, 속성은 블록 속성이 되며, <block> 요소는 등록된 블록을 생성합니다:

PHP
<div layout='{"type":"flex","justifyContent":"space-between"}'>
  <block name="core/site-title" />
  <block name="core/navigation" overlayMenu="mobile" />
</div>

Blockstudio은 이를 다음 블록 마크업으로 컴파일합니다:

HTML
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->

직접 작성했다면 이런 결과가 나왔을 것입니다. 직접 만든 블록도 같은 방식으로 작동합니다. <block name="acme/announcement" />, <bs:acme-announcement /> 태그 또는 구성된 태그 접두어는 모두 해당 블록의 블록 주석으로 컴파일됩니다.

파트는 문단 하나만으로도 만들 수 있습니다. 이 예제는 소스가 프로그램이 아니라 마크업이라는 점을 보여주기 위해 index.html을 사용합니다:

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<p>Built with Acme.</p>

<!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->로 컴파일됩니다.

3단계: 프런트 페이지 및 단일 템플릿

템플릿에는 template.json을 사용합니다. slug은 WordPress 템플릿 계층 이름과 정확히 일치해야 합니다. 예: front-page, single, page, archive, 404 또는 single-product. Blockstudio은 이름 앞에 자동으로 붙지 않습니다.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<block name="core/template-part" slug="header" tagName="header" />

<main>
  <block name="core/post-content" />
</main>

<block name="core/template-part" slug="footer" tagName="footer" />

단일 글 템플릿도 글 블록을 사용해 같은 구조로 만듭니다:

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<block name="core/template-part" slug="header" tagName="header" />

<main>
  <block name="core/post-title" level="1" />
  <block name="core/post-date" />
  <block name="core/post-content" />
</main>

<block name="core/template-part" slug="footer" tagName="footer" />

컴파일된 단일 템플릿:

HTML
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

<main>은 tagName: "main"을 포함한 그룹 블록이 되었으며, 템플릿 파트 블록은 1단계와 2단계에서 만든 파트를 슬러그로 참조합니다. WordPress이 템플릿을 렌더링할 때 이 참조는 파일 기반 파트로 연결됩니다. 따라서 프런트 페이지 출력은 사이트 제목과 내비게이션이 있는 <header class="wp-block-template-part">으로 시작하고, 푸터 문단이 있는 <footer class="wp-block-template-part">로 끝납니다.

4단계: 페이지용 사용자 지정 템플릿

계층에 포함되지 않는 슬러그를 가진 템플릿은 사용자 지정 템플릿입니다. postTypes로 적용할 글 유형을 나열하면 편집자가 템플릿 선택기에서 선택할 수 있습니다:

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<main>
  <block name="core/post-content" />
</main>

<block name="core/template-part" slug="footer" tagName="footer" />

get_block_templates( array( 'post_type' => 'page' ), 'wp_template' )에는 이제 page-landing이 포함되고, 템플릿 객체에는 post_types: ["page"]가 들어갑니다.

소스는 한 번만 컴파일됩니다

소스는 요청마다 컴파일되는 것이 아니라 한 번 읽혀 블록 마크업으로 컴파일됩니다. 이때 현재 글이나 요청 컨텍스트는 없습니다. index.php은 마크업으로 읽힙니다. 그 안의 PHP 코드는 실행되지 않으므로 <?php echo get_bloginfo( 'name' ); ?>는 아무것도 컴파일하지 않습니다. 요청에 따라 달라지는 내용은 런타임에 렌더링되는 블록에 넣으세요. 사이트 이름을 직접 출력하는 대신 core/site-title을, the_title() 대신 core/post-title를 사용하거나 직접 동적 Blockstudio 블록을 만들면 됩니다.

컴파일 결과는 파일 감시 메타데이터와 함께 캐시됩니다. 매니페스트나 소스 파일을 수정하면 해당 항목의 캐시된 콘텐츠가 무효화되므로, 별도의 빌드 단계 없이 다음 요청부터 변경 사항이 반영됩니다.

WordPress이 파일을 찾는 방법

Blockstudio은 테마 템플릿을 찾을 때 WordPress이 사용하는 것과 같은 조회 방식에 연결됩니다. get_block_templates()에서 파일 기반 템플릿은 네이티브 테마 파일처럼 source: "theme" 및 origin: "theme"와 함께 표시되고, get_block_template( 'acme//header', 'wp_template_part' )는 area이 있는 헤더 파트를 반환합니다.

조회 순서:

  1. 데이터베이스에 저장된 사이트 편집기 사용자 지정 항목.
  2. 활성 테마에 있는 네이티브 .html 파일.
  3. Blockstudio 파일 기반 소스.
  4. 부모 테마 또는 플러그인의 대체 항목.

이 순서는 사이트 편집기 워크플로우를 그대로 유지합니다. 사용자가 푸터를 편집하고 저장하면 WordPress은 wp_template_part 글을 저장하고, get_block_template()는 source: "custom"을 사용해 해당 사용자 지정 항목을 반환합니다. 사용자 지정 항목이 있는 동안에는 parts/footer/index.html의 이후 변경 사항이 표시되지 않습니다. 사용자가 파트를 초기화하거나 글을 삭제하면 조회는 파일로 대체되어 최신 컴파일 소스를 다시 반환합니다.

Blockstudio은 사이트 편집기의 수정 사항을 파일에 다시 쓰지 않습니다. 사용자가 변경한 내용을 새 기본값으로 적용하려면 소스 파일에 복사한 다음 사용자 지정 항목을 초기화하세요.

중첩된 index.html 및 슬러그

WordPress은 templates/ 및 parts/에서 .html 파일을 재귀적으로 찾습니다. 따라서 index.html를 사용하는 매니페스트 폴더(예: parts/footer/index.html)도 경로에서 파생된 슬러그 footer/index를 가진 네이티브 파트로 표시됩니다. Blockstudio 7.6.6이므로, 매니페스트가 관리하는 index.html는 선언된 슬러그로만 노출됩니다. 따라서 사이트 편집기에는 푸터가 하나만 표시됩니다. 매니페스트가 없는 중첩 .html 파일은 그대로 둡니다.

PHP에서 템플릿 확인하기

Blockstudio\Site_Templates 클래스는 소스를 읽고 컴파일하므로 테스트와 배포 확인에 유용합니다:

PHP
$templates = Blockstudio\Site_Templates::templates();
$header    = Blockstudio\Site_Templates::get_part( 'header' );

echo $header['area'];    // header
echo $header['content']; // compiled block markup

$errors = Blockstudio\Site_Templates::errors();

각 항목에는 slug, title, description, type(wp_template 또는 wp_template_part), 템플릿의 경우 status 및 source_type, 파트의 경우 postTypes 또는 area, meta, 컴파일된 content이 포함됩니다. 컴파일할 항목만 목록으로 전달하고, 해당 항목의 문제는 selection_errors()로 확인하세요:

PHP
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors   = Blockstudio\Site_Templates::selection_errors( 'templates' );

다른 폴더 추가하기

Blockstudio 소스를 네이티브 템플릿과 분리하거나 플러그인에서 제공하려면 필터를 사용해 검색 루트를 추가하세요:

PHP
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;
} );

blockstudio/site_templates/template_content 및 part_content 필터는 구문 분석 전에 소스를 조정하며, blockstudio/site_templates/parser는 개별 항목의 파서를 바꿉니다. 전체 목록은 사이트 템플릿 훅 표를 참조하세요.

상황에 맞는 기능 선택하기

원하는 항목 사용할 기능
테마 레이아웃에서 URL의 헤더, 푸터, 단일 글, 아카이브를 선택하는 WordPress 사이트 템플릿 및 파트
콘텐츠를 파일에 저장하는 라우팅 가능한 페이지 파일 기반 페이지
편집자가 삽입할 수 있는 재사용 가능한 섹션 패턴

템플릿은 글을 만들지 않습니다. 페이지가 글을 만듭니다. 예를 들어 문서 섹션은 페이지 모음이며, 각 페이지의 글은 여기서 작성할 수 있는 템플릿을 통해 렌더링됩니다.

다음 단계