Gutenberg Editörüne Özel Blok Stili Ekleme

Tarafındankomut
0 Comments

WordPress ile çalışırken en sık karşılaşılan ihtiyaçlardan biri, Gutenberg editörüne özel blok stilleri eklemektir. Müşteriler tasarımcıdan aldıkları bir mockup’ı sana gösterip “bu butonu şöyle yapabilir misin?” diye sorar, sen de arayüzden bir şey yapamazsın çünkü o özellik yoktur. İşte tam burada functions.php devreye girer. Bu yazıda Gutenberg’e özel blok stilleri eklemenin tüm yollarını, gerçek dünya senaryolarıyla birlikte ele alacağız.

Gutenberg Blok Stili Nedir?

Gutenberg editöründe bir bloğu seçtiğinde sağ panelde “Stiller” sekmesini görmüşsündür. Örneğin Buton bloğu için “Doldurulmuş” ve “Ana Hat” gibi hazır stiller gelir. İşte bu stillere sen de kendi özel stillerini ekleyebilirsin.

Blok stili eklemek şu anlama gelir: Editörde kullanıcı bir blok seçtiğinde, senin tanımladığın stil seçeneği de listede görünür. Kullanıcı bu stili seçtiğinde bloğun wrapper elementine otomatik olarak is-style-{stil-adın} CSS sınıfı eklenir. Sen de bu sınıfa istediğin CSS kurallarını yazarsın.

Bu sistem son derece temiz ve modülerdir. Tema değişse bile kullanıcının seçtiği stil bilgisi blok içeriğinde saklanır. Yani içerik taşınabilirdir.

Temel Kullanım: register_block_style Fonksiyonu

WordPress, blok stilleri kaydetmek için register_block_style() fonksiyonunu sunar. Bu fonksiyonu init hook’una bağlayarak çalıştırman gerekir.

// functions.php - Temel blok stili ekleme
function my_custom_block_styles() {
    register_block_style(
        'core/button',
        array(
            'name'  => 'gradient-outline',
            'label' => 'Degrade Çerçeve',
        )
    );
}
add_action( 'init', 'my_custom_block_styles' );

Bu kadar basit. Şimdi bu stilin CSS’ini yazman gerekiyor. Bunun için enqueue_block_editor_assets veya wp_enqueue_scripts hook’larını kullanabilirsin. Ama en doğru yol, stilin hem editörde hem ön yüzde çalışmasını sağlamaktır.

CSS Dosyası ile Blok Stilini Bağlamak

Pratikte en iyi yaklaşım, blok stillerini ayrı bir CSS dosyasında tutup hem editöre hem ön yüze yüklemektir.

// functions.php - CSS dosyasını editöre ve ön yüze yükleme
function my_block_styles_assets() {
    wp_enqueue_style(
        'my-block-styles',
        get_template_directory_uri() . '/assets/css/block-styles.css',
        array(),
        '1.0.0'
    );
}
add_action( 'wp_enqueue_scripts', 'my_block_styles_assets' );
add_action( 'enqueue_block_editor_assets', 'my_block_styles_assets' );

assets/css/block-styles.css dosyanda ise şöyle bir şey olur:

/* block-styles.css */
.wp-block-button.is-style-gradient-outline .wp-block-button__link {
    background: transparent;
    border: 2px solid transparent;
    background-clip: padding-box;
    box-shadow: 0 0 0 2px #6200ea;
    color: #6200ea;
    transition: all 0.3s ease;
}

.wp-block-button.is-style-gradient-outline .wp-block-button__link:hover {
    background: #6200ea;
    color: #ffffff;
}

Burada dikkat edilmesi gereken nokta, .is-style-gradient-outline sınıfının blok wrapper’ına eklendiğidir. Hangi elementi hedef aldığını doğru belirlemek için tarayıcının geliştirici araçlarıyla bloğun HTML yapısını incelemen gerekir.

Inline Stil ile Hızlı Prototipleme

