İçeriğe geç

Önbelleğe Alınmış Sayfalarda Kişiselleştirilmiş Parçalar

Statik önbellekten sunulan bir sayfa herkes için aynıdır. Önbelleğe almanın amacı budur; aynı zamanda sorunun kaynağı da: üstbilgi, oturum açmış müşteriye “Merhaba, Ada” demek, sepet simgesi de üç ürün göstermek ister. Şablon geçerli kullanıcıya göre dallanırsa önbellek ya bir ziyaretçinin selamını herkese sunar ya da sayfayı tümüyle önbellek dışında bırakmak gerekir.

Blockstudio’ın dinamik adacıkları bu iki ihtiyacı birbirinden ayırır. Önbelleğe alınan HTML, önbellek açısından güvenli bir yer tutucu içerir. Sayfa yüklendikten sonra küçük bir çalışma zamanı bileşeni ziyaretçinin kendi isteği içinde WordPress’tan kişisel parçayı ister ve onu sayfaya yerleştirir. Sayfa önbelleğe alınabilir kalır; yalnızca parça canlıdır.

Bu kılavuzda bir selamlama ve bir sepet sayısı olmak üzere iki adacık oluşturuluyor. Önbelleğe alınan sayfanın neler içerdiği, parça isteğinin nasıl göründüğü ve uç noktanın ziyaretçinin kimliğini nasıl belirlediği anlatılıyor. Kılavuz, Statik WordPress Olarak HTML Sunma ile birlikte kullanılabilir.

Dinamik adacık nasıl çalışır

  1. Blok, yer tutucusunu bir işaretleyici öğe içinde oluşturur. İşaretleyici; blok adını, izin verilen öznitelikleri ve sunucu tarafından oluşturulmuş bir imzayı taşır.
  2. Oluşturulan sayfada bir işaretleyici bulunduğunda Blockstudio adacık çalışma zamanı bileşenini ekler. Adacık içermeyen sayfalarda adacık JavaScript gönderilmez.
  3. Çalışma zamanı bileşeni hazır işaretleyicileri toplar ve /wp-json/blockstudio/v1/island/render‘e toplu bir POST gönderir.
  4. Uç nokta her imzayı doğrular, bloğu ziyaretçinin istek bağlamında oluşturur ve parçaları döndürür.
  5. Çalışma zamanı bileşeni her yer tutucuyu değiştirir ve olayları tetikler.

Blok düzenleyicide blok, yer tutucu olmadan normal biçimde oluşturulur.

1. Adım: Selamlama bloğu

Bloğu üç dosyayla oluşturun:

Kod
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" bu bloğu parça isteği kullanan bir adacık yapan özelliktir. tag işaretleyici öğeyi belirler; böylece adacık gezinme çubuğunda satır içinde yer alabilir. attributes, parça isteğiyle gönderilen blok özniteliklerinin izin verilenler listesidir; listede olmayan hiçbir şey gönderilmez veya imzalanmaz. cache aşağıda daha ayrıntılı ele alınır.

Önbelleğe alınan sayfada yer tutucu bulunur. Her ziyaretçiye gösterilmesi güvenli olmalıdır; bu nedenle kullanıcı verisi içermez. “Hesap” bağlantısı herkes için uygundur:

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

Ana şablon gerçek parçayı oluşturur:

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; ?>

Burada geçerli kullanıcıya göre dallanmak uygundur: bu şablon yalnızca parça isteği için çalışır, önbelleğe alınan sayfa için çalışmaz.

Üstbilginin oluşturulduğu her yere yerleştirin:

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

Blok etiketleri de çalışır: <bs:acme-greeting /> veya <block name="acme/greeting" />.

2. Adım: Önbelleğe alınan sayfanın içeriği

Sunucuda oluşturulduğunda blok yalnızca işaretleyici ve yer tutucu üretir:

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>

