본문으로 건너뛰기

필드 패턴 실전 모음

Blockstudio의 필드 시스템은 단독으로 보면 간단합니다. blockstudio.attributes에 필드를 추가하고 템플릿에서 $a로 접근하면 됩니다. 하지만 실제 블록에는 필드가 하나만 있는 경우가 드뭅니다. 관련 설정 그룹, 다른 필드 값에 따라 표시되거나 숨겨지는 필드, 복잡한 행 구조를 가진 반복 필드, 블록 편집기 밖에서도 쿼리할 수 있어야 하는 데이터가 포함됩니다.

이 가이드에서는 자주 쓰이는 필드 패턴을 위한 실용적인 레시피를 모았습니다. 각 레시피는 block.json 설정과 이에 대응하는 템플릿 코드를 보여 줍니다. 블록에 그대로 복사한 뒤 필요에 맞게 수정하세요.

조건부 필드

가장 흔한 패턴은 다른 필드의 값에 따라 필드를 표시하거나 숨기는 것입니다. 관련 옵션만 보여 주어 편집기를 깔끔하게 유지할 수 있습니다.

토글로 옵션 표시

사용자가 버튼을 활성화하면 추가 설정이 나타나는 CTA 블록입니다:

JSON
{
  "name": "my-theme/cta",
  "title": "Call to Action",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "Ready to get started?" },
      { "id": "description", "type": "textarea", "label": "Description" },
      { "id": "showButton", "type": "toggle", "label": "Show Button", "default": true },
      {
        "id": "buttonText",
        "type": "text",
        "label": "Button Text",
        "default": "Get Started",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      },
      {
        "id": "buttonUrl",
        "type": "link",
        "label": "Button Link",
        "conditions": [[{ "id": "showButton", "operator": "==", "value": true }]]
      }
    ]
  }
}

토글이 켜져 있을 때만 버튼 텍스트와 링크 필드가 나타납니다. 템플릿에서는 렌더링 전에 토글 상태를 확인하세요:

PHP
<div useBlockProps>
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <?php if ( $a['description'] ) : ?>
    <p><?php echo esc_html( $a['description'] ); ?></p>
  <?php endif; ?>
  <?php if ( $a['showButton'] && $a['buttonUrl'] ) : ?>
    <a href="<?php echo esc_url( $a['buttonUrl']['url'] ); ?>">
      <?php echo esc_html( $a['buttonText'] ); ?>
    </a>
  <?php endif; ?>
</div>

선택 항목으로 필드 세트 전환

배경 유형에 따라 표시되는 필드가 달라지는 히어로 블록입니다:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      {
        "id": "bgType",
        "type": "select",
        "label": "Background Type",
        "default": "color",
        "options": [
          { "value": "color", "label": "Solid Color" },
          { "value": "gradient", "label": "Gradient" },
          { "value": "image", "label": "Image" },
          { "value": "video", "label": "Video" }
        ]
      },
      {
        "id": "bgColor",
        "type": "color",
        "label": "Background Color",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "color" }]]
      },
      {
        "id": "bgGradient",
        "type": "gradient",
        "label": "Background Gradient",
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "gradient" }]]
      },
      {
        "id": "bgImage",
        "type": "files",
        "label": "Background Image",
        "multiple": false,
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "image" }]]
      },
      {
        "id": "bgVideo",
        "type": "files",
        "label": "Background Video",
        "multiple": false,
        "allowedTypes": ["video"],
        "conditions": [[{ "id": "bgType", "operator": "==", "value": "video" }]]
      },
      {
        "id": "overlay",
        "type": "range",
        "label": "Overlay Opacity",
        "default": 50,
        "min": 0,
        "max": 100,
        "conditions": [[{ "id": "bgType", "operator": "!=", "value": "color" }]]
      }
    ]
  }
}

오버레이 불투명도 필드는 !=를 사용하여 단색을 제외한 모든 경우에 표시됩니다. 한 번에 배경 필드 하나만 표시됩니다. color 필드는 색상의 value, name, slug가 포함된 배열을 반환하므로 템플릿에서는 ['value']를 읽습니다:

PHP
<?php
$bg_style = match ( $a['bgType'] ) {
	'color'    => $a['bgColor'] ? "background-color: {$a['bgColor']['value']}" : '',
	'gradient' => $a['bgGradient'] ? "background: {$a['bgGradient']}" : '',
	'image'    => $a['bgImage'] ? "background-image: url({$a['bgImage']['url']})" : '',
	default    => '',
};
?>
<div useBlockProps style="<?php echo esc_attr( $bg_style ); ?>">
  <?php if ( $a['bgType'] === 'video' && $a['bgVideo'] ) : ?>
    <video autoplay muted loop playsinline>
      <source src="<?php echo esc_url( $a['bgVideo']['url'] ); ?>" />
    </video>
  <?php endif; ?>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
</div>

OR 조건

여러 조건 중 하나라도 참일 때 필드를 표시합니다. 각 내부 배열은 AND 그룹이고, 외부 배열은 이를 OR로 결합합니다:

JSON
{
  "id": "caption",
  "type": "text",
  "label": "Caption",
  "conditions": [
    [{ "id": "bgType", "operator": "==", "value": "image" }],
    [{ "id": "bgType", "operator": "==", "value": "video" }]
  ]
}

이 설정은 bgType이 “image” 또는 “video”일 때 캡션 필드를 표시합니다.

연쇄 조건

동일한 내부 배열의 여러 조건은 AND 논리를 사용합니다:

JSON
{
  "id": "altText",
  "type": "text",
  "label": "Alt Text",
  "conditions": [[
    { "id": "bgType", "operator": "==", "value": "image" },
    { "id": "bgImage", "operator": "!empty" }
  ]]
}

대체 텍스트 필드는 bgType이 “image”이고 이미지가 선택된 경우에만 표시됩니다.

전역 조건

다른 필드의 값 대신 게시물 유형, 게시물 ID 또는 사용자 역할에 따라 필드를 표시합니다:

JSON
{
  "id": "seoTitle",
  "type": "text",
  "label": "SEO Title",
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

사용 가능한 전역 조건 유형: postType, postId, userRole, userId.

체계적인 설정

블록이 복잡해질수록 필드를 논리적인 그룹으로 구성하면 인스펙터를 관리하기 쉽습니다.

시각적 구성을 위한 그룹

그룹을 만들면 인스펙터에 접을 수 있는 섹션이 생깁니다. 이름 없는 그룹(id 없음)은 시각적 구성만 담당하며, 필드는 기본 ID로 접근합니다:

JSON
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "title": "Content",
        "attributes": [
          { "id": "title", "type": "text", "label": "Title" },
          { "id": "description", "type": "textarea", "label": "Description" },
          { "id": "image", "type": "files", "label": "Image", "multiple": false }
        ]
      },
      {
        "type": "group",
        "title": "Link",
        "attributes": [
          { "id": "url", "type": "link", "label": "URL" },
          { "id": "openInNewTab", "type": "toggle", "label": "Open in New Tab" }
        ]
      },
      {
        "type": "group",
        "title": "Appearance",
        "attributes": [
          {
            "id": "style",
            "type": "select",
            "label": "Style",
            "default": "elevated",
            "options": [
              { "value": "elevated", "label": "Elevated" },
              { "value": "outlined", "label": "Outlined" },
              { "value": "flat", "label": "Flat" }
            ]
          },
          { "id": "accentColor", "type": "color", "label": "Accent Color" }
        ]
      }
    ]
  }
}
PHP
<div useBlockProps>
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['description'] ); ?></p>
</div>

필드에 직접 접근합니다: $a['title'], $a['style'], $a['accentColor']. 그룹은 인스펙터 레이아웃에만 영향을 줍니다.

bs_get_group을 사용하는 이름 있는 그룹

그룹에 id가 있으면 하위 필드 ID에 접두사가 붙습니다. bs_get_group()를 사용해 접두사를 제거하세요:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "avatar", "type": "files", "label": "Avatar", "multiple": false }
  ]
}

