본문으로 건너뛰기

저장소

기본적으로 모든 필드 값은 글 콘텐츠 내 블록 주석에 블록 속성으로 저장됩니다. 저장 기능을 사용하면 글 메타(wp_postmeta) 또는 옵션(wp_options)에도 값을 저장할 수 있어 블록 외부에서 값을 사용할 수 있습니다.

저장소를 사용하는 이유

블록 속성은 글 콘텐츠의 HTML 주석 안에 저장되므로 블록 콘텐츠를 파싱할 때만 사용할 수 있습니다. 추가 저장 위치를 사용하면 다음을 할 수 있습니다:

  • meta_query을 사용해 필드 값으로 글을 조회
  • 헤드리스 환경에서 REST API를 통해 값에 액세스
  • SEO 또는 캐싱 플러그인 같은 다른 플러그인과 데이터 공유
  • 여러 글에 걸쳐 유지되는 전역 설정 생성

저장 유형

유형 위치 범위 적합한 용도
postMeta wp_postmeta 테이블 글별 조회 가능한 글별 데이터
option wp_options 테이블 전역(사이트 전체) 사이트 설정, 공유 값

참고

블록 속성 저장은 (글 콘텐츠의 HTML 주석에) 항상 자동으로 이루어집니다. storage 속성은 저장 위치를 추가하며 블록 저장을 대체하지 않습니다.

구성

모든 필드 정의에 storage 속성을 추가하세요:

JSON
{
  "name": "blockstudio/example",
  "title": "Example Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "subtitle",
        "type": "text",
        "label": "Subtitle",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "my_subtitle"
        }
      }
    ]
  }
}

저장 속성

속성 유형 설명
type string | string[] 추가 저장 location(s): "postMeta", "option"
postMetaKey string 사용자 지정 메타 키(기본값: {block_name}_{field_id})
optionKey string 사용자 지정 옵션 키(기본값: {block_name}_{field_id})

단일 저장과 다중 저장

JSON
// Add post meta storage
"storage": {
  "type": "postMeta"
}

// Add both post meta and option storage
"storage": {
  "type": ["postMeta", "option"]
}

작동 방식

  1. 등록: WordPress이 로드되면 Blockstudio은 필드 설정에 따라 메타 키와 설정을 등록합니다
  2. 편집: 값은 편집기에서 블록 속성으로 관리됩니다(항상 블록에 저장됨)
  3. 저장: 글을 저장하면 글 메타가 동기화됩니다. 사이트 옵션은 글을 게시하거나 게시된 글의 필드 값이 변경될 때 동기화됩니다.

자동 저장 및 리비전에서는 어느 저장 위치도 동기화되지 않습니다. 임시 글, 검토 대기 중인 글, 비공개 글 및 예약 글은 자체 글 메타를 업데이트할 수 있지만 현재 사이트 옵션은 변경하지 않습니다. 예약 글의 옵션은 WordPress이 글을 게시할 때 동기화됩니다.

값은 백슬래시, 따옴표, 중첩된 반복 필드 값을 포함해 그대로 복사됩니다. WordPress 메타 저장을 보완하려고 필드 값에 이스케이프 문자를 추가하지 마세요. 이 경계는 Blockstudio가 처리합니다. 사이트 옵션도 추가로 슬래시를 붙이지 않고 동일한 값을 그대로 유지합니다.

이전 버전에서 게시물 메타 사본의 백슬래시가 제거되었다면 업그레이드한 뒤 게시물을 다시 저장하세요. 블록 속성의 원래 필드 값을 사용해 메타 사본을 새로 고칩니다.

사이트 옵션 저장

옵션은 사이트 전체에서 공유됩니다. 새 블록을 게시하면 저장된 속성에 제공된 옵션 필드가 기록됩니다. 이후 저장에서는 블록의 이전 저장 버전과 각 필드를 비교해 변경된 값만 기록합니다. 글 제목을 저장하거나 다른 글에 있는 변경되지 않은 이전 블록 사본을 저장해도 더 최신 옵션 값은 덮어쓰지 않습니다.

저장된 속성에서 필드를 생략하면 해당 옵션은 변경되지 않습니다. 새 필드를 block.json에 추가할 때도 기존 옵션을 보호합니다. 명시적인 null은 옵션을 삭제하며, 빈 문자열, false, 0 및 빈 배열은 값으로 저장됩니다. 블록을 제거해도 해당 옵션은 삭제되지 않습니다.

