본문으로 건너뛰기

페이지 및 패턴

Blockstudio을 사용하면 테마의 파일로 WordPress 페이지, 블록 패턴, 사이트 편집기 템플릿을 정의할 수 있습니다. HTML과 비슷한 템플릿을 작성하면 Blockstudio 파서가 이를 네이티브 WordPress 블록으로 변환합니다.

  • 페이지는 데이터베이스에 WordPress 글로 동기화되어 파일 템플릿과 페이지 콘텐츠가 일치하게 유지됩니다.
  • 패턴은 register_block_pattern()을 통해 메모리에 등록되며, 블록 삽입기에서 사용할 수 있어 사용자가 원하는 곳에 배치할 수 있습니다.
  • 사이트 템플릿은 WordPress 사이트 편집기에서 사용할 파일 기반 wp_template 및 wp_template_part 소스를 제공합니다.

세 기능 모두 동일한 HTML 파서와 블록 구문을 공유합니다.

파일 기반 페이지 만들기

파일 기반 페이지 템플릿, 동기화, 잠금에 관한 실용적인 안내입니다.

폴더 구조

코드
theme/
├── pages/
│   ├── about/
│   │   ├── page.json
│   │   └── index.php
│   └── contact/
│       ├── page.json
│       └── index.twig
├── patterns/
    ├── hero/
    │   ├── pattern.json
    │   └── index.php
    └── cta/
        ├── pattern.json
        └── index.blade.php
├── templates/
    └── front-page/
        ├── template.json
        └── index.php
└── parts/
    └── header/
        ├── part.json
        └── index.php

각 하위 폴더에는 JSON 설정 파일(page.json, pattern.json, template.json 또는 part.json)과 템플릿 파일이 들어 있습니다.

템플릿 엔진

템플릿은 index.php의 일반 마크업이나 Twig 또는 Blade로 작성할 수 있습니다.

파일 엔진 요구 사항
index.php 없음(있는 그대로 읽으며 PHP 코드는 실행되지 않음) 없음
index.twig Twig Timber
index.blade.php Blade illuminate/view

템플릿 파일이 여러 개 있으면 우선순위는 다음과 같습니다. index.php > index.blade.php > index.twig.

템플릿은 요청 컨텍스트가 생기기 전인 초기화 시점에 컴파일되므로 Twig 및 Blade 템플릿은 동적 변수에 접근할 수 없습니다. {{ "text"|upper }}이나 {{ strtoupper("text") }} 같은 내장 함수와 필터에 유용합니다.

HTML에서 블록으로 매핑

표준 HTML 요소는 해당하는 WordPress 블록으로 자동 변환됩니다.

텍스트

HTML 블록
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list (순서 없음)
<ol> core/list (순서 있음)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

목록의 구조는 유지됩니다. <li> 안의 <ul> 또는 <ol>은 해당 core/list-item의 core/list 내부 블록이 됩니다. 이는 편집기가 저장하는 형태이므로 목록을 원하는 깊이까지 중첩할 수 있습니다. 목록이나 항목의 class은 해당 요소의 className이 됩니다. 따라서 페이지 파일에서 is-style-checks 같은 블록 스타일을 설정할 수 있으며 <block name="core/list" className="...">도 같은 방식으로 처리됩니다.

미디어

HTML 블록
<img> core/image
<figure> 캡션이 있는 core/image
<audio> core/audio
<video> core/video

레이아웃

HTML 블록
<div>, <section> core/group
<main>, <header>, <footer>, <article>, <aside> 요소를 tagName로 유지하는 core/group
<hr> core/separator
<details> core/details
<table> core/table

블록 구문

직접 대응하는 HTML 요소가 없는 블록에는 <block> 요소를 사용하세요.

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1>Welcome</h1>
  <p>Content inside the cover block.</p>
</block>

코어 블록

HTML
<!-- Pullquote -->
<block name="core/pullquote">
  <p>An important quote.</p>
</block>

<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>

<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
  <h2>Cover Title</h2>
</block>

<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />

<!-- Spacer -->
<block name="core/spacer" height="50px" />

<!-- Gallery -->
<block name="core/gallery">
  <img src="https://example.com/1.jpg" alt="Image 1" />
  <img src="https://example.com/2.jpg" alt="Image 2" />
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <h3>Column 1</h3>
  </block>
  <block name="core/column">
    <h3>Column 2</h3>
  </block>
</block>

<!-- Buttons -->
<block name="core/buttons">
  <block name="core/button" url="/get-started">Get Started</block>
</block>

<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Item 1</p>
  <p>Item 2</p>
</block>

사용자 정의 블록

등록된 모든 블록에서 같은 구문을 사용할 수 있습니다.

HTML
<block name="blockstudio/section">
  <h1>Welcome</h1>
</block>

<block name="acf/hero" title="Hero Title" background="dark">
  <p>Inner content becomes InnerBlocks.</p>
</block>

속성

<block> 요소의 HTML 속성은 블록 속성으로 전달됩니다. JSON 값도 지원됩니다.

HTML
<block name="core/heading" level="3">Custom Heading</block>

<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked content.</p>
</block>

<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />

속성 값은 브라우저가 읽는 방식대로 한 번 디코딩되므로 data-animate="[&amp;>span]:fade"과 data-animate="[&>span]:fade"은 같은 값을 저장합니다.

