WordPress Eklentime Live Preview Özelliğini Nasıl Ekledim? Playground ve Blueprint Deneyimim

WordPress Live Preview, bir eklentinin ziyaretçi tarafından indirilmeden ve mevcut bir siteye kurulmadan denenmesini sağlayan canlı önizleme özelliğidir. WordPress.org eklenti sayfasından açılan bu önizleme, WordPress Playground üzerinde çalışır. Blueprint dosyasıyla yapılandırıldığında eklentinin yanında örnek içerikler, medya dosyaları, sayfalar ve gerekli ayarlar da hazırlanabilir.

Ancak bir eklentinin Playground ortamında açılması, kullanılabilir bir demo oluşturulduğu anlamına gelmez. Ürün kataloğu eklentisinde ürünlerin, galeri eklentisinde görsellerin, form eklentisinde ise örnek bir formun bulunması gerekir. Önizleme yalnızca boş bir yönetim ekranı gösteriyorsa ziyaretçi eklentinin ne yaptığını anlamak için kurulumu baştan tamamlamak zorunda kalır.

Bu rehberde WordPress eklentisine Live Preview ekleme süreci; Blueprint dosyasının hazırlanması, demo verilerinin oluşturulması, görsellerin Medya Kütüphanesine aktarılması, SVN üzerinden yayımlama ve önizlemenin herkese açılması aşamalarıyla ele alınmaktadır. OZD Product Catalogue için hazırlanan dört ürünlü katalog, anlatılan işlemlerin uygulama örneğini oluşturmaktadır.

WordPress Live Preview Nedir?

WordPress Live Preview, WordPress.org eklenti dizinindeki bir eklentiyi hazır bir deneme ortamında çalıştıran özelliktir. Ziyaretçi, eklenti sayfasındaki Live Preview düğmesini kullanarak WordPress Playground üzerinden oluşturulan kuruluma ulaşır. Böylece eklentinin yönetim ekranlarını veya ziyaretçiye gösterdiği çıktıyı kendi sitesinde değişiklik yapmadan inceleyebilir.

Ekran görüntüleri arayüzün belirli bir anını gösterirken canlı önizleme, kullanıcıya etkileşim kurma imkânı verir. Bir katalogda arama yapmak, filtreleri değiştirmek veya ürün ayrıntılarına geçmek bu etkileşimlere örnektir. Demo içeriğinin önceden hazırlanması, eklentinin temel işlevine ulaşmak için gereken adımları azaltır.

Canlı önizlemenin amacı eklentinin bütün ayarlarını tek ekrana yerleştirmek değildir. Ziyaretçinin temel kullanım senaryosunu anlayabildiği, gerekli kontrolleri deneyebildiği ve ortaya çıkan sonucu görebildiği bir başlangıç ortamı sunulmalıdır. Çok sayıda gereksiz ürün, sayfa veya bağımlılık eklemek, önizlemeyi daha yararlı hâle getirmeden açılış süresini uzatabilir.

WordPress Playground Nasıl Çalışır?

WordPress Playground, WordPress’i tarayıcı içinde çalıştırabilen bir altyapıdır. PHP çalışma ortamı WebAssembly teknolojisiyle tarayıcıya taşınır; veritabanı işlemlerinde SQLite tabanlı entegrasyondan yararlanılır. Bu yapı, klasik bir PHP ve MySQL sunucusu hazırlamadan WordPress ile deneme yapılmasını sağlar.

Playground kullanımı ile normal bir hosting kurulumu arasında çalışma ortamı farkları vardır. Tarayıcıdaki ağ erişimi, dosya sistemi, veri saklama biçimi ve kullanılabilir PHP özellikleri gerçek sunucuyla aynı koşulları sunmayabilir. Bu nedenle Playground üzerinde çalışan bir demo, eklentinin bütün hosting yapılandırmalarında sorunsuz çalıştığını kanıtlamaz.

Live Preview için hazırlanan ortam, ziyaretçinin mevcut WordPress sitesinden bağımsızdır. Demo ürünlerinde yapılan değişiklikler, geliştiricinin üretim sitesindeki ürünleri güncellemez. Bununla birlikte ortamın saklanması ve yeniden açılması kullanılan Playground yöntemine bağlı olduğundan, önizleme kalıcı içerik barındırma hizmeti olarak tasarlanmamalıdır.

Playground, Blueprint ve Live Preview Arasındaki Fark

Bu üç kavram aynı sürecin farklı parçalarını ifade eder. Aralarındaki görev ayrımı anlaşılmadığında, yalnızca bir JSON dosyası hazırlamanın veya Playground bağlantısı oluşturmanın WordPress.org üzerindeki düğmeyi otomatik etkinleştireceği düşünülebilir.

• WordPress Playground: WordPress’in çalışacağı deneme ortamını sağlar.
• Blueprint: Ortam hazırlanırken uygulanacak ayarları ve işlemleri tarif eder.
• Live Preview: Eklenti sayfasından yapılandırılmış önizlemeye ulaşmayı sağlar.

Örneğin bir katalog demosunda Playground WordPress’i çalıştırır; Blueprint örnek ürünleri ve demo sayfasını oluşturur; Live Preview düğmesi ise ziyaretçiyi bu hazırlanmış ortama yönlendirir. Sorun giderirken de hata, bu parçaların hangisinde oluştuğuna göre değerlendirilmelidir.

Live Preview Eklemek İçin Gerekenler

WordPress.org üzerinde canlı önizleme yayımlayabilmek için eklentinin onaylanmış, SVN deposunun açılmış ve işlem yapan hesabın gerekli depo yetkisine sahip olması gerekir. İlk başvuru ile canlı önizleme yapılandırması farklı aşamalardır. Henüz yayımlanmamış bir eklenti için önce WordPress.org’a eklenti gönderme süreci tamamlanmalıdır.