Bazen ayrı bir CSS dosyası oluşturmadan doğrudan register_block_style içinde stil tanımlamak istersin. Bu özellikle küçük projeler veya hızlı test senaryoları için idealdir.

// functions.php - Inline stil ile blok stili ekleme
function my_inline_block_styles() {
    register_block_style(
        'core/paragraph',
        array(
            'name'         => 'callout-box',
            'label'        => 'Callout Kutu',
            'inline_style' => '
                .wp-block-paragraph.is-style-callout-box {
                    background-color: #fff3cd;
                    border-left: 4px solid #ffc107;
                    padding: 16px 20px;
                    border-radius: 4px;
                    font-size: 0.95em;
                    line-height: 1.7;
                }
            ',
        )
    );
}
add_action( 'init', 'my_inline_block_styles' );

Bu yöntem işe yarasa da büyük projelerde CSS kodunu functions.php içinde tutmak bakımı zorlaştırır. Proje büyüdükçe ayrı dosya yöntemine geçmen önerilir.

Gerçek Dünya Senaryosu: E-Ticaret Sitesi için Ürün Kartı Stilleri

Diyelim ki bir WooCommerce sitesi kuruyorsun ve müşteri birkaç farklı ürün listeleme görünümü istiyor. Gutenberg’deki core/group bloğunu ürün kartı olarak kullandığını varsayalım.

// functions.php - E-ticaret için özel grup stilleri
function ecommerce_block_styles() {
    
    // Gölgeli kart stili
    register_block_style(
        'core/group',
        array(
            'name'  => 'product-card',
            'label' => 'Ürün Kartı',
        )
    );

    // Öne çıkan ürün stili
    register_block_style(
        'core/group',
        array(
            'name'  => 'featured-product',
            'label' => 'Öne Çıkan Ürün',
        )
    );

    // İndirimli ürün bandı stili
    register_block_style(
        'core/group',
        array(
            'name'  => 'sale-badge',
            'label' => 'İndirim Etiketi',
        )
    );
}
add_action( 'init', 'ecommerce_block_styles' );

Bu stillerin CSS’i şöyle görünebilir:

/* Ürün Kartı */
.wp-block-group.is-style-product-card {
    background: #ffffff;
    border-radius: 12px;
    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08);
    overflow: hidden;
    transition: transform 0.2s ease, box-shadow 0.2s ease;
}

.wp-block-group.is-style-product-card:hover {
    transform: translateY(-4px);
    box-shadow: 0 8px 30px rgba(0, 0, 0, 0.15);
}

/* Öne Çıkan Ürün */
.wp-block-group.is-style-featured-product {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    border-radius: 16px;
    color: #ffffff;
    padding: 32px;
    position: relative;
}

.wp-block-group.is-style-featured-product::before {
    content: "⭐ ÖNE ÇIKAN";
    position: absolute;
    top: 16px;
    right: 16px;
    background: rgba(255,255,255,0.2);
    padding: 4px 12px;
    border-radius: 20px;
    font-size: 0.75em;
    font-weight: 700;
}

/* İndirim Etiketi */
.wp-block-group.is-style-sale-badge {
    border: 2px dashed #e44d26;
    border-radius: 8px;
    padding: 16px;
    position: relative;
}

.wp-block-group.is-style-sale-badge::after {
    content: "İNDİRİM";
    position: absolute;
    top: -12px;
    left: 20px;
    background: #e44d26;
    color: white;
    padding: 2px 10px;
    border-radius: 4px;
    font-size: 0.7em;
    font-weight: 800;
    letter-spacing: 1px;
}

Bu yaklaşımla içerik editörler, kodla uğraşmadan ürün kartı görünümlerini kolayca değiştirebilir.

Mevcut Bir Stili Kaldırmak: unregister_block_style