헬퍼를 사용하지 않으면 필드에 $a['author_name'], $a['author_role'], $a['author_avatar']로 접근합니다. 헬퍼를 사용하면:

PHP
<?php $author = bs_get_group( $a, 'author' ); ?>
<div class="author">
  <?php if ( $author['avatar'] ) : ?>
    <img src="<?php echo esc_url( $author['avatar']['url'] ); ?>" alt="" />
  <?php endif; ?>
  <p><?php echo esc_html( $author['name'] ); ?></p>
  <p><?php echo esc_html( $author['role'] ); ?></p>
</div>

이름 있는 그룹은 여러 그룹에서 같은 필드 이름을 쓸 때(e.g, author_name, company_name 등)나 부분 템플릿에 그룹 전체를 전달할 때 유용합니다.

그룹의 그리드 레이아웃

style 속성을 사용해 그룹의 하위 필드를 나란히 배치하세요:

JSON
{
  "type": "group",
  "title": "Dimensions",
  "style": {
    "display": "grid",
    "grid-template-columns": "1fr 1fr",
    "grid-gap": "16px"
  },
  "attributes": [
    { "id": "width", "type": "unit", "label": "Width", "default": "100%", "switch": false },
    { "id": "height", "type": "unit", "label": "Height", "default": "auto", "switch": false }
  ]
}

단위 필드 두 개가 쌓이지 않고 인스펙터에 나란히 표시됩니다. 치수 쌍, 여백 및 패딩 값, 개념적으로 짝을 이루는 두 필드에 적합합니다.

주요 섹션의 탭

블록에 설정이 많다면 긴 그룹 목록보다 탭으로 구성하는 편이 깔끔합니다:

JSON
{
  "type": "tabs",
  "tabs": [
    {
      "title": "Content",
      "attributes": [
        { "id": "title", "type": "text", "label": "Title" },
        { "id": "body", "type": "wysiwyg", "label": "Body" }
      ]
    },
    {
      "title": "Media",
      "attributes": [
        { "id": "image", "type": "files", "label": "Image", "multiple": false },
        { "id": "video", "type": "files", "label": "Video", "multiple": false, "allowedTypes": ["video"] }
      ]
    },
    {
      "title": "Settings",
      "attributes": [
        { "id": "layout", "type": "select", "label": "Layout", "options": [
          { "value": "left", "label": "Media Left" },
          { "value": "right", "label": "Media Right" }
        ]},
        { "id": "fullWidth", "type": "toggle", "label": "Full Width" }
      ]
    }
  ]
}

각 탭의 필드는 최상위 필드처럼 액세스합니다. $a['title'], $a['image'], $a['layout']. 탭은 순전히 UI 컨테이너입니다.

반복 필드 패턴

반복 필드를 사용하면 여러 행의 필드를 추가할 수 있습니다. 목록, 그리드, 타임라인, 항목 수가 유동적인 모든 구성 요소에 필수적입니다.

제약 조건이 있는 기본 반복 필드

