아일랜드
블록 아일랜드를 사용하면 블록은 일반 Blockstudio 렌더링 파이프라인을 유지하면서 요청별 출력을 초기 HTML 응답에서 분리할 수 있습니다.
페이지를 적극적으로 캐시해야 하지만, 특정 블록이 현재 방문자, 세션, 장바구니, 권한 또는 다른 실시간 요청 컨텍스트에 계속 의존하는 경우 유용합니다.
Blockstudio 블록은 여전히 동적 WordPress 블록입니다. 아일랜드가 이를 미리 컴파일된 정적 HTML으로 바꾸지는 않습니다. 대신 Blockstudio가 첫 요청에서 렌더링되는 내용을 바꿉니다.
- 하이드레이션된 아일랜드는 일반적인 캐시 안전 HTML를 렌더링하고 마운트 이벤트를 받습니다.
- 동적 아일랜드는 먼저 캐시 안전한 플레이스홀더를 렌더링한 다음 방문자의 브라우저에서 실제 조각을 가져옵니다.
모드
하이드레이션된 아일랜드
서버 출력을 안전하게 캐시할 수 있고 블록에 프런트엔드 마운트 신호만 필요하다면 하이드레이션된 아일랜드를 사용하세요.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
초기 응답에 전체 블록 HTML가 포함됩니다. 아일랜드 런타임은 이를 위해 REST 요청을 보내지 않습니다. 마커에 blockstudio:island:hydrate를 전달하여 프런트엔드 코드가 동작을 연결할 수 있게 합니다.
동적 아일랜드
실제 블록 출력을 방문자의 요청 컨텍스트에서 렌더링해야 하는 경우 동적 아일랜드를 사용하세요.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
초기 응답에는 플레이스홀더만 포함됩니다. 브라우저는 준비된 모든 동적 아일랜드를 다음 주소로 보내는 단일 요청에 묶습니다.
POST /wp-json/blockstudio/v1/island/render
엔드포인트는 등록된 Blockstudio 블록 중 동적이며 blockstudio.island.mode가 dynamic로 설정된 블록만 렌더링합니다.
구성
island 값은 축약형이나 객체일 수 있습니다.
{
"blockstudio": {
"island": true
}
}
true와 "hydrate"는 모두 하이드레이션을 의미합니다. "dynamic"는 동적을 의미합니다.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| 속성 | 유형 | 기본값 | 설명 |
|---|---|---|---|
mode |
"hydrate" 또는 "dynamic" |
"hydrate" |
아일랜드 모드. |
tag |
string |
"div" |
마커 래퍼 태그. |
attributes |
string[] |
모든 블록 속성 | 동적 프래그먼트 요청에 전송되는 속성 허용 목록. |
placeholder |
string |
자동 감지 | 상대 경로의 플레이스홀더 템플릿 경로. |
loading |
"eager" 또는 "visible" |
"eager" |
런타임에서 동적 아일랜드를 가져올 시점. |
event |
string |
설정되지 않음 | 동적 아일랜드를 새로 고치는 윈도우 이벤트 이름. |
context |
boolean |
false |
동적 프래그먼트를 위해 쿼리된 페이지의 게시물 ID와 게시물 유형에 서명하고 복원합니다. |
cache |
boolean 또는 object |
false |
선택적 프래그먼트 캐시 정책. |
페이지 컨텍스트
동적 프래그먼트는 일반적으로 페이지 셸과 독립적으로 렌더링됩니다. 블록에서 페이지별 설정이나 관련 콘텐츠를 읽는 경우 페이지 식별 정보를 사용하도록 설정하세요:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
마커에는 쿼리된 페이지의 postId 및 postType이 data-bs-island-context에 포함됩니다. 두 값은 제공 사이트의 비밀 키를 사용해 블록 이름 및 허용 목록에 포함된 속성과 함께 서명됩니다. 서명이 무효화되지 않고서는 요청에서 값을 변경하거나 추가할 수 없습니다. 런타임은 표시 중이거나 이벤트에 의해 시작된 새로 고침을 포함해 기존의 일괄 프래그먼트 요청과 함께 이 값들을 전송합니다. bs_render_block(), bs_block() 및 블록 태그에서도 작동합니다.
프래그먼트를 렌더링하는 동안 $block['postId'], $block['postType'], get_the_ID() 및 get_queried_object_id()은 해당 페이지를 가리킵니다. 렌더링 예외가 발생한 경우를 포함해 이후에 WordPress 쿼리 및 게시물 전역 변수가 복원됩니다. 여기서 말하는 페이지는 쿼리된 페이지이며 Query Loop 안의 항목이 아닙니다. 임의의 URL 매개변수를 다시 실행하거나 원래 요청의 URL을 복원하지는 않습니다. HTML 페이지의 표준 URL이 필요한 경우 get_permalink($block['postId'])을 사용하세요. 아카이브와 쿼리된 게시물 없이 렌더링되는 경우에는 페이지 식별 정보가 전송되지 않습니다.
엔드포인트는 프래그먼트 캐시를 확인하기 전에 페이지가 여전히 존재하는지, 서명된 게시물 유형인지, 현재 방문자가 읽을 수 있는지 확인합니다. 유효한 서명이 있어도 비공개 게시물이나 비밀번호 보호, 아일랜드 적합성, 속성 허용 목록 또는 블록 자체의 권한 검사를 우회할 수 없습니다. 페이지 식별 정보가 있으면 항상 프래그먼트 캐시 키에 포함되므로 페이지가 다른 경우 같은 블록과 속성이라도 프래그먼트를 공유하지 않습니다. 출력이 방문자에 따라서도 달라진다면 per: "user"을 사용하거나 프래그먼트 캐시를 사용하지 마세요.
context을 생략하거나 false인 경우 기존 마커와 컨텍스트가 없는 동작은 변경되지 않습니다. 공개 마커에 기밀 데이터를 넣지 마세요.
동적 플레이스홀더
동적 아일랜드는 공유 전체 페이지 캐시에서 안전하게 사용할 수 있는 플레이스홀더를 렌더링해야 합니다. 플레이스홀더 분기에 방문자별 데이터를 포함하지 마세요.
Blockstudio는 다음 순서로 플레이스홀더를 찾습니다.
- 명시적
island.placeholder경로 placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- 플레이스홀더 플래그가 있는 일반 템플릿
<div class="cart-count-placeholder">
Loading cart...
</div>
플레이스홀더 파일이 없으면 일반 템플릿에서 템플릿 플래그를 사용하세요.
<?php if ( $isIslandPlaceholder ) : ?>
<div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
<div class="cart-count">
<?php echo esc_html( acme_cart_count() ); ?>
</div>
<?php endif; ?>
다음 템플릿에서 동일한 값을 사용할 수 있습니다: PHP, Twig, Blade.
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase는 "normal", "hydrate", "placeholder" 또는 "fragment"입니다.
런타임 동작
Blockstudio는 렌더링된 페이지에 아일랜드 마커가 있을 때만 아일랜드 런타임을 삽입합니다. 아일랜드가 없는 페이지에는 추가 아일랜드 JavaScript가 전달되지 않습니다.
동적 아일랜드의 런타임은 다음을 수행합니다.
- 준비된 모든 마커 수집
- 동일한 블록 이름, 속성 및 서명 쌍의 중복 제거
- 일괄 REST 요청 한 번 전송
- 각 플레이스홀더를 반환된 조각으로 교체
blockstudio:island:rendered전달blockstudio:island:hydrate전달
loading: "eager" 아일랜드는 런타임이 시작되는 즉시 렌더링됩니다. loading: "visible" 아일랜드는 IntersectionObserver를 기다립니다. 표시되는 아일랜드 여러 개가 동시에 뷰포트에 들어오면 하나의 요청으로 묶입니다.
event는 지정된 창 이벤트가 발생하면 아일랜드를 새로 고칩니다.
window.dispatchEvent(new Event('cart:updated'));
실패하면 플레이스홀더를 그대로 두고 blockstudio:island:error를 전달합니다.
조각 엔드포인트
아일랜드 엔드포인트는 공개되어 있지만, 일반적인 블록 렌더링 API는 아닙니다.
각 마커에는 다음이 포함됩니다.
- 블록 이름
- 허용 목록에 포함된 속성
- 서버에서 생성한 서명
엔드포인트는 다음 조건을 만족할 때만 렌더링합니다.
- 블록이 등록되어 있음
- 블록이 동적 WordPress 블록임
- 블록이 동적 Blockstudio 아일랜드로 지정되어 있음
- 입력 속성이 블록 스키마 및 아일랜드 허용 목록을 통과함
- 서명이 정규화된 블록 이름 및 속성과 일치함
서명은 제공 사이트의 WordPress 사이트에서 렌더링 시 해당 사이트의 솔트와 아일랜드 페이로드를 사용해 생성됩니다. 테마로 내보내거나 테마에 포함하지 않습니다.
엔드포인트 응답은 캐시 불가로 표시됩니다. 조각 캐싱을 원한다면 island.cache를 사용하세요.
조각 캐싱
동적 조각은 기본적으로 캐시되지 않습니다.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true는 짧은 전역 캐시를 사용합니다. 명시적으로 제어하려면 객체 형식을 사용하세요.
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global"은 동일한 블록, 속성, 옵트인 페이지 컨텍스트에 대해 캐시된 프래그먼트 하나를 공유합니다.
per: "user"은 현재 WordPress 사용자 ID에 따라 캐시를 구분합니다.
프로그래밍 방식 렌더링
아일랜드는 Blockstudio 블록이 렌더링되는 모든 곳에서 작동합니다.
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
블록 태그를 통해서도 사용할 수 있습니다.
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
초기 출력은 여전히 아일랜드 마커와 플레이스홀더이며, 렌더링된 응답에 해당 마커가 있으면 런타임이 삽입됩니다.
PHP API
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);
marker()는 블록 메타데이터를 검증합니다. 동적 마커는 island.mode가 dynamic로 설정된 등록된 동적 Blockstudio 블록에 대해서만 생성됩니다.
훅
감지 및 마크업:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
엔드포인트 및 렌더링:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request는 일괄 엔드포인트 요청 하나가 허용하는 동적 아일랜드의 최대 개수를 변경합니다. 기본값은 50입니다.
런타임 구성:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
서명:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
수명 주기 액션:
blockstudio/islands/registered
blockstudio/islands/rendered
아일랜드를 사용하지 말아야 할 경우
SEO에 중요한 콘텐츠에는 동적 아일랜드를 사용하지 마세요. 동적 아일랜드 조각은 초기 HTML에 포함되지 않으며 색인될 용도가 아닙니다.
캐시 안전하고 크롤러에게 보여야 하는 콘텐츠에는 일반 렌더링이나 하이드레이션된 아일랜드를 사용하세요. 페이지 셸이 로드된 뒤 표시되어도 되는 콘텐츠에만 동적 아일랜드를 사용하세요. 예를 들면 계정 UI, 장바구니 상태, 개인화된 추천 또는 권한이 있어야 사용할 수 있는 컨트롤입니다.