WordPress Tema Desteği Ekleme: add_theme_support Kullanımı

WordPress tema geliştirirken en çok kafanın karıştığı noktalardan biri, temanın hangi özellikleri desteklediğini WordPress’e bildirmektir. İşte tam burada add_theme_support() fonksiyonu devreye giriyor. Bu fonksiyon olmadan WordPress, temanızın hangi yeteneklere sahip olduğunu bilemez ve pek çok özellik sessiz sedasız devre dışı kalır.

add_theme_support() Nedir ve Neden Kullanılır?

add_theme_support(), WordPress’e “Hey, benim temam şu özellikleri destekliyor” demenin resmi yoludur. Thumbnail desteğinden özel logo alanına, HTML5 biçimlendirmesinden Gutenberg block stillerine kadar onlarca özelliği bu fonksiyonla aktif edebilirsiniz.

Fonksiyonu functions.php dosyasına doğrudan yazmak yerine, after_setup_theme hook’una bağlamak en doğru yaklaşımdır. Bunun sebebi, bu hook’un init hook’undan önce çalışması ve kullanıcı oturum bilgilerinden bağımsız olarak her istekte tetiklenmesidir.

<?php
function mytheme_setup() {
    // Buraya add_theme_support() çağrıları gelecek
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Şimdi gelin, gerçek dünya senaryoları üzerinden bu fonksiyonun kullanımlarını tek tek inceleyelim.

Temel Kullanım: Post Thumbnails (Öne Çıkan Görseller)

En yaygın kullanım senaryosu öne çıkan görsel desteğidir. Eğer bu desteği eklemezseniz, yazı düzenleme ekranında “Öne Çıkan Görsel” kutusu hiç görünmez.

<?php
function mytheme_setup() {
    // Temel thumbnail desteği
    add_theme_support( 'post-thumbnails' );
    
    // Belirli boyutlar eklemek için
    add_image_size( 'blog-thumbnail', 800, 450, true );
    add_image_size( 'hero-image', 1920, 600, true );
    add_image_size( 'card-thumbnail', 400, 300, true );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Sadece belirli post type’lar için thumbnail desteği açmak istiyorsanız, array şeklinde belirtebilirsiniz:

<?php
function mytheme_setup() {
    // Sadece post ve portfolio için thumbnail desteği
    add_theme_support( 'post-thumbnails', array( 'post', 'portfolio' ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Gerçek dünya senaryosu olarak düşünün: Bir e-ticaret sitesi yapıyorsunuz ve ürün görselleri ile blog görselleri farklı boyutlarda olacak. add_image_size() ile özel boyutlar tanımlayıp bunları template dosyalarınızda get_the_post_thumbnail() ile çağırabilirsiniz.

HTML5 Desteği Ekleme

Eski WordPress sürümleri bazı öğeleri HTML4 formatında çıktı verirdi. Bugün hala html5 desteğini eklemezseniz, arama formları, yorum formları ve galeri kısayolları eski biçimlendirme kullanır.

<?php
function mytheme_setup() {
    add_theme_support( 'html5', array(
        'search-form',
        'comment-form',
        'comment-list',
        'gallery',
        'caption',
        'style',
        'script',
    ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Bu ayarın önemini küçümsemeyin. style ve script parametrelerini eklemek, WordPress’in ve etiketlerinde gereksiz type attribute üretmesini engeller. Sayfa hızı ve temiz kod açısından fark yaratır.

Özel Logo (Custom Logo) Desteği

Tema özelleştirici üzerinden logo yüklemek için custom-logo desteğini eklemeniz gerekir. Bu özellik sayesinde kullanıcılar, tema kodu değiştirmeden sitelerinin logosunu değiştirebilir.

<?php
function mytheme_setup() {
    add_theme_support( 'custom-logo', array(
        'height'               => 100,
        'width'                => 300,
        'flex-height'          => true,
        'flex-width'           => true,
        'header-text'          => array( 'site-title', 'site-description' ),
        'unlink-homepage-logo' => true,
    ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Parametreler şu anlama gelir:

• height: Önerilen logo yüksekliği (piksel)
• width: Önerilen logo genişliği (piksel)
• flex-height: Yüksekliğin esnek olmasına izin verir
• flex-width: Genişliğin esnek olmasına izin verir
• header-text: Logo yüklendiğinde gizlenecek CSS sınıfları
• unlink-homepage-logo: Ana sayfada logonun link içermemesini sağlar (SEO açısından önemli)

Template dosyasında logoyu çağırmak için:

<?php
if ( function_exists( 'the_custom_logo' ) ) {
    the_custom_logo();
} else {
    echo '<a href="' . esc_url( home_url( '/' ) ) . '">' . get_bloginfo( 'name' ) . '</a>';
}

Özel Header ve Background Desteği

Bazı projeler, özellikle kurumsal siteler, farklı sayfalarda farklı header görselleri istiyor. custom-header ve custom-background bu ihtiyacı karşılar.

<?php
function mytheme_setup() {
    // Özel header desteği
    add_theme_support( 'custom-header', array(
        'default-image'          => get_template_directory_uri() . '/images/default-header.jpg',
        'width'                  => 1920,
        'height'                 => 400,
        'flex-width'             => true,
        'flex-height'            => true,
        'uploads'                => true,
        'random-default'         => false,
        'header-text'            => true,
        'default-text-color'     => 'ffffff',
        'wp-head-callback'       => 'mytheme_header_style',
    ) );
    
    // Özel arkaplan desteği
    add_theme_support( 'custom-background', array(
        'default-color'          => 'f8f8f8',
        'default-image'          => '',
        'default-repeat'         => 'no-repeat',
        'default-attachment'     => 'fixed',
    ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

// Header stil callback fonksiyonu
function mytheme_header_style() {
    $header_text_color = get_header_textcolor();
    
    if ( get_theme_support( 'custom-header', 'default-text-color' ) === $header_text_color ) {
        return;
    }
    ?>
    <style type="text/css">
        .site-title a,
        .site-description {
            color: #<?php echo esc_attr( $header_text_color ); ?>;
        }
    </style>
    <?php
}

Gutenberg ve Block Editor Desteği

WordPress 5.0 ile hayatımıza giren Gutenberg editörüyle birlikte yeni tema destek seçenekleri de geldi. Eğer Gutenberg uyumlu bir tema geliştiriyorsanız bunları mutlaka eklemelisiniz.

<?php
function mytheme_setup() {
    // Gutenberg için geniş ve tam genişlik hizalamalar
    add_theme_support( 'align-wide' );
    
    // Editor renk paleti (kullanıcıların seçebileceği renkler)
    add_theme_support( 'editor-color-palette', array(
        array(
            'name'  => __( 'Ana Renk', 'mytheme' ),
            'slug'  => 'primary',
            'color' => '#0073aa',
        ),
        array(
            'name'  => __( 'İkincil Renk', 'mytheme' ),
            'slug'  => 'secondary',
            'color' => '#23282d',
        ),
        array(
            'name'  => __( 'Açık Gri', 'mytheme' ),
            'slug'  => 'light-gray',
            'color' => '#f5f5f5',
        ),
    ) );
    
    // Editor font boyutları
    add_theme_support( 'editor-font-sizes', array(
        array(
            'name' => __( 'Küçük', 'mytheme' ),
            'slug' => 'small',
            'size' => 12,
        ),
        array(
            'name' => __( 'Normal', 'mytheme' ),
            'slug' => 'normal',
            'size' => 16,
        ),
        array(
            'name' => __( 'Büyük', 'mytheme' ),
            'slug' => 'large',
            'size' => 24,
        ),
        array(
            'name' => __( 'Çok Büyük', 'mytheme' ),
            'slug' => 'huge',
            'size' => 36,
        ),
    ) );
    
    // Özel renkleri devre dışı bırak (sadece palette renklerini kullan)
    add_theme_support( 'disable-custom-colors' );
    
    // Block editör stilleri
    add_theme_support( 'editor-styles' );
    add_editor_style( 'assets/css/editor-style.css' );
    
    // Karanlık editör arkaplanı
    add_theme_support( 'dark-editor-style' );
    
    // Duyarlı gömmeler
    add_theme_support( 'responsive-embeds' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Bunların dışında WordPress 5.8 ile gelen Full Site Editing (FSE) desteği için:

<?php
function mytheme_setup() {
    // Block template desteği (FSE için)
    add_theme_support( 'block-templates' );
    
    // Block template parts desteği
    add_theme_support( 'block-template-parts' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

WooCommerce Uyumluluğu İçin Tema Desteği

WooCommerce kullanan bir site geliştiriyorsanız, tema WooCommerce desteğini açıkça belirtmezse bazı özellikler çalışmaz ya da garip görünür.

<?php
function mytheme_setup() {
    // Temel WooCommerce desteği
    add_theme_support( 'woocommerce', array(
        'thumbnail_image_width' => 300,
        'single_image_width'    => 600,
        'product_grid'          => array(
            'default_rows'    => 3,
            'min_rows'        => 1,
            'max_rows'        => 6,
            'default_columns' => 3,
            'min_columns'     => 1,
            'max_columns'     => 6,
        ),
    ) );
    
    // WooCommerce galeri özellikleri
    add_theme_support( 'wc-product-gallery-zoom' );
    add_theme_support( 'wc-product-gallery-lightbox' );
    add_theme_support( 'wc-product-gallery-slider' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

WooCommerce desteği olmayan bir temada ne olur? Ürün resimleri yanlış boyutta görünür, galeri slider çalışmaz, lightbox özelliği aktif olmaz. Bir müşteri siparişi tamamladıktan sonra sizi arayıp “Ürün fotoğraflarım neden bu kadar küçük?” diye sorarsa, büyük ihtimalle bu satırları eklemeyi unutmuşsunuzdur.

Post Formats Desteği

Blog ağırlıklı siteler için farklı yazı formatları sunmak kullanıcı deneyimini zenginleştirir. Video yazısı, alıntı yazısı, ses yazısı gibi formatlar için ayrı template dosyaları oluşturabilirsiniz.

<?php
function mytheme_setup() {
    add_theme_support( 'post-formats', array(
        'aside',
        'gallery',
        'link',
        'image',
        'quote',
        'status',
        'video',
        'audio',
        'chat',
    ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Template dosyasında post formatına göre farklı içerik göstermek için:

<?php
// single.php veya content.php içinde
$format = get_post_format();

if ( $format === 'video' ) {
    // Video embed alanını göster
    get_template_part( 'template-parts/content', 'video' );
} elseif ( $format === 'quote' ) {
    // Alıntı formatını göster
    get_template_part( 'template-parts/content', 'quote' );
} else {
    // Standart içeriği göster
    get_template_part( 'template-parts/content', 'standard' );
}

Hepsini Bir Arada: Gerçek Dünya functions.php Örneği

Şimdiye kadar anlattığımız her şeyi bir müşteri projesi için nasıl bir araya getireceğimizi görelim. Orta ölçekli bir kurumsal site düşünün, blog var, WooCommerce yok ama Gutenberg aktif:

<?php
/**
 * Tema Kurulum Fonksiyonu
 * Tüm add_theme_support() çağrıları burada toplanır.
 */
function mytheme_setup() {

    /*
     * Çeviri desteği. Tema metinlerinin çevrilebilir olması için.
     */
    load_theme_textdomain( 'mytheme', get_template_directory() . '/languages' );

    /*
     * RSS feed linkleri otomatik eklenir.
     */
    add_theme_support( 'automatic-feed-links' );

    /*
     * WordPress'in sayfa başlığını yönetmesine izin ver.
     * Bu olmadan <title> tagını manuel eklemeniz gerekir.
     */
    add_theme_support( 'title-tag' );

    /*
     * Öne çıkan görsel desteği.
     */
    add_theme_support( 'post-thumbnails' );
    add_image_size( 'mytheme-hero', 1920, 700, true );
    add_image_size( 'mytheme-featured', 800, 500, true );
    add_image_size( 'mytheme-card', 400, 280, true );
    add_image_size( 'mytheme-thumb', 150, 150, true );

    /*
     * Menü konumları kaydet.
     */
    register_nav_menus( array(
        'primary'   => __( 'Ana Menü', 'mytheme' ),
        'footer'    => __( 'Alt Menü', 'mytheme' ),
        'social'    => __( 'Sosyal Medya Menüsü', 'mytheme' ),
    ) );

    /*
     * HTML5 biçimlendirmesi.
     */
    add_theme_support( 'html5', array(
        'search-form',
        'comment-form',
        'comment-list',
        'gallery',
        'caption',
        'style',
        'script',
    ) );

    /*
     * Özel logo.
     */
    add_theme_support( 'custom-logo', array(
        'height'      => 80,
        'width'       => 250,
        'flex-height' => true,
        'flex-width'  => true,
    ) );

    /*
     * Gutenberg geniş hizalama desteği.
     */
    add_theme_support( 'align-wide' );
    add_theme_support( 'responsive-embeds' );

    /*
     * Editor renk paleti - marka renklerimiz.
     */
    add_theme_support( 'editor-color-palette', array(
        array(
            'name'  => __( 'Marka Mavisi', 'mytheme' ),
            'slug'  => 'brand-blue',
            'color' => '#1a73e8',
        ),
        array(
            'name'  => __( 'Koyu Gri', 'mytheme' ),
            'slug'  => 'dark-gray',
            'color' => '#333333',
        ),
        array(
            'name'  => __( 'Açık Gri', 'mytheme' ),
            'slug'  => 'light-gray',
            'color' => '#f9f9f9',
        ),
        array(
            'name'  => __( 'Beyaz', 'mytheme' ),
            'slug'  => 'white',
            'color' => '#ffffff',
        ),
    ) );

    /*
     * Editor stilleri.
     */
    add_theme_support( 'editor-styles' );
    add_editor_style( 'assets/css/editor.css' );

    /*
     * Post formats.
     */
    add_theme_support( 'post-formats', array(
        'gallery',
        'video',
        'quote',
        'link',
    ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

Tema Desteğini Kontrol Etmek: current_theme_supports()

Bazen, bir özelliğin aktif olup olmadığını kontrol etmeniz gerekebilir. Özellikle plugin geliştirirken veya koşullu mantık yazarken bu fonksiyon hayat kurtarır.

<?php
// Thumbnail desteği var mı?
if ( current_theme_supports( 'post-thumbnails' ) ) {
    echo 'Öne çıkan görsel desteği aktif.';
}

// HTML5 içinde belirli bir özellik var mı?
if ( current_theme_supports( 'html5', 'gallery' ) ) {
    echo 'HTML5 galeri aktif.';
}

// WooCommerce desteği var mı? (Plugin uyumluluğu için)
if ( current_theme_supports( 'woocommerce' ) ) {
    // WooCommerce'e özel kodları çalıştır
}

Plugin geliştiricileri için bir gerçek dünya senaryosu: Bir slider plugin’i yazıyorsunuz ve hero image boyutunu otomatik algılaması gerekiyor. get_theme_support() ile tema ayarlarına erişebilirsiniz:

<?php
// Temanın belirlediği görsel boyutlarına eriş
$logo_support = get_theme_support( 'custom-logo' );

if ( $logo_support && isset( $logo_support[0]['width'] ) ) {
    $logo_width = $logo_support[0]['width'];
    // Bu değeri kullan
}

Sık Yapılan Hatalar ve Çözümleri

Hata 1: after_setup_theme yerine init kullanmak

add_theme_support() çağrılarını init hook’una bağlarsanız, bazı özellikler çalışmaz. Her zaman after_setup_theme kullanın.

Hata 2: title-tag desteğini unutmak

add_theme_support( 'title-tag' ) eklemeden Önceki