Çalışmaya başlamadan önce aşağıdaki bileşenler hazırlanmalıdır:

• Eklentinin güncel dosyalarını içeren SVN çalışma kopyası.
• Bilgisayarda kullanılabilir bir SVN istemcisi.
• UTF-8 kodlamasıyla JSON ve PHP dosyalarını düzenleyebilen bir kod editörü.
• Demoda gösterilecek sınırlı ve anlaşılır bir örnek veri seti.
• Örnek içeriklere ait yayımlanabilir görseller.
• Eklentinin içerik türleri, özel alanları, ilişkileri ve kısa kodları hakkında bilgi.

Eklentinin veri yapısı bu hazırlığın teknik temelidir. Ürünler özel bir içerik türünde tutuluyorsa içerik türünün adı, fiyat ve model bilgileri özel alanlarda saklanıyorsa bu alanların anahtarları bilinmelidir. Eklenti kendi tablolarını veya kayıt servislerini kullanıyorsa demo verileri de bu yapıya uygun biçimde oluşturulmalıdır.

Demo İçeriği Nasıl Planlanmalıdır?

Demo içeriği, eklentinin en önemli işlevini gösterecek şekilde seçilmelidir. Bir katalog için farklı kategorilerde birkaç ürün, değişen satış durumları ve ürün görselleri yeterli olabilir. Bir form eklentisinde örnek alanlar ve gönderim sonrası mesajı; bir galeri eklentisinde ise farklı görsel düzenleri öncelikli olabilir.

OZD Product Catalogue uygulamasında Classic Wooden Chair, Modern Table, Bookshelf ve Desk Lamp adlı dört ürün kullanılmıştır. Ürünlere model, fiyat, satış durumu ve teknik özellik bilgileri eklenmiş; bunları içeren Demo Catalogue adlı bir katalog hazırlanmıştır. Katalog, OZD Product Catalogue Demo adlı sayfada görüntülenmiştir.

Bu yapı, demo verisinin üç katmanını gösterir: önce kayıtlar oluşturulur, ardından kayıtların ilişkileri kurulur, son olarak kullanıcıya gösterilecek sayfa hazırlanır. Ürün oluşturmakla katalog oluşturmak aynı işlem değildir. Ürünler veritabanında bulunsa bile ilgili katalogla ilişkilendirilmemişse katalog sayfası boş görünebilir.

Örnek veriler gerçek müşteri bilgisi içermemeli ve ürün fiyatları gerçek satış teklifi izlenimi vermemelidir. Gösterilen içerikler, eklentinin veri alanlarını ve arayüzünü açıklayan örnekler olarak düzenlenmelidir. Demo için gerekli veriler normal eklenti etkinleştirme işlemine eklenmemeli; önizleme hazırlığı içinde tutulmalıdır.

Blueprint Dosyası Nereye Eklenir?

WordPress.org eklenti önizlemesi için kullanılan dosyanın SVN deposu içindeki yolu assets/blueprints/blueprint.json olmalıdır. Buradaki assets, deponun kök dizinindeki klasördür. Eklentinin çalıştırılabilir dosyalarının bulunduğu trunk içindeki bir assets klasörü aynı konum değildir.

Örnek katalog için Blueprint ve ürün görselleri şu dosya yollarında tutulabilir:

assets/blueprints/blueprint.json
assets/blueprints/images/classic-wooden-chair.jpg
assets/blueprints/images/modern-table.jpg
assets/blueprints/images/bookshelf.jpg
assets/blueprints/images/desk-lamp.jpg

Bu ayrım, önizleme varlıklarının eklentinin dağıtım dosyalarıyla karışmasını önler. Yalnızca demo için kullanılan görsellerin eklenti ZIP paketine taşınması gerekmez. Buna karşılık eklentinin normal çalışmasında ihtiyaç duyduğu bir dosya, yalnızca önizleme klasöründe bırakılmamalıdır.

Dosya adı ve klasör yolu doğru olsa da içerik geçersizse önizleme hazırlanamaz. Bu nedenle klasör yerleşimi, JSON sözdizimi ve Blueprint şemasına uygunluk ayrı ayrı kontrol edilmelidir.

Blueprint Dosyasının Temel Alanları

Blueprint, Playground’un ortamı nasıl hazırlayacağını açıklayan JSON dosyasıdır. Kullanılacak sürümler, açılış adresi ve kurulum adımları bu dosyada tanımlanır. Alanların güncel yapısı Blueprint veri biçimi belgesinde açıklanmaktadır.

$schema: Yapısal Doğrulama

$schema alanı, JSON düzenleyicisinin Blueprint yapısını tanımasına yardımcı olur. Alan adlarının ve değer türlerinin denetlenmesini kolaylaştırır. Dosyanın bu şemaya uyması, içindeki PHP kodunun veya eklentiye özel işlemlerin doğru sonuç üreteceğini tek başına garanti etmez.

preferredVersions: PHP ve WordPress Sürümleri

preferredVersions içinde PHP ve WordPress sürüm tercihleri belirtilir. Önizleme için eklentinin desteklediği bir kombinasyon seçilmelidir. latest değeri güncel sürümle denemeyi kolaylaştırırken desteklenen belirli bir sürümün seçilmesi karşılaştırmalı testlerde daha tutarlı bir başlangıç sağlar.

landingPage: Önizlemenin Açılış Adresi

landingPage, hazırlık adımları tamamlandığında açılacak yolu belirler. Kök adres için /, yönetim paneli için /wp-admin/ kullanılabilir. Demo bir katalog çıktısını gösterecekse açılışın doğrudan o çıktıya yönlendirilmesi daha anlaşılır bir kullanım sunar.

features: Ağ Erişimi

Harici dosyaların WordPress HTTP API üzerinden indirilmesi gereken demolarda ağ erişimi dikkate alınmalıdır. features.networking ayarı bu desteği yönetir. Ağ desteğinin açık olması, her kaynağın mutlaka indirilebileceği anlamına gelmez; uzak sunucu ve tarayıcı kaynaklı kısıtlar ayrıca değerlendirilmelidir.

steps: İşlem Sırası

steps dizisi, hazırlık işlemlerini sıralar. Bir işlem öncekinin sonucuna bağlıysa bu sıra özellikle önemlidir. Katalog ilişkisi kurulmadan önce ürünler oluşturulmalı; görsel ürüne atanmadan önce medya kaydı hazırlanmalıdır.

Temel Blueprint Örneği

Aşağıdaki Blueprint, yapılandırmanın başlangıç noktasıdır. PHP 8.3 ve güncel WordPress sürümünü tercih eder, ağ erişimini açık tutar ve kök adrese yönlendirir. Eklenti kurulumu veya ürün oluşturma adımı içermediği için tek başına tamamlanmış bir katalog demosu üretmez.

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "preferredVersions": {
    "php": "8.3",
    "wp": "latest"
  },
  "features": {
    "networking": true
  },
  "landingPage": "/",
  "steps": []
}

JSON içinde anahtar adları ve metin değerleri çift tırnakla yazılmalıdır. Son öğeden sonra fazladan virgül bırakılmamalı, açıklama amacıyla yorum satırı eklenmemelidir. Özellikle PHP kodunu JSON içindeki bir metne dönüştürürken tırnakların, ters eğik çizgilerin ve satır sonlarının doğru kodlanması gerekir.

Uzun PHP kodlarını elle tek satıra dönüştürmek yerine bir JSON kodlayıcısı kullanmak daha güvenilir bir yöntemdir. Geçerli bir PHP dosyası, hatalı kaçırma nedeniyle JSON içine aktarıldığında çalışmaz hâle gelebilir. Önce PHP parçası, ardından ortaya çıkan JSON ayrı olarak kontrol edilmelidir.

WordPress.org Önizlemesi ile Bağımsız Playground Demosu

WordPress.org üzerinden başlatılan önizleme ile doğrudan bir Blueprint bağlantısından açılan bağımsız demo aynı kurulum varsayımlarına sahip değildir. WordPress.org akışı hedef eklentiyi önizlemeye yükler. Bağımsız bir yapılandırmada ise eklentinin kurulması açıkça tanımlanmalıdır.

Bu nedenle WordPress.org için hazırlanan dosyaya eklentinin kendisini tekrar kuran bir adım eklemeden önce mevcut akış kontrol edilmelidir. OZD Product Catalogue uygulamasında yinelenen kurulum adımının kaldırılmasıyla bu gereksiz tekrar giderilmiştir. Buna karşılık başka bir eklentiye bağımlılık varsa o bağımlılığın hazırlanması ayrıca gerekebilir.

Bağımsız Playground demosunda eklenti kurulumu için kullanılabilecek örnek adım şöyledir:

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "wordpress.org/plugins",
    "slug": "ozd-katalog-eklentisi"
  },
  "options": {
    "activate": true
  }
}

Bu nesne, uygun Blueprint içindeki steps dizisine yerleştirilir. slug, eklentinin WordPress.org adresindeki kısa addır; görünen eklenti başlığı değildir. Örnek kurulum adımı, tek başına demo ürünlerini veya katalog sayfasını oluşturmaz.

runPHP ile Demo İçeriği Oluşturma

runPHP adımı, Blueprint hazırlanırken PHP kodu çalıştırmayı sağlar. WordPress’in içerik ve seçenek fonksiyonlarına erişmek için önce WordPress yüklenmelidir. Web Playground’un standart dizin yapısında bu işlem aşağıdaki başlangıç satırıyla yapılabilir:

<?php
require_once '/wordpress/wp-load.php';

Bu kod ziyaretçiye sunulan yazı alanına çalıştırılmak üzere eklenmez; Blueprint’in PHP çalıştırma adımında kullanılır. runPHP adımının belgesi, kodun Blueprint içindeki konumunu ve kabul edilen alanları açıklar.

PHP kodu, steps dizisi içindeki runPHP nesnesinin code alanına metin olarak yerleştirilir. Site başlığını değiştiren kısa bir adım şu biçimdedir:

{
  "step": "runPHP",
  "code": "<?php require_once '/wordpress/wp-load.php'; update_option( 'blogname', 'Eklenti Demosu' );"
}

Demo sayfası ve ürün oluşturma kodları da aynı code alanında çalıştırılabilir. Aşağıdaki çok satırlı PHP örnekleri bu alana aktarılırken geçerli JSON metnine dönüştürülmelidir. İşlem sırası korunmalı ve birbirine bağlı adımlar aynı veri varsayımlarıyla çalışmalıdır.

Özel içerik türlerini kullanan bir demo hazırlanırken eklentinin etkin olması ve ilgili kayıtların WordPress tarafından tanınması gerekir. PHP kodunu daha erken bir aşamada çalıştırmak, ürün türünün bulunmaması veya eklenti fonksiyonlarının kullanılamaması gibi hatalara yol açabilir.

İçerik oluşturma akışında doğrudan veritabanı tablolarına yazmak yerine WordPress’in veya eklentinin sunduğu kayıt yöntemleri tercih edilmelidir. Böylece gerekli alanların, ilişkilerin ve kayıt sırasında çalışan işlemlerin atlanma ihtimali azalır.

Demo Sayfası Oluşturma ve Ana Sayfa Olarak Ayarlama

Demo sayfasını oluşturmak için wp_insert_post() kullanılabilir. Fonksiyon yalnızca blog yazıları için değil, sayfa ve uygun özel içerik türleri için de kayıt oluşturur. İkinci parametre true verildiğinde hata bilgisinin WP_Error olarak alınması sağlanır.

Aşağıdaki PHP örneği, temiz bir demo ortamında sabit kısa ada sahip bir sayfa oluşturur veya mevcut sayfayı günceller. Ardından sayfayı WordPress’in statik ön sayfası olarak belirler. Örnekteki içerik, eklentiye bağımlı olmayan basit bir tanıtım paragrafıdır.

<?php
require_once '/wordpress/wp-load.php';

$existing_page = get_page_by_path( 'eklenti-demosu', OBJECT, 'page' );

$page_data = array(
    'post_type'    => 'page',
    'post_status'  => 'publish',
    'post_name'    => 'eklenti-demosu',
    'post_title'   => 'Eklenti Demosu',
    'post_content' => '<p>Örnek eklenti ortamına hoş geldiniz.</p>',
);

if ( $existing_page ) {
    $page_data['ID'] = $existing_page->ID;
}

$page_id = wp_insert_post( wp_slash( $page_data ), true );

if ( is_wp_error( $page_id ) ) {
    throw new RuntimeException( $page_id->get_error_message() );
}

if ( ! $page_id ) {
    throw new RuntimeException( 'Demo sayfası oluşturulamadı.' );
}

update_option( 'show_on_front', 'page' );
update_option( 'page_on_front', (int) $page_id );

Katalog çıktısı göstermek için post_content alanına eklentinin ürettiği geçerli kısa kod yerleştirilir. Katalog kimliği, oluşturulan katalog kaydından alınmalıdır. Farklı bir kurulumdaki kimliği sabit biçimde kopyalamak yanlış kataloğun açılmasına veya boş çıktı oluşmasına neden olabilir.

Kısa kodun kayıtlı olması ile sayfa içeriğinde bulunması da ayrı konulardır. Eklenti etkin değilse veya kısa kod adı yanlışsa metin sayfada işlenmeden kalabilir. Kısa kod yapısının ayrıntıları için WordPress kısa kod oluşturma rehberi incelenebilir.

show_on_front ve page_on_front WordPress’in ana sayfa seçimini yapar. Blueprint içindeki landingPage ise hangi adresin açılacağını belirler. Kök adreste katalog gösterilecekse hem WordPress’in ön sayfa ayarı hem de Blueprint’in açılış yolu birbiriyle uyumlu olmalıdır.

Demo Verilerinin Tekrarlanmasını Önleme

Hazırlık işlemi aynı ortamda yeniden çalıştırıldığında her defasında yeni ürün ve sayfa eklenmesi, kısa sürede mükerrer kayıtlar oluşturabilir. Bu nedenle demo kayıtları başlıklarına bakılarak gelişigüzel değil, sabit bir kısa ad veya demoya özel tanımlayıcıyla bulunmalıdır.

Sayfa örneğinde kullanılan get_page_by_path(), belirtilen yoldaki mevcut kaydın bulunmasına yardımcı olur. Ürünler farklı veri yapılarında saklanıyorsa aynı yaklaşım eklentinin sorgulama yöntemine uyarlanmalıdır. Kayıt bulunursa güncelleme, bulunamazsa oluşturma yapılabilir.

Görseller için de aynı sorun ortaya çıkabilir. Her çalıştırmada aynı JPG dosyasını yeniden indirmek, aynı ürüne ait birden fazla medya kaydı üretir. Kaynak URL’yi bir medya özel alanında saklamak veya mevcut attachment kimliğinin geçerliliğini kontrol etmek tekrarları azaltabilir. Tekrar kullanılacak medya kaydının gerçekten mevcut olduğu ayrıca doğrulanmalıdır.

Demo Görsellerini Hazırlama

Ürün görselleri, katalog demosunun anlaşılabilirliğini doğrudan etkiler. Başlık ve fiyat alanları dolu olsa bile görselsiz ürün kartları tamamlanmamış bir katalog izlenimi verir. Örnek görseller, ürünün ne olduğunu açıklamalı ve kart düzeninde tutarlı görünmelidir.

Dosya adlarında kısa, açıklayıcı ve kolay eşleştirilebilir ifadeler kullanılmalıdır. Örneğin Classic Wooden Chair ürünü için classic-wooden-chair.jpg adı, hangi görselin hangi kayda ait olduğunu izlemeyi kolaylaştırır. Farklı dosyalarda büyük ve küçük harf kullanımını tutarlı tutmak, uzak adreslerde oluşabilecek yol hatalarını önler.

Görseller gereksiz derecede büyük olmamalıdır. Önizleme başlarken indirilecek dosya sayısı ve toplam boyut arttıkça kurulum da ağırlaşır. Ürün kartında küçük gösterilecek bir görsel için çok yüksek çözünürlüklü kaynak kullanmak yerine yeterli boyut ve uygun sıkıştırma tercih edilmelidir.

SVN ile Blueprint ve Görselleri Yayımlama

SVN işlemleri eklentinin yerel çalışma kopyasında yürütülür. Dosyayı bilgisayarda oluşturmak veya ilgili klasöre kopyalamak, uzak depoya gönderildiği anlamına gelmez. Yeni dosyanın takibe alınması, değişikliklerin incelenmesi ve commit işleminin tamamlanması gerekir.

Yeni Dosyaları SVN Takibine Alma

