BU DERSİN BAŞLIKLARI
- 1 Ön İzleme Bölümü Mü? Customizer API Alanları Mı?
- 2 Customizer API Alanlarında Customizer JavaScript API Kullanımı
- 3 Temanın Canlı Ön İzleme Bölümünde (Preview) Customizer JavaScript API Kullanımı
Customizer JavaScript API ara yüzü, kaynak bakımından çok zengin bir konu değildir. Bu uygulamaya işi düşenler zannediyorum bu durumu açık bir şekilde fark etmişlerdir. Birazdan okuyacağınız yazı, oldukça uzun bir araştırma sonucu ortaya çıkmıştır. Tabi şunu da hatırlatmakta fayda var, en iyi kaynak, kaynak kodlarının kendisidir. Bu yüzden, kaynak kodlarını merak edenler, WordPress kurulumundaki wp-admin/js/customize-controls.js dosyasına bakabilirler.
Customizer JavaScript API, yönetim panelinden gidilen Görünüm->Özelleştir sayfasında kullanılan bir ara yüzdür. Bu ara yüz ile, Customizer API alanları oluşturabiliriz, bu alanları saklayabilir, koşullu işlemler yapabilir veya temamızın canlı ön izleme kısmına bir takım özellikler ekleyebiliriz.
Ön İzleme Bölümü Mü? Customizer API Alanları Mı?
Biliyorsunuz, bir WordPress temasının özelleştirme sayfasını açtığımızda, karşımıza çıkan sayfada iki ana bölüm vardır. Bunlar;
- Customizer API alanlarına ait kısım (Site kimliği, Menüler, Renkler gibi alanların olduğu ve özelleştirme sayfanın sol tarafında kalan sütundur.)
- Temanın canlı ön izleme bölümüdür.
Customizer JavaScript API kullanımı, bu bölümlerin her biri için farklı şekilde olur. Yani, API kodlamaya başlamadan önce, çalışacağımız kısıma karar vermeliyiz. Aşağıda, Customizer JavaScript API kullanımı, bu kısımların her ikisi için de ayrı ayrı anlatılmıştır.
Customizer API Alanlarında Customizer JavaScript API Kullanımı
Customizer JavaScript API ile Customizer API alanları oluşturabilir, oluşturulmuş alanları gizleyebilir veya koşullu işlemler oluşturabiliriz. Bütün bunlar için öncelikle bir js dosyası oluşturmalı ve bu dosyayı temanıza 'customize_controls_enqueue_scripts' kancası ile ve önce 'customize-controls' ve 'jquery' scriptlerinin yüklenmesi şartı ile eklemelisiniz. Aşağıda bu amaçla oluşturulmuş ve temanın ana dizinindeki js klasörün içine yerleştirilmiş, customizer-control.js dosyasının temaya eklenmesi için gereken kodlar verilmiştir:
functions.php
function ilktemam_customize_control_js() {
wp_enqueue_script( 'tuts_customizer_control', get_template_directory_uri() . '/js/customizer-control.js', array( 'customize-controls', 'jquery' ), null, true );
}
add_action( 'customize_controls_enqueue_scripts', 'ilktemam_customize_control_js' );Yukarıdaki kod ile birlikte Customizer JavaScript API kullanımı için hazır ve customizer-control.js adında bir dosyamız olur. Bu dosyada, kullanacağımız JavaScript API kodları için şöyle bir çerçeve kod oluşturuyoruz:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
// Customizer JavaScript API kodları buraya yazılır
} );
})( jQuery );Customizer JavaScript API ile, Customizer API alanlarına ulaşmak istersek şu kodları kullanırız:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
wp.customize.panel.each( function ( panel ) { /* ... */ } );
wp.customize.section.each( function ( section ) { /* ... */ } );
wp.customize.control.each( function ( control ) { /* ... */ } );
} );
})( jQuery );Customizer API Alanları Arasında Bağlantı Kurma
Aşağıdaki kod, WordPress temalarının özelleştirme sayfasında gördüğümüz “Site başlığı” adındaki kontrol alanının PHP kodudur:
$wp_customize->add_control( 'blogname', array(
'label' => __( 'Site başlığı' ),
'section' => 'title_tagline',)
);Yukarıdaki kodda da görüldüğü gibi Site başlığı alanı 'title_tagline' adındaki bir bölüme (section) aittir. Bunu öğrenmek için aşağıdaki Customizer JavaScript API kodunu da kullanabiliriz:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
// id değişkeni 'title_tagline' değerini döndürecektir
var id = wp.customize.control( 'blogname' ).section();
} );
})( jQuery );Yukarıda elde ettiğimiz id değerine ait alana (section) ulaşmak için şu kodu kullanırız:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
// id değişkeni 'title_tagline' değerini döndürecektir
var id = wp.customize.control( 'blogname' ).section();
// 'title_tagline' bölümünü döndürür
var bolum = wp.customize.section( id );
} );
})( jQuery );Aşağıdaki kod, Site başlığı adındaki kontrol alanını Menüler adındaki bölüme taşır:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
wp.customize.control( 'blogname' ).section( 'nav' );
} );
})( jQuery );Aşağıdaki kod, kimliği belirtilen bir bölümün ait olduğu panelin id değerini döndürür:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
// Site kimliği ('title_tagline') bölümünün ait olduğu panelin kimliğini döndürür
var panel = wp.customize.section('title_tagline').panel();
} );
})( jQuery );Aşağıdaki kod, bir panele veya bölüme ait alt alanları verir:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
// Bileşenler ('widgets') panelindeki bölümlerini döndürür
var sections = wp.customize.panel( 'widgets' ).sections();
// Site kimliği ('title_tagline') bölümündeki kontrol alanlarını döndürür
var controls = wp.customize.section( 'title_tagline' ).controls();
} );
})( jQuery );Site kimliği ('title_tagline') bölümündeki bütün kontrol alanlarını Menüler ('nav') bölümüne taşır:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
_.each( wp.customize.section( 'title_tagline' ).controls(), function ( control ) {
control.section( 'nav' )
;}
);
} );
})( jQuery );Panel Bölüm ve Kontrolleri Aktive/Deaktive Etmek
Customizer API alanlarını saklamak veya tekrar göstermek için activate() ve deactivate() metotları kullanılır. Aşağıdaki kodlar, Customizer API alanlarını aktive veya deaktive eder:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
wp.customize.section( 'nav' ).deactivate(); // Menüler bölümünü slide up efekti ile saklar
wp.customize.section( 'nav' ).activate({ duration: 1000 }); // Menüler bölümünü slide down efekti ile gösterir
wp.customize.section( 'colors' ).deactivate({ duration: 0 }); // Renkler bölümünü saklar
wp.customize.section( 'nav' ).deactivate({ completeCallback:
function () {
wp.customize.section( 'colors' ).activate(); // Menüler bölümü saklanınca Renkler bölümünü gösterilir.
}
});
} );
})( jQuery );Costomizer API Alanına Focuslama
Aşağıdaki kod, fare imlecini Site başlığı alanına taşır yani Site başlığı alanını focuslar:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
wp.customize.control( 'blogname' ).focus();
} );
})( jQuery );Aşağıdaki kod, fare imlecini Site kimliği bölümüne focuslar:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
wp.customize.section( 'title_tagline' ).focus();
} );
})( jQuery );Bir Customizer API alanına focuslamanın bir diğer yolu URL ifadeleri kullanmaktır. Aşağıda verilen URL ifadeleri ilgili alanlara focuslar:
…/wp-admin/customize.php?autofocus[panel]=widgets: “Bileşenler” paneline focuslar…/wp-admin/customize.php?autofocus[section]=colors: “Renkler” bölümüne focuslar…/wp-admin/customize.php?autofocus[control]=blogname: “Site başlığı” kontrolüne focuslar
Customizer API Alanlarının Menü Sıralaması (Priority)
Aşağıdaki kodda, Customizer API alanlarının menü sıralamasını değiştiren örnekler verilmiştir:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
// 'sira' değişkeni, "Bileşenler" panelinin sıra numarasını (110) döndürür
var sira = wp.customize.panel( 'widgets' ).priority(); // returns 110 by default
// "Bileşenler" panelini, sıra numarasını 1 olan yere taşır
wp.customize.panel( 'widgets' ).priority( 1 );
} );
})( jQuery );Customizer API Alanları İçin JavaScript Örnekleri
1- Customizer JavaScript API ile alanlar oluşturma:
Aşağıdaki kod, Customizer JavaScript API ile bir panel, bu panele ait bir bölüm ve bu bölüme ait bir kontrol alanı oluşturur:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
// Bir panel oluşturuyoruz.
wp.customize.panel.add(
new wp.customize.Panel('deneme_paneli', {
title: 'DENEME',
})
);
// Bir bölüm oluşturuyoruz.
wp.customize.section.add(
new wp.customize.Section('deneme_bolumu', {
title: 'Deneme Bölümü',
panel: 'deneme_paneli',
customizeAction: 'Deneme amaçlı aluşturulmuştur.'
})
);
// Bit ayar oluşturuyoruz.
var setting = new wp.customize.Setting( 'deneme_ayari', 'varsayılan değer', { transport: 'postMessage' } );
// Bit text inputu oluşturuyoruz.
wp.customize.control.add(
new wp.customize.Control('deneme_kontorlu', {
type: 'text',
setting: setting,
section: 'deneme_bolumu',
label: 'Buraya birşeyler yaz.'
})
);
} );
})( jQuery );2- Customizer JavaScript API ile oluşturulan bir kontrol alanına event ekleme
Aşağıdaki kod, checkbox tipinde bir input kutucuğu oluşturur ve bu kutucuk işaretliyken “Site başlığı” alanını gizler:
js/customizer-control.js
(function( $ ) {
wp.customize.bind( 'ready', function() {
var ayar_alani = new wp.customize.Setting( 'basligi_gizle', false, { transport: 'postMessage' } );
// Bir checkbox kontrolü ekler.
wp.customize.control.add(
new wp.customize.Control('baslik_gizlensin_mi', {
type: 'checkbox',
setting: ayar_alani,
section: 'title_tagline',
label: 'Site başlığını sakla',
})
);
$('li#customize-control-baslik_gizlensin_mi input').on('click', function(){
// Başlığı gizleyen kutucuk işaretli ise 'Site başlığı' gizlenir, yoksa gösterilir
if( wp.customize.control('baslik_gizlensin_mi').setting.get() ) { wp.customize.control( 'blogname' ).activate(); }
else { wp.customize.control( 'blogname' ).deactivate(); }
wp.customize.state( 'saved' ).set( false ); // Yayımla butonunu aktifleştirir
});
} );
})( jQuery );Temanın Canlı Ön İzleme Bölümünde (Preview) Customizer JavaScript API Kullanımı
Bu başlık altında bahsedeceğimiz JavaScript kodları, Görünüm->Özelleştir sayfasında, temanın canlı ön izleme kısmını ilgilendiriyor.
Bir JavaScript Dosyası Oluştur
Customizer JavaScript API ara yüzünü, canlı ön izleme bölümünde kullanabilmek için, customize-preview.js adında bir js dosyası oluşturuyoruz. Tabi siz dilerseniz bu dosya için başka bir isim kullanabilirsiniz. Ben, customizer-preview.js dosyasını, temamızın ana dizininde ve js adlı bir klasörün içinde oluşturduğumuz kabul ediyorum.
Dosyayı oluşturduktan sonra, 'customize_preview_init' kancasını kullanarak ve 'customize-preview' kütüphanesi şartı ile bu dosyayı temamıza tanıtmamız gerekecek. Bunun için functions.php dosyasına gidip şu kodları yapıştırıyoruz:
functions.php
function ilktemam_customize_preview_js() {
wp_enqueue_script( 'ilktemam_customize_preview', get_template_directory_uri() . '/js/customize-preview.js', array( 'customize-preview' ), null, true );
}
add_action( 'customize_preview_init', 'ilktemam_customize_preview_js' );Canlı Ön İzleme Alanında Customizer JavaScript API Örnekleri
Peki customize-preview.js ile neler yapabiliriz? Sizlere fikir vermesi açısından, bu dosya ile yapılabilecek işlerden bir kaç örnek vermek istiyorum:
Selective Refresh Ekleme
Aşağıdaki kod,WordPress temalarında bulunan bazı standart Customizer API ayarlarına selective refresh özelliği ekler:
js/customize-preview.js
( function( $ ) {
$(document).ready(function(){
// Site kimliğini canlı ayarlar...
wp.customize( 'blogname', function( value ) {
value.bind( function( newval ) {
$( '#site-title a' ).html( newval ); // "#site-title a" seçicisini kendi temanıza uygun şekilde değiştirmeyi unutmayın
} );
} );
// Sloganı canlı ayarlar...
wp.customize( 'blogdescription', function( value ) {
value.bind( function( newval ) {
$( '.site-description' ).html( newval ); // ".site-description" seçicisini kendi temanıza uygun şekilde değiştirmeyi unutmayın
} );
} );
// Üst kısım text rengini canlı ayarlar...
wp.customize( 'header_textcolor', function( value ) {
value.bind( function( newval ) {
$('#site-title a').css('color', newval ); // "#site-title a" seçicisini kendi temanıza uygun şekilde değiştirmeyi unutmayın
} );
} );
// Arka plan rengini canlı ayarlar...
wp.customize( 'background_color', function( value ) {
value.bind( function( newval ) {
$('body').css('background-color', newval );
} );
} );
} );
} )( jQuery );Yukarıdaki kodun çalışabilmesi için, temanızda şu 3 ayarın da yapılmış olması gereklidir:
- Kodlarda kimlikleri verilen (
'blogname', 'blogdescription', 'header_textcolor', 'background_color') Customizer API kontrol alanlarının oluşturulmuş olması gereklidir. - Bu ayarlar için temanızda oluşturduğunuz HTML elemanlarının, yukarıdaki kodda gördüğünüz
idveyaclassdeğerlerine sahip olması gerekmektedir. - Bu koddaki kontrollerin ayarlarında,
'transport'argümanının'postMessage'değeri almış olması gerekmektedir. Eğer, bu durumdan emin değilseniz, aşağıdaki kodlar bu ayarlara'postMessage'özelliği ekler:
functions.php
function ilktemam_customize_register( WP_Customize_Manager $wp_customize ) {
$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';
$wp_customize->get_setting( 'background_color' )->transport = 'postMessage';
}
add_action( 'customize_register', 'ilktemam_customize_register' );Temanın Ön İzlemesinde Canlı Düzenleme Butonu Oluşturma
Tema, canlı ön izlemede iken, başlık ve slogan bölümünde görünecek birer buton oluşturacağız ve bu butonlara tıklandığında, temanın başlık ve sloganını düzenleyen kontrol alanlarına gidilecek. Bunu başarmak için, hem Customizer API alanları için hem de canlı ön izleme için JavaScript kodlamamız gerekecek.
JavaScript API kodlamaya geçmeden önce, temamızın header.php sayfasına, sadece temamız canlı ön izlemede iken görünecek iki buton yerleştirelim:
header.php
<h1 class="site-title">
<a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>
</h1>
<?php if ( is_customize_preview() ) : // sadece canlı önizlemede iken ?>
<button class="site-basligini-duzenle" data-control='{"name":"blogname" }'><?php esc_html_e( 'Başlığı Düzenle', 'textdomain' ); ?></button>
<?php endif; ?>
<br />
<br />
<p class="site-description">
<?php bloginfo( 'description' ); ?>
</p>
<?php if ( is_customize_preview() ) : // sadece canlı önizlemede iken ?>
<button class="slogani-duzenle" data-control='{"name":"blogdescription"}'><?php esc_html_e( 'Sloganı Düzenle', 'textdomain' ); ?></button>
<?php endif; ?>Oluşturduğumuz butonlardan ilki Site başlığı ikincisi de Slogan alanına götürecek. Butonlara eklediğimiz class="site-basligini-duzenle" ve class="slogani-duzenle" sınıfları, bu butonlara JavaScript ile ulaşmak için kullanılacak.
Yine butonlara eklediğimiz data-control='{"name":"blogname" }' ve data-control='{"name":"blogdescription"}' özellikleri ile ulaşacağımız alanların kimlik değerlerini kaydettik. Bu değerleri, JavaScript API’ye, butonların hangi Customizer API alanına gitmek istediğini söylemek için kullanacağız.
Yukarıdaki kod ile eklediğimiz botunlar, temamızın özelleştirme sayfasında şöyle görünecektir:
Artık Customizer JavaScript API kodlarına geçebiliriz. Öncelikle, canlı ön izleme kısmı ile ilgili kodları oluşturuyoruz. Bunun için biraz önce temamıza eklediğimiz 'customize-preview.js' dosyasını kullanıyoruz:
js/customize-preview.js
;(function($){
$(document).ready(function(){
var customize = wp.customize;
$( '.site-basligini-duzenle' ).on( 'click', function(){
customize.preview.send( 'preview-edit', $( this ).data( 'control' ) );
});
$( '.slogani-duzenle' ).on( 'click', function(){
customize.preview.send( 'preview-edit-2', $( this ).data( 'control' ) );
});
});
})(jQuery)Yukarıdaki kodlar, oluşturduğumuz butonlara tıklandığında, bu butonların data-control değerlerini gönderir. Peki nereye gönderir? Dananın kuyruğunun koptuğu yer de işte burasıdır sayın okuyucum. Yukarıdaki kod, butonların data-control değerlerini Customizer API alanlarına ait JavaScript dosyasına gönderir. Hani yukarıda customizer-control.js adında bir dosya oluşturmuştuk, işte ona gönderir. Ben bu dersin başını okumadım diyorsanız, bu dosyayı temanın ana dizininde bir js klasörü içinde tekrar oluşturalım ve aşağıdaki kodlar ile temamıza ekleyelim:
functions.php
function ilktemam_customize_control_js() {
wp_enqueue_script( 'tuts_customizer_control', get_template_directory_uri() . '/js/customizer-control.js', array( 'customize-controls', 'jquery' ), null, true );
}
add_action( 'customize_controls_enqueue_scripts', 'ilktemam_customize_control_js' );Şimdi customize-preview.js dosyasından gelen bilgileri alalım ve bu bilgilere göre butonlara tepki verelim:
js/customizer-control.js
;(function ($, api) {
api.bind('ready', function () {
// customize-preview.js dosyasından gelen bilgi fonksiyonun data parametresinde yüklü
api.previewer.bind( 'preview-edit', function( data ) {
// Butonların data-control değerindeki 'name' değerini aldık
var control = api.control( data.name );
control.focus({
completeCallback : function() {
setTimeout( function() {
control.container.addClass("titre");
}, 300 );
}
} );
} );
});
})(jQuery, wp.customize);Yukarıdaki kod, bir butona tıklandığında, butonun belirttiği yeri düzenleyen Customizer API alanını focuslar ve bu alana "titre" adında bir CSS sınıfı ekler. Dilerseniz bu sınıfı kullanarak, biraz da jQuery ile focuslanan alanı titretebilirsiniz.
1 yorum: “5.3 Customizer JavaScript API”