Blockstudio 블록에 매핑된 요소의 모든 속성은 블록에 저장됩니다. 선언된 필드는 템플릿에 전달됩니다. 블록에서 선언하지 않은 전역 속성(id, style, role, title, lang, dir, hidden, tabindex, aria-* 및 data-*)은 렌더링 시 블록의 루트 요소에 설정되며 블록 태그와 동일하게 처리됩니다. 페이지와 패턴 소스에서 html- 접두사는 이러한 전역 속성 중 하나만 지정하므로 html-role="note"는 role로 전달되지만 html-onclick 같은 이벤트 핸들러는 렌더링되지 않습니다. 선언되지 않은 class을 포함한 나머지 항목은 페이지에 표시되지 않고 글 콘텐츠에 남으며, wp bs pages sync은 파싱하는 모든 페이지에서 이를 보고합니다.

사용자 정의 블록 렌더러

HTML 파서는 레지스트리 기반 구조를 사용합니다. blockstudio/block_tags/builders로 사용자 정의 블록 빌더를 추가하세요.

PHP
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
    $builders['acf/hero'] = function( array $attrs, string $inner_content ) {
        $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );

        return array(
            'blockName'    => 'acf/hero',
            'attrs'        => $attrs,
            'innerBlocks'  => $inner_blocks,
            'innerHTML'    => '',
            'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
        );
    };

    return $builders;
}, 10, 2 );

그런 다음 템플릿 어디서나 사용할 수 있습니다.

HTML
<block name="acf/hero" background="dark">
  <h1>Welcome</h1>
</block>

코어 블록의 렌더링 방식도 재정의할 수 있습니다.

PHP
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
    $renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
        $content = trim( $inner_content );
        $attrs['align'] = $attrs['align'] ?? 'center';

        return array(
            'blockName'    => 'core/paragraph',
            'attrs'        => $attrs,
            'innerBlocks'  => array(),
            'innerHTML'    => '<p class="has-text-align-center">' . $content . '</p>',
            'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
        );
    };

    return $renderers;
}, 10, 2 );

빌더 콜백은 파싱된 속성과 원시 내부 콘텐츠를 받습니다. WordPress 블록 배열을 반환해야 합니다. 전체 필터 순서와 컨테이너 예제는 사용자 정의 렌더러를 참조하세요.

빌더 함수 시그니처

PHP
/**
 * @param array  $attrs         Parsed element or block-tag attributes.
 * @param string $inner_content Raw inner content.
 * @return array WordPress block array.
 */
function my_builder( array $attrs, string $inner_content ): array {}

요소 매핑

기본적으로 <h1>, <p>, <img> 같은 표준 HTML 요소는 코어 WordPress 블록에 매핑됩니다. blockstudio/parser/element_mapping 필터를 사용하면 이 매핑을 재정의하여 모든 HTML 요소를 다른 블록에 연결할 수 있습니다.

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['h1'] = 'custom/heading';
    $mapping['h2'] = 'custom/heading';
    $mapping['p']  = 'custom/paragraph';
    $mapping['img'] = 'custom/image';

    return $mapping;
}, 10, 2 );

이 필터를 활성화하면 템플릿의 모든 <h1>이 core/heading 대신 custom/heading 블록을 생성합니다. 요소의 속성은 대상 블록으로 전달됩니다. 대상 블록 이름에 등록된 렌더러가 있으면 해당 렌더러를 사용하고, 없으면 일반 블록 구조를 만듭니다.

테마나 플러그인이 모든 페이지 및 패턴 템플릿에서 기본 블록을 대체할 사용자 정의 블록 유형을 제공할 때 유용합니다.

간단한 <p> 매핑에서는 Blockstudio을 사용해 내부 HTML를 등록된 비코어 Blockstudio 블록의 content 리치 텍스트 속성으로 바로 전달할 수 있습니다. 대상 블록은 id: "content" 및 type: "richtext" 속성을 선언해야 합니다. 기본적으로 같은 태그가 요소 매핑되는 code와 img의 경우에도 인라인 서식(a, b, br, code, del, em, i, img, ins, mark, s, small, span, strong, sub, sup, u)은 전달된 값에 유지됩니다. 자식이 이미지뿐인 단락은 <img>이 매핑되는 블록이 됩니다. 이는 단독 이미지를 Markdown이 생성하는 방식과 같습니다. 중첩된 블록 태그와 블록 수준 HTML는 계속 내부 블록으로 파싱됩니다.

대상 블록이 요소 속성에 따라 달라지는 경우 매핑 값으로 호출 가능한 함수를 사용할 수도 있습니다.

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['div'] = function( array $attrs ) {
        if ( isset( $attrs['width'] ) ) {
            return 'theme/row';
        }

        if ( isset( $attrs['gap'] ) ) {
            return 'theme/flow';
        }

        return 'theme/div';
    };

    return $mapping;
} );

<section> 및 <div> 같은 컨테이너 요소에서 매핑된 사용자 정의 블록은 중첩된 HTML 자식을 재귀적으로 파싱하므로 내부 제목, 이미지, 블록 태그, 단락이 네이티브 자식 블록이 됩니다.

전체 예제

여러 블록 유형을 결합한 전체 페이지 템플릿입니다.

HTML
<div>
  <h1>Welcome to Our Site</h1>
  <p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>

  <block name="core/columns">
    <block name="core/column">
      <h3>Feature One</h3>
      <p>First feature description.</p>
    </block>
    <block name="core/column">
      <h3>Feature Two</h3>
      <p>Second feature description.</p>
    </block>
  </block>

  <block name="core/cover" url="https://example.com/hero.jpg">
    <h2>Our Mission</h2>
    <p>Building amazing things together.</p>
  </block>

  <details>
    <summary>FAQ</summary>
    <p>Answers to common questions.</p>
  </details>

  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
    <block name="core/button" url="/learn-more">Learn More</block>
  </block>
</div>