항목이 1개에서 6개까지 있는 기능 목록입니다:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 6,
  "textButton": "Add Feature",
  "attributes": [
    { "id": "icon", "type": "icon", "label": "Icon" },
    { "id": "title", "type": "text", "label": "Title", "default": "Feature" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<div useBlockProps class="grid grid-cols-3 gap-8">
  <?php foreach ( $a['features'] as $feature ) : ?>
    <div>
      <?php if ( $feature['icon'] ) : ?>
        <?php bs_render_icon( $feature['icon'] ); ?>
      <?php endif; ?>
      <h3><?php echo esc_html( $feature['title'] ); ?></h3>
      <p><?php echo esc_html( $feature['description'] ); ?></p>
    </div>
  <?php endforeach; ?>
</div>

사용자 지정 행 레이블

기본적으로 최소화된 반복 필드 행에는 일반 레이블이 표시됩니다. textMinimized를 사용하면 대신 필드 값을 표시할 수 있습니다:

JSON
{
  "id": "team",
  "type": "repeater",
  "label": "Team Members",
  "textMinimized": { "id": "name", "fallback": "Team Member" },
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" },
    { "id": "photo", "type": "files", "label": "Photo", "multiple": false }
  ]
}

행을 접으면 “Row 1” 대신 사람의 이름이 표시됩니다. 이름 필드가 비어 있으면 fallback를 사용합니다. prefix 및 suffix 문자열도 추가할 수 있습니다.

반복 필드 내부의 조건부 표시

반복 필드 안의 필드는 같은 행의 다른 필드를 기본 id로 참조할 수 있습니다(접두사는 필요 없음):

JSON
{
  "id": "links",
  "type": "repeater",
  "label": "Links",
  "attributes": [
    { "id": "label", "type": "text", "label": "Label" },
    { "id": "url", "type": "link", "label": "URL" },
    {
      "id": "isExternal",
      "type": "toggle",
      "label": "External Link"
    },
    {
      "id": "externalNote",
      "type": "message",
      "label": "Note",
      "description": "External links open in a new tab with rel=\"noopener\".",
      "conditions": [[{ "id": "isExternal", "operator": "==", "value": true }]]
    }
  ]
}

반복 필드 내부에서 바깥 필드 참조하기

반복 필드 내부의 조건에서 반복 필드 바깥의 필드를 확인해야 한다면 "context": "main"를 추가하세요:

JSON
{
  "id": "showDescriptions",
  "type": "toggle",
  "label": "Show Descriptions",
  "default": true
},
{
  "id": "items",
  "type": "repeater",
  "label": "Items",
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    {
      "id": "description",
      "type": "textarea",
      "label": "Description",
      "conditions": [[{
        "id": "showDescriptions",
        "operator": "==",
        "value": true,
        "context": "main"
      }]]
    }
  ]
}

"context": "main"가 없으면 조건은 반복 필드 행 내부에서 showDescriptions 필드를 찾습니다. 이를 추가하면 루트 수준의 토글을 확인합니다.

반복기 내부의 탭

반복기 내부에서는 탭을 사용할 수 없습니다. 반복기 행 안의 tabs 필드는 필드 대신 편집기에 알림을 표시하며, PHPStan 확장 프로그램에서도 이를 보고합니다. 대신 행의 필드를 평면 구조로 유지하세요. 행이 길다면 사용자 지정 행 레이블(textMinimized)을 설정해 접힌 행도 쉽게 알아볼 수 있게 하세요. 또한 위 패턴에서처럼 행 내부의 조건을 사용하면 일부 행에만 필요한 필드를 숨길 수 있습니다.

반복기에서 "minimized": true를 설정하면 기존 행을 접힌 상태로 시작합니다. 새로 추가한 행은 바로 열립니다. 펼친 상태로 둔 예외는 편집기를 다시 불러와도 이 브라우저에 기억됩니다. 이는 편집 설정이며 저장되는 게시물 콘텐츠가 아닙니다. minimized가 없는 반복기는 기존처럼 기본적으로 펼쳐진 상태를 유지합니다.

미디어 패턴

대체 이미지가 있는 단일 이미지

JSON
{
  "id": "image",
  "type": "files",
  "label": "Image",
  "multiple": false
}
PHP
<?php if ( $a['image'] ) : ?>
  <img
    src="<?php echo esc_url( $a['image']['url'] ); ?>"
    alt="<?php echo esc_attr( $a['image']['alt'] ); ?>"
    <?php if ( isset( $a['image']['sizes']['full-width'], $a['image']['sizes']['full-height'] ) ) : ?>
      width="<?php echo esc_attr( $a['image']['sizes']['full-width'] ); ?>"
      height="<?php echo esc_attr( $a['image']['sizes']['full-height'] ); ?>"
    <?php endif; ?>
  />
<?php endif; ?>

기본 returnFormat는 "object"이며, ID, title, alt, caption, description, href, url, sizes를 제공합니다. sizes에는 등록된 모든 이미지 크기(sizes['large'])의 URL와 크기 정보(sizes['large-width'], sizes['large-height'])가 포함됩니다. 전체 목록은 렌더링 속성을 참조하세요.