공유 옵션마다 지정된 게시 블록 하나를 사용해 관리하세요. 여러 블록에서 의도적으로 같은 옵션을 변경하면 마지막으로 변경해 저장한 값이 적용됩니다. 저장소는 현재 옵션 값을 각 블록에 불러오지 않습니다. 각 블록은 자체 필드 값을 게시물 콘텐츠에 보관합니다.

파일 기반 페이지에서는 영구 블록 key을 사용하면 Blockstudio이 문서에서 위치가 바뀐 뒤에도 같은 블록을 식별할 수 있습니다. 키가 없는 블록은 블록 이름과 위치를 기준으로 일치시킵니다.

저장된 값에 액세스하기

블록 템플릿에서

블록 템플릿 안에서는 필드 값을 항상 $attributes을 통해 사용할 수 있습니다.

PHP

PHP
<div>
  <h1><?php echo $a['subtitle']; ?></h1>
</div>

Twig

Twig
<div>
  <h1>{{ a.subtitle }}</h1>
</div>

게시물 메타(블록 컨텍스트 외부)

postMeta에 저장된 값은 WordPress 어디서나 액세스할 수 있습니다.

PHP

PHP
// Get meta value
$subtitle = get_post_meta( $post_id, 'my_subtitle', true );

// Query posts by meta value
$posts = get_posts([
  'meta_key'   => 'my_subtitle',
  'meta_value' => 'Hello World',
]);

Twig

Twig
{# Using Timber #}
{{ post.meta('my_subtitle') }}

{# Or via function #}
{{ function('get_post_meta', post.id, 'my_subtitle', true) }}

게시물 메타는 REST API을 통해서도 사용할 수 있습니다.

셸
GET /wp-json/wp/v2/posts/123
# Response includes: { "meta": { "my_subtitle": "Hello World" } }

옵션(전역 값)

option에 저장된 값은 사이트 전체에서 액세스할 수 있습니다.

PHP

PHP
$company_name = get_option( 'site_company_name' );

Twig

Twig
{{ function('get_option', 'site_company_name') }}

예시

SEO 메타 필드

SEO 데이터를 게시물 메타에 저장해 SEO 플러그인과 호환되도록 하세요.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "seo_title",
        "type": "text",
        "label": "SEO Title",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_title"
        }
      },
      {
        "id": "seo_description",
        "type": "textarea",
        "label": "Meta Description",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_metadesc"
        }
      }
    ]
  }
}

필드 값을 기준으로 게시물을 쿼리할 수 있도록 게시물 메타 저장을 추가하세요.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "featured",
        "type": "toggle",
        "label": "Featured",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "is_featured"
        }
      }
    ]
  }
}

추천 게시물을 쿼리합니다.

PHP
$featured_posts = get_posts([
  'meta_key'   => 'is_featured',
  'meta_value' => '1',
]);

전역 사이트 설정

사이트 전체 설정을 옵션에 저장합니다.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "company_name",
        "type": "text",
        "label": "Company Name",
        "storage": {
          "type": "option",
          "optionKey": "site_company_name"
        }
      },
      {
        "id": "support_email",
        "type": "text",
        "label": "Support Email",
        "storage": {
          "type": "option",
          "optionKey": "site_support_email"
        }
      }
    ]
  }
}

사이트 어디서나 액세스합니다.

PHP
<footer>
  <p>&copy; <?php echo get_option( 'site_company_name' ); ?></p>
  <p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>

게시물 메타와 옵션

게시물 수준과 전역 수준 모두에서 사용할 수 있어야 하는 데이터의 경우:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "important_value",
        "type": "text",
        "label": "Important Value",
        "storage": {
          "type": ["postMeta", "option"],
          "postMetaKey": "important_meta",
          "optionKey": "important_option"
        }
      }
    ]
  }
}

기본 키 이름

사용자 지정 키를 지정하지 않으면 Blockstudio이 자동으로 키를 생성합니다.

저장 유형 기본 키 형식 예시
postMeta {block_name}_{field_id} blockstudio_example_subtitle
option {block_name}_{field_id} blockstudio_example_subtitle

블록 이름은 슬래시를 밑줄로 바꾸어 정리합니다.

경고

프로덕션 환경에서는 사용자 지정 키를 사용하는 것이 좋습니다. 블록 이름을 변경하면 기본 키도 바뀔 수 있습니다.