Bazen temanın veya bir plugin’in eklediği stiller kullanıcıyı karıştırır. Bunları kaldırmak için unregister_block_style() kullanırsın. Ama burada önemli bir detay var: Bu fonksiyonu init hook’unun sonrasında çağırman gerekir, aksi halde kaldırmaya çalıştığın stil henüz kayıtlı olmayabilir.

// functions.php - Gereksiz blok stillerini kaldırma
function remove_unwanted_block_styles() {
    
    // Buton bloğundaki varsayılan "Ana Hat" stilini kaldır
    unregister_block_style( 'core/button', 'outline' );
    
    // Image bloğundaki "Yuvarlak" stilini kaldır
    unregister_block_style( 'core/image', 'rounded' );
    
    // Quote bloğundaki "Büyük" stilini kaldır
    unregister_block_style( 'core/quote', 'large' );
}
add_action( 'init', 'remove_unwanted_block_styles', 20 );

Priority olarak 20 vermek iyi bir pratiktir. WordPress çekirdek stilleri ve plugin’ler genellikle 10 veya varsayılan öncelikte kayıt olur. Sen 20 vererek onlardan sonra çalıştırırsın.

Çoklu Blok için Toplu Stil Ekleme

Büyük bir temada onlarca blok stili eklemen gerekebilir. Bunları ayrı ayrı register_block_style çağrısıyla yazmak yerine bir döngü kullanmak çok daha temiz bir yapı oluşturur.

// functions.php - Toplu blok stili kaydetme
function register_all_custom_block_styles() {
    
    $block_styles = array(
        'core/heading' => array(
            array(
                'name'  => 'underline-accent',
                'label' => 'Alt Çizgi Vurgu',
            ),
            array(
                'name'  => 'gradient-text',
                'label' => 'Degrade Metin',
            ),
        ),
        'core/list' => array(
            array(
                'name'  => 'check-list',
                'label' => 'Onay Listesi',
            ),
            array(
                'name'  => 'icon-list',
                'label' => 'İkon Listesi',
            ),
        ),
        'core/separator' => array(
            array(
                'name'  => 'dotted',
                'label' => 'Noktalı',
            ),
            array(
                'name'  => 'gradient-line',
                'label' => 'Degrade Çizgi',
            ),
        ),
        'core/image' => array(
            array(
                'name'  => 'polaroid',
                'label' => 'Polaroid',
            ),
            array(
                'name'  => 'shadow-float',
                'label' => 'Gölgeli Yüzer',
            ),
        ),
    );

    foreach ( $block_styles as $block_name => $styles ) {
        foreach ( $styles as $style ) {
            register_block_style( $block_name, $style );
        }
    }
}
add_action( 'init', 'register_all_custom_block_styles' );

Bu yapı hem okunabilir hem de bakımı kolaydır. Yeni bir blok veya stil eklemek için sadece array’e bir satır ekliyorsun.

Editörde Stil Önizlemesi Göstermek

WordPress 6.0’dan itibaren blok stillerine style_data parametresi ekleyerek editörde önizleme görüntüsü tanımlayabilirsin. Bu özellikle müşterilerin editörü kullandığı projelerde büyük fark yaratır.

// functions.php - Editör önizlemeli blok stili
function my_preview_block_styles() {
    register_block_style(
        'core/button',
        array(
            'name'         => 'neon-glow',
            'label'        => 'Neon Parlaklık',
            'inline_style' => '
                .wp-block-button.is-style-neon-glow .wp-block-button__link {
                    background: transparent;
                    border: 2px solid #00ff88;
                    color: #00ff88;
                    text-shadow: 0 0 8px #00ff88;
                    box-shadow: 0 0 15px rgba(0, 255, 136, 0.4),
                                inset 0 0 15px rgba(0, 255, 136, 0.1);
                    transition: all 0.3s ease;
                }
                .wp-block-button.is-style-neon-glow .wp-block-button__link:hover {
                    background: rgba(0, 255, 136, 0.1);
                    box-shadow: 0 0 25px rgba(0, 255, 136, 0.6),
                                inset 0 0 25px rgba(0, 255, 136, 0.2);
                }
            ',
            'style_handle' => 'my-block-styles',
        )
    );
}
add_action( 'init', 'my_preview_block_styles' );

