5.2 Customizer API’nin İşimizi Kolaylaştıran Araçları

BU DERSİN BAŞLIKLARI

1 Koşullu Customizer API Alanları
2 Seçimli Yükleme (Selective Refresh)
3 Verileri Doğrulama (Validate) ve Filtreleme (Sanitize)
4 JavaScript Doğrulaması – Tarayıcı Doğrulaması
5 Bildirimler

Koşullu Customizer API Alanları

Customizer API uygulaması ile dilediğimiz bölüme (section) ya da kontrole, koşullu gösterim özelliği ekleyebiliyoruz (WordPress 4.0 ve sonrası için). Yani, Customizer API alanlarını, temamızın sadece belli bir sayfası ya da sayfaları ön izlemede iken görünecek şekilde ayarlayabiliyoruz.

Örneğin, Customizer API ile, sadece ana sayfayı ilgilendiren bir bölüm ya da kontrol alanı oluşturduk diyelim. Bu alanı, yönetim panelinin Görünüm->Özelleştir sayfasında, sadece temanın ana sayfası açıkken yani ana sayfasını özelleştiriliyorken görünecek şekilde ayarlayabiliriz. Ana sayfa için yaptığımız seçimli gösterimi diğer sayfalar için de yapabiliyoruz. Bu durumda, oluşturduğumuz Customizer API alanları, özelleştirme esnasında gerekmedikleri sayfalarda görünmeyecektir.

Aşağıda, standart bazı bölüm ve kontrollerin, koşullu bir şekilde görünmesini sağlayan kodlar vardır:

$wp_customize->get_section( 'header_image' )->active_callback = 'is_front_page';

Yukarıdaki kod parçası ile, Görünüm->Özelleştir sayfasındaki “Üst kısım ortam dosyası” bölümünü sadece, ekranda ana sayfanın ön izlemesi varken görünecek şekilde ayarlar.

$wp_customize->get_control( 'blogdescription' )->active_callback = 'is_front_page'; // "Site kimliği" bölümündeki "Slogan" kontrolü

Yukarıdaki kod parçası ile, Görünüm->Özelleştir sayfasında gördüğümüz “Site kimliği” bölümündeki “Slogan” kontrolünün sadece, ekranda ana sayfanın ön izlemesi varken görünecek şekilde ayarlar.

Yukarıdaki kodun yaptığı işin aynısını, bir Costomizer API bölümü oluşturuken, 'active_callback' argümanı kullanarak da yapabiliriz. Aşağıda bunun bir örneği verilmiştir:

$wp_customize->add_section( 'bir_bolum', array(
  'title'       => __( 'Bölümün Başlığı', 'textdomain' ),
  'description' => __( 'Bölümün açıklaması...', 'textdomain' ),
  'priority'        => 130,
  'active_callback' => 'is_front_page', // Bu bölüm sadece ana sayfada görünür.
) );

Yine yukarıdaki kodun yaptığı işin aynısını, aşağıdaki kod ile de yapabiliriz:

$wp_customize->add_section( 'bir_bolum', array(
  'title'       => __( 'Bölümün Başlığı', 'textdomain' ),
  'description' => __( 'Bölümün açıklaması...', 'textdomain' ),
  'priority'        => 130,
  'active_callback' => function() { return is_front_page(); }, // Bu bölüm sadece ana sayfada görünür.
) );

Aşağıdaki kod da aynı işe yapar:

$wp_customize->add_section( 'bir_bolum', array(
  'title'       => __( 'Bölümün Başlığı', 'textdomain' ),
  'description' => __( 'Bölümün açıklaması...', 'textdomain' ),
  'priority'        => 130,
  'active_callback' => 'sadece_ana_sayfada_goster', // Bu bölüm sadece ana sayfada görünür.
) );
//...
function sadece_ana_sayfada_goster() {
    return is_front_page();
}

Kendimize özel Customizer API alanları oluştururken, bir koşul fonksiyonu da oluşturabiliriz. Aşağıda bu işin nasıl yapılacağı gösterilmiştir:

class Bana_Ozel_Bir_Control_Alani extends WP_Customize_Control {
  // ...
  function active_callback() {
    return is_front_page();
  }
}

Oluşturduğumuz Customizer API alanlarını, gerek olmayan sayfalarda gizleme özelliği ile ilgili olan 'customize_control_active' filtresinden bahsedelim. Bu filtre, biraz önce gördüğümüz argümanların veya fonksiyonların üzerine yazar. Kullanımı şöyledir:

// Bir açıklaması -description- olmayan kontrol alanlarını tek yazı sayfaları görüntülenirken gizler.
function aciklamasi_olmayan_controlleri_filtrele( $active, $control ) {
  if ( '' === $control->description ) {
    $active = is_singular();
  }
  return $active;
}
add_filter( 'customize_control_active', 'aciklamasi_olmayan_controlleri_filtrele', 10, 2 );

Seçimli Yükleme (Selective Refresh)

