Blok şablonu uygulanmıyor mu? İşe veritabanından başlayın

Şablon dosyanız neredeyse kesinlikle yok sayılıyor, çünkü veritabanındaki bir kopya kazanıyor. Site Editor’da bir şablonu açıp Kaydet’e bastığınız anda WordPress bir wp_template kaydı yazar ve o andan itibaren tema klasörünüzdeki .html dosyası yerine bu kayıt sunulur — dolayısıyla sonrasında dosyada yaptığınız her düzenleme ön yüzde görünmez. Çözüm o kaydı temizlemektir ve hiyerarşiye, dosya adına ya da önbelleğe dokunmadan önce bakılacak ilk şey budur.

Veritabanı kopyasının var olduğunu doğrulayın

Görünüm → Editör → Şablonlar bölümüne gidin. WordPress’in veritabanından sunduğu her şablon listede işaretlidir — WordPress sürümünüze göre rozette “Özelleştirilmiş” yazar ya da şablon “Özelleştirilmiş” filtresi altında görünür. O rozet cevabın tamamıdır. Oradaysa dosyanız kullanılmıyor demektir.

Aynı şeyi komut satırından da kontrol edebilirsiniz; bu daha hızlıdır ve Site Editor sorun çıkarırken bile çalışır:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

Her satır bir veritabanı geçersiz kılmasıdır. post_name değeri şablon slug’ıyla eşleşir; yani single adlı bir satır templates/single.html dosyasını gölgeliyordur.

İnsanları yanıltan bir ayrıntı: bu kayıtlar temaya bir yol üzerinden değil, bir taksonomi terimi üzerinden bağlanır. Temanızın klasör adını değiştirirseniz kaydedilmiş şablonlar veritabanında kalır ama etkin temayla eşleşmeyi bırakır ve site birdenbire dosyalara geri döner. Bu, “dosyam yok sayılıyor” değil “özelleştirmelerim uçtu” gibi görünür — aynı mekanizma, ters belirti.

Kaydı temizleyin

Site Editor’da şablonun seçenekler menüsünü açın (yanındaki üç nokta) ve Özelleştirmeleri temizle seçeneğini seçin — bazı sürümlerde bunun adı Sıfırla’dır. Bu işlem veritabanı kaydını siler ve denetim diskteki dosyaya döner.

Menüde Özelleştirmeleri temizle ya da Sıfırla yerine Sil yazıyorsa, o şablon yalnızca veritabanında vardır ve arkasında bir dosya yoktur. Silmek şablonu tamamen kaldırır ve WordPress hiyerarşide bir alt basamağa düşer.

Yukarıdaki listeden bir kimlik kullanarak WP-CLI ile:

wp post delete 482 --force

Bedeli konusunda kendinize karşı dürüst olun: özelleştirmeleri temizlemek, o şablon için Site Editor’da kurduğunuz her şeyi kalıcı olarak siler ve geri alınamaz. Site Editor sürümünde gerçek bir emek varsa, önce blok işaretlemesini dışarı kopyalayın — şablonu editörde açın, kod görünümüne geçin ve sonucu .html dosyanıza yapıştırın. Böylece doğruluk kaynağı dosya olur ve hiçbir şey kaybolmaz.

WordPress bir şablonu nasıl seçer

Blok temalar klasik temalarla aynı hiyerarşi mantığını kullanır; tek fark, tema kökündeki .php dosyaları yerine templates/ içindeki .html dosyalarıdır. WordPress en özelden en genele doğru yürür ve var olan ilk dosyayı kullanır.

Görüntülenen	Bakılma sırası
Tek bir yazı	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
Bir sayfa	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
Bir kategori arşivi	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
Özel bir yazı türü	single-{post-type}.html → single.html → singular.html → index.html
404 sayfası	404.html → index.html

Bunu tamamen geçersiz kılan iki şey var. Birincisi, yukarıda anlatılan veritabanı kaydı. İkincisi, doğrudan bir yazıya ya da sayfaya atanmış bir şablon — yazı editörünü açın, kenar çubuğundaki Şablon panelini bulun ve orada özel bir şeyin seçili olup olmadığına bakın. Açık bir atama her seferinde hiyerarşiyi yener ve arayıp bakmadıkça görünmezdir.

Slug tabanlı şablonlar, içselleştirmeye değecek bir kırılganlığa sahiptir. page-about.html yalnızca sayfanın slug’ı about olduğu sürece eşleşir. Sayfayı about-us olarak yeniden adlandırın; şablon hiçbir uyarı ve hata vermeden uygulanmayı bırakır.

Şablon ile şablon parçası