Blueprint klasörü ilk kez oluşturulmuşsa aşağıdaki komut kullanılabilir:

svn add assets/blueprints

Bu işlem yeni klasörün altındaki dosyaları da ekleme işlemine alır. Blueprint klasörü zaten takip ediliyor ve yalnızca images klasörü yeni ekleniyorsa daha dar kapsamlı komut yeterlidir:

svn add assets/blueprints/images
svn status

Aynı dosya için iki ekleme komutunun art arda çalıştırılması gerekmez. Önceden takip edilen bir dosyada yapılan düzenleme, yeniden svn add kullanılmadan değişiklik olarak görünür.

svn status Çıktısını Okuma

svn status, yerel çalışma kopyasındaki değişiklikleri listeler. A işareti yeni eklenen öğeyi, M işareti değiştirilmiş dosyayı, soru işareti ise henüz takip edilmeyen öğeyi gösterir. Ünlem işareti takip edilen bir öğenin yerelde eksik olduğunu belirtebilir; bu durum dosyanın bilinçli olarak silinip silinmediği incelenerek çözülmelidir.

Blueprint düzenlenmiş ve görseller yeni eklenmişse JSON dosyasının M, görsellerin A olarak görünmesi beklenir. Beklenmeyen başka dosyalar varsa commit öncesinde bunların neden listelendiği kontrol edilmelidir.

Değişiklikleri Kontrol Etme ve Commit İşlemi

Metin dosyasındaki farklar aşağıdaki komutla incelenebilir:

svn diff assets/blueprints/blueprint.json

Görseller ikili dosyalardır; metin farkı çıktısı onların içeriğini değerlendirmek için yeterli değildir. Doğru dosyanın eklendiği, dosya adının Blueprint’teki adresle eşleştiği ve görselin açılabildiği ayrıca kontrol edilmelidir.

Blueprint ve ilgili görselleri aynı gönderimde yayımlamak için:

svn commit assets/blueprints -m "Add catalogue preview and demo images"

Commit mesajı yapılan değişikliği açıklamalıdır. Dosya kapsamının assets/blueprints ile sınırlandırılması, çalışma kopyasındaki ilgisiz değişikliklerin yanlışlıkla gönderilmesini önlemeye yardımcı olur. Commit çıktısında revizyon numarası görülmesi, işlemin depoya yazıldığını gösterir; önizlemenin doğru çalıştığını doğrulamak için ayrıca test yapılmalıdır.

SVN çalışma kopyası, güncelleme ve gönderim işlemlerinin ayrıntıları WordPress’in Subversion belgesinde açıklanmaktadır.

SVN’deki Görselleri Medya Kütüphanesine Aktarma

Görselin SVN deposunda bulunması, WordPress Medya Kütüphanesinde kayıtlı olduğu anlamına gelmez. Dosya adresi yalnızca kaynağın nerede bulunduğunu gösterir. WordPress’in attachment kimliğiyle çalışan görsel alanlarına veri verebilmek için dosyanın demo ortamına aktarılması gerekir.

Aktarım üç aşamada ele alınmalıdır. Önce kaynak dosya indirilir, ardından medya kaydı oluşturulur, son olarak oluşan kimlik ilgili ürünle ilişkilendirilir. Bu aşamalardan biri başarısız olduğunda sonraki aşama geçerli sonuç varmış gibi sürdürülmemelidir.

download_url() ile Geçici Dosya Oluşturma

download_url(), uzak dosyayı WordPress HTTP API üzerinden geçici bir dosyaya indirir. Başarılı sonuç bir dosya yoludur; doğrudan medya kimliği değildir. İndirme başarısız olduğunda WP_Error dönebildiği için sonuç kontrol edilmeden medya işlemine verilmemelidir.

media_handle_sideload() ile Medya Kaydı Oluşturma

media_handle_sideload(), hazırlanan dosyayı WordPress’in medya yükleme sürecinden geçirir. Dosyanın adı ve geçici yolu bu işlemin girdileri arasındadır. Başarılı sonuç attachment kimliğidir; başarısızlık ise ayrı olarak ele alınmalıdır.

set_post_thumbnail() ile Öne Çıkan Görsel Atama

set_post_thumbnail(), mevcut medya kaydını belirtilen içeriğin öne çıkan görseli yapar. Uzak JPG adresi yerine attachment kimliği verilmelidir. Eklenti görselleri kendi özel alanında tutuyorsa öne çıkan görsel ataması tek başına yeterli olmayabilir.

Görsel İçe Aktarma İçin PHP Örneği

WordPress yönetim fonksiyonlarının tamamı yalnızca wp-load.php yüklenmesiyle kullanılabilir hâle gelmez. Görsel aktarımı yapılmadan önce dosya, medya ve görsel işleme işlevlerinin bulunduğu yönetim dosyaları yüklenmelidir.

Aşağıdaki örnek, standart Playground ortamında bir görseli indirip mevcut bir içeriğe bağlamak için kullanılabilecek fonksiyonu tanımlar. Eklentinin ürünü oluşturulduktan sonra dönen gerçek içerik kimliğiyle çağrılmalıdır. Eklentiye özel galeri veya ürün meta alanlarını güncellemez.

<?php
require_once '/wordpress/wp-load.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/image.php';

