WordPress’te Inline JavaScript Ekleme: wp_add_inline_script Kullanımı

Tarafındankomut
0 Comments

WordPress geliştirme sürecinde JavaScript yönetimi, özellikle büyük projelerde ciddi bir karmaşıklık yaratabilir. Harici script dosyaları her zaman çözüm değildir; bazen dinamik veriler, koşullu yüklemeler veya küçük kod parçacıkları için inline JavaScript’e ihtiyaç duyarsınız. İşte tam bu noktada wp_add_inline_script() fonksiyonu devreye girer ve hayatınızı kolaylaştırır.

wp_add_inline_script Nedir ve Neden Kullanmalısınız?

wp_add_inline_script(), WordPress’in script yönetim sistemine entegre şekilde çalışan, kayıtlı bir script’e inline JavaScript kodu eklemenizi sağlayan bir fonksiyondur. WordPress 4.5 sürümüyle birlikte geldi ve wp_enqueue_scripts sisteminin doğal bir parçası haline geldi.

Peki neden bu fonksiyonu kullanmalısınız? Düşünün, bir tema veya eklenti geliştiriyorsunuz ve kullanıcının ayarlar panelinden belirlediği renk kodlarını, API anahtarlarını veya dinamik konfigürasyon verilerini JavaScript’e aktarmanız gerekiyor. Bunun için ayrı bir JS dosyası oluşturmak mantıklı değil, çünkü bu veriler her kullanıcı veya sayfa için değişiyor. wp_localize_script() alternatif olsa da sadece JSON formatında veri aktarımına odaklanır. wp_add_inline_script() ise sizi bu kısıtlamadan kurtararak tam bir JavaScript kodu yazmanıza imkan tanır.

Ana avantajları şunlardır:

  • Bir script’in bağımlılık sıralamasına uygun şekilde önce veya sonra ekleme yapabilirsiniz
  • wp_localize_script()‘ten farklı olarak herhangi bir JavaScript kodu ekleyebilirsiniz, sadece obje tanımlamayla sınırlı değilsiniz
  • WordPress’in script kuyruğuyla tam entegrasyon sayesinde aynı handle için birden fazla inline kod eklenebilir
  • Performans açısından ek HTTP isteği oluşturmaz

Fonksiyon Parametreleri

wp_add_inline_script( $handle, $data, $position ) şeklinde kullanılır.

  • $handle: Inline script’i bağlamak istediğiniz kayıtlı script’in adı (string). Bu, wp_register_script() veya wp_enqueue_script() ile kayıt ettiğiniz handle adıdır.
  • $data: Eklemek istediğiniz JavaScript kodu (string). Burada tag’leri kullanmayın, sadece saf JavaScript yazın.
  • $position: Kodun nereye ekleneceği (string). 'before' veya 'after' değerlerini alır. Varsayılan değer 'after'dir.

Geri dönüş değeri olarak başarılı olursa true, başarısız olursa false döner. Handle geçerli değilse ya da script sistemde kayıtlı değilse false döner.

Temel Kullanım Örneği

İlk olarak en basit kullanım şeklini görelim. Diyelim ki sitenize özel bir Google Maps entegrasyonu yapıyorsunuz ve API anahtarınızı JavaScript’e aktarmanız gerekiyor:

function mytheme_enqueue_maps_script() {
    wp_enqueue_script(
        'google-maps-init',
        get_template_directory_uri() . '/js/maps-init.js',
        array( 'jquery' ),
        '1.0.0',
        true
    );

    $maps_config = array(
        'apiKey'    => get_option( 'mytheme_maps_api_key' ),
        'lat'       => get_option( 'mytheme_default_lat', '41.0082' ),
        'lng'       => get_option( 'mytheme_default_lng', '28.9784' ),
        'zoom'      => intval( get_option( 'mytheme_default_zoom', 12 ) ),
    );

    $inline_script = 'var MapsConfig = ' . wp_json_encode( $maps_config ) . ';';

    wp_add_inline_script( 'google-maps-init', $inline_script, 'before' );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_maps_script' );

Bu örnekte 'before' parametresini kullandık. Yani inline script, maps-init.js dosyası yüklenmeden hemen önce çalışacak. Bu kritik bir nokta: JavaScript dosyanız MapsConfig değişkenine ihtiyaç duyuyorsa, o değişkenin önce tanımlanmış olması gerekir.

WooCommerce ile Gerçek Dünya Senaryosu

WooCommerce projelerinde sıklıkla karşılaşılan bir senaryo: Sepet sayfasında dinamik hesaplamalar için müşteriye özel veriler aktarımı. Örneğin kargo hesaplayıcı:

function woo_shipping_calculator_inline_script() {
    if ( ! is_cart() && ! is_checkout() ) {
        return;
    }

    wp_enqueue_script(
        'woo-shipping-calc',
        plugin_dir_url( __FILE__ ) . 'js/shipping-calculator.js',
        array( 'jquery', 'wc-cart' ),
        '2.1.0',
        true
    );

    $current_user = wp_get_current_user();
    $cart = WC()->cart;

    $shipping_data = array(
        'cartTotal'      => $cart->get_cart_total(),
        'cartWeight'     => $cart->get_cart_contents_weight(),
        'freeShipping'   => get_option( 'woocommerce_free_shipping_threshold', 500 ),
        'userCountry'    => $current_user->ID ? get_user_meta( $current_user->ID, 'billing_country', true ) : 'TR',
        'nonce'          => wp_create_nonce( 'woo_shipping_nonce' ),
        'ajaxUrl'        => admin_url( 'admin-ajax.php' ),
        'currency'       => get_woocommerce_currency_symbol(),
    );

    wp_add_inline_script(
        'woo-shipping-calc',
        'window.WooShippingData = ' . wp_json_encode( $shipping_data ) . ';',
        'before'
    );

    // Script sonrasinda da ek bir init komutu ekleyelim
    wp_add_inline_script(
        'woo-shipping-calc',
        'jQuery(document).ready(function($){ WooShippingCalc.init(); });',
        'after'
    );
}
add_action( 'wp_enqueue_scripts', 'woo_shipping_calculator_inline_script' );

Burada dikkat edilmesi gereken önemli bir nokta: Aynı handle için hem 'before' hem de 'after' konumunda inline script ekleyebilirsiniz ve bunlar birbirinin üstüne yazmaz, birikimlildir.

Birden Fazla Inline Script Birikimliliği

WordPress’in bu fonksiyonun güçlü özelliklerinden biri, aynı handle için birden fazla wp_add_inline_script() çağrısı yapabilmenizdir. Kodlar sırayla birikir:

function mytheme_analytics_setup() {
    wp_enqueue_script(
        'site-analytics',
        get_template_directory_uri() . '/js/analytics.js',
        array(),
        '1.5.0',
        true
    );

    // Temel konfigürasyon
    wp_add_inline_script(
        'site-analytics',
        'var AnalyticsConfig = { debug: false, version: "1.5" };',
        'before'
    );

    // Sayfa tipine göre ek veri
    if ( is_single() ) {
        $post_data = array(
            'postId'     => get_the_ID(),
            'postType'   => get_post_type(),
            'author'     => get_the_author_meta( 'display_name' ),
            'categories' => wp_get_post_categories( get_the_ID(), array( 'fields' => 'names' ) ),
        );

        wp_add_inline_script(
            'site-analytics',
            'AnalyticsConfig.pageData = ' . wp_json_encode( $post_data ) . ';',
            'before'
        );
    }

    // WooCommerce aktifse e-ticaret verisi ekle
    if ( class_exists( 'WooCommerce' ) && is_product() ) {
        global $product;
        $ecommerce_data = array(
            'productId'    => $product->get_id(),
            'productName'  => $product->get_name(),
            'productPrice' => $product->get_price(),
            'sku'          => $product->get_sku(),
        );

        wp_add_inline_script(
            'site-analytics',
            'AnalyticsConfig.ecommerce = ' . wp_json_encode( $ecommerce_data ) . ';',
            'before'
        );
    }

    // Analytics'i başlat
    wp_add_inline_script(
        'site-analytics',
        'document.addEventListener("DOMContentLoaded", function() { SiteAnalytics.init(AnalyticsConfig); });',
        'after'
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_analytics_setup' );

Bu yaklaşım, modüler bir yapı kurmanızı sağlar. Her koşul kendi inline script bloğunu ekler ve WordPress bunları doğru sırayla çıktı verir.

Admin Paneli için wp_add_inline_script Kullanımı

wp_add_inline_script() sadece ön yüz için değil, admin paneli için de kullanılabilir. Bir eklenti geliştiriyorsanız ve ayarlar sayfanızda dinamik davranış eklemeniz gerekiyorsa:

function myplugin_admin_scripts( $hook ) {
    // Sadece kendi ayarlar sayfamizda calis
    if ( 'settings_page_myplugin-settings' !== $hook ) {
        return;
    }

    wp_enqueue_script(
        'myplugin-admin-settings',
        plugin_dir_url( __FILE__ ) . 'admin/js/settings.js',
        array( 'jquery', 'wp-color-picker' ),
        MYPLUGIN_VERSION,
        true
    );

    // Mevcut ayarlari JS'e aktar
    $current_settings = array(
        'primaryColor'   => get_option( 'myplugin_primary_color', '#0073aa' ),
        'fontSize'       => get_option( 'myplugin_font_size', '16' ),
        'enableFeatureA' => get_option( 'myplugin_feature_a', '1' ),
        'enableFeatureB' => get_option( 'myplugin_feature_b', '0' ),
        'maxItems'       => intval( get_option( 'myplugin_max_items', 10 ) ),
        'restUrl'        => rest_url( 'myplugin/v1/' ),
        'restNonce'      => wp_create_nonce( 'wp_rest' ),
    );

    wp_add_inline_script(
        'myplugin-admin-settings',
        'var MyPluginAdmin = ' . wp_json_encode( $current_settings ) . ';',
        'before'
    );

    // Renk secici baslangici
    wp_add_inline_script(
        'myplugin-admin-settings',
        '
        jQuery(document).ready(function($) {
            $(".myplugin-color-picker").wpColorPicker({
                defaultColor: MyPluginAdmin.primaryColor,
                change: function(event, ui) {
                    MyPluginAdmin.primaryColor = ui.color.toString();
                }
            });
        });
        ',
        'after'
    );
}
add_action( 'admin_enqueue_scripts', 'myplugin_admin_scripts' );

wp_localize_script ile Karşılaştırma ve Birlikte Kullanım

wp_localize_script() sadece JavaScript objesi olarak veri aktarımı yapabilirken, wp_add_inline_script() tam anlamıyla kod yazmanıza izin verir. Ancak ikisini birlikte de kullanabilirsiniz:

function mytheme_combined_approach() {
    wp_enqueue_script(
        'mytheme-main',
        get_template_directory_uri() . '/js/main.js',
        array( 'jquery' ),
        '3.0.0',
        true
    );

    // wp_localize_script ile basit veri aktarimi
    wp_localize_script( 'mytheme-main', 'ThemeData', array(
        'ajaxUrl'  => admin_url( 'admin-ajax.php' ),
        'nonce'    => wp_create_nonce( 'theme_nonce' ),
        'siteUrl'  => get_site_url(),
        'isLoggedIn' => is_user_logged_in() ? 'true' : 'false',
    ));

    // wp_add_inline_script ile gercek JS kodu ekle
    // Bu tur mantiği wp_localize_script ile yazamazsiniz
    $custom_js = '
    (function() {
        "use strict";
        var cookieConsent = localStorage.getItem("cookie_consent");
        if (!cookieConsent) {
            document.addEventListener("DOMContentLoaded", function() {
                var banner = document.getElementById("cookie-banner");
                if (banner) {
                    banner.style.display = "block";
                    banner.setAttribute("aria-hidden", "false");
                }
            });
        }
        
        // Performans izleme
        if (window.performance && window.performance.timing) {
            window.addEventListener("load", function() {
                var loadTime = window.performance.timing.loadEventEnd 
                             - window.performance.timing.navigationStart;
                console.log("Sayfa yükleme süresi: " + loadTime + "ms");
            });
        }
    })();
    ';

    wp_add_inline_script( 'mytheme-main', $custom_js, 'after' );
}
add_action( 'wp_enqueue_scripts', 'mytheme_combined_approach' );

Önemli not: wp_localize_script() çağrısının wp_add_inline_script() ile 'before' pozisyonundaki çağrıdan önce geldiğinden emin olun. WordPress, wp_localize_script() çıktısını her zaman 'before' inline script’lerinden önce yerleştirir. Bu sıralamaya dikkat etmezseniz beklenmedik davranışlarla karşılaşabilirsiniz.

Güvenlik: Doğru Veri Sanitizasyonu

Bu fonksiyonu kullanırken güvenlik kritik öneme sahiptir. Kullanıcıdan gelen veya veritabanından çekilen verileri doğrudan string concatenation ile JS’e aktarmayın:

function mytheme_user_profile_script() {
    if ( ! is_user_logged_in() ) {
        return;
    }

    wp_enqueue_script(
        'user-profile-js',
        get_template_directory_uri() . '/js/user-profile.js',
        array( 'jquery' ),
        '1.0.0',
        true
    );

    $current_user = wp_get_current_user();

    // YANLIS YAKLASIM - XSS acigi olusturabilir:
    // $inline = 'var userName = "' . $current_user->display_name . '";';

    // DOGRU YAKLASIM - wp_json_encode her zaman kullanin:
    $user_data = array(
        'displayName' => sanitize_text_field( $current_user->display_name ),
        'email'       => sanitize_email( $current_user->user_email ),
        'role'        => implode( ',', $current_user->roles ),
        'avatarUrl'   => esc_url( get_avatar_url( $current_user->ID ) ),
        'profileUrl'  => esc_url( get_edit_user_link( $current_user->ID ) ),
        'meta'        => array(
            'bio'      => sanitize_textarea_field( get_user_meta( $current_user->ID, 'description', true ) ),
            'location' => sanitize_text_field( get_user_meta( $current_user->ID, 'location', true ) ),
        ),
    );

    // wp_json_encode otomatik olarak escape islemi yapar
    wp_add_inline_script(
        'user-profile-js',
        'var CurrentUser = ' . wp_json_encode( $user_data ) . ';',
        'before'
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_user_profile_script' );

Güvenlik kuralları:

  • Her zaman wp_json_encode() kullanın, json_encode() değil. WordPress’in versiyonu ek güvenlik kontrolleri içerir.
  • Veritabanından gelen string verileri uygun WordPress sanitizasyon fonksiyonlarıyla temizleyin
  • URL’leri esc_url() ile escape edin
  • Kullanıcı rolü ve yeteneklerini kontrol edin, herkesin görmemesi gereken verileri göndermekten kaçının
  • Nonce değerlerini AJAX çağrıları için mutlaka ekleyin

Koşullu Yükleme ve Performans Optimizasyonu

Her sayfada her şeyi yüklememek, iyi bir WordPress geliştirici alışkanlığıdır:

function mytheme_conditional_inline_scripts() {

    // Slider sadece ana sayfada
    if ( is_front_page() ) {
        wp_enqueue_script( 'slick-slider', get_template_directory_uri() . '/js/slick.min.js', array( 'jquery' ), '1.8.1', true );

        $slider_config = array(
            'autoplay'       => (bool) get_theme_mod( 'slider_autoplay', true ),
            'autoplaySpeed'  => intval( get_theme_mod( 'slider_speed', 3000 ) ),
            'dots'           => (bool) get_theme_mod( 'slider_dots', true ),
            'arrows'         => (bool) get_theme_mod( 'slider_arrows', false ),
            'slidesToShow'   => intval( get_theme_mod( 'slider_count', 1 ) ),
        );

        wp_add_inline_script(
            'slick-slider',
            'var SliderConfig = ' . wp_json_encode( $slider_config ) . ';',
            'before'
        );

        wp_add_inline_script(
            'slick-slider',
            'jQuery(document).ready(function($){ $(".hero-slider").slick(SliderConfig); });',
            'after'
        );
    }

    // Iletisim formu sadece iletisim sayfasinda
    if ( is_page( 'iletisim' ) || is_page( 'contact' ) ) {
        wp_enqueue_script( 'contact-form-js', get_template_directory_uri() . '/js/contact.js', array( 'jquery' ), '1.0.0', true );

        $form_config = array(
            'ajaxUrl'        => admin_url( 'admin-ajax.php' ),
            'nonce'          => wp_create_nonce( 'contact_form_nonce' ),
            'successMessage' => __( 'Mesajınız gönderildi!', 'mytheme' ),
            'errorMessage'   => __( 'Bir hata oluştu, lütfen tekrar deneyin.', 'mytheme' ),
            'recaptchaKey'   => get_option( 'mytheme_recaptcha_site_key' ),
        );

        wp_add_inline_script(
            'contact-form-js',
            'var ContactFormConfig = ' . wp_json_encode( $form_config ) . ';',
            'before'
        );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_conditional_inline_scripts' );

Yaygın Hatalar ve Çözümleri

Geliştirme sürecinde en sık karşılaşılan sorunlar:

Handle kayıtlı değilse fonksiyon çalışmaz. wp_add_inline_script() çağrısından önce o handle’ın wp_register_script() veya wp_enqueue_script() ile sisteme eklenmiş olması şarttır. Bu hatayı debug etmek için wp_script_is( 'handle-adi', 'registered' ) kullanabilirsiniz.

tag’leri kullanmayın. $data parametresine veya tag’leri yazmayın. WordPress bunları otomatik olarak ekler. Tag koyarsanız geçersiz HTML çıktısı elde edersiniz.

Position parametresini göz ardı etmeyin. Script dosyanızın içinde kullandığınız global değişkenler önce tanımlanmalı. Eğer inline script’inizde bir değişken tanımlıyor ve JS dosyanız bunu kullanıyorsa 'before' kullanın. Tersi durumda 'after'.

Çoklu eklenti çakışmaları. Birden fazla eklenti aynı handle’ı kullanıyorsa inline script’ler beklenmedik şekilde birikebilir. Kendi handle isimlerinizi benzersiz tutun.

Sonuç

wp_add_inline_script(), WordPress JavaScript yönetiminde gerçek anlamda güçlü bir araçtır. wp_localize_script() ile kıyaslandığında çok daha esnek bir yapı sunar; tam JavaScript kodu yazabilir, koşullu mantık ekleyebilir ve aynı script için birden fazla inline blok oluşturabilirsiniz.

Pratikte en iyi sonucu almak için şu noktaları aklınızda tutun: Her zaman wp_json_encode() ile güvenli veri aktarımı yapın, koşullu yüklemelerle gereksiz kod yükünden kaçının, 'before' ve 'after' parametrelerini bağımlılık sırasına göre seçin ve handle’larınızı benzersiz tutun.

Büyük tema veya eklenti projelerinde bu fonksiyon, PHP’den JavaScript’e köprü kurmanın en temiz ve WordPress standartlarına en uygun yoludur. Script kuyruğuyla tam entegrasyon sayesinde hem önbellek hem de bağımlılık yönetimi sorunsuz çalışır. Bir sonraki projenizde inline script ihtiyacı duyduğunuzda doğrudan HTML’e tag’i gömmek yerine bu fonksiyonu tercih edin. Hem kodunuz daha temiz kalır hem de WordPress’in altyapısıyla uyumlu çalışırsınız.

Bir yanıt yazın

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