Plugin ile Gelen Blok Stillerini Özelleştirme

Yalnızca çekirdek bloklar değil, plugin’lerin kaydettiği bloklara da stil ekleyebilirsin. Örneğin WooCommerce bloklarına özel stil eklemek istiyorsan:

// functions.php - WooCommerce bloklarına özel stiller
function woocommerce_block_custom_styles() {
    
    // WooCommerce aktif mi kontrol et
    if ( ! class_exists( 'WooCommerce' ) ) {
        return;
    }

    // Ürünler bloğu için özel grid stili
    register_block_style(
        'woocommerce/product-template',
        array(
            'name'  => 'masonry-grid',
            'label' => 'Örme Izgara',
        )
    );

    // Ürün başlığı bloğu için stil
    register_block_style(
        'woocommerce/product-title',
        array(
            'name'         => 'highlighted-title',
            'label'        => 'Vurgulu Başlık',
            'inline_style' => '
                .wp-block-woocommerce-product-title.is-style-highlighted-title a {
                    background: linear-gradient(120deg, #f6d365 0%, #fda085 100%);
                    -webkit-background-clip: text;
                    -webkit-text-fill-color: transparent;
                    background-clip: text;
                    font-weight: 800;
                }
            ',
        )
    );
}
add_action( 'init', 'woocommerce_block_custom_styles', 25 );

WooCommerce blok adlarını bulmak için eklentinin src/blocks klasörüne bakabilir ya da browser’ın geliştirici araçlarında editörde oluşturulmuş blokların data-type attribute’unu inceleyebilirsin.

Blok Stillerini Koşullu Olarak Yüklemek

Performans odaklı sitelerde her sayfaya tüm blok stillerini yüklemek istemeyebilirsin. Sayfa türüne göre koşullu yükleme yapabilirsin.

// functions.php - Koşullu blok stil yükleme
function conditional_block_styles() {
    
    // Sadece tekil sayfalarda yükle
    if ( is_singular( 'post' ) ) {
        wp_enqueue_style(
            'post-block-styles',
            get_template_directory_uri() . '/assets/css/post-block-styles.css',
            array(),
            '1.0.0'
        );
    }

    // Sadece landing page şablonunda yükle
    if ( is_page_template( 'page-landing.php' ) ) {
        wp_enqueue_style(
            'landing-block-styles',
            get_template_directory_uri() . '/assets/css/landing-block-styles.css',
            array(),
            '1.0.0'
        );
    }

    // WooCommerce sayfalarında yükle
    if ( function_exists( 'is_woocommerce' ) && is_woocommerce() ) {
        wp_enqueue_style(
            'woo-block-styles',
            get_template_directory_uri() . '/assets/css/woo-block-styles.css',
            array(),
            '1.0.0'
        );
    }
}
add_action( 'wp_enqueue_scripts', 'conditional_block_styles' );

Bu yaklaşım özellikle büyük sitelerde Core Web Vitals skorlarını iyileştirmek için oldukça etkilidir.

Hata Ayıklama ve Yaygın Sorunlar

Blok stilleri bazen beklediğin gibi çalışmayabilir. İşte en sık karşılaşılan sorunlar ve çözümleri:

Stil editörde görünüyor ama ön yüzde uygulanmıyor:

  • CSS dosyasının hem wp_enqueue_scripts hem de enqueue_block_editor_assets hook’larına bağlandığından emin ol.
  • Tarayıcı cache’ini temizle. Bazen CSS önbellekte kalır.

is-style-* sınıfı oluşmuyor:

  • Blok adını doğru yazdığından emin ol. core/button yerine core/buttons yazmak gibi hatalar sık görülür.
  • WordPress ve tema sürümünü kontrol et. Bazı eski temalar init hook’unu geç çalıştırabilir.

Stiller birbirini eziyor:

  • CSS özgüllük (specificity) sorunudur. Selector’ı daha spesifik yap veya CSS değişkenleri kullan.
  • Tema stillerinin üzerine yazmak gerekiyorsa .editor-styles-wrapper prefix’ini editör tarafı için kullan.
/* Editör ve ön yüz için farklı hedefleme */

/* Ön yüz */
.wp-block-paragraph.is-style-callout-box {
    border-left: 4px solid #0073aa;
    padding-left: 20px;
}

/* Editör içi (Gutenberg editör wrapper'ı) */
.editor-styles-wrapper .wp-block-paragraph.is-style-callout-box {
    border-left: 4px solid #0073aa;
    padding-left: 20px;
}

Tema.json ile Entegrasyon

Block theme kullanıyorsan theme.json dosyası ile blok stillerini entegre etmek daha temiz bir yaklaşım sunar. Ancak functions.php yöntemi class tabanlı temalar (classic themes) için hala en geçerli yoldur.

Block theme kullanırken theme.json dosyasında tanımladığın renk paleti ve spacing değerlerini CSS değişkenleri üzerinden blok stillerinde kullanabilirsin:

/* theme.json'dan gelen CSS değişkenlerini kullanma */
.wp-block-button.is-style-brand-primary .wp-block-button__link {
    background-color: var(--wp--preset--color--primary);
    color: var(--wp--preset--color--background);
    border-radius: var(--wp--preset--spacing--small);
    font-size: var(--wp--preset--font-size--medium);
    transition: opacity 0.2s ease;
}

.wp-block-button.is-style-brand-primary .wp-block-button__link:hover {
    opacity: 0.85;
}

Bu yaklaşım, kullanıcı tema özelleştirici üzerinden renk değiştirdiğinde stilin otomatik olarak güncellenmesini sağlar.

Organizasyon: Blok Stillerini Ayrı Dosyada Tutmak

Büyük projelerde tüm blok stili kodunu functions.php içine yazmak bakımı zorlaştırır. Bunun için inc/block-styles.php gibi ayrı bir dosya oluşturup require etmek en iyi pratiktir.

// functions.php - Harici dosyayı dahil etme
if ( file_exists( get_template_directory() . '/inc/block-styles.php' ) ) {
    require_once get_template_directory() . '/inc/block-styles.php';
}

inc/block-styles.php içinde tüm register_block_style çağrıların ve ilgili asset yüklemelerin bulunur. Bu yapı ekip çalışmasında da son derece faydalıdır: Bir geliştirici blok stilleri üzerinde çalışırken diğeri functions.php‘yi değiştirmek zorunda kalmaz.

Sonuç

Gutenberg blok stilleri, içerik editörlerine güçlü bir tasarım esnekliği sunarken geliştiricilerin kontrolü elinde tutmasını sağlayan şık bir sistemdir. register_block_style fonksiyonu çok basit görünse de arkasında ciddi bir esneklik barındırır.

Özetlemek gerekirse:

  • Küçük projeler için inline stil yöntemini kullan, hızlı ve pratiktir.
  • Orta ve büyük projeler için ayrı CSS dosyası ve inc/block-styles.php organizasyonunu tercih et.
  • WooCommerce projeleri için blok adlarını doğru tespit et ve class_exists kontrolünü ihmal etme.
  • Performans kritik sitelerde koşullu yükleme yaparak gereksiz CSS’i engelle.
  • Ekip projelerinde toplu kayıt döngüsünü kullan, kod tekrarından kaçın.

Müşterilere sunarken şunu söylemeyi unutma: Bu stiller sayfa içeriğine gömülür. Kal temayı değiştirirsen stiller CSS olmadan uygulanmaya devam eder, görünmez olur ama veri kaybolmaz. Dolayısıyla bir yedekleme ve geçiş planı her zaman hazırda bulundurmalısın.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir