Gutenberg Blok Geçersiz Kılma: İçeriği Bozmadan Güncelleme

Özet

Bir Gutenberg bloğunu güncellemek genellikle eski sürümü kullanan mevcut yayınları bozar. Bu makale, block.json içindeki deprecated özelliğini kullanarak geriye dönük uyumluluğu nasıl sağlayacağınızı gösterir. Mevcut blok işaretlemesini yakalama, bir veya daha fazla geçersiz kılınmış sürüm tanımlama ve öznitelikleri doğru şekilde eşleme adımlarını öğreneceksiniz. Hem statik hem de dinamik blokları pratik örneklerle ele alacağız. Makale ayrıca, geçersiz kılmanın her zaman en iyi yaklaşım olduğu varsayımına karşı çıkar ve temiz bir kopuşun ne zaman daha iyi olabileceğini tartışır. Sonunda, kullanıcılarınızın içeriğini bozmadan bloklarınızı güvenle güncelleyebileceksiniz.

Kırıcı Değişiklik Senaryosu

Altı ay önce özel bir referans bloğu yayınladınız. Basit bir <div> içinde bir alıntı ve yazar adı çıktısı veriyor. Şimdi müşteriniz yeni bir tasarım istiyor: yazar, alıntının üstünde ve farklı bir CSS sınıfıyla görünmeli. Bloğun save fonksiyonunu ve render_callback'ini güncelliyorsunuz. Yeni bir yayında test ediyorsunuz—harika görünüyor. Ardından bloğu kullanan eski bir yayına gidiyorsunuz. Felaket: alıntı metni kaybolmuş, yazar yanlış yerde ve stil bozuk. Bloğu kullanan her sayfayı bozdunuz.

Bu, Gutenberg blok geliştirmede klasik "kırıcı değişiklik" sorunudur. Bloklar aslında işaretleme ile birleştirilmiş veri yapılarıdır. İşaretlemeyi değiştirdiğinizde, düzenleyici eski içeriği yeni yapıya otomatik olarak eşleyemez. Sonuç, bir doğrulama hatası (blok geçersiz hale gelir) veya daha kötüsü—bloğun yanlış işlenmesiyle sessiz bozulmadır.

Blok Geçersiz Kılma Nedir?

Blok geçersiz kılma, Gutenberg'in sürüm değişikliklerini yönetmek için yerleşik mekanizmasıdır. Bloğunuzun block.json dosyasında bir deprecated dizisi tanımlayarak düzenleyiciye şunu söylersiniz: "Bu eski sürümlerden biriyle eşleşen bir blokla karşılaşırsan, onu mevcut sürüme dönüştür." Her bir geçersiz kılma girişi, önceki attributes, supports ve save fonksiyonunu (veya render_callback) belirtir. Düzenleyici eski bir blok yüklediğinde, geçersiz kılma dizisini sırayla tarar ve ilk eşleşen dönüşümü uygular.

Bu özellik genellikle yeterince kullanılmaz çünkü geliştiriciler bir bloğun işaretlemesini asla değiştirmeyeceklerini varsayarlar. Ancak gerçek dünya projelerinde gereksinimler evrilir. Geçersiz kılmayı atlarsanız, kullanıcıları blokları silmeye ve yeniden eklemeye zorlarsınız (kötü deneyim) veya bloğun iki ayrı sürümünü sürdürürsünüz (dağınık). Resmi WordPress geliştirici el kitabı bunu Blok Düzenleyici El Kitabı'nda ele alır, ancak pratik uygulama eksiktir.

Adım 1: Mevcut Durumu Yakalayın

Herhangi bir değişiklik yapmadan önce, bloğunuzun kullandığı tam save çıktısını (veya dinamik bloklar için render_callback) ve attributes'lerini kaydedin. Bunu bir anlık görüntü almak gibi düşünün. Statik bloklar için save fonksiyonu tarafından döndürülen JSX'i kaydedin. Dinamik bloklar için render_callback tarafından oluşturulan PHP işaretlemesini kaydedin.

Eklentinizde deprecated.js (veya benzeri) adlı yeni bir dosya oluşturun ve eski save fonksiyonunu orada saklayın. Alternatif olarak, geçersiz kılınmış sürümleri doğrudan bloğun ana JavaScript dosyasında tutun. Önemli olan, bu kodu bloğun ilk dağıtıldığı zamanki haliyle korumaktır.

Adım 2: Geçersiz Kılınmış Sürümlerinizi Tanımlayın

block.json dosyanıza bir deprecated dizisi ekleyin. Her bir giriş, aşağıdakileri içerebilen bir nesnedir:

• attributes (nesne): Önceki öznitelik tanımları.
• supports (nesne): Değişen önceki destek ayarları.
• save (fonksiyon veya dize): Önceki save fonksiyonu. Yalnızca JavaScript blokları için, eski fonksiyonu içe aktarırsınız. PHP ile işlenen dinamik bloklar için bunun yerine migrate ve render_callback kullanabilirsiniz.
• migrate (fonksiyon): Eski öznitelikleri yenilerine eşleyen bir fonksiyon (isteğe bağlı).

Örnek:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

Not: block.json içindeki save fonksiyonu genellikle JavaScript'te tanımlanır. Harici bir betik kullanıyorsanız, onu kuyruğa almanız ve fonksiyon adına başvurmanız gerekir. Alternatif olarak, fonksiyonu bir dize olarak satır içine alabilirsiniz (ancak bu karmaşık bloklar için önerilmez).

