Към съдържанието

Персонализирани фрагменти на кеширани страници

Страница, предоставена от статичен кеш, е еднаква за всички. В това е смисълът на кеширането, но тук е и проблемът: в заглавката трябва да пише „Здравей, Ada“ за влязъл клиент, а иконата на количката трябва да показва три продукта. Ако шаблонът използва условие според текущия потребител, кешът или ще запази поздрава на един посетител за всички, или ще трябва изцяло да пропусне страницата.

Динамичните острови на Blockstudio разделят тези две задачи. Кешираният HTML съдържа безопасен за кеширане заместител. След зареждането на страницата малка среда за изпълнение иска от WordPress персонализирания фрагмент в рамките на заявката на самия посетител и го заменя на страницата. Страницата остава кешируема, а динамичен е само фрагментът.

Това ръководство създава два острова — поздрав и брой продукти в количката — и разглежда съдържанието на кешираната страница, формата на заявката за фрагмент и начина, по който крайният адрес разпознава посетителя. То допълва ръководството Предоставяне на WordPress като статичен HTML.

Как работи динамичен остров

  1. Блокът изобразява своя заместител в маркиращ елемент. Маркерът съдържа името на блока, разрешените в списък атрибути и генериран от сървъра подпис.
  2. Тъй като изобразената страница съдържа маркер, Blockstudio добавя средата за изпълнение на острова. Страниците без острови не включват неговия JavaScript.
  3. Средата за изпълнение събира готовите маркери и изпраща една групирана POST до /wp-json/blockstudio/v1/island/render.
  4. Крайният адрес проверява всеки подпис, изобразява блока в контекста на заявката на посетителя и връща фрагментите.
  5. Средата за изпълнение заменя всеки заместител и изпраща събития.

В редактора на блокове блокът се изобразява нормално, без заместител.

Стъпка 1: Блокът за поздрав

Създайте блока с три файла:

Код
blocks/
└── greeting/
    ├── block.json
    ├── placeholder.php
    └── index.php
JSON
{
  "apiVersion": 3,
  "name": "acme/greeting",
  "title": "Greeting",
  "category": "widgets",
  "icon": "admin-users",
  "description": "Account link that greets signed-in visitors.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "span",
      "attributes": ["guestLabel"],
      "cache": {
        "ttl": 300,
        "per": "user"
      }
    },
    "attributes": [
      { "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
    ]
  }
}

mode: "dynamic" превръща блока в остров със заявка за фрагмент. tag задава маркиращия елемент, така че островът да може да бъде вграден в навигационна лента. attributes е списъкът с разрешени атрибути на блока, които се предават със заявката за фрагмент; всичко извън списъка нито се изпраща, нито се подписва. cache е разгледано по-надолу.

Кешираната страница съдържа заместителя. Той трябва да е безопасен за показване на всички посетители, затова не съдържа потребителски данни. Връзка „Профил“ е подходяща за всички:

PHP
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>

Основният шаблон изобразява истинския фрагмент:

PHP
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
  <a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
    <?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
  </a>
<?php else : ?>
  <a href="<?php echo esc_url( wp_login_url() ); ?>">
    <?php echo esc_html( $a['guestLabel'] ); ?>
  </a>
<?php endif; ?>

Тук условието според текущия потребител е подходящо: този шаблон се изпълнява само за заявката за фрагмент, никога за кешираната страница.

Поставете го навсякъде, където се изобразява заглавката:

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

Работят и етикети за блокове: <bs:acme-greeting /> или <block name="acme/greeting" />.

Стъпка 2: Какво съдържа кешираната страница

Изобразен на сървъра, блокът създава само маркера и заместителя:

HTML
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{&quot;guestLabel&quot;:&quot;Sign in&quot;}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>

Изобразете го веднъж като анонимен посетител и веднъж като влязъл потребител — двата низа са побитово еднакви. Именно това е необходимо за статично предварително изобразяване с включено serveLoggedIn: независимо кой задейства изобразяването, съхраненият документ е един и същ и не може да съдържа лична информация.

Стъпка 3: Заявката за фрагмент

Средата за изпълнение изпраща всяка готова островна заявка в една заявка:

JSON
{
    "islands": [
        {
            "clientId": "a1",
            "name": "acme/greeting",
            "attributes": {
                "guestLabel": "Sign in"
            },
            "signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
        }
    ]
}

Отговорът е индексиран по clientId. За влязъл посетител:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/account/\">\n    Hi, Ada  </a>\n"
}

Елемент, който не премине проверката, връща код за грешка вместо HTML, без да проваля останалата част от групата. Тук вторият елемент е променил guestLabel без съответстващ подпис, а третият посочва блок, който не е динамичен остров:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/wp-login.php\">\n    Sign in  </a>\n",
    "a2": {
        "error": "blockstudio_island_invalid_signature"
    },
    "a3": {
        "error": "blockstudio_island_not_allowed"
    }
}

Всеки отговор съдържа Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache и X-Robots-Tag: noindex. Крайният адрес е в /wp-json, който статичното предварително изобразяване винаги заобикаля. Затова нито кешът на изходния сървър, нито CDN, който спазва заглавките на източника, ще съхранява фрагмент.

Кой е посетителят

Средата за изпълнение изпраща заявката с credentials: 'same-origin', така че браузърът включва бисквитката за влизане WordPress. WordPress REST API обикновено игнорира удостоверяването чрез бисквитка без nonce, а nonce не може да присъства в кеширана страница. Крайният адрес на острова обработва това сам: при заявка от браузър със същия източник той проверява бисквитката logged_in и възстановява потребителя преди изобразяването.

Заявката се смята за такава от същия източник въз основа на заглавката Sec-Fetch-Site и, ако е налична, заглавката Origin, сравнена с home_url(). Заявка от друг източник, която случайно съдържа бисквитката, се обработва като анонимна, така че заявка от друг сайт никога не изобразява личния фрагмент на посетител. На практика:

Заявка Изобразява се като
Заявка от същия източник с валидна бисквитка за влизане влезлия потребител
Заявка от друг източник със същата бисквитка анонимен
Без бисквитка анонимен

Коя страница е това?

Добавете "context": true към blockstudio.island, когато фрагментът се нуждае от идентичността на страницата си. Тогава маркерът подписва идентификатора и типа на публикацията на заявената страница заедно с атрибутите. Във фрагмента $block['postId'], $block['postType'], get_the_ID() и get_queried_object_id() се отнасят до тази страница. В рамките на цикъл на заявка това продължава да означава външната заявена страница, а не елемента от цикъла.

Контекстът на страницата е включен само при изрично задаване и също е част от ключа на кеша на фрагментите. Крайната точка проверява достъпа отново дори за кеширани фрагменти, така че подписан маркер не разкрива страница, която междувременно е станала частна или защитена с парола. Вижте Контекст на страницата за подробности относно конфигурацията и сигурността. Не се възпроизвеждат произволни URL или параметри на заявката.

Стъпка 4: Брояч на количката, който се обновява сам

Вторият остров показва другия стил на заместител и две опции за средата за изпълнение. Вместо отделен файл за заместителя, шаблонът проверява $isIslandPlaceholder:

JSON
{
  "apiVersion": 3,
  "name": "acme/cart-count",
  "title": "Cart Count",
  "category": "widgets",
  "icon": "cart",
  "description": "Number of items in the visitor's cart.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "loading": "visible",
      "event": "acme:cart-updated"
    },
    "attributes": []
  }
}
PHP
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
  <a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
  <a href="/cart/" class="cart-count">
    Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
  </a>
<?php endif; ?>

Във всеки език за шаблони са налични същите флагове: isIsland, isIslandPlaceholder, isIslandFragment и islandPhase ("normal", "hydrate", "placeholder" или "fragment"). Тук броят идва от филтър acme/cart_count, който се попълва от кода на магазина; когато той връща 3, крайният адрес отговаря така:

JSON
{"c1":"<!--blockstudio/acme/cart-count-->  <a href=\"/cart/\" class=\"cart-count\">\n    Cart <span class=\"cart-count__badge\">3</span>\n  </a>\n"}

loading: "visible" отлага заявката, докато маркерът влезе в областта на видимост, като използва IntersectionObserver. Видимите острови, които се появяват едновременно, все пак се групират в една заявка. event задава име на събитие в прозореца, което извлича острова отново, така че след извикване за добавяне в количката скриптът ви трябва само да го задейства:

JavaScript
window.dispatchEvent(new Event('acme:cart-updated'));

Реакция в кода на фронтенда

Събитията се разпространяват от маркера, затова един слушател на document покрива всеки остров. event.detail.name съдържа името на блока:

JavaScript
document.addEventListener('blockstudio:island:rendered', (event) => {
  if (event.detail.name !== 'acme/cart-count') return;
  event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});

document.addEventListener('blockstudio:island:error', (event) => {
  console.warn('Island failed', event.detail.name, event.detail.error);
});

След замяна средата изпраща blockstudio:island:rendered, а след това blockstudio:island:hydrate. При неуспех заместителят остава на място и се задейства blockstudio:island:error. Хидратираните острови ("island": "hydrate") пропускат заявката изцяло: целият им HTML е в страницата и получават само събитието hydrate, което е подходящо за интерактивни блокове, безопасни за кеширане, като раздели.

Кеширане на фрагменти

По подразбиране фрагментите се изобразяват при всяка заявка. Поздравът по-горе използва кратко кеширане:

JSON
{
  "cache": {
    "ttl": 300,
    "per": "user"
  }
}

per: "user" променя кеширания фрагмент според потребителското ID на WordPress, а анонимните заявки никога не се кешират с него, така че двама анонимни посетители не могат да споделят запис, предназначен за потребител. per: "global" споделя един фрагмент за същия блок и атрибути, което е подходящо за съдържание, което се променя, но не е персонално, например ниво на наличност. ttl по подразбиране е 60 секунди, а cache: true е глобален кеш за 60 секунди.

Моделът на сигурност

Крайната точка е публична, но не е универсален рендерер на блокове. Тя изобразява запис само ако са изпълнени всички условия:

  • блокът е регистриран, динамичен и за island.mode е зададено dynamic
  • подписът съвпада с името на блока и атрибутите, преминали през филтъра: само ключове, присъстващи както в схемата на блока, така и в списъка с разрешения за острова

Подписът е HMAC-SHA256 върху нормализираното име на блока и атрибутите, с ключ солта auth на сайта, който го обслужва. Подписите се създават при изобразяването на този сайт и никога не се вграждат в тема. От това следват две последици. Документ, изобразен в тестова среда, съдържа подписи от нея, затова изобразявайте документите на сайта, който ги обслужва. А смяната на солите WordPress обезсилва всеки подпис в съхранените документи, затова изчистете статично предварително изобразеното съдържание след смяна на солта.

Една заявка приема до 50 острова; при повече се връща HTTP 413. Променете лимита с blockstudio/islands/max_per_request. Налични са куки за подпис (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) за хостове, които се нуждаят от друга схема.

Кога да не използвате остров

Фрагментите не са в първоначалния HTML, затова роботите не ги виждат. Дръжте съдържанието, свързано с SEO, в обичайното изобразяване. Използвайте динамични острови за съдържание, което може да се зареди след обвивката на страницата: връзки към акаунт, състояние на количката, препоръки и контроли с ограничен достъп. Когато цялата страница е персонална, например табло на акаунт, вместо това добавете пътя ѝ в dynamicPaths и я изобразявайте динамично.

Следващи стъпки