$import_demo_image = static function ( $source_url, $post_id, $alt_text ) {
    $post_id = absint( $post_id );

    if ( ! $post_id || ! get_post( $post_id ) ) {
        return new WP_Error( 'invalid_demo_post', 'İçerik bulunamadı.' );
    }

    $url_path = wp_parse_url( $source_url, PHP_URL_PATH );
    $filename = is_string( $url_path )
        ? sanitize_file_name( wp_basename( $url_path ) )
        : '';

    if ( '' === $filename ) {
        return new WP_Error( 'invalid_demo_filename', 'Dosya adı alınamadı.' );
    }

    $temporary_file = download_url( $source_url, 30 );

    if ( is_wp_error( $temporary_file ) ) {
        return $temporary_file;
    }

    $attachment_id = media_handle_sideload(
        array(
            'name'     => $filename,
            'tmp_name' => $temporary_file,
        ),
        $post_id
    );

    if ( is_wp_error( $attachment_id ) ) {
        if ( is_file( $temporary_file ) ) {
            wp_delete_file( $temporary_file );
        }
        return $attachment_id;
    }

    if ( ! wp_attachment_is_image( $attachment_id ) ) {
        wp_delete_attachment( $attachment_id, true );
        return new WP_Error( 'invalid_demo_image', 'Dosya görsel değil.' );
    }

    update_post_meta(
        $attachment_id,
        '_wp_attachment_image_alt',
        sanitize_text_field( $alt_text )
    );

    set_post_thumbnail( $post_id, $attachment_id );

    if ( (int) get_post_thumbnail_id( $post_id ) !== (int) $attachment_id ) {
        return new WP_Error( 'demo_thumbnail_failed', 'Görsel atanamadı.' );
    }

    return (int) $attachment_id;
};

Fonksiyonun döndürdüğü sonuç, çağıran kodda is_wp_error() ile denetlenmelidir. Geçerli attachment kimliği alındıktan sonra eklentinin özel görsel alanına aktarım yapılabilir. Bu örnek mevcut medya kaydını aramadığından, aynı ürün için tekrar çağrılacaksa öncesine tekrar kontrolü eklenmelidir.

Örnek aktarım kodu, güvenilen demo kaynakları için tasarlanmıştır. Genel kullanıma açık bir URL yükleme formu olarak doğrudan kullanılmamalıdır. Demo kaynağının belirli bir alan adı ve dosya listesiyle sınırlı tutulması, beklenmedik dosyaların içeri alınmasını önlemeyi kolaylaştırır.

Ürünler Göründüğü Hâlde Görseller Neden Görünmez?

Ürün adı, fiyat ve model alanları görüntüleniyor fakat görsel alanları boş kalıyorsa önce veri kaydıyla medya aktarımı birbirinden ayrılmalıdır. Bu belirti, ürün oluşturma işleminin en azından bir kısmının tamamlandığını gösterir. Ancak görsel indirme, medya kaydı oluşturma veya ürüne atama işlemlerinin hangisinin başarısız olduğunu tek başına açıklamaz.

OZD Product Catalogue önizlemesinin ilk aşamasında ürün kartları oluşmuş, görsel alanlarında ise yer tutucular kalmıştır. Kaynak görseller SVN üzerinde erişilebilir durumdayken aktarım kodunun çalışma sırası incelenmiş; gerekli yönetim dosyalarının fonksiyon çağrılarından önce yüklenmesiyle sorun giderilmiştir.

Tanımsız Fonksiyon Hatası

download_url() kullanılmadan önce wp-admin/includes/file.php yüklenmemişse ilgili fonksiyon bulunamayabilir. Benzer şekilde medya işlevleri için gerekli dosyaların eksik olması aktarımı durdurabilir. Çözüm, yalnızca fonksiyon adını değiştirmek değil, bağımlılıkları doğru sırada yüklemektir.

Yanlış veya Erişilemeyen Görsel Adresi

Dosya adı, uzantı ve klasör yolu birebir eşleşmelidir. Adresin bir HTML hata sayfasına yönlenmesi, oturum açma gerektirmesi veya gerçekten 404 döndürmesi indirmeyi etkiler. Yerel dosya yolu ile herkese açık SVN URL’si karıştırılmamalıdır.

Playground İçinden Ağ İsteğinin Başarısız Olması

Görselin normal bir tarayıcı sekmesinde açılması, WordPress HTTP API isteğinin Playground içinde de başarılı olacağını kesinleştirmez. Ağ desteği, uzak sunucunun yanıtı ve tarayıcı kısıtları değerlendirilmelidir. Asıl teşhis için indirme fonksiyonunun hata kodu ve mesajı incelenmelidir.

Medya Kaydı Var, Ürün Kartı Boş

Görsel Medya Kütüphanesinde bulunmasına rağmen kartta görünmüyorsa ürünün kullandığı alan kontrol edilmelidir. Bazı eklentiler öne çıkan görseli, bazıları özel bir görsel kimliğini, bazıları ise galeri dizisinin ilk öğesini kullanır. Aynı kimliği yanlış alan adına yazmak görünür bir sonuç üretmeyebilir.

Yanlış İçerik Kimliği Kullanılması

Görsel yanlış ürüne bağlanmış olabilir. Başka kurulumdan alınan sabit ID değerleri kullanılmamalı; ürün oluşturma işleminin döndürdüğü gerçek kimlik izlenmelidir. Katalog kimliği, ürün kimliği ve attachment kimliği farklı kayıtları temsil eder.

Blueprint Düzeltmesini Yeniden Gönderme

Görseller depoda mevcutsa ve sorun PHP sırasından kaynaklanıyorsa yalnızca Blueprint dosyasının güncellenmesi yeterli olabilir. Gereksiz yere aynı görselleri silip yeniden eklemek, hatanın kaynağına yönelik bir düzeltme değildir.

svn status
svn diff assets/blueprints/blueprint.json
svn commit assets/blueprints/blueprint.json -m "Fix preview image import"

Değişiklik gönderilmeden önce diff çıktısında beklenen düzenleme görülmelidir. Commit başarılı olduktan sonra WordPress.org eklenti sayfasından yeni bir önizleme başlatılmalıdır. Önceden açık olan sekmedeki veriler, güncel hazırlık işleminin baştan çalıştığını doğrulamak için yeterli değildir.