Seçimli yükleme, Customizer API ile birlikte gelen büyülü özelliklerden biridir. Bu özellik, temamızı özelleştirirken, yaptığımız değişiklikleri canlı olarak takip etmemizi sağlar. Seçimli yükleme özelliği, değişiklik yaptığımız sayfanın sadece güncellediğimiz kısmının tekrar yüklenmesini ve yaptığımız değişikleri hızlı bir şekilde görmemizi sağlar.

Seçimli yineleme, WordPress 4.5 sürümü ile birlikte gelmiştir. Bu özellik ile, yönetim panelinin özelleştirme sayfasında, temamız ile ilgili güncelleme işlemleri yaparken, sadece sayfanın gereken kısmı için bir AJAX isteği (AJAX request) gönderilir ve sayfanın yaptığımız değişikler ile ilgili olmayan kısımlarına ait bir çok PHP ve JavaScript sorgusunun gereksiz yere çalışması engellenmiş olur. Bu sayede, yapmış olduğumuz değişiklikleri daha hızlı bir şekilde takip etme imkanımız olur.

Temamız için oluşturduğumuz Customizer API alanlarına, selective refresh özelliği eklemek için, bir örnek üzerinden gidelim. Örneğimizde hero-image.php adında bir şablon parçası oluşturalım ve bu şablon parçasında şu özellikler olsun:

Bir resim olsun
Resmin üzerinde bir başlık ve açıklama olsun
Resmin üzerinde, bizi seçtiğimiz bir sayfaya yönlendiren bir buton olsun
Bu şablon parçasının arkaplan rengini de kontrol edebilelim.

Yukarıdaki özellikleri Customizer API ile selective refresh özelliğini de kullanarak kontrol edebileceğiz.

Customizer API Alanları Oluşturma

Öncelikle, bahsettiğimiz Customizer API alanlarını oluşturalım:

functions.php

class Hero_Resmi
{
  /**
   * Şablon parçasındaki her bir özellik için bir alan oluşturuyoruz
   */
  public static function register($wp_customize)
  { 
  
    // Ayar ile ilgili olarak bir seçimli yükleme varsa 'postMessage', yoksa 'refresh'
    $transport = ( $wp_customize->selective_refresh ? 'postMessage' : 'refresh' );

    // "Hero Resmi" adına bir bölüm oluşturuyoruz
    $wp_customize->add_section( 'hero', array(
      'title' => 'Hero Resmi',
      'priority' => 0
    ));

    // Başlık için setting & control alanları oluşturuyoruz
    $wp_customize->add_setting( 'hero_title', array(
      'default' => 'Resim üzerine yazılacak başlıktır.',
      'transport' => $transport,
    ));

    $wp_customize->add_control( 'hero_title', array(
      'label' => 'Başlık',
      'section' => 'hero',
      'settings' => 'hero_title',
      'type' => 'text'
    ));

    // Açıklama kısmı için setting & control alanları oluşturuyoruz
    $wp_customize->add_setting( 'hero_description', array(
      'default' => 'Resim üzerine yazılacak açıklamadır.',
      'transport' => $transport
    ));

    $wp_customize->add_control( 'hero_description', array(
      'label' => 'Açıklama',
      'section' => 'hero',
      'settings' => 'hero_description',
      'type' => 'textarea'
    ));

    // Hero resmi için setting & control alanları oluşturuyoruz
    $wp_customize->add_setting( 'hero_image', array(
      'default' => get_template_directory_uri() . '/images/hero-image.jpg', // varsayılan resim
      'transport' => $transport
    ));

    $wp_customize->add_control(
      new WP_Customize_Cropped_Image_Control( $wp_customize, 'hero_image', array(
        'label' => 'Resim',
        'section' => 'hero',
        'context' => 'hero-image',
        'flex_width' => false,
        'flex_height' => true,
        'width' => 1200,
        'height' => 600,
      ) )
    );

    // Arkaplan rengi için setting & control alanları oluşturuyoruz
    $wp_customize->add_setting( 'hero_background_color', array(
      'default' => '#c3f2f5',
      'transport' => $transport
    ));

    $wp_customize->add_control( 
      new WP_Customize_Color_Control( $wp_customize, 'hero_background_color', array(
        'label' => 'Arkaplan rengi',
        'section' => 'hero',
        'settings' => 'hero_background_color'
      ) ) 
    );

    // Sayfa seçimi için setting & control alanları oluşturuyoruz
    $wp_customize->add_setting( 'hero_page', array(
      'transport' => 'none'
    ));

    $wp_customize->add_control( 'hero_page', array(
      'label' => 'Şu sayfaya git',
      'section' => 'hero',
      'type' => 'dropdown-pages',
      'settings' => 'hero_page'
    ));

    // Buton üzerine yazılacak text için setting & control alanları oluşturuyoruz
    $wp_customize->add_setting( 'hero_button_text', array(
      'default' => 'Detaylar için tıkla',
      'transport' => $transport
    ));

    $wp_customize->add_control( 'hero_button_text', array(
      'label' => 'Button text',
      'section' => 'hero',
      'settings' => 'hero_button_text',
      'type' => 'text'
    ));
  }
}

