Sayfalar
Sayfalar, gönderiler olarak WordPress veritabanına eşitlenen dosya tabanlı şablonlardır.
Eşitleme açıkça yapılır: kaynak değişikliklerini uygulamak istediğinizde wp bs pages sync komutunu çalıştırın veya Pages API aracını çağırın. Önyüzün veya WordPress yönetim panelinin yüklenmesi, sayfaların tamamını keşfetmez ya da sayfa gönderilerini değiştirmez.
Sayfalar tek bir page.json klasörü, bağımsız Markdown dosyaları veya pages.json manifesti bulunan bir koleksiyon olarak tanımlanabilir. Koleksiyonlar; belgeler, bilgi bankaları, açılış sayfası kitaplıkları veya dosyalardan oluşturulması gereken iç içe sayfa kümeleri için kullanışlıdır.
page.json
JSON ile tanımlanmış bir sayfa için page.json yapılandırma dosyası ekleyin:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
Özellikler
| Özellik | Tür | Varsayılan | Açıklama |
|---|---|---|---|
name |
string |
gerekli | Sayfanın benzersiz tanımlayıcısı |
title |
string |
Ad değerinden otomatik | Sayfa başlığı |
slug |
string |
Ad ile aynı | Sayfanın URL kısa adı |
path |
string |
"." |
Koleksiyon içindeki mantıksal yol |
order |
integer |
0 |
Eşitlenen yazının menü sırası |
postType |
string |
"page" |
WordPress yazı türü |
postStatus |
string |
"draft" |
Yeni yazıların durumu (publish, draft, pending, private) |
postId |
integer |
– | Sayfayı belirli bir WordPress yazı kimliğine sabitleyin |
blockEditingMode |
string |
– | Blok düzenleme modu: "default", "contentOnly" veya "disabled" |
templateLock |
string|false |
"all" |
Kilit modu: "all", "insert", "contentOnly" veya false |
templateFor |
string|null |
null |
Bir yazı türü için varsayılan şablon olarak ayarlayın |
sync |
boolean |
true |
Normal ve açık eşitlemenin yazıyı oluşturup oluşturamayacağı veya güncelleyip güncelleyemeyeceği |
render |
string|object|false |
– | Sayfayı kayıtlı bir sayfa işleyiciyle işleyin (bkz. Bileşen Sayfaları) |
page.json, önbilgi ve yükleyici girdilerinde tanınan anahtarlar şunlardır: blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock ve title. Yukarıda listelenmeyen tüm anahtarlar, sayfanın meta dizisi altında saklanır.
İçerik Kaynakları
Sayfa tanımı, hangi WordPress gönderisinin mevcut olması gerektiğini belirler. İçerik kaynağı ise bu gönderiye hangi blok işaretlemesinin yazılacağını belirler.
Bir sayfa klasöründe page.json varsa Blockstudio, aynı klasördeki kaynak dosyalarını şu sırayla arar:
| Dosya | Kullanım |
|---|---|
index.php |
HTML benzeri blok işaretlemesi, olduğu gibi okunur (PHP kodu çalıştırılmaz) |
index.blade.php |
Blade şablon içeriği |
index.twig |
Twig şablon içeriği |
index.md |
Markdown içeriği |
page.json, aynı klasördeki bir dosya yerine satır içi markdown veya html de sağlayabilir:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
Koleksiyonlar iki ek kaynak modu sunar:
- Koleksiyon ağacında doğrudan bulunan Markdown dosyaları.
loader.phptarafından döndürülen yükleyici girdileri.
Yükleyici girdileri, contentType ile birlikte markdown, html veya content kullanabilir. Ayrıca yerel bir file veya template dosyasına işaret edebilirler. contentType açıkça ayarlanmadığı sürece dosya ve şablon kaynaklarının türü uzantılarından belirlenir.
Desteklenen contentType değerleri php, blade, twig, markdown ve html şeklindedir. Önce Markdown, HTML biçimine dönüştürülür; ardından yerel WordPress blokları olarak ayrıştırılır. PHP, Blade, Twig ve HTML kaynakları normal Blockstudio sayfa ayrıştırıcısından geçer.
Çekirdek bloklardaki sınıflar
Çekirdek bir bloğa eşlenen HTML öğesindeki class, bloğun className değeri olur.
Açıkça belirtilen bir çekirdek blok etiketi doğrudan className kullanabilir. Her iki biçim de blok için kaydedilmiş sarmalayıcıdaki sınıfları, WordPress tarafından oluşturulan sınıflarla birlikte korur:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
Her iki özellik de mevcutsa className önceliklidir. Bu dönüştürme yalnızca çekirdek bloklara uygulanır: özel bir blok eşlemesi, class alanını değiştirmeden korur. is-style-outline gibi düğme stili sınıfları bağlantıya değil, düğme sarmalayıcısına aittir.
Daha önce eşitlenen sayfalara ayrıştırıcı düzeltmelerini uygulamak için wp bs pages sync komutunu çalıştırın. Ayrıştırıcı yükseltmeleri, kaynak dosyada değişiklik yapılmadan sonraki açık eşitlemede tanınır. Kilitli sayfalar ve sync: false bulunan sayfalar normal korumalarını sürdürür; ön yüz istekleri bu eşitlemeyi hiçbir zaman gerçekleştirmez.
Serileştirilmiş WordPress blokları
Sayfa ve desen kaynakları, WordPress kod düzenleyicisinden kopyalanmış serileştirilmiş bloklar da içerebilir:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
Kaynakta bir <!-- wp:... --> blok sınırlayıcısı varsa, Blockstudio tüm kaynak için WordPress yerel blok ayrıştırıcısını kullanır. Öznitelikler, iç içe bloklar, Query Loop gibi dinamik bloklar ve Blockstudio blokları serileştirilmiş yapılarını korur. Blok yorumlarının dışındaki HTML, yerel serbest biçimli HTML olarak kalır; ek bloklara dönüştürülmez. Blockstudio’in HTML blok etiketlerini bu biçimle karıştırıp dönüştürülmelerini beklemeyin. Sıradan HTML yorumları serileştirilmiş blok modunu seçmez.
Markdown Sayfaları
Metin dosyalarda yer alırken eşitleme sonrasında düzenlenebilir WordPress blok içeriğine dönüşsün istiyorsanız Markdown kullanın. Eşitleme sırasında Markdown kaynağı blok işaretlemesine dönüştürülür. Eşitlenen gönderide ham Markdown gövdesi değil, bloklar saklanır.
Markdown üç şekilde kullanılabilir:
| Kaynak | Ön madde gerekli mi? | Notlar |
|---|---|---|
Bağımsız pages/example/index.md |
Evet | Ön madde sayfa kimliğini sağlar. |
page.json ve index.md |
Hayır | page.json sayfayı tanımlar, Markdown ise içeriği sağlar. |
| Koleksiyon içindeki Markdown | Hayır | Koleksiyon, dosya konumundan name ve path değerlerini çıkarır. |
Ön maddesi olmayan bağımsız bir index.md atlanır; çünkü Blockstudio eşitleme için sayfa kimliğine sahip değildir. Koleksiyon içindeki Markdown için ön madde gerekmez; koleksiyon manifesti ve dosya yolu bu kimliği sağlar.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
page.json dosyasını index.md ile de eşleştirebilirsiniz. Bu durumda page.json sayfayı tanımlar, index.md ise içeriği sağlar. index.md içindeki ön madde, eşleşen page.json değerlerini geçersiz kılar.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
Koleksiyon Markdown için, ön madde geçersiz kılmadığı sürece dosya yolu mantıksal sayfa yolu olur:
| Dosya | Varsayılan yol |
|---|---|
pages/docs/index.md |
. |
pages/docs/getting-started.md |
getting-started |
pages/docs/guide/install/index.md |
guide/install |
pages/docs/guide/install.md |
guide/install |
Bilinmeyen ön madde anahtarları sayfanın meta dizisinde korunur. Bu sayede section veya description gibi veriler ekleyebilir ve bunları PHP API içinden okuyabilirsiniz.
Markdown, Markdown Flavored GitHub olarak ayrıştırılır. Ham HTML kullanılabilir; güvenli olmayan bağlantılar kaldırılır ve açık bir kimliği olmayan başlıklara kalıcı bir kimlik atanır. İç içe YAML ön maddeleri için pakete dahil YAML ayrıştırıcısı gerekir.
Ham Markdown
Markdown dosya kaynakları, harici araçlara ve dokümantasyon tüketicilerine özgün kaynak Markdown değerini sunabilir. Satır içi Markdown bir kaynak dosyasına sahip olmadığından bloklara eşitlenir, ancak ham .md yanıtı üretmez.
Sayfayı .md sonekiyle, örneğin https://example.com/docs/reference.md ile isteyin. Ya da normal sayfa URL adresine bir Accept: text/markdown başlığı gönderin:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
Ön madde yanıttan çıkarılır. Başarılı ham Markdown yanıtları Content-Type: text/markdown, X-Robots-Tag: noindex ve standart bir Link başlığını HTML sayfasına geri gönderir. Bulunamayan .md rotaları gerçek bir 404 döndürür.
İçerik anlaşması statik önceden oluşturmayla çalışır: Accept başlığında text/markdown bulunan bir istek, önceden oluşturulmuş depodan veya erken sunum eklentisinden yanıtlanmaz; dolayısıyla WordPress ve Markdown işleyicisine ulaşır. Önceden oluşturulmuş HTML yanıtları, Markdown için de içerik anlaşması yapan bir sayfanın HTML değeri ve Accept üzerinden yanıtlanan Markdown, Vary: Accept gönderir; böylece Vary ilkesine uyan önbellekler bu yanıtları birbirinden ayrı tutar. Önbelleğini yalnızca URL değerine göre anahtarlayan bir CDN, bu tür isteklerde önbelleği atlamak için kendi kuralını gerektirir. Pages::negotiates_markdown( $post_id ), bir sayfanın Markdown isteklerine yanıt verip vermediğini bildirir.
Koleksiyon Markdown, ham Markdown için aynı URL yapısını korur:
| Sayfa URL | Ham Markdown URL |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
blockstudio/pages/serve_markdown filtresiyle ham Markdown yanıtlarını devre dışı bırakın:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
.md URL bir Markdown tabanlı sayfaya çözümlenmezse yalnızca yol bir sayfa koleksiyonuna ait olduğunda 404 döndürür. Hiçbir koleksiyona ait değilse Blockstudio, isteği WordPress ve diğer eklentilerin işlemesi için olduğu gibi bırakır.
Bileşen Sayfaları
Bir bileşen sayfası, blok olarak saklanmak yerine bir sayfa işleyici tarafından işlenir. Blockstudio bir işleyiciyle birlikte gelmez. Bir tema veya eklenti, örneğin page.tsx için bir React işleyicisi gibi, işlediği giriş dosyaları için bir işleyici kaydeder; Blockstudio ise sayfayı, WordPress yazısını ve işlenmiş yuva içeriğini işleyiciye iletir.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
render açıkça belirtilmelidir. index.php ve page.tsx içeren ancak render içermeyen bir dizin sıradan bir sayfa olarak kalır; böylece işleyici eklemek mevcut bir sayfanın iki kez işlenmesine yol açmaz. Biçimler şöyledir:
| Değer | Anlamı |
|---|---|
"page.tsx" |
Veri yükleyicisi olmayan, yalnızca giriş |
{ "entry": "page.tsx", "data": "data.php" } |
Giriş ve veri yükleyicisi |
{ "entry": "page.tsx", "renderer": "react" } |
Açık bir işleyici kimliği belirtilmiş giriş |
false |
Koleksiyon varsayılanı bir işleyici belirtse bile işleyici yok |
Yollar, sayfa dizinine veya yükleyici girdileri için koleksiyon köküne göre çözülür. blockstudio/pages/allow_external_loader_path izin vermediği sürece keşif kaynağının içinde kalmaları gerekir. renderer olmadığında girişin uzantısını sahiplenen işleyici kullanılır. Var olmayan bir giriş veya veri dosyasını belirten render, bilinmeyen bir işleyici ya da hiçbir işleyicinin sahiplenmediği bir uzantı keşif hatasıdır ve herhangi bir şey budanmadan önce eşitlemenin başarısız olmasına neden olur.
Eşitlemenin sakladıkları
Eşitleme tek bir blockstudio/page bloğu saklar. Sayfa dizininde ayrıca bir index.* kaynağı varsa bu kaynak, herhangi bir sayfa kaynağı gibi ayrıştırılır ve bloğun iç blokları, yani yuvası olur:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
Kısa kodlar gibi WordPress tarafından yönetilen içeriği yuvada tutun. [download_checkout] gibi yalnızca tek bir kısa koddan oluşan bir kaynak, bir core/shortcode bloğu olarak saklanır; böylece çıktısının çevresine paragraf eklenmez. Kaynak post_content içinde kalır; bu sayede has_shortcode() denetimleri onu görür, anahtarlı yuva blokları da iç içe anahtarlı bloklarda olduğu gibi düzenleyici değişiklikleriyle birleştirilir. Ayrıca do_shortcode kısa kodları, işleyici bunları çerçeveledikten sonra olağan the_content önceliğinde bir kez genişletir.
İşleme tanımı, yazıyla birlikte taşınabilir theme: yolları olarak saklanır. Sayfa parmak izi, girişin veya veri yükleyicisinin baytlarını değil tanımı kapsar: page.tsx ya da data.php dosyasını düzenlemek yazıyı değiştirmez; ziyaretçilere yapılan sunum ve giriş dosyasını, veri yükleyicisini ve işleyicinin bildirdiği tüm dosyaları kaydeden statik ön işleme grafiği aracılığıyla yansır.
İşleyici kaydetme
İşleyicileri blockstudio/pages/renderers eylemine kaydedin. Bu eylem, ilk keşif veya işleme başlamadan önce istek başına bir kez tetiklenir; böylece wp bs pages sync ve ön yüz istekleri aynı kayıt defterini görür.
add_action(
'blockstudio/pages/renderers',
static function (): void {
Blockstudio\Page_Renderers::register(
'react',
array(
'extensions' => array( 'tsx' ),
'layouts' => array( 'layout.tsx' ),
'render' => 'my_theme_render_page',
)
);
}
);
İşleyici kimlikleri küçük harfle yazılır. Bir uzantı veya düzen adı yalnızca tek bir işleyiciye ait olabilir ve layout.php, Blockstudio işleyicisinin kendi düzeni olarak kalır. Çağrılabilir öğe tek bir istek alır:
| Anahtar | Değer |
|---|---|
kind |
page veya bir işleyici düzeni için layout |
renderer |
İşleyici kimliği |
entry |
Mutlak giriş yolu |
data |
Mutlak veri yükleyicisi yolu veya null |
page |
meta dahil kanonik sayfa verileri |
post_id |
WordPress yazı kimliği |
slot |
İşlenmiş yuva içeriği veya düzen için sayfa içeriği |
context |
frontend, rest, feed veya cli |
HTML, işlemenin okuduğu dosyaları ve isteğe bağlı varlıkları döndürür:
function my_theme_render_page( array $request ): array {
return array(
'html' => '<main>...</main>',
'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
'assets' => array( array( 'path' => '/abs/path/to/page.js' ) ),
);
}
context istek türünden gelir, ziyaretçiden asla alınmaz; bu nedenle bir
render işleyicisi bunu okuyarak oturum açmış ve anonim kullanıcılar arasındaki
bayt eşitliğini bozamaz. Başarısız olan bir render işleyicisi hata fırlatır:
sayfa boş bir gövdeyle render edilmez. Bir REST düzenleyici önizlemesinde
blok, hatayı bildirim olarak gösterir. Başarılı bir render işleminden sonra
blockstudio/pages/rendered eylemi sayfayı,
HTML değerini ve bağımlılıklarını alır.
assets, sayfanın ihtiyaç duyduğu betik ve stil dosyalarını listeler. Bu dosyalar blok varlıklarıyla aynı işlemden geçer (*.inline.* kuralı, ES modülleri, küçültme ve
?ver dahil) ve sayfa bunları, blok varlıklarını yazdıran aynı arabellek üzerinden bir kez yazdırır; böylece önceden render edilmiş bir sayfa da bu dosyaları içerir. Bir varlık, version değerini ayarlayarak kendi ?ver değerini değiştirebilir. Bir render işleyicisinin dışındaki kod da aynı kanalı Blockstudio\Assets::register_owner() üzerinden kullanabilir; bu işlev yazdırılacak işaretçi yorumunu döndürür.
Düzenleyici
Düzenleyicide blockstudio/page, iç blokları yuva olarak kullanan sayfanın sunucuda render edilmiş bir önizlemesini gösterir; bu bloklar sayfanın templateLock değerini izler. Blok eklenemez, çoğaltılamaz veya başka bir bloğun içine yerleştirilemez.
Sayfa Koleksiyonları
Koleksiyon, pages.json manifesti içeren bir klasördür. Birçok sayfa kaynağını tek bir koleksiyon slug’ı altında toplar, varsayılanları uygular, iç içe yolları destekler ve otomatik olarak özel bir gönderi türü kaydedebilir.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| Özellik | Tür | Açıklama |
|---|---|---|
collection / slug / name |
string |
Koleksiyon kısa adı. En açık biçim collection olup herkese açık URL temelini oluşturur. |
title |
string |
İnsanların okuyabileceği koleksiyon başlığı. |
postType |
string |
Oluşturulan sayfalar için gönderi türü. Varsayılanı page değeridir. Mevcut değilse Blockstudio kaydeder. |
postTypeArgs |
object |
Blockstudio koleksiyon gönderi türünü kaydederken register_post_type() öğesine aktarılan bağımsız değişkenler. |
defaults |
object |
Koleksiyondaki her sayfaya uygulanan varsayılan sayfa özellikleri. Varsayılan bir render, yalnızca sayfa dizininde ilgili girdisi varsa sayfaya uygulanır. |
scope |
string |
collection (varsayılan) veya site. Bkz. Site Koleksiyonları. |
meta |
object |
Özel koleksiyon meta verileri. Bilinmeyen bildirim anahtarları da meta içinde saklanır. |
Koleksiyon sayfa yolları mantıksal yollardır. path: "guide/install" değerine sahip bir sayfa, guide öğesinin alt sayfası olarak eşitlenir; bu üst sayfalar varsa guide değeri de koleksiyon kökünün alt sayfası olarak eşitlenir.
Hiyerarşik bir koleksiyonda iç içe bir sayfa varsa ancak aradaki üst kaynağı yoksa Blockstudio, ilgili yol için boş bir kapsayıcı sayfa oluşturur ve WordPress hiyerarşisinin tamamlanmasını sağlar. page-attributes üst desteği olmayan hiyerarşik olmayan gönderi türleri boş kapsayıcılar oluşturmaz. Bunlar saklanan koleksiyon yoluna göre yönlendirme yapar; böylece guide/install ve setup/install gibi iç içe yollar, her ikisi de install ile bitse bile birlikte bulunabilir.
Koleksiyon Gönderi Türleri ve URL’ler
Koleksiyondaki her sayfayı bu gönderi türüne eşitlemek için koleksiyon manifestinde postType ayarlayın. Aynı değeri defaults içinde tekrarlamanız gerekmez. Tek tek sayfalar, ön maddede veya page.json içinde postType değerini geçersiz kılabilir.
Gönderi türü yoksa Blockstudio, türü show_in_rest: true, sayfa benzeri bir düzenleyici kurulumu ve herkese açık URL tabanı olarak koleksiyon slug’ıyla kaydeder. postTypeArgs kayıt bağımsız değişkenlerini geçersiz kılabilir. Kayıtlı koleksiyon gönderi türleri veya yeniden yazma bağımsız değişkenleri değiştiğinde koleksiyon gönderi türü yeniden yazma kuralları otomatik olarak yenilenir; WordPress kalıcı bağlantılarını yeniden kaydetmeniz gerekmez.
Koleksiyon URL’leri, koleksiyon slug’ını ve her sayfanın mantıksal path değerini kullanır:
| Kaynak yolu | Herkese açık URL |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
Bu URL modeli hem hiyerarşik hem de hiyerarşik olmayan koleksiyon yazı türleriyle çalışır. Blockstudio ayrıca /docs/docs/ veya /docs/docs/getting-started/ gibi yinelenmiş URL’leri standart URL adresine yönlendirir.
Koleksiyon sayfaları, aynı URL’lerde ham Markdown sunar (bkz. Ham Markdown).
Bir koleksiyonu postType: "page" türünden özel bir yazı türüne geçirirseniz, Blockstudio kayıtlı sayfa kimlikleri eşleştiğinde önceden eşitlenmiş koleksiyon yazılarını yerinde taşır. Böylece yazı kimlikleri, meta veriler ve mevcut içerik korunurken eski türde yinelenen yazılar oluşmaz. Eski koleksiyon yazıları, tüm yazı durumlarında blockstudio/pages/orphan_action filtresine göre temizlenir.
Site Koleksiyonları
"scope": "site" içeren bir bildirim, sayfaları koleksiyon sayfalarına dönüştürmeden, altındaki tüm sayfaları gruplandırır. Ortak varsayılanları uygulamak ve sitenin sayfalarını blockstudio_page_tree( 'my-site' ) ile listelemek için bunu sitenin sayfa ağacının kökünde kullanın.
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
Site koleksiyonundaki sayfalar, bildirim olmadan sahip oldukları kimliği aynen korur. Bu nedenle mevcut bir ağaca sayfa eklemek hiçbir gönderi satırını güncellemez ve hiçbir şey oluşturmaz ya da çöpe taşımaz:
- Anahtarlar genel kapsamda kalır:
Pages::get_page( 'home' )ile saklanan sayfa anahtarları eşleşmeye devam eder. - URL’ler WordPress sayfa URL’leri olarak kalır. Koleksiyon yeniden yazma kuralları, kalıcı bağlantı filtresi veya çift URL yönlendirmesi uygulanmaz ve boş kapsayıcı sayfalar oluşturulmaz.
- Mantıksal yollar, kısa adlar, üst öğeler ve kaynak kimlikleri bağımsız sayfalardakiyle aynıdır; düzenler en yakın üst öğeye göre çözülür.
- İç içe
pages.jsonbildirimleri kendi koleksiyonlarını korur ve alt ağaçları site koleksiyonunun dışında bırakılır. - Varsayılanlar sayfa başına uygulanır: varsayılan bir
renderyalnızca dizininde ilgili girdi bulunan sayfalara uygulanır; bu nedenle kısa kodlu ve Markdown sayfaları kendi kaynaklarını korur.
Koleksiyon Yükleyicileri
Koleksiyonlara güvenilir bir yerel loader.php eklenebilir. Koleksiyon sayfaları harici bir belge klasörü, paket veya oluşturulmuş bir bildirim dosyası gibi başka bir yerel kaynaktan geldiğinde bunu kullanın.
Yükleyici, açık sayfa keşfi ve eşitleme sırasında çalışır. Belirleyici ve yerel olmalıdır. loader.php üzerinden uzak içerik getirmekten kaçının; bu, dağıtım eşitlemesini o hizmete bağımlı hâle getirir.
<?php
return array(
'meta' => array(
'source' => 'loader',
),
'paths' => array(
__DIR__ . '/external-docs',
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
'pages' => array(
array(
'name' => 'docs-api',
'title' => 'API',
'path' => 'api',
'content' => "# API\n\nGenerated markdown content.",
'contentType' => 'markdown',
),
array(
'name' => 'docs-template',
'title' => 'Template',
'path' => 'template',
'file' => __DIR__ . '/template.md',
),
),
);
Yükleyici, pages, meta ve paths anahtarlarını içeren bir dizi döndürebilir:
| Anahtar | Açıklama |
|---|---|
pages |
Sayfa dizilerinin listesi. Her sayfa, page.json ve Markdown ön bilgisinde tanınan anahtarların aynısını destekler. |
meta |
Yükleyicinin oluşturduğu her sayfanın meta dizisiyle birleştirilen meta veriler. |
paths |
Bu koleksiyonun parçası olarak keşfedilecek ek yerel dizinler. Girdiler metin dizeleri veya yol nesneleri olabilir. |
render |
render tanımı; paths içinden keşfedilen her Markdown sayfasına uygulanır. |
Kısayol olarak yükleyici, doğrudan sayfa dizilerinden oluşan bir liste döndürebilir.
Yükleyici sayfa girdileri şu şekillerde içerik sağlayabilir:
| Biçim | Açıklama |
|---|---|
markdown |
Satır içi Markdown içeriği. |
html |
Satır içi HTML içeriği. |
content + contentType |
Genel satır içi içerik. contentType, markdown veya html olarak çözümlenmelidir. |
file |
Yerel dosya kaynağı. contentType ayarlanmadıkça tür, dosya uzantısından çıkarılır. |
template |
file için takma ad. |
Yükleyici dosya başvuruları PHP, Blade, Twig, Markdown veya HTML kaynaklarını gösterebilir. Göreli yollar koleksiyon köküne göre çözümlenir. Mutlak yollara ve koleksiyon kökünün dışındaki yollara yalnızca blockstudio/pages/allow_external_loader_path filtresi izin veriyorsa izin verilir.
Yükleyici sayfaları varsayılan olarak generated: true değerini alır. Oluşturulan bir yükleyici sayfası yükleyici çıktısından kaybolduğunda, Blockstudio sonraki eşitlemede eşitlenmiş yazıyı sahipsiz kabul eder ve blockstudio/pages/orphan_action filtresine göre temizler.
paths içinde listelenen dizinler, normal koleksiyon klasörleri gibi keşfedilir. Markdown dosyaları veya page.json klasörleri içerebilirler. Bu yollar koleksiyon kökünün dışındaysa aynı harici yol filtresi uygulanır.
Harici dizinin kendi mantıksal yollarını koruması gerekiyorsa dize girdisi kullanın. Dizini bir koleksiyon yolu önekinin altına bağlamak için nesne girdisi kullanın:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
Bu yapılandırmayla koleksiyonda cli-docs/index.md, path: "cli" olur ve cli-docs/getting-started.md, path: "cli/getting-started" olur. Önekler, oluşturulan sayfa adlarının çakışmasını da önler; böylece bağlanan birden fazla dizinin her biri index.md veya getting-started.md içerebilir. page.json veya Markdown ön verilerindeki açık name değerlerinin korunması gerekiyorsa yol nesnesinde preserveNames değerini true olarak ayarlayın.
Yol nesnesi özellikleri:
| Özellik | Tür | Açıklama |
|---|---|---|
path |
string |
Keşfedilecek yerel dizin. Göreli yollar koleksiyon köküne göre çözümlenir. |
prefix |
string |
Koleksiyon içindeki isteğe bağlı mantıksal yol öneki. |
preserveNames |
boolean |
Önekli yoldan ad üretmek yerine açıkça belirtilen sayfa adlarını korur. prefix ayarlandığında varsayılanı false olur. |
meta |
object |
Bu yoldan keşfedilen her sayfayla birleştirilen meta veriler. Yinelenen anahtarlarda sayfa düzeyindeki meta veriler önceliklidir. |
render |
string|object |
Bu yolun Markdown sayfaları için render tanımı; yükleyicinin render değerini geçersiz kılar. |
Markdown bileşen üzerinden render etme
render kullanıldığında, yükleyicinin keşfettiği Markdown sayfaları blok olarak saklanmak yerine bir sayfa render işleyicisi üzerinden render edilir:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Bunlar Markdown sayfaları olarak kalır: içerik türü, içerik yolu, .md yanıtları ve ön bilgi değişmez. Eşitleme, ayrıştırılmış bloklar yerine, iç HTML içeriği dönüştürülmüş Markdown olan tek bir blockstudio/page bloğu saklar; koleksiyon içeriği temizliyorsa bu içerik de temizlenir. Böylece post_content belge metnini korur. Render işleyicisi bu HTML değerini yuva olarak alır ve kaynağı page.content_path üzerinden okuyabilir. Göreli yollar koleksiyon köküne göre çözümlenir; yollar için olduğu gibi harici yol filtresi uygulanır. Ön bilgisi kendi render değerini ayarlayan veya render: false belirten sayfa kapsam dışında bırakılır.
Düzenler
Bir layout.php dosyası, dosya tabanlı bir sayfanın ön yüz oluşturma işlemini sarar. Eşitlenmiş post_content öğesinin WordPress içinde saklanan hâlinin yerini almaz ve düzenleyici tuvalini sarmaz. Düzen yalnızca tekil ön yüz isteklerinde çalışır.
Koleksiyonlarda, o koleksiyondaki her ön yüz sayfasını sarmak için layout.php öğesini pages.json yanına koyun:
<?php $current = blockstudio_current_page(); ?>
<main class="docs-layout">
<aside>
<?php foreach (blockstudio_page_tree('docs') as $item) : ?>
<?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
<a
href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
<?php echo $is_current ? 'aria-current="page"' : ''; ?>
>
<?php echo esc_html($item['title']); ?>
</a>
<?php endforeach; ?>
</aside>
<article>
<?php echo blockstudio_page_content(); ?>
</article>
</main>
blockstudio_page_content(), WordPress öğesinin normalde the_content üzerinden oluşturacağı sayfa gövdesini yazdırır. Bir düzen blockstudio_page_content() çıktısını üretmezse sayfa içeriği kasıtlı olarak gizlenir.
Düzenlerde sayfa yardımcı işlevleri kullanılabilir:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
Koleksiyona ait olmayan iç içe sayfalar, pages ağacındaki en yakın üst öğe layout.php öğesini de devralabilir. Koleksiyon sayfalarında koleksiyon kök düzeni her eşitlenmiş yazıda saklanır ve sayfa parmak izinin bir parçası olarak izlenir; böylece düzen değişiklikleri bir sonraki eşitlemede algılanır.
Render İşleyicisi Düzenleri
Bir düzen, örneğin layouts: ["layout.tsx"] kaydeden bir render işleyicisi için layout.tsx gibi bir render işleyicisi girdisi de olabilir. layout.php ile aynı yerlerde bulunur; yanındaki isteğe bağlı layout.data.php ise veri yükleyicisidir. Render sırasında işleyici, kind: "layout" değerini ve render edilmiş sayfa içeriğini slot olarak, layout.php ile aynı the_content önceliğinde alır. Bir dizinde layout.php veya tek bir render işleyicisi düzeni bulunabilir, ikisi birden bulunamaz; ikisinin de bulunması keşif hatasına yol açar. Düzen başarısız olursa blockstudio/pages/layout_error tetiklenir ve sayfa içeriği, layout.php durumunda olduğu gibi, bir sarmalayıcı olmadan bırakılır.
Blok Düzenleme Modu
blockEditingMode özelliği, blokların düzenleyicide nasıl düzenlenebileceğini belirler. Sayfa düzeyinde varsayılanı page.json içinde ayarlayın ve şablonda öğe başına geçersiz kılın:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| Değer | Açıklama |
|---|---|
"default" |
Tam düzenleme. Bloklar seçilebilir, taşınabilir ve düzenlenebilir |
"contentOnly" |
Yalnızca metin düzenleme. Blok metni düzenlenebilir; ayarlar ve yapı kilitlidir |
"disabled" |
Düzenleme yok. Bloklar tamamen etkileşimsizdir |
Öğe başına geçersiz kılmalar, herhangi bir öğede (<h1>, <p>, <div> vb.) veya <block> öğelerinde HTML öznitelikleri olarak ayarlanır. Geçersiz kılınan öğelerin üst kapsayıcı blokları, alt öğelerine erişilebilmesi için otomatik olarak contentOnly değerine ayarlanır. Bu yayılım, geçersiz kılınan öğeden sayfa köküne kadar ilerler; bu nedenle yalnızca düzenlenebilir yapmak istediğiniz öğelerde blockEditingMode ayarlamanız yeterlidir.
Şablon Kilidi
templateLock özelliği, kullanıcıların sayfayı düzenleyicide nasıl düzenleyebileceğini belirler:
| Değer | Ekleme/Kaldırma | Taşıma | İçeriği Düzenleme |
|---|---|---|---|
"all" |
Hayır | Hayır | Hayır |
"insert" |
Hayır | Evet | Evet |
"contentOnly" |
Hayır | Hayır | Evet |
false |
Evet | Evet | Evet |
templateLock ayarlandığında Blockstudio, düzenleyici UI aracılığıyla blokların kilidini açma olanağını devre dışı bırakır.
Sanal Rotalar
Bazı belgelerin arkasında bir yazı yoktur: verilerden oluşturulmuş bir bileşen başvurusu, katalog veya hesap alanı. template_redirect kancasını kendiniz kullanmak yerine bunları sanal rotalar olarak kaydedin:
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );
Yol, site ana dizinine göredir. prefix ile rota altındaki tüm yolları da sunar ve match bu kalan yolu (rotanın kendisi için boş dize) alır ve oluşturma geri çağrısının alacağı değeri ya da null değerini döndürür; böylece URL öğesi WordPress öğesine bırakılır ve bu da her zamanki gibi 404 yanıt verir. Oluşturma geri çağrısı belgeyi ekrana yazdırır veya dize olarak döndürür; title bir dize ya da eşleşme değerini alan bir kapatmadır.
Eşleşen bir istekte Blockstudio, WordPress öğesinin bir 404 olarak işaretlemesini, redirect_canonical öğesinin de yönlendirmesini önler; ana sorgunun bildirdiği tekil durumu temizler, durum kodunu gönderir (varsayılan olarak status, 200) ve template_redirect öncelik Virtual_Routes::PRIORITY ile oluşturur. Bu, Blockstudio çıktı arabelleğinin Assets::BUFFER_PRIORITY noktasında açılmasından hemen sonradır; böylece tamamlanan belge, herhangi bir sayfa gibi blok varlıklarını, paketlenmiş UI varlıklarını ve derlenmiş Tailwind öğesini alır ve öncelik 10’daki redirect_canonical öncesinde oluşturulur. Belgenin tamamını kendi oluşturan bir işleyici, bu işlemenin atlanmaması için Assets::BUFFER_PRIORITY sonrasında da çalışmalıdır. urls içindeki yollar (varsayılan olarak önek rotası değilse rotanın kendi yolu), statik ön oluşturma derlemelerine eklenir ve Virtual_Routes::urls() bunları site haritası için mutlak URL’ler olarak döndürür.
Virtual_Routes::match( $path ), bir yolu istek gibi çözümler.
Eşitleme Davranışı
Sayfa yazıları yalnızca açık bir eşitleme işlemiyle değişir:
wp bs pages sync
Komut, kaynak envanterinin tamamını keşfeder, değişen yazıları oluşturur veya günceller, doğrulanmış yetim kayıtları temizler, koleksiyon yönlendirmesini ve derlenmiş templateFor yapılandırmasını yeniler ve değişiklikleri bildirir. Anahtarlı düzenleyici içeriğini korumak yerine yönetilen içeriği değiştirmek için --authoritative ekleyin; kayıtlı kaynak kimliğinden bağımsız olarak işlemin tam uzlaştırma olduğunu bildirmek için --full ekleyin:
wp bs pages sync --authoritative --full
Normal ön yüz, yönetici, AJAX, REST, cron ve genel WP-CLI başlangıç istekleri tam sayfa keşfi yapmaz, yönetilen uzlaştırma envanterini sorgulamaz veya sayfa yazılarını kaydetmez. Son açık işlemde kalıcılaştırılmış, önceden eşitlenmiş WordPress yazılarını ve kompakt koleksiyon ile yazı türü şablon yapılandırmasını kullanırlar. İlk kurulum veya yükseltme, yönlendirme meta verilerini geri yüklemek için koleksiyon bildirim dosyalarını bir kez tarayabilir; bu salt okunur başlangıç içerikleri eşitlemez. Kimliği doğrulanmış, isteğe bağlı Canvas yenileme uç noktası açık bir içerik oluşturma API işlemidir: Canvas, yeni eklenen veya değişen kaynakların başlangıç envanterinde görünmesi için çalışma alanı açıldığında bu uç noktayı bir kez çağırır. Canlı mod, bir sayfa kaynağı değişikliği algıladığında aynı sınırı çağırır.
Blockstudio\Pages::init() artık yalnızca istek zamanı kancalarını kaydeder. Bu yönteme daha önce force bağımsız değişkeni veren entegrasyonlar bunun yerine Blockstudio\Pages::reconcile() çağırmalı veya wp bs pages sync çalıştırmalıdır.
Elle düzenlendikten sonra bir sayfanın üzerine yazılmasını önlemek için page.json içinde "sync": false ayarlayın.
Taşınabilir Kaynak Konumları
Eşitlenen tema dosyaları, mutlak kurulum yolları yerine temaya göreli konumlarda saklanır. Alt tema ve üst tema dosyaları, göreli dosya adları aynı olsa bile ayrı kimliklerini korur. Sayfa yardımcıları, geçerli istek için çözümlenmiş mutlak template_path, content_path, layout_path ve directory değerlerini döndürmeye devam eder.
Bu, CLI senkronizasyonunun ve web isteklerinin, hapsedilmiş barındırma ortamlarında olduğu gibi, farklı dosya sistemi kökleri kullanmasını sağlar; Markdown yanıtlarını, düzenleri, düzenleyici Tailwind taramasını veya önceden oluşturulmuş kaynak takibini bozmaz. Tema dizininin adı değişmediğinde mevcut mutlak tema yolları okuma sırasında yeniden eşleştirilir. Bunları okumak için senkronizasyon, veritabanı geçişi veya istek sırasında meta veri yazımı gerekmez; bir sonraki açık senkronizasyon taşınabilir konumları kaydeder.
Örneğin bir geliştirme çalışma kopyasına giden sembolik bağlantı olan tema dizini, kaynak sembolik bağlantı üzerinden ya da hedefi üzerinden okunmuş olsun, aynı theme: konumlarını kaydeder ve bunları yapılandırılmış tema dizinine çözümler.
Etkin alt ve üst temaların dışındaki dosyalar, PHP’ın open_basedir kısıtlamalarına tabi olarak yapılandırılmış mutlak yollarında desteklenmeye devam eder. Bu dosyalar otomatik olarak taşınabilir değildir: harici bir kaynağı taşıdıktan sonra yapılandırılmış yolunu güncelleyin ve açık bir senkronizasyon çalıştırın.
Yazı Alanlarının Sahipliği
postStatus başlangıç durumunu belirler. Sonraki senkronizasyonlar, --authoritative kullanıldığında da mevcut taslak, beklemede, özel, yayımlanmış ve zamanlanmış durumları korur. Dosyasında postStatus: "publish" yazıyor diye taslak yeniden yayımlanmaz. Mevcut yetim kurtarma davranışı değişmez: kaynak mevcutsa açık bir senkronizasyon, çöpe atılmış yönetilen bir yazıyı geri yükler. Bu geri yüklemeyi önlemek için sayfayı kilitleyin veya senkronizasyonu devre dışı bırakın.
Başlık, kısa ad, yazı türü, üst öğe ve yapılandırılmış menü sırası dosyanın kontrolünde olmaya devam eder. Bunları WordPress içinde düzenlemek kaynak tanımını değiştirmez. Bir sonraki açık senkronizasyon dosyadaki değerleri yeniden uygular ve etkilenen alanları pages.<name>.overwritten içinde listeler; CLI tablo çıktısında da bir uyarı gösterilir. Senkronizasyonu yapan kullanıcı yazıları yayımlayamıyorsa beklemedeki yazılar için boş kısa ad kullanılması da dahil, WordPress’ın yerleşik izinleri geçerliliğini korur.
Farklı bir durum politikasına açıkça sahip olan bir entegrasyon için blockstudio/pages/update_post_data kullanın. Anahtarlı bloklar, düzenleyicinin sahip olduğu blok içeriğini korur; anahtarlar yazı başlığının veya kısa adının sahipliğini değiştirmez.
Koleksiyon sayfalarında parmak izleri bildirim dosyasını, yükleyiciyi, sayfa kaynağını, düzen dosyasını, meta verileri ve ilgili kaynak yollarını kapsar. Sonraki açık eşitleme, bu girdilerdeki değişiklikleri uygular.
Bir koleksiyon kaynağı kaldırıldığında Blockstudio, kaynak dosyası silindikten sonra eski koleksiyon sayfalarının kalmaması için oluşturulan sayfayı kaldırır. Varsayılan olarak sahipsiz koleksiyon sayfaları çöp kutusuna taşınır. trash, delete veya keep döndürmek için blockstudio/pages/orphan_action kullanın.
Ön yüz isteklerinde Blockstudio, sayfa kayıt defterini önceden eşitlenmiş ve yayımlanmış yazılardan oluşturur. Taslak ve özel sayfalar yönetici ve eşitleme bağlamlarında kullanılabilir; ancak ön yüz yardımcıları yalnızca yayımlanmış sayfaları kaydeder.
Dağıtım Uzlaştırması
Blockstudio\Pages::reconcile(), PHP dağıtım giriş noktasıdır. İstenen envanterin tamamını keşfeder, kaynak ve eşitleme motoru parmak izlerini karşılaştırır ve makinece okunabilir bir rapor döndürür:
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
'renames' => [
[
'from' => 'pages/old/index.php',
'to' => 'pages/new/index.php',
],
],
]);
Rapor; discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, sayfa başına sonuçları, keşif hatalarını ve deterministik bir sourceIdentity içerir.
Kilitli sayfalarda status: "locked" bulunur ve bu sayfalar değişmemiş sayfalardan ayrı sayılır. removedPages, kaldırılan her sayfanın name, key, postId ve gerçek action değerini (trash veya delete) listeler; tutulan ya da zaten çöpe atılmış yazılar yeni kaldırılanlar arasında sayılmaz. CLI tablo çıktısında da oluşturulan, güncellenen, kilitlenen, kaldırılan ve içeriği korunan sayfalar yazı kimlikleriyle listelenir.
Ayrıştırma ve anahtarlı birleştirmeden sonra, nihai yazı aynıysa wp_update_post() çağrılmaz, post_modified değiştirilmez, bir revizyon oluşturulmaz ve yazı güncelleme kancaları tetiklenmez. Sonuç unchanged olur. Kaynağın içeriği düzenleyicinin sahip olduğu anahtarlı içerikten farklıysa, bu kararı preserved: true belirtir ve üst düzey preserved sayısına dahil edilir. Bir sonraki değişmemiş senkronizasyonun işlem yapmaması için yeni kaynak parmak izi ve yönetilen meta veriler yine de kaydedilir. preserved özel bir durum değil, ek bir bayraktır: Bir sayfa, anahtarlı içeriği korurken dosyanın kontrolündeki başlığı güncelleyebilir veya başka bir blok ekleyebilir.
authoritative: true, Sayfa Eşitleme kilidini kaldırabilir ve anahtarlı düzenleyici içeriğini korumak yerine dosya tanımındaki içerikle değiştirir. Normal açık eşitleme için false değerinde bırakın. plan_valid: false, full: true, broad: true, önceki kaynak kimliğinin eksik olması veya eşitleme motoru parmak izinin değişmesi, işlemi tam uzlaştırma olarak işaretler (raporda fullReconciliation). Her işlem, her iki durumda da envanterin tamamını karşılaştırır. Git yeniden adlandırma kayıtları yalnızca kimlik ipuçlarıdır. Envanterin tamamının karşılaştırılmasının yerini asla almazlar.
Değişmemiş çalışma zamanı yollarına sahip eşleşen parmak izleri, yazı veya postmeta verisi yazmaz ve güncelleme kancalarını tetiklemez. Değişmemiş bir kaynak yeni bir sürüm dizinine taşındığında uzlaştırma yalnızca kalıcılaştırılmış şablon, içerik, düzen ve dizin yollarını yeniler; post_content öğesini veya yazının değiştirilme zaman damgasını güncellemez. Yönetilen eksik sayfalar, yalnızca keşif veya sayfa yazma hatası olmadan tam uzlaştırma işlemi tamamlandıktan sonra temizlenir.
Doğrudan API uzlaştırması dağıtımın başarılı olduğunu işaretlemez. Eşleşen statik yapıyı ve rotaları etkinleştirip doğruladıktan sonra döndürülen kimliği açıkça kalıcılaştırın:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync, başarılı bir işlemden sonra döndürülen kimliği kaydeder. Olağan WP-CLI başlangıç işlemi yalnızca kalıcılaştırılmış koleksiyon yazı türlerini ve yeniden yazma kurallarını kaydeder. Sayfaları keşfetmez veya eşitlemez.
Yazı Kimliğini Sabitleme
Varsayılan olarak WordPress yazı kimliklerini otomatik atar. Bir sayfa silinip yeniden oluşturulursa kimliği değişir ve menüler veya sabit kodlanmış bağlantılar gibi harici başvurular bozulur.
Bir sayfayı belirli bir kimliğe sabitlemek için postId kullanın:
{
"name": "about",
"title": "About Us",
"postId": 42
}
Sayfa oluşturulurken Blockstudio, kimliği import_id aracılığıyla WordPress öğesine iletir. Kimlik kullanılabilir durumdaysa WordPress bunu aynen kullanır. Kimlik ilgisiz başka bir yazı tarafından zaten kullanılıyorsa WordPress sessizce yeni bir kimlik atar.
Mevcut sayfalar aranırken Blockstudio, meta verileri veya kısa adı denetlemeden önce sabitlenmiş kimliği kontrol eder. Böylece bir sayfa silinip yeniden eşitlendiğinde aynı kimliği yeniden alır.
Anahtarlı Blokları Birleştirme
Varsayılan olarak, bir şablon dosyası değiştiğinde Blockstudio yazı içeriğinin tamamını yeni şablonla değiştirir. Böylece WordPress düzenleyicisinde yapılan tüm değişiklikler kaybolur.
Şablon eşitlemeleri sırasında kullanıcı düzenlemelerini korumak için bloklara key özniteliği ekleyin. Bir şablonda anahtarlı bloklar olduğunda Blockstudio, mevcut yazı içeriğini değiştirmek yerine şablon değişikliklerini bu içerikle birleştirir.
Anahtar Ekleme
Herhangi bir HTML öğesinde veya <block> öğesinde key özniteliğini kullanın:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
Anahtarlar tüm şabloda benzersiz olmalıdır. Bir anahtar, bloğun tamamını ve tüm içeriğini korur. Anahtarlı bir üst öğenin içindeki alt öğelere ayrıca anahtar vermeniz gerekmez. Anahtarlı bloklar şablon güncellemeleri arasında herhangi bir konuma veya iç içe geçme düzeyine taşınabilir; kullanıcı içerikleri yine korunur.
Anahtarlar Blockstudio özel bloklarında da aynı şekilde çalışır. key yapısal Sayfa Eşitleme meta verisidir; özel alan değerleri normal Blockstudio öznitelikleri olarak kalır. Düzenleyici bu alanları değiştirdiğinde, sonraki şablon eşitlemesi düzenleyici değerlerini korurken bağımsız şablon değişikliklerini de uygular. Anahtarın özel alan verisinin içinde bulunduğu eski sürümlerle oluşturulmuş sayfalar, sonraki eşitlemede otomatik olarak taşınır.
Birleştirme Nasıl Çalışır
Şablon dosyası değişip sayfa yeniden eşitlendiğinde:
| Blok | Davranış |
|---|---|
| Anahtarlı blok | Kullanıcı içeriği ve Blockstudio alan değerleri korunur. Şablonun sahip olduğu öznitelikler ve yapı uygulanır. |
| Anahtarsız blok | Tamamen şablon sürümüyle değiştirilir (anahtar yokmuş gibi) |
Örnekler
Kullanıcı düzenlemeleri anahtarlı bloklarda korunur:
- Şablon
<p key="intro">Default intro.</p>tanımlar - Kullanıcı, düzenleyicide paragrafı "Özel giriş metni." olarak değiştirir
- Geliştirici şablonu günceller, yeni bir blok ekler ve düzeni değiştirir
- Eşitlemede paragraf "Özel giriş metni." olarak kalırken yeni düzen uygulanır
Şablondaki öznitelikler uygulanmaya devam eder:
- Şablonda
key="hero"veurlözniteliği bulunan bir kapak bloğu vardır - Geliştirici kapağın
urlözniteliğini yeni bir arka plan görüntüsüyle değiştirir - Eşitlemede yeni arka plan görüntüsü uygulanır, ancak kullanıcının kapak içindeki içerik düzenlemeleri korunur
Uç Durumlar
| Senaryo | Davranış |
|---|---|
| Şablona yeni anahtarlı blok eklenmesi | Şablondaki varsayılan içeriğiyle görünür |
| Anahtarlı bloğun şablondan kaldırılması | Yazıdan silinir |
| Blok türünün değişmesi (aynı anahtar) | Şablon tümüyle uygulanır, içerik birleştirilmez |
| Yinelenen anahtarlar | İkinci oluşum anahtarsız kabul edilir |
| Şablonda anahtar olmaması | Tam değiştirme (anahtar yokmuş gibi) |
| Zorunlu eşitleme | Tam değiştirme; anahtarlar yok sayılır |
| Kilitli yazı | Hiç eşitleme yapılmaz |
Düzenleme Denetimleriyle Birleştirme
Anahtarlar, templateLock ve blockEditingMode birlikte kullanıldığında, müşterilerin neler yapıp yapamayacağını ayrıntılı biçimde denetleyebilirsiniz. Yaygın iş akışı kalıpları şunlardır.
Tamamen kilitli sayfa
Geliştirici her şeyi kontrol eder. Sayfa, müşterilerin hiçbir şekilde değiştiremeyeceği statik bir düzendir. Yasal sayfalar, hizmet koşulları veya yalnızca kod aracılığıyla değiştirilmesi gereken sayfalar için kullanışlıdır.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
Anahtar gerekmez. Tek doğruluk kaynağı şablondur. Her eşitleme sayfanın tamamının üzerine yazar.
Düzeni kilitli, içeriği düzenlenebilir
En yaygın kalıp. Müşterilerin blok ekleyememesi, kaldıramaması veya yeniden sıralayamaması için sayfa yapısını kilitleyin; ancak belirli yerlerdeki metni düzenlemelerine izin verin. Anahtarlar, şablon güncellemelerinde yaptıkları değişikliklerin korunmasını sağlar.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
İstemci kahraman başlığını, açıklamayı ve özellik girişini düzenleyebilir. Başka hiçbir şeyi düzenleyemez. Düğme metni, URL ve kapak arka plan görseli geliştirici tarafından kontrol edilir. Geliştirici şablonu güncellediğinde (e.g., ikinci bir düğme eklediğinde), anahtarlı bölümler istemcinin metnini korur.
İçeriği koruyarak gelişen şablon
Zamanla büyüyen sayfalar için. Geliştirici şablona yeni bölümler ekler ve her eşitleme, istemcinin özelleştirdiği içeriğe dokunmadan yeni içeriği ekler.
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
Yeni referanslar bölümü ve düğme eşitleme sırasında görünür. İstemcinin başlık, giriş ve hizmetlerde yaptığı düzenlemelere dokunulmaz.
Tek seferlik iskelet
Başlangıç yapısına sahip bir sayfa oluşturun, ardından sayfanın tüm kontrolünü devredin. sync değerini false olarak ayarlayın; böylece normal eşitleme sayfayı hiçbir zaman oluşturmaz veya güncellemez ve sayfayı bir kez Blockstudio\Pages::force_sync('blog') ile oluşturun. Bundan sonra sayfanın tüm kontrolü istemcidedir.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
wp bs pages sync bu sayfayı atlar; bu nedenle force_sync() sayfayı bir kez oluşturur. Bundan sonra istemci blokları serbestçe ekleyebilir, kaldırabilir ve yeniden sıralayabilir. Şablon değişiklikleri yok sayılır.
Blok Bağlamaları
Anahtarlı birleştirmeye alternatif olarak, blokları yazı meta verilerine bağlamak için WordPress çekirdeğinin Blok Bağlamaları API özelliğini kullanın. Bu bir Blockstudio özelliği değildir; yerel bir WordPress API özelliğidir. Blockstudio, metadata özniteliğini oluşturulan blok işaretlemesine aktarmaktan ibarettir. İçerik blok işaretlemesi yerine yazı meta verilerinde tutulur; böylece düzenleyici innerHTML yerine meta verilerini okuduğundan şablon eşitlemeleri işaretlemeyi serbestçe üzerine yazabilir.
metadata özniteliğini herhangi bir HTML öğesine veya <block> öğesine ekleyin:
<h1
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
Default Title
</h1>
<p
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
Default description text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
Meta anahtarları show_in_rest etkinleştirilerek kaydedilmelidir:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
Anahtarlar ve bağlamalar
| Özellik | Anahtarlar | Bağlamalar |
|---|---|---|
| İçeriğin saklandığı yer | Blok işaretlemesi (post_content) |
Yazı meta verileri (wp_postmeta) |
| Şablon eşitlemesinden etkilenmez | Evet (anahtara göre birleştirilir) | Evet (veriler meta verilerde tutulur) |
WP_Query üzerinden sorgulanabilir |
Hayır | Evet (meta_query) |
| REST API içinde kullanılabilir | Hayır | Evet |
| Kayıt gerektirir | Hayır | Evet (register_post_meta) |
| Kullanıcı blokları taşıyabilir | Hayır (şablon yapıyı yeniden uygular) | Hayır (şablon yapıyı yeniden uygular) |
Her iki yaklaşım da aynı şablonda kullanılabilir. Blok yapısının önemli olduğu bölümlerde (e.g., birden fazla alt öğesi olan bir grupta) anahtarları kullanın. Verilerin blok düzenleyicisinin dışında da erişilebilir olmasını istediğiniz tekil alanlarda ise bağlamaları kullanın.
Yazı Türü Şablonları
Bir sayfayı yazı türü için varsayılan şablon olarak ayarlamak üzere templateFor kullanın:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Bu türdeki tüm yeni yazılar tanımlanan blok yapısıyla başlar.
Özel Yollar
Varsayılan olarak Blockstudio, get_template_directory() . '/pages' dizinini tarar. Filtreyle ek yollar ekleyin:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
Birden çok kökten dosya oluşturan çalışma zamanı entegrasyonları, dosya sistemi taramasını mantıksal keşif kaynağı ile değiştirebilir. Sayfa manifestleri, düzenler, yükleyiciler ve kaynak şablonları, seçilen dosyaları farklı köklerde bulunsa bile mantıksal yola göre çözümlenir.
Filtreler ve Eylemler
Sayfa keşfi, eşitleme ve koleksiyon yönlendirme şu genişletme noktalarını sunar:
| Kanca | Tür | Açıklama |
|---|---|---|
blockstudio/pages/paths |
Filtre | Blockstudio aracının sayfa kaynaklarını taradığı dizinleri ekler. |
blockstudio/pages/collection_post_type_args |
Filtre | Bir koleksiyon CPT’si için register_post_type() bağımsız değişkenlerini düzenler. |
blockstudio/pages/template_candidates |
Filtre | Sayfa kaynağı için dikkate alınan şablon dosya adlarını düzenler. |
blockstudio/pages/serve_markdown |
Filtre | Ham Markdown yanıtlarını etkinleştirir veya devre dışı bırakır. |
blockstudio/pages/orphan_action |
Filtre | Yetim temizliği için trash, delete veya keep değerini döndürür. |
blockstudio/pages/docs_allowed_html |
Filtre | Oluşturulan Markdown belgeleri içeriği için izin verilen HTML değerlerini düzenler. |
blockstudio/pages/allow_external_loader_path |
Filtre | Yükleyici paths öğelerinin koleksiyon kökü dışına çıkmasına izin verir. |
blockstudio/pages/manifest_scan_interval |
Filtre | Yükseltme sırasında kalıcı çalışma zamanı yapılandırmasını başlatmak için kullanılabilecek, 7.6.2 öncesi eski bildirim önbelleğinin azami yaşını belirler. |
blockstudio/pages/create_post_data |
Filtre | Senkronize edilmiş bir sayfa oluşturulmadan önce yazı verilerini değiştirir. |
blockstudio/pages/update_post_data |
Filtre | Senkronize edilmiş bir sayfa güncellenmeden önce yazı verilerini değiştirir. |
blockstudio/pages/sync_engine_inputs |
Filtre | Uzlaştırmayı bir kez bilinçli olarak genişletmesi gereken bir ayrıştırıcı, eşleme veya geçiş sürümü ekler. |
blockstudio/pages/post_created |
Eylem | Senkronize edilmiş bir sayfa yazısı oluşturulduktan sonra çalışır. |
blockstudio/pages/post_updated |
Eylem | Senkronize edilmiş bir sayfa yazısı güncellendikten sonra çalışır. |
blockstudio/pages/synced |
Eylem | Sayfa kaydı eşitlemesi tamamlandıktan sonra çalışır. |
blockstudio/pages/reconciled |
Eylem | Makine tarafından okunabilir raporuyla birlikte açık bir uzlaştırma işleminden sonra çalışır. |
blockstudio/pages/renderers |
Eylem | Sayfa oluşturucularını Blockstudio\Page_Renderers::register() ile kaydeder. İstek başına bir kez çalışır. |
blockstudio/pages/rendered |
Eylem | Bir bileşen sayfası oluşturulduktan sonra; sayfa, HTML değeri ve bağımlılıklarıyla birlikte çalışır. |
blockstudio/pages/layout_error |
Eylem | Bir düzen oluşturulamadığında hata, düzen yolu ve sayfayla birlikte çalışır. |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
Bağımsız değişkenlerin anlamı, rapor alanları ve doğrulanmış kaynak kimliği sınırı için Dağıtım Uzlaştırması bölümüne bakın.
Şablonlar ve düzenler için genel yardımcı işlevler kullanılabilir:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() ve genel yardımcılar tarafından döndürülen sayfa dizileri; eşitlenen yazı kimliğini, kaynak ve şablon yollarını, koleksiyon/yol meta verilerini, içerik türünü, eşitleme ilkesini, yazı türü/durumunu, düzenleme ilkesini, özel meta verileri ve bir permalink anahtarını içerir. Koleksiyon meta verileri, son başarılı açık uzlaştırmadan yüklenir. Normal istekler bu çalışma zamanı verilerini, sayfa kaynak ağaçlarını okumadan kalıcı yapılandırma ve eşitlenen yazı meta verilerinden yeniden oluşturur. Pages sınıfı ayrı bir kalıcı bağlantı yöntemi sunmaz.
Dosya Tabanlı Sayfalar Oluşturma
Şablon kilitleme, blok düzenleme modları, anahtarlı birleştirme ve istemcilerin düzenleyebileceği alanları kontrol etme.