본문으로 건너뛰기

블록 태그로 템플릿 구성하기

프로젝트에 블록이 몇 개 생기면 템플릿끼리 서로를 필요로 하기 시작합니다. features 블록은 카드 세 개를 출력하고 싶고, 랜딩 페이지에는 버튼이 들어 있는 섹션이 필요합니다. 각 항목마다 bs_render_block()을 호출할 수 있지만, 중첩 배열을 사용하는 PHP 호출로 가득한 템플릿은 읽기 어렵고 중첩하기는 더 어렵습니다.

블록 태그를 사용하면 출력이 들어갈 위치에 HTML 태그로 블록을 작성할 수 있습니다:

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

같은 태그라도 작성된 위치에 따라 서로 다른 의미를 가집니다. 블록 템플릿이나 글 콘텐츠 안에서는 블록의 렌더링된 HTML로 대체됩니다. 페이지, 패턴 또는 Site Template 소스 안에서는 편집기에 표시되는 실제 WordPress 블록이 됩니다. 이 가이드에서는 블록 몇 개를 만들고, 두 방식으로 조합하고, 짧은 이름을 위한 프로젝트 접두사를 추가한 뒤, 그 축약형을 이식성 있는 표기로 되돌리는 방법을 보여 줍니다.

블록

작은 블록 세 개면 충분합니다. 필드 두 개가 있는 카드:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title", "default": "" },
      { "id": "text", "type": "textarea", "label": "Text", "default": "" }
    ]
  }
}
PHP
<article useBlockProps class="acme-card">
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['text'] ); ?></p>
</article>

안에 배치된 항목을 감싸는 섹션입니다. heading 필드는 카드의 필드와 같은 방식으로 선언합니다:

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

그리고 두 번째 네임스페이스 acme-ui/button에 있는 버튼과 label, href 필드입니다:

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

블록 템플릿 안의 태그

블록 템플릿은 태그를 자동으로 렌더링합니다. 별도의 설정은 필요하지 않습니다. features 블록에서 카드 두 개와 core 구분선을 바로 출력할 수 있습니다:

PHP
<div useBlockProps class="acme-features">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <block name="acme/card" title="Typed" text="Fields come from block.json." />
  <block name="core/separator" />
</div>

acme/features을 렌더링하면 다음과 같이 출력됩니다:

HTML
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Typed</h3>
  <p>Fields come from block.json.</p>
</article>

  <hr class="wp-block-separator has-alpha-channel-opacity">
</div>

출력의 각 Blockstudio 블록 앞에는 <!--blockstudio/namespace/slug--> 주석이 있습니다. 페이지 버퍼가 응답에서 이 주석을 제거합니다. 버퍼를 거치지 않는 출력에는 bs_strip_render_markers()를 사용하세요. 두 구문은 동일합니다. <bs:acme-card>는 태그에 블록 이름을 인코딩하고, <block name="acme/card">는 이를 속성으로 전달합니다. 다른 모든 속성은 필드 값이 되므로 title은 카드 템플릿에 $a['title']로 전달됩니다. 기본 제공 블록 렌더러를 사용하는 WordPress를 통해 코어 블록도 렌더링됩니다.

짝을 이루는 태그와 내부 콘텐츠

짝을 이루는 태그는 자식 요소를 블록에 전달합니다. Blockstudio 블록에서는 자식 요소가 <InnerBlocks />을 채우며, 안에 중첩된 태그가 먼저 렌더링됩니다:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
HTML
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
  <h2>Why Acme</h2>
  <div>
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>

</div>
</section>

태그 이름이 블록 이름이 되는 방식

<bs:> 태그 이름에는 슬래시가 없으므로 Blockstudio이 이름을 찾습니다. 왼쪽에서 오른쪽으로 하이픈을 하나씩 슬래시로 바꾸고, 등록된 첫 후보를 사용합니다. <bs:acme-card>는 첫 번째 시도에서 acme/card으로 확인됩니다. <bs:acme-ui-button>는 acme/ui-button를 시도하지만 찾지 못한 뒤 acme-ui/button으로 확인됩니다. 따라서 하이픈이 포함된 네임스페이스도 두 후보가 모두 존재하지 않는 한 별도 설정 없이 사용할 수 있습니다.

접두사로 이름 줄이기

