Острівці
Острівці блоків дають змогу блоку й надалі використовувати звичайний конвеєр рендерингу 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 відновлюються, зокрема й після помилки рендерингу. Це запитана сторінка, а не елемент усередині циклу запиту. Довільні параметри URL не відтворюються, а початковий URL запиту не відновлюється. Використовуйте get_permalink($block['postId']), якщо вам потрібен канонічний URL сторінки HTML. Для архівів і рендерингу без запитаного допису ідентифікація сторінки не надсилається.
Перш ніж звертатися до кешу фрагментів, кінцева точка перевіряє, чи сторінка досі існує, чи відповідає підписаному типу допису та чи може її читати поточний відвідувач. Чинний підпис не обходить захист приватних дописів паролем, вимоги до придатності острова, списки дозволених атрибутів або власні перевірки дозволів вашого блоку. Якщо ідентифікацію сторінки передано, вона завжди входить до ключа кешу фрагмента, тож однакові блоки з однаковими атрибутами на різних сторінках не використовують спільний фрагмент. Використовуйте 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" змінює кеш залежно від поточного ID користувача WordPress.
Програмний рендеринг
Острівці працюють скрізь, де рендеряться блоки 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() перевіряє метадані блока. Динамічні маркери створюються лише для зареєстрованих динамічних блоків Blockstudio, у яких island.mode має значення dynamic.
Хуки
Виявлення та розмітка:
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, стану кошика, персоналізованих рекомендацій або елементів керування з обмеженим доступом.