Temiz oturumda ürünlerin, katalog ilişkilerinin ve görsellerin yeniden oluştuğu kontrol edilir. Önceki denemede elle eklenen bir görsel veya düzeltilen bir ayar varsa bunların yeni oturumda da otomatik hazırlanması gerekir. Demo, yalnızca geliştiricinin açık sekmesinde değil, ilk kez gelen ziyaretçinin ortamında da tamamlanmalıdır.

WordPress.org Live Preview Özelliğini Etkinleştirme

WordPress.org önizleme belgesinde geçerli Blueprint dosyası ve public önizleme ayarı temel koşullar olarak belirtilir. Dosyanın depoda bulunmasıyla test erişimi sağlanabilir; bütün ziyaretçilere açılması ise ayrıca yapılır.

1. WordPress.org hesabına, ilgili eklentinin commit yetkisine sahip kullanıcıyla giriş yapın.
2. Eklenti sayfasını açın ve Blueprint dosyasının doğru konuma gönderildiğini kontrol edin.
3. Kullanılabilir test önizlemesini başlatın; demo kurulumu ve açılış sayfasını inceleyin.
4. Eklentinin Advanced View bölümündeki önizleme ayarını public olarak etkinleştirin.
5. Hesaba bağlı olmayan bir ziyaretçi görünümünde Live Preview düğmesinin erişilebilirliğini kontrol edin.

Test Preview yalnızca yetkili hesapta görünüyorsa bu durum, herkese açık önizlemenin etkin olduğu anlamına gelmez. Dosyanın okunması, testin başarıyla tamamlanması ve public ayarı ayrı ayrı değerlendirilmelidir.

Live Preview Düğmesi Görünmüyorsa Ne Yapılmalıdır?

Öncelikle dosyanın assets/blueprints/blueprint.json yolunda bulunduğu doğrulanmalıdır. Dosyanın yerel klasörde bulunması yeterli değildir; SVN commit işlemi tamamlanmış olmalıdır. Yanlış adlandırma veya trunk altına yerleştirme gibi konum hataları giderilmelidir.

Ardından JSON’un ayrıştırılabildiği ve Blueprint şemasına uygun olduğu kontrol edilmelidir. Geçerli JSON içinde yanlış alan konumları da bulunabilir. Örneğin kurulum seçeneklerini yanlış nesnenin içine yazmak, sözdizimi doğru olsa bile yapılandırmanın kabul edilmemesine yol açabilir.

Dosya ve test akışı doğruysa yetkili hesap, eklenti sayfasındaki public ayarı ve yeni bir oturumdan erişim incelenmelidir. Bir depo değişikliğinin sayfaya yansımasıyla ilgili gecikme olasılığı, ancak temel yapılandırma hataları elendikten sonra değerlendirilmelidir. Her görünmeme durumunu önbelleğe bağlamak, asıl hatanın gözden kaçmasına neden olur.

Başarılı Bir Katalog Demosu Nasıl Kontrol Edilir?

Katalog demosunda ürünlerin veritabanına yazılması tek başına başarı ölçütü değildir. Açılış sayfası, kartlar, görseller ve etkileşimli kontroller bir arada değerlendirilmelidir. OZD Product Catalogue örneğinde düzeltmeden sonra sandalye, masa, kitaplık ve lamba görselleri ürün kartlarına yüklenmiştir.

Ürün kartlarının görsel kontrolünden sonra filtreleme, arama ve ürün ayrıntıları denenmelidir. Sonuç bulunamayan bir arama yapıldığında kullanıcıya anlaşılır bilgi verilmesi ve filtre temizlendiğinde ürünlerin yeniden listelenmesi de test kapsamına alınmalıdır.

Dar ekranlarda ürün başlıklarının, fiyatların ve düğmelerin taşmaması gerekir. Klavye ile filtre alanlarına ulaşılabilmeli, odak konumu anlaşılabilmeli ve form kontrollerinin erişilebilir adları bulunmalıdır. Görsel görünüm düzgün olsa bile ekran okuyucunun bir alanın amacını anlayamaması kullanım sorununa yol açar.

Alternatif metinlerde gereksiz anahtar kelime tekrarından kaçınılmalıdır. Bir ürün görseli için ürünün kısa adı çoğu zaman yeterlidir. Demo ekranındaki her görsele uzun teknik açıklamalar eklemek, ekran okuyucu kullanıcısının ürünler arasında ilerlemesini zorlaştırabilir.

Demo Performansı ve Sürdürülebilirlik

Canlı önizleme, ziyaretçi eklentiyi incelemeye başlamadan önce çeşitli hazırlık işlemleri yapar. Çok sayıda büyük görsel indirmek, gereksiz eklentiler kurmak veya kullanılmayacak içerikler üretmek bu aşamayı uzatır. Demo veri seti işlevi gösterecek kadar kapsamlı, açılışı gereksiz yere ağırlaştırmayacak kadar sınırlı tutulmalıdır.

Uzak kaynakların sayısını azaltmak da bakım açısından yararlıdır. Birkaç farklı siteden alınan görsellerin her biri zaman içinde taşınabilir veya erişime kapanabilir. Geliştiricinin yönetebildiği sabit demo dosyaları, bu bağımlılıkları izlemeyi kolaylaştırır.

Eklentinin yeni sürümü yayımlandığında Blueprint yeniden sınanmalıdır. Ürün alanlarının adı, kısa kod parametreleri veya katalog ilişki yöntemi değişmişse eski demo hazırlığı artık doğru veri üretmeyebilir. Eklenti dosyalarının güncellenmesi, Blueprint içindeki özel kodu kendiliğinden güncellemez.