<bs:acme-ui-button>은 정확하지만 깁니다. 프로젝트 접두사를 설정하면 짧은 태그 접두사를 하나 이상의 네임스페이스에 연결할 수 있습니다. blockstudio.json에서 설정하세요:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

또는 PHP에서 같은 매핑을 등록할 수 있습니다:

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

이제 <acme-card>은 acme/card로, <ui-button>는 acme-ui/button로 확인됩니다. 접두사에 여러 네임스페이스가 지정된 경우 순서대로 확인하며, 첫 번째로 등록된 블록을 사용합니다. 따라서 프로젝트 블록이 같은 slug를 가진 라이브러리 블록보다 우선하도록 할 수 있습니다.

접두사는 조합해서 사용할 수도 있습니다. <acme-ui-button>은 먼저 acme/ui-button을 시도합니다. 해당 블록은 없고 태그의 나머지 부분인 ui-button 자체가 등록된 접두사 태그이므로, 확인 과정은 acme-ui/button으로 이어집니다. 직접 일치하는 항목이 중첩된 항목보다 항상 우선합니다.

HTML
<bs:acme-section heading="Why Acme">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

이 코드는 위의 정식 버전과 똑같은 HTML을 렌더링합니다.

접두사에는 다음 규칙이 적용됩니다:

  • 접두사는 영문 소문자와 숫자로 구성하고, 영문자로 시작해야 하며, 대시는 포함할 수 없습니다.
  • 접두사가 붙은 태그가 등록된 블록으로 확인되지 않으면 출력에서 변경되지 않으므로 <acme-missing title="x" />은 작성된 그대로 유지됩니다.
  • blockstudio/block_tags/tag_aliases 필터의 정확히 일치하는 별칭은 접두사보다 우선합니다. 별칭은 대시가 있는 태그 하나를 블록 하나에 연결합니다. 예를 들어 $aliases['acme-cta'] = 'acme-ui/button';는 <acme-cta>이 버튼을 렌더링하도록 합니다.

접두사 및 별칭 태그는 Blockstudio 7.5의 <bs:> 및 <block> 태그와 함께 블록 템플릿에서 렌더링됩니다.

속성

필드 ID와 일치하는 속성은 필드 값이 됩니다. 두 가지 접두사는 다른 용도로 사용됩니다:

  • data-* 속성은 렌더링된 블록의 루트 요소에 복사됩니다.
  • html-* 속성은 접두사를 제거한 상태로 루트 요소에 복사되므로 html-id="intro"는 id="intro"이 됩니다.
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<article data-track="card" id="intro" class="featured">
  <h3>Hi</h3>
  <p>There</p>
</article>

html-class은 속성을 설정할 뿐 추가하지 않습니다. 블록 자체의 acme-card wp-block-acme-card 클래스는 모두 사라집니다. 호출자가 블록에 클래스를 추가하도록 하려면 해당 필드를 선언하고 템플릿에서 병합하세요.

선언된 필드가 아닌 다른 속성은 모두 삭제됩니다. <bs:acme-card>에 class="wide"만 단독으로 사용하면 클래스 없이 카드가 렌더링됩니다. WP_DEBUG가 활성화되어 있으면 Blockstudio 7.7은 이런 속성을 _doing_it_wrong() 알림으로 표시합니다.

페이지 소스에서 같은 태그 사용하기

파일 기반 페이지, 패턴, Site Template에서는 태그가 렌더링되지 않습니다. 소스를 파싱할 때 블록으로 변환되므로 편집기에 표시됩니다. 다음 페이지 소스는:

HTML
<bs:acme-section heading="Why Acme">
  <p>Everything below is a real block.</p>
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

다음 블록 마크업으로 파싱됩니다(읽기 쉽게 줄바꿈을 추가함):

HTML
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->

필드 값은 blockstudio.attributes 아래에 저장됩니다. Blockstudio 블록은 여기에 값을 보관하며, 문단과 두 내부 블록은 섹션의 내부 블록이 됩니다. 접두사와 별칭은 템플릿에서와 동일하게 여기서도 확인됩니다.

글 콘텐츠의 태그

편집기에서 작성하거나 위젯에 저장한 콘텐츠는 기본적으로 검사하지 않습니다. blockstudio.json에서 페이지 수준 렌더링을 활성화하세요:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

그러면 the_content과 widget_text의 태그가 우선순위 5로 렌더링됩니다. 같은 설정으로 모든 문자열의 태그를 렌더링하는 필터도 등록됩니다:

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

