İçeriğe geç

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:

JSON
{
  "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:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "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.php tarafı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:

HTML
<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:

HTML
<!-- 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.

Markdown
---
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.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
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:

Kabuk
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:

PHP
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.

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "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:

HTML
<!-- 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.

PHP
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:

PHP
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.

Kod
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "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.

JSON
{
  "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.json bildirimleri 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 render yalnı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
<?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:

PHP
'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
<?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
<?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:

PHP
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:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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:

PHP
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:

Kabuk
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:

Kabuk
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:

PHP
$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:

PHP
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:

JSON
{
  "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:

HTML
<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:

  1. Şablon <p key="intro">Default intro.</p> tanımlar
  2. Kullanıcı, düzenleyicide paragrafı "Özel giriş metni." olarak değiştirir
  3. Geliştirici şablonu günceller, yeni bir blok ekler ve düzeni değiştirir
  4. Eşitlemede paragraf "Özel giriş metni." olarak kalırken yeni düzen uygulanır

Şablondaki öznitelikler uygulanmaya devam eder:

  1. Şablonda key="hero" ve url özniteliği bulunan bir kapak bloğu vardır
  2. Geliştirici kapağın url özniteliğini yeni bir arka plan görüntüsüyle değiştirir
  3. 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.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<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.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<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.

HTML
<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>
HTML
<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.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<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:

HTML
<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:

PHP
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:

JSON
{
  "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:

PHP
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

PHP
// 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:

PHP
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.