파일 3개로 사용자 지정 블록 만들기
JavaScript도, 빌드 단계도, 상용구 코드도 필요 없습니다.
JSON에서 필드 정의
blockstudio 키를 block.json에 추가하세요. text, toggle, color와 같은 유형으로 속성을 정의하세요. Blockstudio가 편집기 UI를 자동으로 생성하며, 텍스트 입력부터 반복 입력기와 코드 편집기까지 27 필드 유형을 제공하고 직접 등록한 필드 유형도 지원합니다.
전체 JSON 스키마를 지원해 VS Code, PhpStorm 및 호환되는 모든 편집기에서 자동 완성과 유효성 검사를 사용할 수 있습니다.
각 필드에는 새 블록의 default과 필드가 비어 있을 때 템플릿에 전달되는 fallback을(를) 설정할 수 있습니다.
{
"name": "starter/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading" },
{ "id": "showCta", "type": "toggle", "label": "Show CTA" },
{ "id": "background", "type": "color", "label": "Background" }
]
}
}3개 파일로 작업
필드용 block.json, 마크업용 템플릿, 선택 사항인 스타일시트를 사용하세요.
PHP의 React
RichText, InnerBlocks, useBlockProps는 PHP, Twig 또는 Blade에서 바로 사용할 수 있습니다.
SCSS 및 Tailwind
CSS, SCSS 또는 Tailwind를 사용하세요. SCSS은 가져오기 경로와 공유 전처리 구문을 지원하며, 중첩된 부분 템플릿을 편집하면 이를 가져오는 모든 파일이 다시 컴파일됩니다.
27개 필드 유형
텍스트, 색상, 이미지, 반복 필드, 선택 필드, 코드 편집기 등을 JSON에서 구성하세요.
JSON Schema
VS Code, PhpStorm 및 호환되는 편집기에서 자동 완성과 유효성 검사를 사용할 수 있습니다.
세 가지 템플릿 언어
PHP, Twig, Blade는 같은 변수와 구성 요소를 공유합니다.
npm 가져오기
script.js에서 패키지를 가져오세요. 프로덕션에서는 로컬 패키지를 사용하고 편집기에서는 CDN을 기반으로 사용합니다.
Interactivity API
플래그 하나로 WordPress Interactivity API을 활성화하세요.
PHP 템플릿의 React 구성 요소
하나의 템플릿에서 인라인 편집 및 정적 프런트엔드 HTML에는 <RichText />를, 하위 블록에는 <InnerBlocks />를, 래퍼에는 useBlockProps를 사용하세요.
편집기에서는 실제 React 구성 요소로 표시됩니다. 프런트엔드에서는 서버 측 HTML로 렌더링되므로 방문자에게 JavaScript가 전송되지 않습니다.
<div useBlockProps class="container">
<RichText
class="text-xl font-semibold"
tag="h1"
attribute="headline"
placeholder="Enter headline"
/>
<?php if ($a['showCta']): ?>
<a href="<?= esc_url($a['ctaUrl']) ?>">
<?= esc_html($a['ctaLabel']) ?>
</a>
<?php endif; ?>
<InnerBlocks class="mt-4 p-4 border" />
</div>PHP, Twig 또는 Blade로 작성
익숙한 템플릿 언어를 사용하세요. PHP은(는) 기본 제공되고, Timber을(를) 설치하면 Twig이(가) 실행되며, Blockstudio\Blade_Renderer을(를) 통해 illuminate/view 8~12에서 Blade이(가) 실행됩니다. 변수, 컴포넌트, 동작은 동일하게 유지됩니다.
$a(속성), $b(블록), $c(컨텍스트), $innerBlocks를 모든 언어에서 사용할 수 있습니다.
Twig 템플릿도 전체 Timber 컨텍스트를 받습니다. Blade는 페이지, 패턴, Site Editor 템플릿도 렌더링합니다. 이전 jenssegers/blade 래퍼는 illuminate/view 10 이상에서 작동하지 않으므로 대신 Blade_Renderer를 사용하세요.
<div useBlockProps class="card">
<RichText tag="h2" attribute="title" placeholder="Card title" />
{% if a.image %}
<img src="{{ a.image.url|esc_url }}"
alt="{{ a.image.alt|esc_attr }}" />
{% endif %}
<div class="card__body">{{ a.description|esc_html }}</div>
<InnerBlocks allowedBlocks='["core/button"]' />
</div><div useBlockProps class="card">
<RichText tag="h2" attribute="title" placeholder="Card title" />
@if ($a['description'])
<div class="card__body">{{ $a['description'] }}</div>
@endif
<InnerBlocks allowedBlocks='["core/button"]' />
</div>조건부 로직 및 동적 옵션
==, !=, includes, empty 같은 연산자와 비교 조건을 사용해 필드를 표시하거나 숨기세요. OR 로직으로 조건을 결합할 수 있습니다.
옵션은 다른 필드에 종속될 수 있습니다. populate 인수에 {attributes.post_type.value}를 넣으면 해당 필드가 변경될 때 목록이 다시 로드됩니다. 편집자가 입력하는 동안 게시물을 검색하려면 fetch: true을 추가하세요.
type: custom와 blockstudio/blocks/attributes/populate 필터를 사용하면 여러 블록에서 하나의 옵션 목록을 공유할 수 있으며, 구매 확인 같은 자체 전역 조건은 blockstudio/blocks/conditions를 통해 등록할 수 있습니다.
{
"name": "starter/posts",
"title": "Posts",
"blockstudio": {
"attributes": [
{
"id": "post_type",
"type": "select",
"label": "Post type",
"options": [
{ "value": "page", "label": "Pages" },
{ "value": "post", "label": "Posts" }
]
},
{
"id": "selected_post",
"type": "select",
"label": "Post",
"populate": {
"type": "query",
"query": "posts",
"arguments": { "post_type": "{attributes.post_type.value}" }
}
},
{
"id": "style",
"type": "select",
"label": "Style",
"populate": { "type": "custom", "custom": "cardStyles" },
"conditions": [[
{ "type": "purchasedProduct", "operator": "==", "value": "yes" }
]]
}
]
}
}add_filter('blockstudio/blocks/attributes/populate', function ($options) {
$options['cardStyles'] = [
['value' => 'light', 'label' => 'Light'],
['value' => 'dark', 'label' => 'Dark'],
];
return $options;
});
add_filter('blockstudio/blocks/conditions', function ($conditions) {
$conditions['purchasedProduct'] = user_has_purchased(123) ? 'yes' : 'no';
return $conditions;
});관리하기 쉬운 리피터
min와 max을 설정하고, default개 행으로 새 블록을 시작하며, minimized으로 기존 행을 접으세요. textMinimized는 이름과 같은 해당 행의 필드 하나를 사용해 접힌 행에 라벨을 표시합니다.
행에는 탭을 제외한 모든 필드 유형을 사용할 수 있으며, 중첩 리피터도 포함됩니다. 행 안의 조건은 "context": "main"을 사용해 행 외부의 필드를 확인하고, <RichText />과 <MediaPlaceholder />는 attribute이 repeaterId[index].fieldId를 가리킬 때 단일 행을 편집합니다.
{
"name": "starter/team",
"title": "Team",
"blockstudio": {
"attributes": [
{
"id": "members",
"type": "repeater",
"label": "Team members",
"min": 1,
"max": 12,
"minimized": true,
"textMinimized": { "id": "name", "fallback": "Team member" },
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "bio", "type": "richtext", "label": "Bio" }
]
}
]
}
}<div useBlockProps class="team">
<?php foreach ($a['members'] as $index => $member): ?>
<article>
<h3><?= esc_html($member['name']) ?></h3>
<RichText
tag="p"
attribute="members[<?= $index ?>].bio"
placeholder="Short bio"
/>
</article>
<?php endforeach; ?>
</div>재사용 가능한 필드 모음
field.json에서 필드 그룹을 한 번 정의하고 "type": "custom/cta"로 모든 블록에서 참조하세요. 필드가 인라인으로 삽입되므로 템플릿에서 다른 속성과 동일한 방식으로 읽을 수 있습니다.
hero_{id} 같은 idStructure을 사용해 같은 필드 모음을 두 번 재사용하고, overrides로 블록마다 라벨, 기본값 또는 조건을 변경하세요. block 필드 유형은 블록 전체에도 같은 방식으로 작동합니다. 해당 블록의 필드를 인라인으로 확장하고 렌더링된 HTML를 반환합니다.
{
"name": "cta",
"title": "Call to action",
"attributes": [
{ "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
{ "id": "url", "type": "link", "label": "Button URL" }
]
}{
"name": "starter/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "type": "custom/cta", "idStructure": "primary_{id}" },
{
"type": "custom/cta",
"idStructure": "secondary_{id}",
"overrides": {
"label": { "default": "Contact us" }
}
},
{
"id": "card",
"type": "block",
"block": "starter/card",
"idStructure": "card_{id}"
}
]
}
}빌드 단계 없는 ES 모듈
script.js를 추가하면 ES 모듈로 로드됩니다. npm: 접두사를 사용해 npm 패키지를 가져오면 Blockstudio가 프로덕션용 파일을 로컬에 다운로드합니다.
편집기에서는 즉시 미리 볼 수 있고, 프런트엔드는 외부 의존성 없이 로컬 모듈을 사용하며 한 번만 대기열에 추가됩니다.
스타일시트도 같은 방식으로 가져옵니다. import "npm:swiper@11.0.0/swiper.min.css"는 파일을 다운로드하고 버전별로 한 번만 enqueue하므로 여러 블록에서 사용해도 중복되지 않습니다.
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";
for (const el of document.querySelectorAll(".swiper")) {
new Swiper(el, {
slidesPerView: 3,
spaceBetween: 20,
loop: true,
});
}템플릿을 넘어서는 블록 태그
blockstudio.json에서 짧은 접두사를 네임스페이스에 매핑하거나, 별칭 필터로 태그 하나를 블록 하나에 연결하면 <acme-card>가 acme/card를 렌더링합니다. blockTags.enabled을 켜면 게시물 콘텐츠와 위젯의 태그도 렌더링하며, allow 및 deny 패턴으로 제한됩니다.
data-* 속성은 블록의 루트 요소에 전달되고, html-* 속성은 접두사 없이 전달됩니다. blockstudio/block_tags/builders로 자체 태그 빌더를 추가하고, migrate-block-tags 명령으로 축약 표기를 이식 가능한 <bs:acme-card> 표기로 변환하세요.
{
"blockTags": {
"enabled": true,
"prefixes": {
"acme": ["acme"],
"ui": ["acme-ui"]
},
"deny": ["acme-ui/admin-*"]
}
}<div useBlockProps class="acme-features">
<acme-card
title="Fast"
text="Rendered on the server."
data-track="card"
/>
<ui-button label="Get started" href="/start" html-id="start" />
</div>사용자 지정 필드 유형
직접 필드 컨트롤을 등록해 기본 제공 필드처럼 사용하세요.
블록 아일랜드
페이지 전체를 캐시하고 방문자 요청에서 블록 하나를 렌더링하세요.
조건부 등록
게시물 유형, 사용자 역할 또는 다른 전역 조건에 따라 블록을 등록하거나, 필요한 플러그인 또는 플러그인 버전이 없을 때 등록을 건너뛰세요.
게시물 메타 및 옵션
블록 속성과 함께 게시물 메타 또는 옵션에 값을 저장하세요.
조건부 로직
값의 일치, 포함 여부, 비어 있는지, 비교 조건에 따라 필드를 표시하세요.
동적 값 채우기
게시물, 사용자, 용어, 함수 또는 API에서 선택 항목을 가져오세요.
재정의
공유 블록의 이름과 함께 override: true를 설정하면 id별로 속성을 병합하고, 이름이 같은 파일의 에셋을 교체하며, 템플릿을 바꿉니다. Twig 템플릿은 extends를 사용해 개별 블록을 재정의할 수 있습니다.
변형
block.json에서 필드 값을 미리 설정하는 변형을 선언하고, 이를 제어하는 필드는 hidden으로 숨기세요.
구성 요소
PHP 또는 블록 태그에서만 렌더링되는 블록에 component: true를 설정하세요. 필드, 템플릿, 에셋 및 Tailwind은 유지되지만 삽입기에는 표시되지 않습니다.
InnerBlocks 규칙
namespace/*, category: 및 @theme 토큰이 있는 블록을 허용하고, select 옵션으로 내부 템플릿을 전환하며, 필터를 사용해 프런트엔드에서 래퍼를 제거하세요.
코드 필드 에셋
asset: true인 코드 필드는 편집기의 입력을 해당 블록 전용 CSS, SCSS 또는 JavaScript로 변환하며, %selector%를 통해 인스턴스 범위로 한정합니다.
파일 이름으로 에셋 지정
*.view.js는 프런트엔드에서만 로드됩니다. global-, admin-, block-editor- 접두사를 사용하면 파일이 모든 페이지, wp-admin 또는 블록 편집기에서 로드됩니다.
아이콘 및 블록 폴더
블록에 사용자 정의 SVG 또는 HTML 아이콘을 지정하고, blockstudio/path 필터로 검색 위치를 옮기며, Blockstudio\Build::init()로 폴더를 추가하세요.
ACF 및 Meta Box 값
템플릿은 $post_id을 받으므로 get_field() 및 rwmb_get_value()가 편집된 게시물을 읽으며, 저장 후 refreshOn이 미리보기를 새로 고칩니다.
Query Loop 컨텍스트
Query Loop 안에서는 $block[‘context’][‘postId’]가 현재 항목을 따르고, $block[‘postId’]는 계속 조회 중인 게시물을 가리킵니다.
WPML
wp bs wpml config는 텍스트 필드를 번역 가능하게 표시하는 wpml-config.xml를 작성하며, 필드에 저장된 이미지도 대체 텍스트와 캡션을 포함해 WPML 번역 작업에 포함됩니다.
공식 확장 키트
프리미엄 사이트 템플릿, AI 시스템 지침, 비공개 Discord 커뮤니티를 제공합니다. 한 번 구매하면 업데이트를 평생 받을 수 있습니다.
- 500개 이상의 사이트 템플릿
- AI 시스템 지침
- 평생 업데이트
- 비공개 Discord 커뮤니티