속성 렌더링
템플릿 파일 안에서는 $attributes 또는 $a 변수와 해당 필드 ID를 사용해 모든 속성에 액세스할 수 있습니다.
PHP
<h1><?php echo $attributes['message']; ?></h1>
<h1><?php echo $a['message']; ?></h1>
Twig
<h1>{{ attributes.message }}</h1>
<h1>{{ a.message }}</h1>
프로그래밍 방식으로 속성 쓰기
편집기는 저장된 값을 blockstudio.attributes 아래에 중첩합니다. REST API, WP-CLI, 콘텐츠 마이그레이션 또는 MCP 서버처럼 편집기 외부에서 블록을 작성하는 코드는 WP_Block_Type의 속성 Blockstudio에서 블록을 찾고 최상위 수준에 기록합니다. 두 형식 모두 렌더링됩니다.
// Top level, as a programmatic writer produces it.
echo do_blocks( '<!-- wp:acme/hero {"visual_type":"media"} /-->' );
// Nested, as the editor saves it.
echo do_blocks( '<!-- wp:acme/hero {"blockstudio":{"attributes":{"visual_type":"media"}}} /-->' );
블록이 선언한 ID만 최상위 수준에서 읽으므로 WordPress의 anchor, className, lock, metadata 및 style 같은 자체 속성은 필드 값으로 채택되지 않습니다. 동일한 ID가 두 위치에 있으면 중첩된 값이 우선합니다.
프로그래밍 방식으로 속성 읽기
save_post의 구조화된 데이터, 내보내기, 검색 색인 또는 render_block 필터처럼 템플릿 외부에서 실행되는 코드는 저장된 블록의 값을 템플릿에서 보이는 형태로 가져와야 하는 경우가 많습니다. bs_block_values()는 블록을 렌더링하지 않고 값을 반환합니다. 블록 등록 후(init 이후) parse_blocks()의 attrs 배열 전체를 전달해 호출하세요:
foreach (parse_blocks($post->post_content) as $block) {
if ($block['blockName'] === null) {
continue;
}
$a = bs_block_values($block['blockName'], $block['attrs']);
if ($a === null) {
// Not a Blockstudio block, and no extension applies.
continue;
}
echo esc_html($a['title'] ?? '');
}
결과는 템플릿의 $a 배열이며, 필드 ID를 키로 사용합니다:
- 필드 기본값이 적용되고,
min가 있는 반복 필드에는 초기 행이 포함됩니다. - 최상위 값과
blockstudio.attributes이 병합되며 중첩 값이 우선합니다. 최상위에서는 선언된 ID만 읽고, 렌더링 시와 마찬가지로 WordPress는 필드에 등록된 유형과 정확히 일치하지 않는 최상위 값(예: 선택 항목 문자열)을 제거합니다. - 일치하는 확장의 필드가 기본값과 함께 포함됩니다. 코어 블록이나 타사 블록의 확장은 렌더링 시와 마찬가지로
blockstudio.attributes만 읽습니다. - 반환 형식이 적용됩니다. 따라서
label인returnFormat선택 필드는 레이블을 반환하고, 파일 필드는 첨부 파일 데이터를 반환합니다. - 비활성화된 필드와 빈 필드는 템플릿에서와 마찬가지로
false처리됩니다.
null는 블록이나 확장이 Blockstudio에서 관리되지 않음을 의미합니다. 필드가 없는 Blockstudio 블록은 []을 반환합니다.
이 함수는 렌더링과 동일한 변환을 수행하므로 부작용도 같습니다. 파일 필드는 첨부 파일을 쿼리하고, data을 반환하지 않는 블록 필드는 참조된 블록을 렌더링하며, blockstudio/blocks/attributes/render 필터는 모든 값에 대해 실행됩니다. 블록 자체의 템플릿은 렌더링하지 않으며 innerBlocks도 확인하지 않으므로 직접 순회해야 합니다. 코드 필드에는 호출마다 달라지는 생성된 %selector% ID가 유지됩니다.
확인에는 현재 WordPress 컨텍스트가 사용됩니다. 블록 카운터 및 innerBlocks와 같은 렌더링 전용 메타데이터는 생성되지 않습니다. 속성 렌더 필터에는 완전히 렌더링된 블록의 메타데이터가 아니라 블록 이름이 전달됩니다.
변환하지 않은 저장 값을 가져오는 옵션은 없습니다. 저장된 값이 필요하면 attrs 배열을 직접 읽거나, bs_validate_block()를 사용해 확인하세요.
빈 값
필드가 비어 있거나 선택된 옵션이 없으면 속성 값은 false을 반환합니다.
PHP
<?php if ($a['message']) : ?>
<h1><?php echo $a['message']; ?></h1>
<?php endif; ?>
Twig
{% if a.message %}
<h1>{{ a.message }}</h1>
{% endif %}
복합 유형
파일
기본적으로(returnFormat이 없거나 "returnFormat": "object"인 경우) 파일 필드는 첨부 파일 데이터가 담긴 배열을 반환합니다. "multiple": true를 사용하면 이러한 배열의 목록을 반환합니다. 첨부 파일이 더 이상 존재하지 않는 파일은 false입니다.
| 키 | 설명 |
|---|---|
ID |
첨부 파일 ID입니다. |
title |
첨부 파일 제목입니다. |
alt |
대체 텍스트입니다. 비어 있으면 첨부 파일 제목을 사용합니다. |
caption |
캡션입니다. |
description |
설명입니다. |
href |
첨부 파일 페이지의 퍼머링크입니다. |
url |
파일의 URL입니다. 크기 드롭다운("size": true)을 사용하면 선택한 크기의 URL입니다. |
sizes |
아래에 설명된 대로 등록된 모든 이미지 크기의 URL 및 치수입니다. |
PHP
<?php if ($a['image']) :
$image = $a['image'];
$sizes = $image['sizes'] ?? [];
?>
<img
src="<?php echo esc_url($sizes['large'] ?? $image['url']); ?>"
alt="<?php echo esc_attr($image['alt']); ?>"
<?php if (isset($sizes['large-width'], $sizes['large-height'])) : ?>
width="<?php echo esc_attr($sizes['large-width']); ?>"
height="<?php echo esc_attr($sizes['large-height']); ?>"
<?php endif; ?>
/>
<?php endif; ?>
Twig
{% if a.image %}
<img
src="{{ (a.image.sizes.large ?? a.image.url)|e('html_attr') }}"
alt="{{ a.image.alt|e('html_attr') }}"
{% if a.image.sizes['large-width'] is defined and a.image.sizes['large-height'] is defined %}
width="{{ a.image.sizes['large-width']|e('html_attr') }}"
height="{{ a.image.sizes['large-height']|e('html_attr') }}"
{% endif %}
/>
{% endif %}
sizes에는 등록된 각 이미지 크기와 full에 대한 항목이 하나씩 있습니다. 크기 이름 아래에 URL가 있고, 치수는 <size>-width 및 <size>-height 아래에 있습니다. 첨부 파일에 대해 크기 WordPress가 생성되지 않은 경우 원본 파일과 해당 치수를 반환합니다. WordPress이 이미지 또는 미리보기를 확인할 수 없으면 sizes 키가 없습니다. 예를 들어 생성된 미리보기가 없는 PDF에는 sizes가 없지만, 미리보기 메타데이터가 있는 PDF에는 이미지 크기가 있을 수 있습니다. 등록된 이미지 크기가 없거나 files/sizes필터가 이미지 크기를 비활성화하면 sizes는 null입니다. 이 필터는 맵의 항목 수도 줄일 수 있으므로, 위 예시처럼 치수를 읽기 전에 해당 크기가 있는지 확인하세요.
객체에는 width, height, mime, type 또는 size 키가 없습니다. 치수는 sizes에서 읽거나 wp_get_attachment_image() 및 get_post_mime_type() 같은 함수를 사용해 ID을 읽으세요.
반환 형식
returnFormat는 필드의 반환값을 변경합니다:
returnFormat |
값 |
|---|---|
"object" (기본값) |
위에서 설명한 배열입니다. |
"id" |
저장된 첨부 파일 ID이며, "multiple": true와 함께 사용하면 ID 목록입니다. |
"url" |
문자열 형식의 URL이며, "multiple": true와 함께 사용하면 URL 목록입니다. 이미지는 returnSize로 설정한 크기(기본값 full)를 사용하고, 다른 파일은 파일 URL를 사용합니다. |
링크
링크 필드는 URL 및 속성이 포함된 객체를 반환합니다.
PHP
<?php if ($a['link']) : ?>
<a
href="<?php echo $a['link']['url']; ?>"
target="<?php echo $a['link']['target']; ?>"
>
<?php echo $a['link']['title']; ?>
</a>
<?php endif; ?>
Twig
{% if a.link %}
<a href="{{ a.link.url }}" target="{{ a.link.target }}">
{{ a.link.title }}
</a>
{% endif %}
아이콘
아이콘 필드는 set, subSet 및 icon 키가 포함된 객체를 반환합니다. SVG를 출력하려면 bs_render_icon() 및 bs_icon() 도우미 함수를 사용하세요.
PHP
<?php if ($a['icon']) : ?>
<div class="icon">
<?php bs_render_icon($a['icon']); ?>
</div>
<?php endif; ?>
Twig
{% if a.icon %}
<div class="icon">
{{ bs_icon(a.icon) }}
</div>
{% endif %}
bs_render_icon()은 SVG를 바로 출력합니다. bs_icon()은 SVG를 문자열로 반환합니다.
속성
속성 필드 유형은 HTML 속성으로 렌더링할 {attribute, value} 쌍의 배열을 반환합니다. 이를 출력하려면 bs_render_data_attributes()를 사용하세요.
PHP
<div <?php bs_render_data_attributes($a['attributes']); ?>>
Content
</div>
Twig
<div {{ fn('bs_render_data_attributes', a.attributes) }}>
Content
</div>
bs_render_data_attributes()은 속성을 바로 출력합니다. bs_data_attributes()은 문자열을 반환합니다.
그룹
그룹 필드는 자식 속성 ID 앞에 그룹 이름을 붙입니다. 그룹 필드를 깔끔한 배열로 추출하려면 bs_get_group()을 사용하세요.
PHP
<?php $group = bs_get_group($a, 'settings'); ?>
<h1><?php echo $group['title']; ?></h1>
<p><?php echo $group['description']; ?></p>
Twig
{% set group = fn('bs_get_group', a, 'settings') %}
<h1>{{ group.title }}</h1>
<p>{{ group.description }}</p>
이렇게 하면 속성 키에서 그룹 접두사가 제거됩니다. 예를 들어 $a['settings_title']은 $group['title']이 됩니다.
그룹이 재사용되는 사용자 지정 필드에서 온 경우에도 이 도우미를 사용할 수 있습니다.
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"attributes": [
{ "id": "kicker", "type": "text" },
{ "id": "title", "type": "text" }
]
}
]
}
{
"blockstudio": {
"attributes": [
{ "type": "custom/section-header" }
]
}
}
{% set sectionHeader = fn('bs_get_group', a, 'section-header') %}
<p>{{ sectionHeader.kicker }}</p>
<h2>{{ sectionHeader.title }}</h2>
반복 필드
반복 필드 항목을 순회합니다.
PHP
<?php foreach ($a['items'] as $item) : ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['description']; ?></p>
</div>
<?php endforeach; ?>
Twig
{% for item in a.items %}
<div class="item">
<h3>{{ item.title }}</h3>
<p>{{ item.description }}</p>
</div>
{% endfor %}