JSON
{
  "id": "gallery",
  "type": "files",
  "label": "Gallery",
  "multiple": true,
  "max": 6,
  "allowedTypes": ["image"]
}
PHP
<?php if ( $a['gallery'] ) : ?>
  <div class="grid grid-cols-3 gap-4">
    <?php foreach ( $a['gallery'] as $image ) : ?>
      <img
        src="<?php echo esc_url( $image['url'] ); ?>"
        alt="<?php echo esc_attr( $image['alt'] ); ?>" />
    <?php endforeach; ?>
  </div>
<?php endif; ?>

스위치로 비활성화할 수 있는 이미지

switch 속성을 사용하면 눈 아이콘이 표시되어 값을 삭제하지 않고도 필드를 비활성화할 수 있습니다:

JSON
{
  "id": "logo",
  "type": "files",
  "label": "Logo",
  "multiple": false,
  "switch": true
}
PHP
<?php
$is_disabled = ! empty( $a['_disabled'] ) && in_array( 'logo', $a['_disabled'], true );
if ( $a['logo'] && ! $is_disabled ) : ?>
  <img src="<?php echo esc_url( $a['logo']['url'] ); ?>" alt="" />
<?php endif; ?>

사용자는 업로드한 파일을 삭제하지 않고 로고를 끌 수 있습니다. 다시 켜면 같은 파일이 표시됩니다.

반환 형식 변형

파일 필드의 반환값을 제어합니다:

JSON
// Full object (default)
{ "id": "photo", "type": "files", "returnFormat": "object", "multiple": false }
// $a['photo']['url'], $a['photo']['alt'], $a['photo']['sizes']['full-width'], etc.

// Just the ID
{ "id": "photo", "type": "files", "returnFormat": "id", "multiple": false }
// $a['photo'] = 42

// Just the URL
{ "id": "photo", "type": "files", "returnFormat": "url", "multiple": false }
// $a['photo'] = "https://example.com/photo.jpg"

직접 wp_get_attachment_image()를 호출해야 할 때는 "id"를 사용하세요. 단순한 배경 이미지에는 "url"를 사용하세요. 그 밖의 모든 경우에는 "object"(기본값)를 사용하세요.

"returnFormat": "id"를 사용하면 "buckshair-home"과 같은 가져온 문자열 참조가 변경되지 않고 전달됩니다. 반복기 행을 포함해 편집기에는 썸네일이 없는 대체 카드가 표시됩니다. 페이지를 열거나 저장해도 스칼라 참조가 배열로 변환되지 않습니다. 첨부 파일 ID와 문자열 참조가 섞인 목록도 작동하며, 양수인 첨부 파일 ID만 미디어 라이브러리에서 조회됩니다.

Blockstudio는 사용자 지정 문자열 참조를 첨부 파일로 해석하지 않습니다. 사이트 간에 이식 가능한 이름을 사용하려면 직접 렌더링 필터나 템플릿에서 이를 해석하세요. 미디어 라이브러리에서 대체 항목을 선택하면 평소처럼 첨부 파일 ID가 저장됩니다.

동적 옵션

게시물에서 채우기

게시된 모든 페이지를 나열하는 선택 필드입니다:

JSON
{
  "id": "linkedPage",
  "type": "select",
  "label": "Linked Page",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "page",
      "post_status": "publish",
      "posts_per_page": -1
    }
  }
}

필드에는 페이지 제목이 레이블로, 게시물 ID가 값으로 자동 입력됩니다. 매핑을 사용자 지정하려면 채우기 설정에서 returnFormat를 사용하세요:

JSON
"populate": {
  "type": "query",
  "query": "posts",
  "arguments": { "post_type": "page" },
  "returnFormat": { "value": "ID", "label": "post_title" }
}

택소노미 용어에서 채우기

JSON
{
  "id": "category",
  "type": "select",
  "label": "Category",
  "stylisedUi": true,
  "populate": {
    "type": "query",
    "query": "terms",
    "arguments": {
      "taxonomy": "category",
      "hide_empty": true
    }
  }
}

PHP 함수에서 채우기