add_action( 'customize_register', array('Hero_Resmi', 'register') );

Yukarıdaki kodları ekledikten sonra, temamızın yönetim panelindeki Görünüm->Özelleştir sayfasında “Hero Resmi” adında bir bölüm ve bu bölümün içinde de aşağıdaki görülen kontroller oluşacaktır:

“Hero Resmi” bölümü:

“Hero Resmi” bölümündeki kontrol alanları:

Yukarıda da görüldüğü gibi, Customizer API ile, 6 farklı kontrol alanı oluşturduk. Bu alanlar ile elde ettiğimiz dataları temamıza şöyle çekeceğiz:

Başlık: get_theme_mod('hero_title')
Açıklama: get_theme_mod('hero_description')
Resim (resmin id değeri): get_theme_mod('hero_image')
Arkaplan rengi (rengin hex kodunu veren ifade): get_theme_mod('hero_background_color')
Şu sayfaya git (sayfanın id değerini veren ifade): get_theme_mod('hero_page')
Button text: get_theme_mod('hero_button_text')

Customizer API Alanlarının Şablon İçinde Kullanımı – HTML

Oluşturduğumuz bütün bu alanları, temamızda şu şekilde kullanalım:

hero-image.php

<div class="hero">
  <div class="hero-content">
    <?php
	 echo '<h1> Sayfa id: '.get_theme_mod('hero_background_color').'</h1>';
	 echo '<h1> Resim url: '.wp_get_attachment_image_src(get_theme_mod('hero_image'))[0].'</h1>';
      // Başlık girilmiş mi kontrol et
      if( $title = get_theme_mod('hero_title') )
      {
        echo '<h1 class="hero-title">' . $title . '</h1>';
      }

      // Açıklama girilmiş mi kontrol et
      if( $subtitle = get_theme_mod('hero_description') )
      {
        echo '<p class="hero-description">' . $subtitle . '</p>';
      }

      // Adı ve bağlanacağı sayfası olmayan butonu gösterme
      if ( $link = get_theme_mod('hero_page') && $text = get_theme_mod('hero_button_text') )
      {
        echo '<p><a href="' . get_permalink($link) . '" class="button">' . $text . '</a></p>';
      }
    ?>
  </div>
  <br />
  <div class="hero-image">
    <?php 
      // Resim yüklenmiş mi kontrol et
      if ( ! empty(hero_image()) && null !== hero_image() )
      {
        echo hero_image(); // Bu fonksiyonu, biradan functions.php de oluşturacağız
      }
      // Resim yüklenmemişse şu resmi kullan
      else
      {
        echo '<img src="' . get_template_directory_uri() . '/inc/images/wp.jpg' . '">';
      }
    ?>
  </div>
</div>

Bu dersin konusu olmadığı için, oluşturduğumuz bu şablon parçasına ait CSS yapısını size bırakıyorum. Oluşturduğumuz bu şablon parçası dosyası temamızın ana dizininde ise, dilediğiniz şablon dosyasına çağırmak için şu kodu kullanmamız yeterlidir:

get_template_part( 'hero', 'image' );

Eğer hero-image.php dosyamız, ana dizinde bulunan template-parts adında bir klasörün içinde ise, bu şablon parçasını kullanmak istediğimizde şu kodu kullanabiliriz:

get_template_part( 'template-parts/hero', 'image' );

Customizer API ile oluşturduğumuz kontrollerin, selective refresh özelliği kazanabilmesi için, bu kontrol alanı için oluşturulan ayarın (setting), aşağıda görüldüğü gibi 'transport' => 'postMessage' argümanına sahip olması gerekmektedir.

$wp_customize->add_setting( 'hero_title', array(
      'default' => 'Resim üzerine yazılacak başlıktır.',
      'transport' => 'postMessage',
    ));

Biz, yukarıda verdiğimiz kodda bu durumu, daha esnek bir şekilde, şu kod ile hallettik:

$transport = ( $wp_customize->selective_refresh ? 'postMessage' : 'refresh' );

Yani, bir kontrol alanı için:

$wp_customize->selective_refresh->add_partial(...

şeklinde başlayan bir selective refresh özelliği eklendi ise, $transport değişkenini 'postMessage' değeri, yoksa 'refresh' değeri alacak şekilde ayarladık.

Customizer Alanlarına Selective Refresh Özelliği Kazandırma

Şimdi, biraz önce başladığımız Hero_Resmi sınıfına, oluşturduğumuz kontroller için, selective refresh özellikleri ekleyelim:

functions.php

class Hero_Resmi
{
  public static function refresh( WP_Customize_Manager $wp_customize )
  { 
    // Selective refresh kullanımda değilse hiç uğraşma
    if ( ! isset( $wp_customize->selective_refresh ) ) return;

    // Başlık için selective refresh özelliği ekler
    $wp_customize->selective_refresh->add_partial('hero_title', array(
      'selector' => '.hero-title',
      'settings' => 'hero_title',
      'render_callback' => function() {
        return get_theme_mod('hero_title');
      }
    ) );

    // Açıklama için selective refresh özelliği ekler
    $wp_customize->selective_refresh->add_partial('hero_description', array(
      'selector' => '.hero-description',
      'settings' => 'hero_description',
      'render_callback' => function() {
        return get_theme_mod('hero_description');
      }
    ) );

    // Resim için selective refresh özelliği ekler
    $wp_customize->selective_refresh->add_partial('hero_image', array(
      'selector' => '.hero-image img',
      'settings' => 'hero_image',
      'render_callback' => self::hero_image_partial() // Birazdan oluşturacağız
    ) );

    // Arkaplan resmi için selective refresh özelliği ekler
    $wp_customize->selective_refresh->add_partial('hero_background_color', array(
      'selector' => '#hero-css',
      'settings' => 'hero_background_color',
      'render_callback' => function() {
        echo self::css('.hero', 'background-color', 'hero_background_color'); // Birazdan oluşturacağız
      }
    ) );

    // Button text için selective refresh özelliği ekler
    $wp_customize->selective_refresh->add_partial('hero_button_text', array(
      'selector' => '.hero .button',
      'settings' => 'hero_button_text',
      'render_callback' => function() {
        return get_theme_mod('hero_button_text');
      }
    ) );
  }
}

add_action( 'customize_register', array('Hero_Resmi', 'refresh') );

Arka Plan Rengini İşleme

Yine Hero_Resmi sınıfında, oluşturduğumuz iki metot ile, aldığımız arkaplan rengini işleyelim ve aynı zamanda, selective refresh özelliği için ihtiyacımız olan 'render_callback' fonksiyonunu da hazırlamış olalım:

functions.php

class Hero_Resmi
{
  // Bu metot kullanıcının seçtiği rengi CSS formatında kullanmak için bir şablon oluşturur.
  public static function css( $selector, $property, $theme_mod )
  {
    $return = '';
    $theme_mod = get_theme_mod($theme_mod);

    if ( ! empty( $theme_mod ) )
    {
      $return = sprintf('%s { %s:%s; }',
        $selector,
        $property,
        $theme_mod
      );
      return $return;
    }
  }

  // Kullanıcıdan gelen rengi, yukarıdaki css() metodunun yardımı ile temanın üst kısmına eklenecek şekle sokar
  public static function output()
  {
    echo '<style id="hero-css">';
    echo self::css('.hero', 'background-color', 'hero_background_color');
    echo '</style>';
  }
}
// output()  metodunu temanın üst kısmına gönderir.
add_action( 'wp_head', array('Hero_Resmi' , 'output') );

Resmi İşleme

Yine Hero_Resmi sınıfında, oluşturduğumuz bir metot ile, aldığımız arkaplan resmini kullanıma hazır hale getirelim ve aynı zamanda, selective refresh özelliği için ihtiyacımız olan 'render_callback' fonksiyonunu da hazırlamış olalım:

functions.php

class Hero_Resmi
{
  public static function hero_image_partial()
  {
    return wp_get_attachment_image(get_theme_mod('hero_image'), array('1200', '600'));
  }
}

Bu metodu, Hero_Resmi sınıfının dışında, bağımsız bir fonksiyon olarak şablon parçasında (hero-image.php) kullanılacak şekilde hazırlıyoruz:

function hero_image()
{
  return Hero_Resmi::hero_image_partial();
}

Selective_refresh-> add_partial() Metoduna Yakından Bakalım

Yukarıda verilen kod örneğindeki public static function refresh() metodu incelendiğinde, bir Customizer API alanına ait bir selective refresh özelliği eklemek için, kullandığımız metodun $wp_customize->selective_refresh->add_partial() metodu olduğu görülecektir. Bu metodu daha yakından incelemek için, “Başlık” alanı için ('hero_title') kullandığımız kodları daha yakından inceleyelim:

  $wp_customize->selective_refresh->add_partial('hero_title', array(
      'selector' => '.hero-title',
      'settings' => 'hero_title',
      'render_callback' => function() {
        return get_theme_mod('hero_title');
      }
   ));

İlk satırda gördüğümüz:

$wp_customize->selective_refresh->add_partial('hero_title', ...

ifadesindeki 'hero_title' değeri, selective refresh özelliği ekleyeceğimiz Customizer API alanının kimlik değeridir. Hatırlarsanız, başlık için oluşturduğumuz alanın kimlik değerini 'hero_title' olarak belirlemiştik.

'selector' => '.hero-title',

ifadesindeki '.hero-title' değeri, hero-image.php adıyla oluşturduğumuz şablon parçasında, başlık için oluşturduğumuz HTML elemanının CSS sınıfıdır. Bu değer, AJAX isteği esnasında, başlık değerine ulaşmak için kullanılacaktır.

'settings' => 'hero_title',

ifadesindeki 'hero_title' değeri de, selective refresh özelliği ekleyeceğimiz Customizer API alanının kimlik değeridir. Hatırlarsanız, başlık için oluşturduğumuz alanın kimlik değerini 'hero_title' olarak belirlemiştik.

'render_callback' => function() {
        return get_theme_mod('hero_title');

ifadesindeki 'render_callback' argümanının değeri bir fonksiyondur. Bu fonksiyon, düzenlediğimiz alanın temamızdaki sunumunu döndüren fonksiyondur. Yani, Customizer API alanı ile elde ettiğimiz veriyi, temamızda nasıl sunuyorsak o ifadeyi döndüren fonksiyondur.

Selective Refresh Argümanları

$wp_customize->selective_refresh->add_partial() metodunun, yukarıda bahsedilenlere ek olarak kabul ettiği başka argümanlar da vardır. Bu argümanlar şunlardır:

‘container_inclusive’

(bool) Bu argüman true değerini alırsa, yineleme olayı bütün kapsayıcı HTML elemanında (container) gerçekleşir; false değerini alırsa da kapsayıcı elemanın yavrusunda gerçekleşir. Varsayılan değeri false olarak ayarlanmıştır.

‘fallback_refresh’

(bool) Temada, yinelenecek HTML elemanı bulunamazsa, sayfanın tamamının yinelenip yinelenmeyeceğini belirler.

‘customize-partial-refreshing’

Selective refresh metodu, yinelediği HTML elemanına anlık olarak, yineleme esnasında görülen ve yineleme bitince hemen kaybolan 'customize-partial-refreshing' adında bir CSS sınıfı ekler. Dilersek, bu sınıf ile, yineleme anına ait stiller oluşturabiliriz.

Selective Refresh İçinde JavaScript Eventlerini Kullanma

Selective refresh kullanırken, başka bir takım özellikler ekleyerek, daha akıllı bir deneyim yaşayabiliriz. Bunun için öncelikle bir js dosyası oluşturmamız ve temamızın dizininde bir yere kaydetmemiz iyi bir başlangıç olacaktır. Diyelim ki bu amaçla selective-refresh-for-prewiev.js adına bir dosya oluşturduk, bu dosyayı da temamızın ana dizinindeki js klasörünün içine yerleştirdik. Bu durumda, oluşturduğumuz bu js dosyasını temamıza tanıtmak için şu kodu kullanmamız gerekecektir:

functions.php

function ilktemam_selective_refresh() {
    $handle = 'selective-refresh-icin';
    $src = get_template_directory_uri() . '/js/selective-refresh-for-prewiev.js';
    $deps = array( 'customize-preview' );
    $ver = '1';
    $in_footer = true;
    wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer );
}
add_action( 'customize_preview_init', 'ilktemam_selective_refresh' );

Yukarıda, Customizer API‘ye, ekstra selective refresh özellikleri eklemek için oluşturduğumuz js dosyasını temamıza tanıtırken 'customize_preview_init' kancası kullandığımıza dikkat edelim.

Aşağıdaki kod, yukarıda verdiğimiz örnekteki başlık ('hero_title') kısmı, selective refresh ile yinelediğinde (yani 'partial-content-rendered' eventi gerçekleştiğinde) çalışan bir jQuery kodu oluşturmamızı sağlar:

js/selective-refresh-for-prewiev.js

jQuery( function( $ ) {
	
    var kontrol = 'hero_title';
        
    if ( 'undefined' !== typeof wp && wp.customize && wp.customize.selectiveRefresh ) {
        
		wp.customize.selectiveRefresh.bind( 'partial-content-rendered', function( placement ) {
		  if ( placement.partial.id === kontrol ) {
			// marifetini burada gösterebilirsin
		  }
		} );	
	}
});

'partial-content-rendered' gibi, wp.customize.selectiveRefresh nesnesi ile birlikte kullanabileceğimiz diğer eventler (olaylar) şunlardır:

'partial-content-rendered': Yaptığımız bir değişiklik gerçekleştiği zaman
'render-partials-response': Bir data döndürüldüğünde.
'partial-content-moved': Bir bileşen bir sidebar’a (yan sütuna) atandığında
‘widget-updated‘: Bir bileşen alanı (WidgetPartial) bu alana ait renderContent metodu ile yinelendiğinde
'sidebar-updated': Bir sidebarın içindeki bileşenlerden biri güncellendiğinde veya yinelendiğinde veya reflowWidgets() metodu ile bileşenlerin sıralaması değiştirildiğinde

is_customize_preview()

Temanızdaki herhangi bir elemenanın, sadece özelleştirme esnasında görünmesini istiyorsanız, is_customize_preview() fonksiyonu ile bunu sağlayabilirsiniz.

<?php if ( is_customize_preview() ) : ?>
    <button class="customizer-edit" data-control='{ "name":"blogname" }'><?php esc_html_e( 'Şunu düzenle', 'textdomain' ); ?></button>
<?php endif; ?>

Yukarıda oluşturduğumuz buton, sadece Görünüm->Özelleştir sayfasında iken görünecektir.

Bileşenlere (Widgets) Selective Refresh Özelliği Ekleme

Bileşenler, sidebar (sayfa yanı) içinde kullandığımız şablon parçalarıdır. Temamızın “Özelleştirme” sayfası ile, temamızda kullandığımız bileşenlerde bazı ayarlamalar yapabiliriz. Hatta bu ayarlamaları selective refresh özelliğini kullanarak da yapabiliriz.

Bir WordPress temasının “Özelleştirme” sayfasına, bileşenler için selective refresh özelliği eklemek, temanın functions.php sayfasına şu kodu eklemek kadar basittir:

functions.php

/* Tema İçin Setup Fonksiyonu */
add_action( 'after_setup_theme', 'ilktemam_setup' );
	
function ilktemam_setup()
{
  add_theme_support( 'customize-selective-refresh-widgets' );
	
}

Yukarıda verdiğimiz kodun çalışması için, bileşene ev sahipliği yapan sidebar (sayfa yanı) eklenirken, before_widget/after_widget argümanlarının boş bırakılmamış olması gerekmektedir.

Bileşenleri (Widgets) Selective Refresh Uyumlu Kodlama

WordPress kurulumu ile birlikte gelen bütün bileşenler, selective refresh özelliğine uyumlu olarak gelirler. Fakat, kendimize özel bir bileşen (widget) kodlamak ta isteyebiliriz.

Kodladığımız bir bileşenin, selective refresh özelliğini desteklemesi için, bileşeni oluşturduğumuz sınıfın __construct() metodu şöyle olmalıdır:

class Ornek_Bir_Widget extends WP_Widget {
 
    public function __construct() {
        parent::__construct(
            ‘ornek-bilesen’,
            __( 'Örnek', 'textdomain' ),
            array(
                'description' => __( ‘Örnek bir bileşen’, ‘textdomain’ ),
                'customize_selective_refresh' => true, // Selective Refresh için
            )
        );
 
        // Selective refresh için
        if ( is_active_widget( false, false, $this->id_base ) || is_customize_preview() ) {
            add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
        }
    }
...

JavaScript İle Bileşenlere Selective Refresh Özelliği Kazandırma

Bileşenlere selective refresh özelliği kazandırmak için, yukarıda verdiğimiz yolun dışında, bir de JavaScript seçeneği vardır.

JavaScript ile, bileşenlere selective refresh özelliği eklemek için öncelikle bir js dosyası oluşturmalı ve bu dosyayı 'customize_preview_init' kancası ile eklemeliyiz. Aşağıda, bu amaç ile temamızın ana dizinindeki js klasöründe oluşturulan bileseni-canli-tazele.js dosyasının eklenmesi verilmiştir:

functions.php

function ilktemam_bilesenleri_canli_tazele() {
    $kimlik = 'bilesenleri-canli-ozellestir';
    $src = get_template_directory_uri() . '/js/bileseni-canli-tazele.js';
    $gerekli = array( 'customize-preview' );
    $ver = '0.1';
    $in_footer = true;
    wp_enqueue_script( $kimlik, $src, $gerekli, $ver, $in_footer );
}
add_action( 'customize_preview_init', 'ilktemam_bilesenleri_canli_tazele' );

Yukarıda verilen kod ile eklediğimiz bileseni-canli-tazele.js dosyasında, aşağıdaki kodları kullanarak, kimliği sidebar-1 olan bir sidebara ulaşabilir ve dilediğimizi yapabiliriz:

bileseni-canli-tazele.js

jQuery( function( $ ) {
    if ( 'undefined' !== typeof wp && wp.customize && wp.customize.selectiveRefresh ) {
        wp.customize.selectiveRefresh.bind( 'sidebar-updated', function( sidebarPartial ) { //sadece sidebar güncellendiğinde
            if ( 'sidebar-1' === sidebarPartial.sidebarId ) {
                // sidebar-1 için marifetini göster
            }
        } );
    }
} );

Bir Customizer API Alanına Sonradan Selective Refresh Özelliği Kazandırmak

Temanızın Özelleştirme sayfasında bulunan kontroller, standart olarak otomatik tazeleme özelliğine sahiptir. Fakat bu tazeleme olayı, temanızın ön izlemedeki sayfanın tamamı yinelenerek gerçekleşir. Bu durum bazen işinizi yavaşlatabilmektedir.

Bir Customizer API kontrol alanına, sonradan da selective refresh özelliği ekleyebiliriz. Örneğin, Site kimliği bölümündeki kontrollerinden biri olan “Site başlığı“, standart olarak selective refresh özelliği taşımaz. Site başlığı ayarının kimliği de "blogname" dir.

Diyelim ki temamız, site başlığını şu şekilde kullanıyor:

header.php

<h1 class="sc-title"><?php bloginfo("name"); ?></h1>

Aşağıdaki kod, “Site başlığı” alanı için selective refresh özelliğini etkinleştirir:

functions.php

function ilktemam_site_basligini_canli_tazele( WP_Customize_Manager $wp_customize ) {
    $wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
    $wp_customize->selective_refresh->add_partial( 'blogname', array(
        'selector' => 'h1.sc-title',
        'render_callback' => function() {
            bloginfo( 'name' );
        },
    ) );
}
add_action( 'customize_register', 'ilktemam_site_basligini_canli_tazele' );

Bir Customizer API ayarına sonradan selective refresh özelliği eklemenin tek yolu PHP kodları değildir. Yukarıdaki kod ile yaptığımız şeyi, JavaScript yardımı ile de yapabiliriz. Bunun için önce, “Site başlığı” ayarının 'transport' argümanını 'postMessage' şeklinde değiştirmeliyiz:

function ilktemam_site_basligini_canli_tazele( WP_Customize_Manager $wp_customize ) {
    $wp_customize->get_setting( 'blogname' )->transport = 'postMessage';
}
add_action( 'customize_register', 'ilktemam_site_basligini_canli_tazele' );

Daha sonra bir js dosyası oluşturmalı ve bu dosyayı 'customize_preview_init' kancası ile eklemeliyiz. Aşağıda, bu amaç ile temamızın ana dizinindeki js klasöründe oluşturulan site-basligini-canli-tazele.js dosyasının eklenmesi verilmiştir:

function ilktemam_site_basligini_canli_tezele() {
  wp_enqueue_script( 'custom_css_preview', get_template_directory_uri() . '/js/site-basligini-canli-tazele.js', array( 'customize-preview', 'jquery' ) );
}
add_action( 'customize_preview_init', 'ilktemam_site_basligini_canli_tezele' );

Daha sonra, oluşturduğumuz site-basligini-canli-tazele.js dosyasında şu kodları kullanıyoruz:

site-basligini-canli-tazele.js

( function( $ ) {
  wp.customize( 'blogname', function( value ) {
    value.bind( function( to ) {
      $( 'h1.sc-title' ).text( to );
    } );
  } );
} )( jQuery );

Verileri Doğrulama (Validate) ve Filtreleme (Sanitize)

Sitemizin arka planında da ön yüzünde de, kullanıcılarımızdan aldığımız veriler için gerekli güvenlik önlemlerini almalıyız. Bunun için, bir Customizer API ayarı oluştururken 'sanitize_callback' ve 'validate_callback' argümanlarını kullanabiliriz. Bu iki argüman, değer olarak, birer fonksiyon alırlar. Bu fonksiyonlar, kullanıcıdan gelecek olan veriyi filtrelemek ve doğrulamak için kullanılır. Aşağıda, 'yayinlanma_yili' adında bir ayar oluşturulurken bu iki argüman da kullanılmıştır:

functions.php

$wp_customize->add_setting( 'yayinlanma_yili', array(
    'sanitize_callback' => 'absint',
    'validate_callback' => 'ilktemam_yili_dogrula'
) );
function ilktemam_yili_dogrula( $validity, $value ) {
    $value = intval( $value );
    if ( empty( $value ) || ! is_numeric( $value ) ) {
        $validity->add( 'required', __( 'Geçerli bir yıl girmelisiniz.' ) );
    } elseif ( $value < 1900 ) {
        $validity->add( 'cok_kucuk', __( 'Yıl çok eski.' ) );
    } elseif ( $value > gmdate( 'Y' ) ) {
        $validity->add( 'cok_buyuk', __( 'Yıl çok yeni.' ) );
    }
    return $validity;
}

Yukarıda verilen kodun 'sanitize_callback' => 'absint' kısmında gördüğümüz 'absint' değeri, hazır bir WordPress fonksiyonunun ismidir. Bu fonksiyon, bir sayısal değeri pozitif tam sayıya dönüştürür.

Bir Customizer API ayarı için 'sanitize_callback' fonksiyonu eklemenin bir başka yolu da, filtrelemedir yani add_filter() fonksiyonudur. Bunun için add_filter() fonksiyonunda, 'customize_sanitize_{$setting_id}' kancası kullanılır. Bu kancadaki {$setting_id} ifadesinin yerine, ayarın kimliği gelmelidir. Aynı şekilde, 'validate_callback' fonksiyonu eklemek için de 'customize_validate_{$setting_id}' kancası kullanılır.

Aşağıda, kimlik adı 'yayinlanma_yili' olan bir ayar için eklenen 'ilktemam_yili_dogrula' adında bir 'validate_callback' fonksiyonu örneği verilmiştir:

add_filter( 'customize_validate_yayinlanma_yili', 'ilktemam_yili_dogrula' );
   
function ilktemam_yili_dogrula( $validity, $value ) {
    $value = intval( $value );
    if ( empty( $value ) || ! is_numeric( $value ) ) {
        $validity->add( 'zorunlu', __( 'Geçerli bir yıl girmelisiniz.' ) );
    } elseif ( $value < 1900 ) {
        $validity->add( 'cok_kucuk', __( 'Yıl çok eski.' ) );
    } elseif ( $value > gmdate( 'Y' ) ) {
        $validity->add( 'cok_buyuk', __( 'Yıl çok yeni.' ) );
    }
    return $validity;
}

JavaScript Doğrulaması – Tarayıcı Doğrulaması

Herhangi bir ayar alanınızın ön izlemesi, JavaScript yardımı ile yönetiliyorsa (selective refresh özelliği yoksa), bu alan için yine JavaScript ile bir doğrulama işlemi uygulayabilirsiniz. Fakat, JavaScript doğrulamaları, PHP doğrulamaları ile yer değiştirmemelidir, çünkü JavaScript doğrulamaları, kötü niyetli kişilerin kolayca atlatabileceği doğrulamalardır.

Customizer API kontrolleri için oluşturulacak JavaScript doğrulamaları için bir js dosyası oluşturmalı ve bu dosyayı temamıza 'customize_controls_enqueue_scripts' kancası ve 'customize-controls' gerekliliği ile eklemeliyiz. Aşağıda, js klasörü altında bu amaç ile oluşturulan yayin-yilini-dogrula.js dosyasının eklenmesine ait kod verilmiştir:

functions.php

function ilktemam_site_basligini_canli_tezele() {
  wp_enqueue_script( 'custom_css_preview', get_template_directory_uri() . '/js/yayin-yilini-dogrula.js', array( 'customize-controls', 'jquery' ) );
}
add_action( 'customize_controls_enqueue_scripts', 'ilktemam_site_basligini_canli_tezele' );

WordPress, Customizer API için JavaScript doğrulamaları yapabilmek amacı ile wp.customize.Setting sınıfında validate metoduna sahiptir.

Aşağıda, kimlik adi 'yayinlanma_yili' olan bir ayarın, JavaScript ile yapılan doğrulaması verilmiştir:

yayin-yilini-dogrula.js

;(function ($, api) {
	
	api.bind('ready', function () {
		
		api( 'yayinlanma_yili', function ( setting ) {
			setting.validate = function ( value ) {
				var code, notification;
				var year = parseInt( value, 10 );
		 
				code = 'zorunlu';
				if ( isNaN( year ) ) {
					notification = new api.Notification(
						code,
						{
							type: 'warning',
							message: 'Bu alanı boş bırakamazsınız.'
						}
					);
					setting.notifications.add( code, notification );
				
				} else {
					setting.notifications.remove( code );
				}
		 
				code = 'cok_kucuk';
				if ( year < 1900 ) {
					notification = new api.Notification(
						code,
						{
							type: 'warning',
							message: 'Bu kadar eski olamaz.'
						}
					);
					setting.notifications.add( code, notification );
				} else {
					setting.notifications.remove( code );
				}
		 
				code = 'cok_buyuk';
				if ( year > new Date().getFullYear() ) {
					notification = new api.Notification(
						code,
						{
							type: 'warning',
							message: 'Bu kadar yeni olamaz.'
						}
					);
					setting.notifications.add( code, notification );
				} else {
					setting.notifications.remove( code );
				}
		 
				return value;
			};
		} );
		
	});
})(jQuery, wp.customize);

Bildirimler

Kullanıcıların girdikleri verilerin doğrulanması kadar, girilen yanlış veriler hakkında anında bilgilendirilmeleri de önemlidir.

Customizer API kontrol alanlarında oluşturulacak JavaScript bildirimleri için, bir js dosyası oluşturmalı ve bu dosyayı temamıza 'customize_controls_enqueue_scripts' kancası ve 'customize-controls' gerekliliği ile eklemeliyiz. Aşağıda, js klasörü altında bu amaç ile oluşturulan site-basligini-denetle.js dosyasının eklenmesine ait kod verilmiştir:

functions.php

function ilktemam_site_basligini_denetle() {
  wp_enqueue_script( 'custom_css_preview', get_template_directory_uri() . '/js/site-basligini-denetle.js', array( 'customize-controls', 'jquery' ) );
}
add_action( 'customize_controls_enqueue_scripts', 'ilktemam_site_basligini_denetle' );

Aşağıda verilen kod, temanın Özelleştir sayfasındaki “Site başlığı” ('blogname') kısmında 20 karakterden büyük bir başlık girilince uyarı vermektedir:

site-basligini-denetle.js

;(function ($, api) {
	
	api.bind('ready', function () {
		
		api( 'blogname', function( setting ) {
			setting.bind( function( value ) {
				var code = 'uzun_baslik';
				if ( value.length > 20 ) {
					setting.notifications.add( code, new api.Notification(
						code,
						{
							type: 'warning',
							message: 'Bu tema 20 karakterden fazla başlığa izin vermiyor.'
						}
					) );
				} else {
					setting.notifications.remove( code );
				}
			});
		});	
		
	});
})(jQuery, wp.customize);

WordPress

Wordpress Tema Yapımı

Wordpress Tema Yapımı

1. BAŞLAMADAN ÖNCE

2. Bir WordPress TEMASININ ANA PARÇALARI

3. ÖRNEKLERLE ŞABLON DOSYALARI

4. DAHA İŞLEVSEL BİR TEMA İÇİN

5. Customızer API - Temayı Özelleştirme

6. GİZLİLİK POLİTİKASI ve ÇEREZ BİLDİRİMİ

7. TEMA YAPIMI İLE İLGİLİ İLERİ DÜZEY KONULAR

8. TEMAYI WORDPRESS.ORG'un TEMA ARŞİVİNDE YAYINLAMA

Online Kimya Özel Dersi Al