Şablon bütün bir görünümü render eder ve hiyerarşi tarafından seçilir. Şablon parçası ise şablonların içine aldığı bir parçadır — üst bilgi, alt bilgi, kenar çubuğu. Parçalar parts/ içinde, şablonlar templates/ içinde durur ve veritabanında ayrı ayrı wp_template_part kayıtları olarak saklanır.

Sık görülen karışıklık şudur: üst bilgiyi düzenlersiniz ve değişiklik hiç dokunmak istemediğiniz sayfalarda belirir. Bu doğru davranıştır. Tek bir parça, onu içeren her şablon tarafından paylaşılır. Bir şablonda farklı bir üst bilgi istiyorsanız ikinci bir parça dosyasına ve onu referans alan bir şablona ihtiyacınız var — paylaşılan parçayı düzenlemek size asla şablon başına farklılık vermez.

Tersi de olur. parts/ içine tam bir sayfa yerleşimi koyarsınız ve hiyerarşinin onu neden hiç seçmediğine şaşarsınız. Parçalar hiyerarşide aday bile değildir; hiçbir istek doğrudan onlara yönlendirilmez.

Dosya adı ve konumu

Daha egzotik bir şey varsaymadan önce şunları kontrol edin:

• Klasörün adı tema kökünde, çoğul olarak templates/ şeklindedir. template/ değil, block-templates/ değil. block-templates/, blok temalar çekirdeğe girmeden önceki Gutenberg eklentisi döneminde doğru addı ve pek çok eğitim içeriği hâlâ onu gösteriyor — güncel WordPress’te çalışmaz.
• Şablon parçaları parts/ içine girer, template-parts/ içine değil (bu ikincisi PHP parçaları için klasik tema geleneğidir).
• Uzantı .html olmalıdır. templates/ içindeki bir .php dosyası yok sayılır.
• Dosya adları küçük harflidir ve tire kullanır. single-Post.html ya da single_post.html eşleşmez. macOS gibi büyük-küçük harf duyarsız bir dosya sisteminde bu yerelde çalışır ve Linux sunucuda bozulur — klasik “benim makinemde çalışıyordu” arızası.
• templates/index.html mutlaka var olmalıdır. Olmazsa WordPress temayı blok tema olarak sınıflandırmaz ve Site Editor hiç görünmeyebilir.
• Bir alt temada çalışıyorsanız onun şablonları ana temanınkilere göre önceliklidir. Alt temada unutulmuş bir dosya, düzenlediğiniz ana tema dosyasını sessizce yener.

Yazı editöründe seçilebilir olması gereken özel şablonların ayrıca theme.json içinde customTemplates altında; dosyanın temel adı, okunabilir bir başlık ve geçerli olduğu yazı türleriyle birlikte bildirilmesi gerekir. Bu girdi olmadan dosya vardır ama Şablon panelinde hiç görünmez.

Önbellek — en son buna bakın

Önbellekleme gerçek bir sorundur ama en düşük olasılıktır; ilk ona sarılmak insanların bir öğleden sonrayı kaybetme biçimidir.

Sayfa önbelleğinizi temizleyin ve Redis ya da Memcached gibi kalıcı bir nesne önbelleği çalıştırıyorsanız onu da boşaltın — şablon çözümleme sonuçları orada tutulabilir. Ardından tarayıcı önbelleğini atlayarak sayfayı yeniden yükleyin.

İşe yaramayacak olan şey: OPcache temizlemek. Blok şablonları .html dosyalarıdır ve hiçbir zaman PHP tarafından derlenmezler, dolayısıyla OPcache’in bunlarla hiçbir ilgisi yoktur. OPcache’i boşaltmak bir keresinde bu sorunu çözmüş gibi göründüyse, aynı anda başka bir şey daha değişmiştir.

Hâlâ takıldınız mı?

Veritabanı kaydı yoksa, dosya adı doğruysa, yazıya açık bir şablon ataması yapılmamışsa ve önbellekler zaten temizlenmişse, eklentilere bakın. Şablon çözümlemesini filtreleyen her şey — bir sayfa oluşturucu, bir üyelik eklentisi, çok dilli bir eklenti, bir LMS — isteğin geç bir anında kendi şablonunu koyabilir. Varsayılan bir blok temaya geçin ve eklentiler devre dışıyken test edin, sonra tek tek yeniden etkinleştirin.

Şablon uygulanıyor ama boş render ediliyorsa, bu başka bir sorundur: dosyadaki blok işaretlemesinin geçerli olduğundan emin olun; bozuk bir blok yorumu, hata fırlatmak yerine editörün içeriği sessizce silmesine yol açabilir.