JSON
{
  "id": "postType",
  "type": "select",
  "label": "Post Type",
  "populate": {
    "type": "function",
    "function": "get_post_types",
    "arguments": { "public": true }
  }
}

채워진 항목을 추가한 정적 옵션

하드코딩한 옵션과 동적 옵션을 결합합니다. 채워진 옵션이 표시될 위치는 position로 제어하세요:

JSON
{
  "id": "source",
  "type": "select",
  "label": "Source",
  "options": [
    { "value": "manual", "label": "Manual Entry" },
    { "value": "latest", "label": "Latest Posts" }
  ],
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": { "post_type": "page" },
    "position": "after"
  }
}

정적 옵션이 먼저 표시되고, 그 뒤에 동적으로 채워진 페이지가 표시됩니다.

쿼리를 위한 데이터 저장

기본적으로 필드 값은 post_content 내부의 블록 속성에 저장됩니다. WP_Query로 쿼리할 수 없습니다. 필드 값으로 게시물을 필터링하거나 정렬해야 한다면 저장 방식을 사용하세요.

쿼리 가능한 필드의 게시물 메타

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
},
{
  "id": "priority",
  "type": "number",
  "label": "Priority",
  "default": 0,
  "min": 0,
  "max": 100,
  "storage": {
    "type": "postMeta",
    "postMetaKey": "priority_score"
  }
}

이제 추천 게시물을 쿼리할 수 있습니다:

PHP
$featured = new WP_Query( array(
    'meta_query' => array(
        array(
            'key'   => 'is_featured',
            'value' => '1',
        ),
    ),
    'orderby'  => 'meta_value_num',
    'meta_key' => 'priority_score',
    'order'    => 'DESC',
) );

메타 키는 show_in_rest에 자동 등록되므로 REST API에서도 사용할 수 있습니다.

이중 저장

블록 속성과 게시물 메타 양쪽에 저장합니다. 블록 속성 덕분에 템플릿에서 $a로 값을 사용할 수 있고, 게시물 메타에 저장된 값은 쿼리할 수 있습니다:

JSON
{
  "id": "eventDate",
  "type": "date",
  "label": "Event Date",
  "storage": {
    "type": ["block", "postMeta"],
    "postMetaKey": "event_date"
  }
}

전역 값을 위한 옵션 저장

사이트 전체에서 동일하게 사용해야 하는 설정에는 옵션 저장을 사용하세요:

JSON
{
  "id": "companyName",
  "type": "text",
  "label": "Company Name",
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

값은 wp_options에 저장되며 어디서나 get_option('site_company_name')로 사용할 수 있습니다. 사용자가 어떤 블록 인스턴스에서든 이 필드를 수정하면 값이 전역적으로 업데이트됩니다.

재사용 가능한 필드 정의

여러 블록에서 같은 필드 구조를 공유한다면 사용자 지정 필드로 한 번 정의한 뒤 어디서나 참조하세요.

사용자 지정 필드 만들기

테마의 blockstudio/fields/ 디렉터리에 field.json를 만드세요:

코드
theme/
└── blockstudio/
    └── fields/
        └── cta/
            └── field.json
JSON
{
  "name": "cta",
  "title": "Call to Action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button Label", "default": "Learn More" },
    { "id": "url", "type": "link", "label": "Button URL" },
    { "id": "style", "type": "select", "label": "Button Style", "default": "primary", "options": [
      { "value": "primary", "label": "Primary" },
      { "value": "secondary", "label": "Secondary" },
      { "value": "outline", "label": "Outline" }
    ]}
  ]
}

사용자 지정 필드 사용하기

"type": "custom/cta"로 모든 블록에서 참조하세요:

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "type": "custom/cta" }
    ]
  }
}

CTA 필드는 블록에 인라인으로 포함됩니다. 다음과 같이 직접 접근하세요: $a['label'], $a['url'], $a['style'].

idStructure를 사용한 접두사 포함 사용자 지정 필드

같은 사용자 지정 필드를 여러 번 사용할 때는 idStructure를 추가해 ID에 접두사를 붙이세요:

JSON
{
  "blockstudio": {
    "attributes": [
      { "type": "custom/cta", "idStructure": "primary_{id}" },
      { "type": "custom/cta", "idStructure": "secondary_{id}" }
    ]
  }
}

첫 번째 CTA의 필드는 primary_label, primary_url, primary_style가 됩니다. 두 번째 CTA에는 secondary_label 등이 붙습니다.

기본값 재정의

사용자 지정 필드를 참조할 때 특정 필드를 사용자 지정할 수 있습니다:

JSON
{
  "type": "custom/cta",
  "idStructure": "hero_{id}",
  "overrides": {
    "label": { "default": "Get Started", "label": "CTA Label" },
    "style": { "default": "primary" }
  }
}

재정의 설정은 원래 정의에 병합됩니다. 기본값, 레이블, 조건 또는 다른 속성을 변경할 수 있습니다.

렌더링 패턴

빈 값 확인

대부분의 필드 유형은 비어 있을 때 false를 반환합니다. 렌더링하기 전에 항상 확인하세요:

PHP
<?php if ( $a['title'] ) : ?>
  <h2><?php echo esc_html( $a['title'] ); ?></h2>
<?php endif; ?>

숫자에서 0는 유효한 값입니다. “empty”와 “zero”를 구분해야 한다면 엄격한 비교를 사용하세요:

PHP
<?php if ( $a['count'] !== 0 || $a['count'] !== false ) : ?>
  <span><?php echo esc_html( $a['count'] ); ?></span>
<?php endif; ?>

returnFormat: both를 사용한 선택 필드

값(로직에 사용)과 레이블(표시에 사용)이 모두 필요할 때:

JSON
{
  "id": "status",
  "type": "select",
  "label": "Status",
  "returnFormat": "both",
  "options": [
    { "value": "active", "label": "Active" },
    { "value": "paused", "label": "On Hold" },
    { "value": "closed", "label": "Closed" }
  ]
}
PHP
<?php if ( $a['status'] ) : ?>
  <span class="badge badge--<?php echo esc_attr( $a['status']['value'] ); ?>">
    <?php echo esc_html( $a['status']['label'] ); ?>
  </span>
<?php endif; ?>

attributes 필드에서 데이터 속성 가져오기

attributes 필드 유형을 사용하면 사용자가 사용자 지정 데이터 속성을 추가할 수 있습니다:

JSON
{
  "id": "dataAttrs",
  "type": "attributes",
  "label": "Data Attributes",
  "link": true,
  "media": true
}
PHP
<div useBlockProps <?php bs_render_data_attributes( $a['dataAttrs'] ); ?>>
  Content here.
</div>

필드 값에서 CSS 변수 만들기

선택한 필드에서 CSS 사용자 지정 속성을 생성합니다:

JSON
{
  "id": "textColor", "type": "color", "label": "Text Color"
},
{
  "id": "fontSize", "type": "unit", "label": "Font Size", "default": "1rem"
}
PHP
<div useBlockProps style="<?php bs_render_variables( $a, array( 'textColor', 'fontSize' ) ); ?>">
  <p>Styled content.</p>
</div>

이렇게 하면 style="--text-color: #333; --font-size: 1rem;"가 출력됩니다(필드 ID는 케밥 케이스로 변환됨). CSS에서 변수를 사용하세요:

CSS
p {
  color: var(--text-color);
  font-size: var(--font-size);
}

다음 단계

  • 속성 등록: id, type, label, default, help, position, conditions 속성.
  • 필드 유형 참조: 각 필드 유형의 모든 속성을 자동 생성한 참조 문서.
  • 조건부 로직: 연산자, 전역 조건, 사용자 지정 조건 필터, 반복 필드 컨텍스트.
  • 옵션 채우기: 동적 옵션 필드의 쿼리, 함수, 사용자 지정, 가져오기 모드.
  • 사용자 지정 필드: field.json, 검색 경로, blockstudio/fields 필터, 고급 idStructure 패턴.
  • 렌더링: $a, $b, $c, 빈 값, 헬퍼 함수.