Adalar
Blok adaları, normal Blockstudio işleme hattını korurken isteğe özgü çıktıyı ilk HTML yanıtının dışına taşır.
Bu, bir sayfanın yoğun biçimde önbelleğe alınması gerektiğinde, ancak bir bloğun yine de geçerli ziyaretçiye, oturuma, sepete, izinlere veya başka bir canlı istek bağlamına bağlı olduğu durumlarda kullanışlıdır.
Blockstudio blokları hâlâ dinamik WordPress bloklarıdır. Adalar bunları önceden derlenmiş statik HTML hâline getirmez. Bunun yerine Blockstudio, ilk istekte neyin oluşturulduğunu değiştirir:
- Hidrate edilmiş adalar, önbelleğe güvenli normal HTML çıktısını oluşturur ve bir bağlama olayı alır
- Dinamik adalar önce önbelleğe güvenli bir yer tutucu oluşturur, ardından gerçek parçayı ziyaretçinin tarayıcısından getirir
Modlar
Hidrate Edilmiş Adalar
Sunucu çıktısı güvenle önbelleğe alınabiliyorsa ve blok yalnızca ön yüzde bir bağlama sinyaline ihtiyaç duyuyorsa hidrate edilmiş ada kullanın.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Blokun tamamı HTML ilk yanıtta bulunur. Ada çalışma zamanı bunun için bir REST isteği yapmaz. Ön yüz kodunun davranış ekleyebilmesi için işaretçide blockstudio:island:hydrate tetikler.
Dinamik Adalar
Gerçek blok çıktısının ziyaretçinin istek bağlamında oluşturulması gerekiyorsa dinamik ada kullanın.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
İlk yanıt yalnızca bir yer tutucu içerir. Tarayıcı, hazır olan tüm dinamik adaları şu adrese tek bir istekte toplar:
POST /wp-json/blockstudio/v1/island/render
Uç nokta yalnızca kayıtlı, dinamik olan ve blockstudio.island.mode değeri dynamic olarak ayarlanmış Blockstudio blokları oluşturur.
Yapılandırma
island değeri kısa biçimde veya bir nesne olarak belirtilebilir.
{
"blockstudio": {
"island": true
}
}
true ve "hydrate" hidrate edilmiş anlamına gelir. "dynamic" dinamik anlamına gelir.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Özellik | Tür | Varsayılan | Açıklama |
|---|---|---|---|
mode |
"hydrate" veya "dynamic" |
"hydrate" |
Ada modu. |
tag |
string |
"div" |
İşaretleyici sarmalayıcı etiketi. |
attributes |
string[] |
tüm blok öznitelikleri | Dinamik parça isteklerine gönderilen öznitelik izin listesi. |
placeholder |
string |
otomatik algılanır | Göreli yer tutucu şablon yolu. |
loading |
"eager" veya "visible" |
"eager" |
Çalışma zamanının dinamik bir adayı ne zaman getireceği. |
event |
string |
ayarlanmamış | Dinamik adayı yenileyen pencere olayı adı. |
context |
boolean |
false |
Dinamik parçalar için sorgulanan sayfanın yazı kimliğini ve yazı türünü imzalayıp geri yükleyin. |
cache |
boolean veya object |
false |
İsteğe bağlı parça önbelleği ilkesi. |
Sayfa Bağlamı
Dinamik parçalar genellikle sayfa kabuğundan bağımsız olarak render edilir. Bloğunuz sayfaya özgü ayarları veya ilişkili içeriği okuduğunda sayfa kimliğini etkinleştirin:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
İşaretleyici, sorgulanan sayfanın postId ve postType değerlerini data-bs-island-context içinde içerir. Her iki değer de sunucu sitesinin gizli anahtarı kullanılarak blok adı ve izin verilen özniteliklerle imzalanır. İmza geçersiz kılınmadan bu değerler değiştirilemez veya isteğe eklenemez. Çalışma zamanı, bunları görünür ve olayla tetiklenen yenilemeler dahil mevcut toplu parça isteğiyle birlikte gönderir. Bu, bs_render_block(), bs_block() ve blok etiketleriyle de çalışır.
Parça işleme sırasında $block['postId'], $block['postType'],
get_the_ID() ve get_queried_object_id() bu sayfayı belirtir. WordPress sorgu
ve gönderi genel değişkenleri, bir işleme hatasından sonra da dahil olmak üzere, sonrasında geri yüklenir.
Bu, bir Sorgu Döngüsü içindeki bir öğe değil, sorgulanan sayfadır. Keyfî
URL parametrelerini yeniden oynatmaz veya özgün istek URL değerini geri yüklemez. Kanonik URL değerine sahip HTML sayfasına ihtiyacınız varsa get_permalink($block['postId']) kullanın.
Arşivlerde ve sorgulanmış bir gönderi olmadan yapılan işlemlerde sayfa kimliği gönderilmez.
Uç nokta, parça önbelleğine başvurmadan önce sayfanın hâlâ var olduğunu, imzalanmış yazı türüne sahip olduğunu ve mevcut ziyaretçi tarafından okunabildiğini denetler. Geçerli bir imza; özel gönderilerin veya parola korumasının, ada uygunluğunun, öznitelik izin listelerinin ya da bloğunuzun kendi izin denetimlerinin atlanmasını sağlamaz. Sayfa kimliği bulunduğunda her zaman parça önbelleği anahtarına dahil edilir; böylece farklı sayfalardaki aynı blok ve öznitelikler hiçbir zaman aynı parçayı paylaşmaz. Çıktı ziyaretçiye de bağlıysa per: "user" kullanın veya parça önbelleğini kapatın.
context atlanırsa veya false ise mevcut işaretleyiciler ve bağlamdan bağımsız davranış değişmeden kalır. Gizli verileri herkese açık işaretleyiciye koymayın.
Dinamik Yer Tutucular
Dinamik adalar, paylaşılan tam sayfa önbelleğinde güvenli olacak bir yer tutucu oluşturmalıdır. Yer tutucu dalına ziyaretçiye özgü veriler eklemeyin.
Blockstudio yer tutucuları şu sırayla arar:
- açıkça belirtilen
island.placeholderyolu placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- yer tutucu işaretli normal şablon
<div class="cart-count-placeholder">
Loading cart...
</div>
Hiçbir yer tutucu dosyası yoksa normal şablonunuzdaki şablon işaretlerini kullanın:
<?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; ?>
Aynı değerler PHP, Twig ve Blade şablonlarında kullanılabilir:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase, "normal", "hydrate", "placeholder" veya "fragment" değerlerinden biridir.
Çalışma Zamanındaki Davranış
Blockstudio, ada çalışma zamanını yalnızca oluşturulan sayfada bir ada işaretçisi varsa ekler. Ada içermeyen sayfalara ek ada JavaScript gönderilmez.
Dinamik adalar için çalışma zamanı:
- Hazır olan tüm işaretçileri toplar
- Aynı blok adı, öznitelikler ve imza çiftlerini tekilleştirir
- Toplu bir REST isteği gönderir
- Her yer tutucuyu döndürülen parçayla değiştirir
blockstudio:island:renderedtetiklerblockstudio:island:hydratetetikler
loading: "eager" adalar, çalışma zamanı başlar başlamaz oluşturulur. loading: "visible" adalar IntersectionObserver öğesini bekler. Görünür birkaç ada aynı anda görüntü alanına girerse tek bir istekte toplanırlar.
Ad, belirtilen pencere olayı tetiklendiğinde bir adayı yeniler: event
window.dispatchEvent(new Event('cart:updated'));
Hata durumunda yer tutucu yerinde kalır ve blockstudio:island:error tetiklenir.
Parça Uç Noktası
Ada uç noktası herkese açıktır, ancak genel amaçlı bir blok oluşturma API değildir.
Her işaretçi şunları taşır:
- blok adı
- izin verilen öznitelikler
- sunucu tarafından oluşturulan imza
Uç nokta yalnızca şu durumlarda içerik oluşturur:
- Blok kayıtlıysa
- Blok dinamik bir WordPress bloğuysa
- Blok dinamik bir Blockstudio adası olarak işaretlenmişse
- Gelen öznitelikler blok şemasını ve ada izin verilenler listesini geçerse
- İmza, normalleştirilmiş blok adı ve özniteliklerle eşleşirse
İmzalar, hizmet veren WordPress sitesinde oluşturma sırasında sitenin salt değerleri ve ada yükü kullanılarak üretilir. Dışa aktarılmaz veya temaya eklenmez.
Uç nokta yanıtları önbelleğe alınamaz olarak işaretlenir. Parça önbelleğe almak istiyorsanız island.cache kullanın.
Parça Önbelleğe Alma
Dinamik parçalar varsayılan olarak önbelleğe alınmaz.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true kısa süreli genel bir önbellek kullanır. Açık denetim için nesne biçimini kullanın:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" aynı blok, öznitelikler ve
isteğe bağlı sayfa bağlamı için önbelleğe alınmış tek bir parça paylaşır.
per: "user" önbelleği geçerli WordPress kullanıcı kimliğine göre değiştirir.
Programatik Oluşturma
Adalar, Blockstudio bloklarının oluşturulduğu her yerde çalışır:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Blok etiketleri üzerinden de çalışırlar:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
İlk çıktı yine ada işaretçisi ve yer tutucudur; çalışma zamanı, oluşturulan yanıt bu işaretçiyi içerdiğinde eklenir.
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(), blok meta verilerini doğrular. Dinamik işaretçiler yalnızca kayıtlı dinamik Blockstudio blokları için ve island.mode değeri dynamic olarak ayarlandığında oluşturulur.
Kancalar
Algılama ve biçimlendirme:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Uç nokta ve oluşturma:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request, tek bir toplu uç nokta isteğinin kabul ettiği dinamik ada sayısı üst sınırını değiştirir. Varsayılan değer 50‘dir.
Çalışma zamanı yapılandırması:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
İmzalar:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Yaşam döngüsü eylemleri:
blockstudio/islands/registered
blockstudio/islands/rendered
Adalar Ne Zaman Kullanılmamalı?
SEO açısından kritik içerikler için dinamik ada kullanmayın. Dinamik ada parçaları ilk HTML içinde bulunmaz ve dizine eklenmeleri amaçlanmamıştır.
İçerik önbelleğe güvenliyse ve tarayıcılar tarafından görünür olması gerekiyorsa normal oluşturmayı veya hidrate edilmiş ada kullanın. Dinamik adayı yalnızca sayfa kabuğundan sonra gelebilecek hesap UI bilgileri, sepet durumu, kişiselleştirilmiş öneriler veya izin gerektiren denetimler gibi içerikler için kullanın.