모든 구문과 두 렌더링 모드에 적용되는 fnmatch() 와일드카드 패턴인 allow과 deny을 사용해 렌더링할 태그를 제한하세요:

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

이 규칙을 적용하면 <acme-ui-button>과 <bs:acme-ui-button>은 렌더링되지 않고 출력에 그대로 남습니다. deny가 allow보다 우선합니다. blockstudio/block_tags/allow와 blockstudio/block_tags/deny 필터는 PHP의 같은 목록을 변경합니다.

분석 단계에서 정식 표기 확인하기

PHPStan 확장은 PHP, Twig, Blade 템플릿의 블록 태그를 검증합니다. 필드나 블록 이름에 오타가 있으면 태그가 확인된 블록과 함께 표시됩니다:

Text
  3      Block tag "acme/card" has unknown attribute "txt" in index.php
         🪪  blockstudio.blockTag.attribute
  4      Block tag references unknown block "acme/cards" in index.php
         🪪  blockstudio.blockTag.unknown

7.6에서는 <bs:> 및 <block> 태그가 검사됩니다. <acme-card txt="..."> 같은 접두사 태그는 검사하지 않습니다. Blockstudio 7.7에서는 접두사 태그, 페이지 소스, 매핑된 HTML 요소까지 규칙이 확장되며, 태그가 전달할 수 있는 전역 속성이 힌트에 표시됩니다.

축약형을 정식 표기로 변환하기

접두사 및 별칭 태그는 프로젝트에서 편리하게 사용하기 위한 기능입니다. 프로젝트의 필터와 설정이 로드된 곳에서만 확인되므로, 다른 프로젝트나 블록 라이브러리로 템플릿을 복사하거나 코딩 에이전트의 컨텍스트에 넣으면 의미를 잃습니다. <bs:namespace-slug>에는 실제 블록 이름이 기록되어 어디서나 확인되므로 Blockstudio의 예제, 진단, 생성된 출력에서도 이를 사용합니다.

독립 실행형 명령은 축약형을 해당 표기로 다시 씁니다. 별칭, 더 이상 존재하지 않는 블록의 태그, 코드 샘플 안의 예제를 포함해 아직 짧은 형식을 사용하는 소스가 있는 프로젝트를 살펴보겠습니다:

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <acme-card title="Example" /></code></pre>

이 명령은 WordPress을 로드하지 않으므로 스캔 대상 트리 외부에 보관된 JSON 파일을 통해 프로젝트 설정을 전달합니다:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

기본값이기도 한 시험 실행부터 시작합니다:

셸
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/acme-tags/prefixes.json \
  --known-blocks=/tmp/acme-tags/blocks.json \
  --aliases=/tmp/acme-tags/aliases.json \
  --report=/tmp/acme-tags/report.json \
  --dry-run
Text
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.

보고서에는 적용할 모든 매핑과 추측하지 않을 모든 항목이 나열됩니다:

JSON
{
  "mappings": [
    { "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
    { "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
    { "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
    { "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
  ],
  "unknown": [
    { "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
  ],
  "manual": [
    { "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
  ]
}

여기서는 보고서 내용을 줄였습니다. 보고서에는 설정 및 파일별 전후 해시도 기록됩니다. 섹션의 여는 태그와 닫는 태그는 두 개의 항목으로 계산됩니다. acme-quote은 acme 접두사와 일치하지만 알려진 블록을 지정하지 않으므로 알 수 없는 태그입니다. <pre><code> 안의 acme-card는 마크업이 아니라 예제이므로 수동 검토 항목으로 표시되며 다시 쓰지 않습니다. HTML 주석과 인라인 코드도 마찬가지입니다.

알 수 없거나 모호하거나 동적인 태그가 남아 있으면 적용이 거부됩니다:

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

명령이 2로 종료됩니다. 여기서는 알 수 없는 태그를 제거해 문제를 해결한 다음 --dry-run 대신 --apply을 사용해 실행하세요:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

태그 이름만 변경됩니다. 속성은 바이트 단위로 그대로 보존됩니다:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

결과에 대해 시험 실행을 다시 하면 0 changed, 0 replacements이 보고됩니다. 그 후에도 접두사를 등록해 둘 수 있으므로, 다른 브랜치에서 짧은 형식을 계속 사용해도 문제가 발생하지 않습니다.

다음 단계