Adım 3: Öznitelikleri Eşleyin

Genellikle, yalnızca işaretlemeyi değil, aynı zamanda öznitelik adlarını veya kaynaklarını da değiştirirsiniz. Örneğin, yazarı düz bir dize olarak depolamaktan zengin metin alanına geçiş yapabilirsiniz. Bu gibi durumlarda, eski öznitelikleri yenilerine dönüştürmek için migrate özelliğini kullanın.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

Eğer bir migrate fonksiyonu sağlamazsanız, düzenleyici eski öznitelikleri doğrudan yeni bloğa iletecektir. Bu, öznitelik adları değiştiyse hatalara neden olabilir.

Adım 4: Gerçek İçerikle Test Edin

Geçersiz kılınmış sürümü tanımladıktan sonra iyice test edin. Yeni bir yayın oluşturun, eski bloğu ekleyin (mevcut bir yayından serileştirilmiş blok kodunu yapıştırarak simüle edebilirsiniz) ve doğrulama hatası olmadan yeni sürüme dönüştüğünü doğrulayın. Ayrıca dönüştürülmüş bloğu düzenleme ve kaydetme işlemlerini test edin. Birden fazla geçersiz kılınmış sürümünüz varsa, bunları da tekrarlayın.

Dinamik bloklar için süreç benzerdir ancak bir farkla: dinamik bir blok için save fonksiyonu genellikle null döndürür (blok PHP ile işlenir). Geçersiz kılma girişinde, save'i dinamik işlemeye geçmeden önce kullanılan önceki statik işaretlemeye ayarlayabilir veya hem eski hem de yeni öznitelik yapılarını işleyen bir PHP render_callback kullanabilirsiniz. Bu daha karmaşıktır ancak yapılabilir.

Uyarılar ve Değiş Tokuşlar

Geçersiz kılma güçlüdür, ancak dezavantajları vardır. Her geçersiz kılınmış sürüm, eklentinize kod ekler. Zamanla, nadiren kullanılan ancak bakımı yapılması gereken beş veya altı eski sürümden oluşan bir zincirle karşılaşabilirsiniz. WordPress çekirdek ekibi en az iki sürüm geriye gitmeyi önerir, ancak bunun ötesinde, etkilenen yayın sayısı azsa temiz bir kopuş düşünebilirsiniz.

Bir başka nüans: geçersiz kılma girişlerinin sırası önemlidir. Düzenleyici, diziyi 0 indeksinden yukarı doğru tarar ve ilk eşleşmeyi kullanır. İki geçersiz kılınmış sürüm benzer ise, yanlış olan uygulanabilir. Her zaman en son geçersiz kılınmış sürümü (mevcut sürümden hemen önceki) ilk sıraya koyun.

Son olarak, geçersiz kılma, site genelinde bir stil değişikliği (örneğin theme.json aracılığıyla) kullanılarak düzenlenen içeriği işlemez. Bloğunuzun görünümü, o zamandan beri değişen küresel stillere dayanıyorsa, geçersiz kılma bunu ayarlamaz. Kaydetme sırasında veya bir eklenti güncelleme kancası aracılığıyla çalışan bir geçiş betiği eklemeniz gerekebilir.

Geçersiz Kılma Ne Zaman Cevap Değildir

Çoğu eğitim, geçersiz kılmayı zorunlu olarak sunar. Gerçekte, temiz bir kopuşun daha iyi olduğu durumlar vardır. Bloğunuz yeniyse ve yalnızca birkaç yayında kullanılıyorsa, bu birkaç örneği manuel olarak güncellemek, geçersiz kılma kodu yazıp test etmekten daha hızlı olabilir. Benzer şekilde, bloğun altında yatan veri modeli temel olarak farklıysa (örneğin, iki bloğu birleştiriyorsanız), geçersiz kılma yeterince esnek olmayabilir. Bu durumda, eklenti güncellendiğinde çalışan ve eski blokları yeni formata dönüştüren tek seferlik bir geçiş betiği yazın.

Bir diğer karşıt görüş: geçersiz kılma, iyi tasarımın yerine kullanılmamalıdır. Sık değişiklikler bekliyorsanız, bloğunuzu baştan itibaren sürüm oluşturmayı düşünerek tasarlayın—örneğin, bir version özniteliği depolayarak ve koşullu işleme kullanarak. Temel Blokların Ötesinde adresinde tartışılan bu yaklaşım, geçersiz kılmadan daha hafiftir ancak öngörü gerektirir.

Sonuç

Blok geçersiz kılma, ciddi herhangi bir Gutenberg geliştiricisi için temel bir araçtır. Kullanıcılarınızın içeriğini bozmadan bloklarınızı geliştirmenizi sağlar. Ana adımlar şunlardır: mevcut durumu yakalayın, block.json içinde geçersiz kılınmış sürümü tanımlayın, gerekirse öznitelikleri eşleyin ve gerçek içerikle test edin. Ancak geçersiz kılmanın bakım maliyetleri getirdiğini unutmayın. Bazen temiz bir kopuş veya sürümlü blok tasarımı daha pragmatiktir. Geçersiz kılmayı otomatik olarak değil, stratejik olarak kullanın; bloklarınız birçok güncelleme boyunca sağlam kalacaktır.

Bakımı yapılabilir eklentiler oluşturma konusunda daha geniş bir perspektif için bkz. Sağlam WordPress Eklentileri Oluşturma. Blok geliştirmede yeniyseniz, Temel Blokların Ötesinde başlamanıza yardımcı olacaktır.