프로그래밍 방식 렌더링
Gutenberg이 고객이 쉽게 편집할 수 있는 웹사이트를 만드는 주요 도구가 되면서, 웹사이트에 필요한 모든 영역을 블록으로 만드는 것이 합리적입니다. 이 방식은 대부분의 경우에 적합하지만, 고급 사용자나 특정 사용 사례에서는 기존 블록을 편집기 밖에서 사용해야 할 수 있습니다.
Blockstudio은 블록을 프로그래밍 방식으로 렌더링하는 두 가지 방법을 제공합니다:
- PHP 함수: PHP 코드에서 렌더링하는
bs_render_block및bs_block - HTML 태그: 페이지 어디서나 블록 출력으로 대체되는
<bs:block-name>태그
인라인 스타일, 스크립트 및 범위가 지정된 스타일 등 Blockstudio 전용 기능을 모두 지원합니다.
아일랜드도 이러한 렌더링 경로에서 작동합니다. bs_render_block(), bs_block() 또는 블록 태그로 렌더링한 동적 아일랜드는 글 콘텐츠에서 렌더링한 블록과 동일한 플레이스홀더 마커를 반환하며, 응답에 해당 마커가 있으면 프런트엔드 런타임이 삽입됩니다.
구조화된 구성 및 완전한 문서
오래 사용하는 도구, 미리 보기, 내보내기 및 컴포넌트 갤러리에는 버전이 지정된 Blockstudio\Render API을 사용하세요. 선언 하나 또는 순서가 있는 목록을 받아 echo 없이 렌더링합니다:
use Blockstudio\Render;
$composition = [
'root' => 'theme/card',
'example' => [
'data' => [
'heading' => 'Example card',
],
'layers' => [
[
'name' => 'theme/button',
'data' => [
'label' => 'Continue',
],
],
],
],
];
$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
'title' => 'Component preview',
'contentElement' => 'main',
'contentClasses' => ['component-preview'],
]);
표준 정규화 선언에는 네 개의 키가 있습니다:
[
'name' => 'theme/card',
'attributes' => [],
'content' => '',
'children' => [],
]
data, inner, innerBlocks, root, layers 및 example은 입력 편의 기능이며 정규화 과정에서 제거됩니다. 중첩 선언은 동일한 Blockstudio 파이프라인을 통해 재귀적으로 렌더링됩니다.
Render::document()은 schemaVersion, html, body, blocks, assets, warnings 및 errors을 반환합니다. assets 값은 head, footer, styles, scripts, modules, interactivity, ui 및 tailwind을 구분합니다.
블록 목록과 에셋에는 선택한 템플릿이 참조하는 종속 항목이 포함되지만, 관련 없는 에셋과 편집기 전용 에셋은 제외됩니다.
완전한 문서에서는 bodyClasses/bodyAttributes을 설정하고, 선택적으로 렌더링된 본문을 contentElement, contentClasses 및 contentAttributes로 감쌀 수 있습니다. 래퍼에는 안전한 요소 이름만 사용할 수 있으며, 반환되는 body는 래핑되지 않은 렌더링 콘텐츠로 유지됩니다.
head 및 footer 옵션은 각 위치에 신뢰할 수 있는 문서 마크업을 추가하며, 반환된 에셋 클로저에 포함됩니다.
이미 렌더링된 HTML을 감싸는 문서를 구성하려면 알려진 루트 블록 이름을 지정하세요:
$document = Render::document_from_html(
$rendered_html,
['theme/hero', 'theme/button'],
['title' => 'Homepage preview']
);
직렬화된 WordPress 블록 콘텐츠에는 Render::content()을 사용하세요. 한 요청에서 여러 독립 문서를 렌더링하는 소비자는 문서 사이에 Blockstudio\Batch_Render::reset()를 호출해야 합니다. Canvas::documents()은 이를 자동으로 처리합니다.
페이지 외부에서 렌더링
Blockstudio은 렌더링하는 모든 블록 앞에 <!--blockstudio/namespace/slug--> 주석을 넣습니다. 프런트엔드 페이지에서는 버퍼가 이 주석을 읽어 어떤 블록이 있는지 확인하고, 해당 에셋을 로드한 다음 응답을 보내기 전에 주석을 제거합니다.
해당 버퍼를 거치지 않는 출력에는 주석이 남습니다. 여기에는 REST 응답, 피드, AJAX 핸들러, 그리고 do_blocks(), Render::content() 또는 bs_render_block() 후 다른 곳에 저장하거나 전송하는 HTML이 포함됩니다. 주석을 제거하려면 bs_strip_render_markers()를 사용하세요:
$html = bs_strip_render_markers(do_blocks($post->post_content));
이 함수는 등록된 Blockstudio 블록의 주석을 제거하고 다른 HTML 주석을 포함해 나머지는 모두 그대로 둡니다. 페이지 버퍼가 제거하는 것과 동일한 마커를 처리합니다. 블록 등록 후(init 또는 그 이후)에 호출하세요.
버퍼링된 프런트엔드 페이지에 여전히 출력되는 마크업은 제거하지 마세요. 페이지는 어떤 블록 에셋을 로드할지 알기 위해 주석이 필요하며, 마지막에 Blockstudio이 직접 주석을 제거합니다.
주석을 제거해도 에셋이 추가되지는 않습니다. 블록 CSS 및 JavaScript 파일은 페이지 버퍼만 삽입합니다. 이를 필요로 하는 소비자에게도 제공하려면 bs_block_assets() 또는 Render::document()를 사용하세요.
블록 검사
내부 레지스트리를 읽지 않고 확인된 필드 정의를 가져오려면 블록 등록 후(init 또는 그 이후)에 bs_block_fields()를 사용하세요:
$fields = bs_block_fields('theme/card');
if ($fields === null) {
// Unknown block, or not a Blockstudio block.
}
반환값은 속성 필터, 확장된 사용자 정의 필드, 재정의 항목, 중첩 그룹, 탭, 리피터를 포함하는 등록된 필드 정의 배열입니다. 필드가 없는 Blockstudio 블록은 []을 반환합니다. 결과는 복사본이므로 이를 변경해도 등록된 블록은 바뀌지 않습니다.
이것들은 정의이지 저장된 값이 아닙니다. 저장된 마크업을 검증하려면 별도의 필드 순회기를 유지하는 대신 bs_validate_block()검증을 사용하세요. 블록이 허용하는 값을 설명하려면 bs_block_schema()속성을 사용하세요. WordPress 소유 속성은 별도로 유지됩니다.
확장이 추가한 필드는 bs_block_fields()에 포함되지 않습니다. 해당 필드를 가져오려면 bs_block_extension_fields()를 사용하세요. 블록 이름으로 확장을 찾으므로 코어 블록과 타사 블록에도 사용할 수 있습니다:
$fields = array_merge(
bs_block_fields('core/paragraph') ?? [],
bs_block_extension_fields('core/paragraph')
);
반환값에는 일치하는 모든 확장의 필드 정의가 확장 등록 순서대로 나열되며, 구조는 bs_block_fields()와 같습니다. 일치하는 확장이 없는 블록은 []을 반환합니다. 확장 값은 블록 자체 필드 값과 동일한 attrs.blockstudio.attributes 객체에 저장되므로 모든 ID가 하나의 네임스페이스를 공유합니다. 두 확장이 같은 ID를 정의하면 두 정의가 모두 반환되고 같은 값을 편집합니다. 렌더링 시에는 나중에 등록된 확장의 정의가 적용됩니다.
저장된 블록의 값 중 템플릿이 실제로 전달받는 값을 읽으려면 bs_block_values()를 사용하세요.
블록에서 검색된 CSS 및 JavaScript를 검사하려면 bs_block_assets()를 사용하세요. 중첩 블록과 공유 런타임 종속성을 포함한 전체 미리 보기 문서가 필요하면 위에서 설명한 Render::document()를 사용하세요.
저장된 값 검증
프로그램으로 생성했거나 가져온 블록 속성을 저장하기 전에 확인하려면 블록 등록 후(init 또는 그 이후)에 bs_validate_block()를 사용하세요:
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);
if ($findings === null) {
// No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
// No stored-value problems were found.
} else {
// Review the findings before saving.
}
attrs 배열 전체를 전달하세요. blockstudio.attributes만 전달하면 안 됩니다.
Blockstudio 렌더링에서는 선언된 필드를 최상위 수준에도 전달할 수 있으며,
두 곳에 모두 값이 있으면 중첩 값이 우선합니다. 코어 및 타사 블록의 확장은 blockstudio.attributes만 읽습니다. 필드가 없는 빈 Blockstudio 블록도 관리 대상이며 null이 아니라 []를 반환합니다.
검증은 명시적으로 실행되며 읽기 전용입니다. 템플릿을 렌더링하거나, 값을 변경하거나, 글을 저장하거나, 미디어를 조회하거나, populate 콜백을 실행하지 않습니다. 저장, 페이지 동기화 또는 렌더링 중에 자동으로 실행되지도 않습니다. 살균 처리, 권한 확인, 첨부 파일 존재 여부 확인 기능이 아닙니다.
각 발견 항목에는 다음과 같은 고정 키가 포함됩니다:
[
'code' => 'unknown_option',
'path' => 'steps/1/style',
'source' => 'block',
'message' => 'This value is not among the field options.',
'value' => 'c',
'expected' => ['a', 'b'],
]
도구에서는 번역된 message이 아니라 code을 사용하세요. source은 block 또는
extension입니다. 경로는 저장소 키와 0부터 시작하는 반복기 행 또는 선택
인덱스를 사용하며, 앞에 슬래시를 붙이지 않습니다. 키의 리터럴 ~와 /은 ~0 및
~1로 이스케이프됩니다. 최상위 그룹은 하위 항목에 접두사를 붙입니다(cta_title). 이름 없는 그룹과 탭은 수준을 추가하지 않습니다. 다른 그룹이나 반복기 안에 ID가 있는 그룹은 빌더에서 지원되지 않으므로 해당 키를 사용할 수 없습니다. 메시지 필드에는 저장된 값이 없습니다. 파일 필드에서는 함께 제공되는 <id>__size을 사용할 수 있습니다.
Blockstudio 블록의 루트에서 장부 관리 키와 렌더링된 요소로 전달되는 전역 HTML 속성은 알 수 없는 필드로 취급되지 않습니다. 그렇다고 반복기 행이나 코어 블록 확장에 임의의 키를 사용할 수 있는 것은 아닙니다.
| 코드 | 의미 | expected |
|---|---|---|
unknown_field |
유지된 필드 중 이 저장소 키를 선언한 항목이 없습니다. | 알려진 저장소 키. |
unknown_option |
선택 항목이 알려진 옵션에 포함되지 않습니다. | 허용되는 옵션 값. |
wrong_type |
저장된 형식이 해당 필드에서 지원되지 않습니다. | 예상되는 저장소 계열 또는 유형. |
too_few_rows, too_many_rows |
존재하는 반복기의 값이 min 또는 max 범위를 벗어납니다. |
행의 경계값. |
definition_conflict |
하나의 키에 적용되는 정의들이 서로 다른 저장소 형식을 요구합니다. | 각 정의의 출처 및 필드 유형. |
shadowed_value |
중첩 값이 다른 최상위 필드 값을 덮어씁니다. | 우선 적용되는 중첩 값. |
extension_top_level |
템플릿은 최상위 값을 읽을 수 있지만 확장 바인딩은 읽을 수 없습니다. | blockstudio/attributes 아래에 필요한 경로. |
unknown_attribute |
Blockstudio 블록의 최상위 키는 렌더링 경로에서 읽히지 않아 삭제됩니다. | 등록된 속성 이름, 확장 필드 및 blockstudio. |
missing_container |
attributes, disabled, name 또는 editor이 최상위에 저장되어 있지만 blockstudio이 없습니다. |
blockstudio 아래에 필요한 경로. |
invalid_container |
blockstudio 또는 blockstudio.attributes이 객체가 아닙니다. |
object. |
unknown_field 항목의 메시지는 세 번 이하의 편집으로 일치하는 같은 수준의 가장 가까운 저장 키를 표시합니다. 알 수 없는 설정 규칙은 다음과 같습니다.
This storage key is not declared by the block or its extensions. Did you mean "title"?
expected에는 알려진 모든 키가 계속 표시됩니다.
일치 여부를 확인할 때 대소문자는 구분하지 않으며 해당 컨테이너의 저장 키만 고려합니다. 메시지는 번역되므로 통합 기능에서는 메시지 텍스트를 분석하지 말고 code, path, expected을 사용해야 합니다.
Blockstudio 블록의 최상위 키가 등록된 속성(필드, supports, lock 및
metadata용으로 WordPress이 추가하는 속성), 일치하는 확장의 필드,
blockstudio, 장부 관리 키 또는 전달되는 HTML 속성 중 어느 것에도 해당하지 않으면 템플릿 실행 전에 삭제됩니다. 필드 ID 오타나 blockstudio 래퍼 없이 저장된 values 객체와 같은 키는 해당 값 없이 블록이 렌더링되므로 진단 결과에 표시됩니다. 확장 필드만 포함된 블록은 최상위 키 검사를 받지 않습니다.
허용되는 형식은 렌더링 동작을 따릅니다. 다중 선택 필드와 체크박스에는 목록, 옵션 객체 하나 또는 숫자 0을 포함한 가져온 스칼라 값을 넣을 수 있습니다. 숫자 필드에는 숫자 문자열도 허용됩니다. 파일에는 첨부 파일 ID, ID 객체, 목록 또는 문자열 참조를 넣을 수 있습니다. 링크 및 아이콘 값은 객체여야 하며, 사용자 지정 필드 유형에는 등록된 속성 유형이 사용됩니다.
attributes 필드에는 이름이 비어 있지 않은 attribute 쌍의 목록과 스칼라 value이 들어갑니다. data.media 등의 선택적 메타데이터는 보존됩니다.
WordPress은 렌더링 전에 등록된 최상위 속성을 검증하므로 blockstudio.attributes 안에서는 허용되는 형식도 거부할 수 있습니다. 예를 들어 "a"의 라디오 값은 중첩 객체 안에서는 작동하지만, 등록된 유형이 object인 최상위에서는 삭제됩니다. 이런 값은 wrong_type를 생성합니다.
편집기에서 기록하는 것과 동일한 저장 형식을 사용하려면 중첩 객체를 사용하세요.
필드는 필수 항목이 아닙니다. 비어 있는 중첩 값(null, false, '',
[])과 비활성화된 필드는 값 오류를 생성하지 않습니다. 명시적으로 비어 있는 반복기는 여전히 min에 대해 검사하지만, 없거나 비활성화된 반복기는 검사하지 않습니다.
WordPress가 최상위의 빈 값을 삭제하고 비어 있지 않은 기본값으로 복원하면 해당 값이 보고됩니다. 중첩 객체에서 같은 값은 이를 지울 수 있습니다.
키에 저장된 값이 없어도 정의 충돌은 보고됩니다.
정적 옵션과 등록 시 이미 확인된 채우기 옵션은 채우기 함수를 다시 호출하지 않고 검사합니다. 원격 fetch 옵션과 {attributes.*}을 포함하는 채우기 인수는 건너뜁니다. disableCustomColors 또는 disableCustomGradients이 설정되지 않았다면 색상 및 그라디언트 값은 사용자 지정 값일 수 있습니다.
이 검사는 저장된 값을 대상으로 하며, default, fallback 또는 편집기 유효성 검사 규칙은 확인하지 않습니다.
일치하는 확장 필드는 대상이 되는 모든 블록에 포함됩니다. 렌더링 때와 마찬가지로 블록 또는 루트의 확장에서는 나중 정의가 우선합니다. 블록 자체 필드와 확장 필드는 동일한 키의 별도 정의로 남으며 둘 다 적용됩니다. 반복기 행 안에서는 렌더러가 각 출처에서 ID가 일치하는 첫 번째 필드를 읽으므로 해당 필드의 옵션과 경계값이 적용됩니다. 충돌 진단을 위해 중복 정의도 유지됩니다. 저장소 형식이 호환되지 않으면 나중 중복 항목이 렌더링에서 읽히지 않더라도 definition_conflict가 생성됩니다.
이 함수는 블록 하나를 검사합니다. 문서를 검증할 때는 innerBlocks을 순회하세요. 동기화된 패턴 및 기타 참조는 자동으로 확장되지 않습니다. wp bs blocks validate 명령은 하나 이상의 게시물에 있는 블록을 순회하고 해당 블록 경로를 보고합니다.
사용자 지정 렌더링 시점 리졸버가 있는 사이트에서는 저장된 데이터를 변경하지 않고 진단 결과를 조정할 수 있습니다:
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
if ($name !== 'my-theme/card') {
return $findings;
}
return array_values(array_filter($findings, function($finding) {
return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
}));
}, 10, 3);
항상 진단 결과 목록을 반환하세요. []을 반환하면 해당 블록이 허용됩니다. 이 필터는 관리형 블록에만 실행되며 null 결과에는 실행되지 않습니다.
저장된 값 설명하기
블록 등록 후(init 이상) bs_block_schema()을 사용해 블록에 저장되는 값을 설명할 수 있습니다. 예를 들어 도구나 AI 통합에서 블록 마크업을 생성하거나 REST 경로에서 입력을 확인할 때 사용할 수 있습니다.
$schema = bs_block_schema('theme/card');
if ($schema === null) {
// No Blockstudio fields or matching extensions apply.
}
결과는 attrs.blockstudio.attributes에 저장된 객체의 JSON 스키마입니다. 블록의 필드와 일치하는 확장의 필드를 포함하며, 검증에 사용되는 저장 키를 다룹니다. 최상위 그룹은 하위 필드에 접두사를 붙이고, 이름 없는 그룹과 탭은 수준을 추가하지 않으며, 파일 필드에는 <id>__size 동반 필드가 추가됩니다. 반복 필드는 min 및 max의 minItems과 maxItems를 갖는 행 객체 목록입니다. additionalProperties은 필드 저장소의 루트와 반복 필드의 행에서 모두 false입니다. 링크나 사용자 지정 객체 같은 객체 값 필드에는 자체 메타데이터가 포함될 수 있습니다. 필드가 없는 블록에는 properties이 없으므로 빈 객체만 일치합니다.
각 필드는 bs_validate_block()에서 허용하는 표준 형식으로 설명됩니다.
| 필드 | 스키마 |
|---|---|
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block |
문자열입니다. |
number, range |
숫자이며, min 및 max의 minimum과 maximum가 적용됩니다. |
toggle |
불리언입니다. |
select, radio, checkbox |
옵션 값 또는 checkbox 및 multiple의 옵션 값 목록이며, enum이 적용됩니다. |
color, gradient |
문자열이며, disableCustomColors 또는 disableCustomGradients이 설정된 경우 enum이 적용됩니다. |
token |
문자열 목록입니다. |
files |
음이 아닌 정수형 첨부 파일 ID 또는 multiple이 적용되는 ID 목록입니다. |
link |
url, title, opensInNewTab가 있는 객체이며, url은 필수입니다. |
icon |
set, subSet, icon이 있는 객체이며, set 및 icon는 필수입니다. |
attributes |
비어 있지 않은 attribute와 스칼라 value가 있는 객체 목록입니다. |
repeater |
행 객체 목록입니다. |
| 사용자 지정 필드 유형 | 등록된 속성 유형입니다. |
enum에는 검증에서 확인하는 옵션이 나열됩니다. 등록 시점에 이미 확인된 정적 옵션과 populate 옵션이 포함됩니다. 원격 fetch 옵션과 {attributes.*}이 포함된 populate 인수에는 enum이 없습니다. 저장 형태가 서로 다른 정의가 있는 키는 제외됩니다. 해당 키에 저장된 모든 값을 검증하기 때문입니다. 블록 필드와 확장 필드가 같은 키를 공유하면 enum에는 두 필드가 모두 허용하는 값이 나열됩니다. 공유 반복 필드는 하위 필드를 결합하고 두 정의에서 더 엄격한 행 제한을 적용합니다. 반복 필드의 행에서는 렌더링과 마찬가지로 각 원본에서 ID가 일치하는 첫 번째 필드가 적용됩니다. 명시적으로 이름을 <id>__size로 지정한 필드가 자동으로 추가되는 파일 크기 동반 필드보다 우선합니다.
닫힌 필드에 선택지가 없거나 적용 가능한 두 옵션 집합의 교집합이 없으면, 단일 선택의 표준 값은 null이고 다중 선택의 표준 값은 빈 목록입니다. 옵션 목록이 비어 있어도 필드가 제한 없는 필드가 되지는 않습니다. 원격 선택지와 속성에 따라 달라지는 선택지는 계속 열려 있습니다.
필드의 label은 title이 되고, help는 description이 되며, default는 주석으로 유지됩니다. 스키마 자체의 title는 블록 제목입니다. 필드는 필수 항목이 아니며 조건부 로직은 스키마에 포함되지 않습니다.
제약 조건에는 rest_validate_value_from_schema()에서 확인하는 키워드만 사용하므로, 스키마를 REST 경로나 기능의 입력 스키마로 그대로 사용할 수 있습니다.
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
$result = rest_validate_value_from_schema($values, $schema);
}
스키마는 필드별로 하나의 폼을 설명하지만, 검증은 옵션 객체, 숫자 문자열, ID 객체 같은 가져온 형태도 허용합니다. 이는 bs_validate_block()를 대체하지 않습니다. 정의 충돌은 구성 문제이며, 충돌하는 키를 생략해도 검증 결과에 계속 나타날 수 있습니다. 검증 필터로 사이트별 규칙을 적용할 수도 있습니다. 저장된 콘텐츠를 확인하려면 bs_validate_block()를 사용하세요. 렌더링 시점에 사용자 지정 리졸버를 사용하는 사이트는 blockstudio/blocks/attributes/schema 필터로 스키마를 조정할 수 있습니다.
PHP 함수
데이터 없음
가장 간단한 형태에서 함수는 페이지에 렌더링할 블록의 ID인 단일 값을 받습니다.
bs_render_block('blockstudio/cta');
데이터 있음
사용자 지정 데이터로 블록을 렌더링하려면 첫 번째 매개변수에 단일 값 대신 배열을 사용해야 합니다. data 키의 값은 블록 템플릿 내 $attributes 및 $a 변수로 전달됩니다.
bs_render_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
]);
중첩
블록 템플릿 내에서 bs_block 함수와 강력한 $content 변수를 함께 사용하면 블록을 서로 중첩할 수 있습니다.
<div>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => bs_block([
'id' => 'blockstudio/button',
'data' => [
'text' => 'Button Text',
]
])
]);
블록 템플릿 내 $content 변수 위치에 버튼 블록이 렌더링됩니다.
bs_render_block() 또는 bs_block()로 렌더링한 임베드 블록은 부모 블록이 현재 편집기 미리 보기를 렌더링 중인 경우에도 항상 프런트엔드에서 해석된 HTML를 출력합니다. <RichText /> 및 <InnerBlocks /> 같은 템플릿 의사 컴포넌트는 임베드 블록이 반환되기 전에 해석됩니다.
여러 슬롯
$content 변수를 연관 배열로 만들고 bs_block 함수에서 해당 키를 호출하면 여러 콘텐츠 슬롯을 만들 수도 있습니다.
<div>
<?php echo $content['beforeContent']; ?>
<h1><?php echo $a['title']; ?></h1>
<p><?php echo $a['subtitle']; ?></p>
<?php echo $content['afterContent']; ?>
</div>
echo bs_block([
'id' => 'blockstudio/cta',
'data' => [
'title' => 'My title',
'subtitle' => 'My subtitle',
],
'content' => [
'beforeContent' => bs_block([
'id' => 'blockstudio/badge',
'data' => ['text' => 'Before Content']
]),
'afterContent' => bs_block([
'id' => 'blockstudio/button',
'data' => ['text' => 'Button Text']
])
]
]);
블록 태그
HTML 태그 구문으로 모든 블록을 임베드하세요. 두 가지 형식을 지원합니다:
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
두 형식 모두 같은 블록을 렌더링합니다. <bs:> 구문은 하이픈을 네임스페이스 구분자로 바꿉니다(acme-hero은 acme/hero가 됩니다). 하이픈을 왼쪽부터 차례로 시도하고 처음 등록된 후보를 선택하므로, 하이픈이 포함된 네임스페이스도 해석됩니다. <bs:acme-ui-button>은 acme/ui-button를 시도한 뒤 acme-ui/button를 시도합니다. <block> 구문은 전체 블록 이름을 name 속성으로 사용합니다.
Blockstudio 블록과 코어 WordPress 블록을 모두 사용할 수 있습니다. Blockstudio 블록은 전체 파이프라인(템플릿, Tailwind, 에셋)을 거쳐 렌더링됩니다. 코어 블록은 내장된 블록 렌더러를 사용하여 WordPress의 블록 렌더링 시스템으로 렌더링됩니다.
작동 방식
블록 태그는 표시되는 위치에 따라 다르게 작동합니다:
블록 템플릿과 글 콘텐츠에서는 태그가 런타임에 렌더링된 HTML로 대체됩니다. 참조된 블록의 최종 마크업이 페이지에 직접 삽입됩니다. 편집기에는 이에 해당하는 WordPress 블록이 없습니다. 블록 태그는 순전히 렌더링을 위한 메커니즘입니다.
페이지, 패턴 및 사이트 템플릿에서는 파일 소스를 동기화하거나 WordPress에 등록하기 전에 태그를 네이티브 WordPress 블록으로 변환합니다. 따라서 편집기에서 블록을 확인할 수 있고, 대상이 편집을 지원하면 편집할 수 있으며, WordPress의 전체 블록 수명 주기를 거칩니다. 태그 구문은 템플릿 파일에서 블록 콘텐츠를 정의하는 간략한 방법입니다.
이 구분이 중요합니다. 템플릿의 블록 태그는 출력을 생성하고, 페이지, 패턴 및 사이트 템플릿의 블록 태그는 네이티브 블록을 생성합니다.
블록 템플릿에서
블록 태그는 Twig 및 PHP 템플릿 안에서 자동으로 렌더링됩니다. 설정이 필요하지 않습니다. 여기에는 <bs:> 및 <block> 구문과 등록된 모든 접두사 및 별칭 태그가 포함되므로, 템플릿에서 bs_render_block()을 호출하는 대신 태그를 직접 출력할 수 있습니다. 출력은 HTML 방식으로 렌더링되어 블록 템플릿 출력에 직접 삽입됩니다:
<div class="my-page">
<bs:mytheme-card title="Featured" />
<block name="core/separator" />
<bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
<block name="core/heading" level="2">Also WordPress</block>
<theme-card title="Prefix shorthand" />
</div>
글 콘텐츠에서
페이지 수준 렌더링(글 콘텐츠, 위젯 영역)은 선택적으로 활성화할 수 있습니다:
{
"blockTags": {
"enabled": true
}
}
또는 필터를 사용합니다:
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');
구문
닫는 태그가 없는 태그:
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />
내부 콘텐츠가 있는 짝 태그:
<bs:mytheme-section layout="wide">
<p>Content inside the block.</p>
</bs:mytheme-section>
<block name="core/group">
<block name="core/paragraph">Inside a group.</block>
</block>
자유롭게 조합할 수 있습니다. 두 구문은 서로 중첩할 수 있습니다:
<bs:mytheme-section>
<block name="core/heading" level="2">Title</block>
<bs:mytheme-card title="Features" />
<block name="core/paragraph">Description text.</block>
</bs:mytheme-section>
접두사 축약형
블록 태그에는 프로젝트별 접두사 축약형도 사용할 수 있습니다. 하나 이상의 네임스페이스로 접두사를 등록하면 Blockstudio은 해당 네임스페이스 순서에서 처음 등록된 블록으로 <prefix-slug>을 해석합니다:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components', 'bsui'];
return $prefixes;
});
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />
위 예시에서 <theme-card>은 theme-components/card로 해석되고, theme-components/button가 등록되지 않은 경우 <theme-button>는 bsui/button로 대체되며, <theme-ui-feature-matrix>는 theme-components/ui-feature-matrix로 해석됩니다.
접두사를 조합할 수도 있습니다. 접두사가 붙은 태그가 직접 해석되지 않고 나머지 슬러그 자체가 등록된 접두사 태그인 경우, 해석이 재귀적으로 진행되므로 브랜드 접두사 위에 네임스페이스 접두사를 둘 수 있습니다:
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
$prefixes['theme'] = ['theme-components'];
$prefixes['ui'] = ['bsui'];
return $prefixes;
});
<theme-ui-input />
<theme-ui-input>에는 theme-components/ui-input 블록이 없으므로 ui 접두사로 넘어가 bsui/input을 해석합니다. 직접 일치 항목은 항상 중첩 해석보다 우선하며, 허용 및 거부 규칙은 최종 해석된 블록에 적용됩니다.
blockstudio.json에서도 접두사를 설정할 수 있습니다:
{
"blockTags": {
"prefixes": {
"theme": ["theme-components", "bsui"]
}
}
}
접두사는 소문자 또는 숫자로만 구성해야 하고, 문자로 시작해야 하며, 하이픈을 포함할 수 없습니다. blockstudio/block_tags/tag_aliases의 명시적 별칭은 접두사 해석보다 우선합니다.
알 수 없는 접두사 태그는 변경되지 않습니다.
접두사 및 별칭 태그는 계속해서 작성 편의 기능으로 지원됩니다. 표준이며 이식성이 있는 표기는 항상 <bs:namespace-slug>입니다. 프로젝트 필터에 의존하지 않고 실제 블록 이름을 기록하기 때문입니다:
<bs:theme-components-card />
<bs:bsui-input />
Blockstudio 예시, 생성된 진단 메시지 및 프로그래밍 방식의 출력은 이 표준 표기를 사용합니다. 이전 축약형을 제거하려는 프로젝트에서는 표준 태그 마이그레이션을 독립 실행형으로 사용할 수 있습니다. 먼저 시험 실행할 수 있으며 WordPress을 부팅하지 않아도 됩니다.
코어 블록
등록된 렌더러가 있는 블록은 무엇이든 사용할 수 있습니다:
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
<bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>
또는 <block> 구문을 사용할 수 있습니다:
<block name="core/group">
<block name="core/columns">
<block name="core/column">
<block name="core/paragraph">Left column</block>
</block>
<block name="core/column">
<block name="core/paragraph">Right column</block>
</block>
</block>
</block>
허용 및 거부 목록
태그로 렌더링할 수 있는 블록을 제어합니다:
{
"blockTags": {
"enabled": true,
"allow": ["mytheme/*", "core/*"],
"deny": ["mytheme/internal-*"]
}
}
allow은 일치하는 패턴만 허용합니다. deny은 일치하는 패턴을 제외하며 우선 적용됩니다. 둘 다 * 와일드카드를 지원하며 fnmatch()를 통해 지정합니다. 두 구문과 템플릿 수준 및 페이지 수준 렌더링 모두에 적용됩니다.
필터: blockstudio/block_tags/allow 및 blockstudio/block_tags/deny.
HTML 전달
data- 접두사가 붙은 속성은 렌더링된 블록의 루트 요소로 전달됩니다. html- 접두사가 붙은 속성도 전달되며, 접두사는 제거됩니다. 두 구문 모두에서 작동합니다. 전달된 속성은 루트 요소의 기존 값을 병합하지 않고 대체하므로, html-class는 블록 자체의 클래스를 대체합니다.
Blockstudio 블록은 필드로 선언하지 않은 전역 속성도 루트 요소에 설정합니다. id, style, role, title, lang, dir, hidden, tabindex 및 모든 aria-* 속성이 여기에 포함됩니다. 선언된 필드는 항상 우선하므로, title 필드가 있는 블록에는 대신 $a['title']의 값이 전달됩니다. 전달된 스타일은 safecss_filter_attr()를 거치며, 글 콘텐츠의 스타일 속성에는 WordPress 필터가 적용되고, 템플릿에서 이미 설정한 스타일에 추가됩니다.
속성 값은 HTML이므로 태그를 파싱할 때 엔티티가 한 번 디코딩됩니다. title="Tom & Jerry"은 템플릿에 Tom & Jerry로 전달되고 출력 시 다시 이스케이프됩니다. 따옴표로 묶인 값에는 >이 포함될 수 있습니다. Tailwind 변형 및 애니메이션 선택자가 그 예이며, 닫는 태그가 없는 태그와 짝 태그 모두에서 사용할 수 있습니다.
class을 포함해 블록이 선언하지 않은 다른 속성은 HTML에 전달되지 않습니다. WP_DEBUG가 켜져 있으면 Blockstudio가 각 요청에서 이런 속성을 한 번씩 _doing_it_wrong()를 통해 보고합니다. 해당 필드를 선언하거나 data-, aria- 또는 html- 속성으로 작성하세요.
<bs:mytheme-card
title="My Card"
html-class="featured-card"
html-id="main-card"
data-analytics="card-click"
/>
<block name="core/paragraph" html-class="highlight" data-section="intro">
Highlighted paragraph.
</block>
사용자 지정 렌더러
추가 블록 유형을 위한 사용자 지정 블록 렌더러를 등록합니다. 렌더러는 속성 배열과 내부 콘텐츠 문자열을 받아 WordPress 블록 배열을 반환합니다:
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
$builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
$html = '<div class="my-block">' . $inner_content . '</div>';
return [
'blockName' => 'myplugin/custom-block',
'attrs' => $attrs,
'innerBlocks' => [],
'innerHTML' => $html,
'innerContent' => [$html],
];
};
return $builders;
}, 10, 2);
내부 콘텐츠를 하위 블록으로 파싱해야 하는 컨테이너 블록은 같은 필터 안에 두 번째 항목을 추가하세요:
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
$content = ['<div class="my-wrapper">'];
foreach ($inner_blocks as $block) {
$content[] = null;
}
$content[] = '</div>';
return [
'blockName' => 'myplugin/wrapper',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '<div class="my-wrapper"></div>',
'innerContent' => $content,
];
};
blockstudio/block_tags/builders은 블록 태그와 blockstudio/parser/element_mapping을 통해 선택한 사용자 지정 블록 모두에 적용됩니다. 요소에 매핑된 프로젝트 블록의 내부 텍스트를 Blockstudio 필드로 옮기거나 사용자 지정 블록 배열을 구성할 때 적합한 후크입니다.
blockstudio/block_tags/renderers 및 blockstudio/parser/renderers은 동일한 레지스트리와 콜백 형식을 받습니다. 호환성과 파서 수준의 최종 재정의를 위해 계속 사용할 수 있습니다. 필터는 다음 순서로 실행됩니다:
blockstudio/block_tags/buildersblockstudio/block_tags/renderersblockstudio/parser/renderers
나중에 실행되는 필터는 앞서 등록한 렌더러를 대체할 수 있습니다.
프로그래밍 방식 사용
PHP의 모든 문자열에 태그 렌더링을 적용합니다:
$html = apply_filters('blockstudio/block_tags/render', $content);
컴포넌트
블록 태그는 컴포넌트와 잘 어울립니다. 컴포넌트는 프로그래밍 방식으로만 렌더링되고 편집기에는 표시되지 않는 블록입니다.
<bs:mytheme-card title="My Card" description="Card content." />
파서
블록 태그는 DOMDocument를 대체하는 경량 문자열 스캐너로 처리됩니다. 파서는 <bs:> 및 <block> 구문, 깊이 추적으로 처리하는 같은 이름의 중첩 태그, 따옴표로 묶인 속성 값, 재귀적 컨테이너 블록을 모두 처리합니다. 이 용도에 맞게 제작되었으며 DOMDocument와 WordPress의 WP_HTML_Tag_Processor보다 벤치마크에서 빠르고, 네임스페이스 접두사 제거 및 속성 소문자화와 관련된 DOMDocument의 알려진 문제를 피합니다.
페이지, 패턴 및 사이트 템플릿에서는 같은 파서가 원시 HTML 요소(<p>, <div>, <h1> 등)도 처리하여 이에 해당하는 WordPress 코어 블록에 매핑합니다.
요소 매핑이 <p>을 등록된 비코어 Blockstudio 블록으로 지정하고 해당 블록이 content 리치 텍스트 속성을 선언한 경우, 내부 HTML는 자동으로 그 content 속성에 전달됩니다. 여기에는 블록 수준에서 요소에 매핑된 code 및 img 같은 인라인 태그도 포함됩니다. 이미지 하나만 자식 요소로 가진 단락은 <img>이 매핑된 블록이 됩니다. 중첩 블록 태그 또는 블록 수준 HTML는 계속 일반적인 내부 블록 파싱으로 처리됩니다. <block name="core/shortcode">는 단축 코드 텍스트를 블록의 콘텐츠로 유지합니다.