Bir kez anonim ziyaretçi olarak, bir kez de oturum açmış kullanıcı olarak oluşturun; iki dize bayt düzeyinde aynıdır. Statik ön oluşturmanın serveLoggedIn etkin durumdayken gerektirdiği özellik tam olarak budur: oluşturmayı kim tetiklerse tetiklesin, saklanan belge aynıdır ve içine kişisel hiçbir bilgi giremez.

3. Adım: Parça isteği

Çalışma zamanı bileşeni hazır tüm adacıkları tek istekte gönderir:

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

Yanıtın anahtarı clientId‘dır. Oturum açmış bir ziyaretçi için:

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

Doğrulamadan geçemeyen bir kayıt, paketin geri kalanını etkilemeden HTML yerine bir hata koduyla döner. Burada ikinci kaydın guestLabel değeri eşleşen imza olmadan değiştirilmiş; üçüncü kayıtta ise dinamik adacık olmayan bir blok adı verilmiştir:

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"
    }
}

Her yanıt Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache ve X-Robots-Tag: noindex içerir. Uç nokta /wp-json altında yer alır; statik ön oluşturma bu yolu her zaman atlar. Bu nedenle ne kaynak önbellek ne de kaynak üstbilgilerini dikkate alan CDN parça önbelleğe alır.

Ziyaretçinin kimliği

Çalışma zamanı bileşeni isteği credentials: 'same-origin' ile gönderir; böylece tarayıcı WordPress oturum açma çerezini ekler. WordPress REST API, nonce olmadan çerez kimlik doğrulamasını normalde yok sayar; nonce ise önbelleğe alınmış bir sayfada bulunamaz. Adacık uç noktası bu işi kendisi halleder: aynı kaynaklı tarayıcı isteğinde logged_in çerezini doğrular ve oluşturma işleminden önce bu kullanıcının oturumunu geri yükler.

Aynı kaynak denetimi, Sec-Fetch-Site üstbilgisindeki değer ile varsa Origin üstbilgisi karşılaştırılarak home_url() ile yapılır. Çerezi taşıyan başka bir kaynaktan gelen istekte içerik anonim kullanıcıya göre oluşturulur; böylece başka bir siteden gelen istek ziyaretçinin kişisel parçasını hiçbir zaman oluşturmaz. Uygulamada:

İstek Oluşturulma biçimi
Geçerli oturum açma çereziyle aynı kaynaklı fetch Oturum açmış kullanıcı
Aynı çerezle kaynaklar arası istek Anonim
Çerez yok Anonim

Bu Hangi Sayfa?

Parçanın ait olduğu sayfanın kimliğine ihtiyacı varsa "context": true işaretçisini blockstudio.island içine ekleyin. Böylece işaretçi, sorgulanan sayfanın gönderi kimliğini ve gönderi türünü özniteliklerle birlikte imzalar. Parçanın içinde $block['postId'], $block['postType'], get_the_ID() ve get_queried_object_id() bu sayfayı ifade eder. Bir Query Loop içinde bu, döngü öğesi değil, dıştaki sorgulanan sayfa anlamına gelmeye devam eder.

Sayfa bağlamı isteğe bağlıdır ve parça önbelleği anahtarının da bir parçasıdır. Uç nokta, önbelleğe alınmış parçalar için bile erişimi yeniden denetler; böylece imzalı bir işaret, sonradan gizli veya parola korumalı hâle gelen bir sayfayı açığa çıkarmaz. Yapılandırma ve güvenlik ayrıntıları için Sayfa Bağlamı bölümüne bakın. Rastgele URL veya sorgu parametreleri yeniden oynatılmaz.

4. Adım: Kendini yenileyen sepet sayısı

İkinci adacıkta farklı bir yer tutucu stili ve iki çalışma zamanı seçeneği gösterilir. Ayrı bir yer tutucu dosyası yerine şablon $isIslandPlaceholder değerini denetler:

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; ?>

Tüm şablon dillerinde aynı işaretler bulunur: isIsland, isIslandPlaceholder, isIslandFragment ve islandPhase ("normal", "hydrate", "placeholder" veya "fragment"). Burada sayı, ticaret kodunuzun doldurduğu bir acme/cart_count filtresinden gelir. Bu filtre 3 döndürdüğünde uç nokta şunu döndürür:

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 kullanarak işaretleyici görüntü alanına girene kadar isteği erteler. Aynı anda görünen adacıklar yine tek istekte toplu olarak gönderilir. event, adacığı yeniden getiren bir pencere olayının adını belirtir. Böylece sepete ürün ekleme çağrısından sonra betiğinizin bu olayı duyurması yeterlidir:

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

Ön yüz kodunda tepki verme

Olaylar işaretçiden yukarı doğru yayılır; bu nedenle document üzerinde tek bir dinleyici tüm adaları kapsar. event.detail.name blok adını tutar:

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);
});

Bir değişimden sonra çalışma zamanı önce blockstudio:island:rendered, ardından blockstudio:island:hydrate olayını gönderir. Başarısız olursa yer tutucu yerinde kalır ve blockstudio:island:error tetiklenir. Hydrate edilmiş adalar ("island": "hydrate") isteği tamamen atlar: tam HTML sayfada bulunur ve yalnızca hydrate olayını alırlar; bu da sekmeler gibi önbellek güvenli etkileşimli bloklar için uygundur.

Parça önbelleğe alma

Parçalar varsayılan olarak her istekte oluşturulur. Yukarıdaki karşılama mesajı kısa süreli önbelleği kullanır:

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

per: "user", önbelleğe alınan parçayı WordPress kullanıcı kimliğine göre değiştirir; anonim istekler hiçbir zaman bu anahtarla önbelleğe alınmaz, böylece iki anonim ziyaretçi bir kullanıcıya ait girdiyi paylaşamaz. per: "global" aynı blok ve öznitelikler için tek bir parçayı paylaşır; bu, stok düzeyi gibi canlı ancak kişisel olmayan içerikler için uygundur. ttl varsayılan olarak 60 saniyedir; cache: true ise 60 saniyelik genel önbellektir.

Güvenlik modeli

Uç nokta herkese açıktır ancak genel amaçlı bir blok oluşturucu değildir. Yalnızca aşağıdakilerin tümü geçerliyse bir girdiyi oluşturur:

  • blok kayıtlı ve dinamiktir; ayrıca island.mode değeri dynamic olarak ayarlanmıştır
  • imza, blok adı ve filtreden geçen özniteliklerle eşleşir: yalnızca hem blok şemasında hem de ada izin verilenler listesinde bulunan anahtarlar

İmza, normalize edilmiş blok adı ve öznitelikler üzerinden hesaplanan bir HMAC-SHA256 değeridir ve hizmeti sunan sitenin auth tuzuyla anahtarlanır. İmzalar o sitede oluşturma sırasında üretilir ve hiçbir zaman temaya gömülmez. Bunun iki sonucu vardır. Hazırlık ortamında oluşturulan bir belge, hazırlık ortamının imzalarını taşır; bu nedenle belgeleri onları sunan sitede oluşturun. Ayrıca WordPress tuzlarının değiştirilmesi, saklanan belgelerdeki tüm imzaları geçersiz kılar; bu yüzden tuz değişikliğinden sonra statik ön oluşturmayı temizleyin.

Tek bir istek en fazla 50 ada kabul eder; daha fazlası HTTP 413 döndürür. Sınırı blockstudio/islands/max_per_request ile değiştirin. Farklı bir şemaya ihtiyaç duyan barındırıcılar için imza kancaları (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) bulunur.

Ada ne zaman kullanılmamalı

Parçalar ilk HTML içinde bulunmaz, bu nedenle tarayıcılar onları göremez. SEO açısından önemli içeriği normal oluşturma akışında tutun. Sayfa kabuğu yüklendikten sonra gelebilecek hesap bağlantıları, sepet durumu, öneriler ve izin denetimli kontroller gibi içerikler için dinamik adalar kullanın. Hesap kontrol paneli gibi sayfanın tamamı kişiselse, bunun yerine yolu dynamicPaths içinde listeleyin ve sayfayı canlı oluşturun.

Sonraki adımlar