Sürüm değişikliklerinde en az bir temiz önizleme kurulumu yapılmalı; açılış sayfası, örnek kayıtlar ve medya eşleştirmeleri kontrol edilmelidir. Böylece ziyaretçinin karşılaştığı demo, eklentinin güncel sürümüyle tutarlı kalır.

Live Preview Yayımlama Kontrol Listesi

• Blueprint dosyası doğru ad ve SVN yoluyla yayımlandı mı?
• JSON sözdizimi ve Blueprint alanları doğrulandı mı?
• Eklenti ile gerekli bağımlılıklar doğru sırada hazırlanıyor mu?
• Demo verileri eklentinin güncel kayıt yapısıyla eşleşiyor mu?
• Ürün, katalog, sayfa ve medya kimlikleri birbirinden doğru ayrılıyor mu?
• İndirme ve medya aktarım hataları kontrol ediliyor mu?
• Ana sayfa ayarı ile açılış adresi aynı demo akışını gösteriyor mu?
• Yeni oturumda bütün hazırlık elle müdahale gerektirmeden tamamlanıyor mu?
• Arama, filtreleme ve ayrıntı bağlantıları çalışıyor mu?
• Klavye kullanımı, ekran okuyucu etiketleri ve mobil görünüm kontrol edildi mi?
• Önizleme public olarak etkinleştirildi mi?
• Eklenti güncellemelerinde demo testi bakım sürecine eklendi mi?

Sık Sorulan Sorular

WordPress Live Preview İçin Ayrı Hosting Gerekir mi?

WordPress.org üzerinden Playground ile sunulan önizleme için ayrıca klasik bir WordPress demo sunucusu kurulması gerekmez. Ancak Blueprint’in indirdiği görseller ve diğer harici kaynaklar erişilebilir adreslerde bulunmalıdır. Örnek varlıklar uygun biçimde eklentinin SVN deposunda tutulabilir.

Blueprint Dosyası WordPress Yönetim Paneline mi Yüklenir?

WordPress.org eklenti önizlemesi için dosya eklentinin SVN deposundaki assets/blueprints/blueprint.json yoluna gönderilir. Medya Kütüphanesine JSON yüklemek veya dosyayı bir blog yazısına eklemek aynı işlemi gerçekleştirmez.

Demo İçeriği Normal Eklenti Kurulumuna Eklenir mi?

Yalnızca Blueprint içinde tanımlanan demo hazırlığı, eklentinin normal kurulumunda otomatik çalışmaz. Bunun korunması için örnek ürün oluşturma işlemleri eklentinin genel etkinleştirme koduna taşınmamalıdır. Normal kullanıcı kurulumu ile önizleme veri hazırlığı ayrı tutulmalıdır.

Her Eklenti Aynı Blueprint Dosyasını Kullanabilir mi?

Ortam ayarlarının genel yapısı yeniden kullanılabilir; ancak içerik oluşturma adımları eklentiye göre değişir. Ürün türleri, tablo yapıları, meta alanları ve kısa kodlar farklı olduğundan katalog demosunun PHP kodu başka bir eklentiye doğrudan uygulanamaz.

Görseli Uzak URL ile Göstermek Yeterli mi?

Bu, eklentinin görseli nasıl kullandığına bağlıdır. Yalnızca URL kabul eden bir alan farklı çalışabilir. WordPress attachment kimliği veya öne çıkan görsel kullanan bir yapıda ise medya kaydı oluşturulmalıdır. Uzak adresi kimlik bekleyen alana yazmak doğru eşleştirme sağlamaz.

Aynı Önizleme Sekmesini Yenilemek Güncellemeyi Test Eder mi?

Sekmeyi yenilemek, Blueprint’in güncel hâlinin temiz kurulum üzerinde baştan çalıştığını her durumda doğrulamaz. Gönderimden sonra eklenti sayfasından yeni önizleme başlatılarak demo verilerinin otomatik oluştuğu kontrol edilmelidir.

Live Preview SEO Sıralamasını Doğrudan Artırır mı?

Live Preview, eklentinin denenmesini kolaylaştıran bir özelliktir. Tek başına arama sonuçlarında sıralama artışı sağlayan bir mekanizma olarak değerlendirilmemelidir. Öncelikli katkısı, kullanıcının eklentinin işlevlerini kurulum yapmadan inceleyebilmesidir.

Sonuç

WordPress eklentisine Live Preview eklemek; geçerli bir Blueprint dosyası hazırlamayı, demo verilerini doğru sırayla oluşturmayı, dosyaları SVN üzerinden yayımlamayı ve önizlemeyi herkese açık duruma getirmeyi gerektirir. Kullanılabilir bir demo için ürünlerin veya sayfaların oluşması kadar görsellerin doğru kayıtlara bağlanması ve ziyaretçinin doğrudan ilgili çıktıya ulaşması da önemlidir.

OZD Product Catalogue uygulaması, görsel ağırlıklı bir eklentide bu aşamaların birbirine bağlı olduğunu göstermektedir. Ürün kayıtları oluşmasına rağmen medya aktarımındaki hata katalog çıktısını eksik bırakabilir. Bu nedenle içerik oluşturma, görsel indirme, medya kaydı ve ürün eşleştirmesi ayrı aşamalar olarak kontrol edilmelidir.

Temiz bir oturumda tekrar kurulabilen, sınırlı örnek veri kullanan ve eklentinin temel işlevini açıkça gösteren bir önizleme sürdürülebilir bir başlangıç sağlar. Uygulama örneği, OZD Product Catalogue eklenti sayfası üzerinden incelenebilir.