API Tanımı : WordPress Shortcode API

WordPress Shortcode API, sistem genelinde en çok kullanılan ve en faydalı API’lerden biridir. Sistem genelinde bugün kullanılan Visual Composer, Divi gibi eklentiler ve WordPress eklenti deposundaki neredeyse tüm eklentiler shortcode api üzerinden işlem yapan fonksiyonlar geliştirmektedirler. Hatta ben bile zamanında yazdığım Auto Attachments eklentisi içerisinde kısa kod desteği vermiştim.

Shortcode Kullanımı

En basit haliyle WordPress kendi içerisinde kısa kodlar ile birlikte gelmektedir. Makalenizi yazarken oluşturduğunuz galeri resimlerini

gallery

kısa kodunu ekleyerek istediğiniz alanda galeriyi gösterebilirsiniz. Aslında kısa kodların kullanım amacının temelini bu oluşturur. Tanımlanmış olan fonksiyon ya da özelliklerin makale içerisinde (şimdilerde bileşenler ve temanın kendi içerisinde bile) istenilen alanda faaliyet göstermesi ve son kullanıcının bu fonksiyonları kodlama bilgisine sahip olmadan da kullanabilmesine yöneliktir.

Bu bağlamda zaten görsel tema oluşturucular kısa kod sistemini kullanmaktadırlar.

Varsayılan WordPress Kısa Kodları

audio //Yerel ses dosyası çağırarak oynatmanızı sağlayan kısa kod
caption //Resimlere alt başlıklar eklemenizi sağlayan kısa kod
wp_caption //Yukarıdaki ile aynı işi yapan kısa kod
embed //Dış site ve sosyal sitelerden içerik eklemenizi sağlayan kısa kod
gallery //Yazıda kullanılan resimlerin tümünü ya da oluşturduğunuz galeriyi çağıran kısa kod
video //Yerel video dosyası çağırarak oynatmanızı sağlayan kısa kod
playlist //Birden fazla ses veya video içeriğini birlikte oynatmanızı sağlayan kısa kod

Shortcode API özellikleri

Yukarıdaki örnekten de baktığımızda en basit kullanımı aşağıdaki gibidir;

[ gallery id="123" size="medium" ] //köşe parantezler arasında boşluk olmadan

API içinde kullanılabilir fonksiyonlar

• do_shortcode() : Temanızda, bileşenlerinizde ya da eklentilerinizde var olan bir kısa kodu çağırmak için kullanılan fonksiyondur.
• add_shortcode() : Kısa kod eklemek için kullanılan fonksiyondur.
• remove_shortcode() : Var olan kısa kodları kaldırmak için kullanılan fonksiyondur.
• remove_all_shortcodes() : Sistemdeki kullanılabilen tüm kısa kodların tamamını kaldırmak için kullanılan fonksiyondur.
• shortcode_atts() : Kısa kod içinde kullanılan verilerin fonksiyon tarafından tanımlanmasını ve yorumlanmasını sağlayan fonksiyondur.
• strip_shortcodes() : Metin içerisinde kullanılan kısa kodların görünüm alanında kullanmasını engellemek için kullanılabilen bir fonksiyondur.
• shortcode_exists() : Kısa kod daha önce tanımlanmış mı diye kontrol sağlayan fonksiyondur.
• has_shortcode() : Metin içerisinde kısa kod kullanılmış mı diye kontrol sağlabilen bir fonksiyondur.
• get_shortcode_regex() : Metin içerisindeki kısa kodları verilen tanıma göre bulmaya yarayan fonksiyondur.
• wp_audio_shortcode() : Ses dosyalarına player gösteren fonksiyondur.
• wp_video_shortcode() : Video dosyalarına player gösteren fonksiyondur.

Bu yazıda add_shortcode() fonksiyonunu sizlere tanıtacağım.

Bu API genel olarak eklenti ve tema geliştiricilerinin kullanıcılara rahat erişim sağlamalarına olanak tanır. Basit bir kısa kod oluşturmak için öncelikle bir fonksiyona ve bunu WordPress sistemine tanımlayıcı add_shortcode() fonksiyonunun kullanılmasına ihtiyaç vardır.

add_shortcode() fonksiyonu

Temel olarak bu fonksiyon sizin yazmış olduğunuz kısa kod fonksiyonunu WordPress sisteminde tanımlar ve kullanılması için gerekli bağlantıları yapar. Aşağıda size aktaracağım fonksiyon örneklerinde ekstra bilgi ve data aktarıp kullanmanızı sağlayan verileri de metin editöründen fonksiyonunuza taşıyacak olan tanımlamalar yine bu fonksiyon ile yapılır.

Bu fonksiyonun kullanımı şu şekildedir;

add_shortcode($kisakod,$kisa_kod_fonksiyon);

Burada $kisakod WordPress sistemi üzerindeki editörde çağrılacak olan kısa kodu tanımlar. $kisa_kod_fonksiyon ise fonksiyonunuza verdiğiniz isimdir. daha iyi kavrayabilmek için bir örnek verelim. Örnek olarak benim_fonksiyonum adında bir kısa kod fonksiyonumuzun olduğunu var sayalım. Ve bu fonksiyon ile benim-fonksiyonum adında bir kısa kod oluşturalım.

function benim_fonksiyonum($atts){
 return "Benim Fonksiyon Çıktım";
}

add_shortcode('benim-fonksiyonum','benim_fonksiyonum');

Bu şekilde oluşturulan kısa kodumuz eklendiği yerde tam olarak Benim Fonksiyon Çıktım yazacaktır. En basit kısa kod (shortcode) oluşturma yöntemi budur. Bu fonksiyonlar temanızdaki functions.php adlı dosya içerisinde yer almalıdır.

Özellik tanımlamaları

Bir üstte yer alan örnekte $atts adında bir tanımlama kullandık ama çıktı alanında yoktu. Fark ettiniz mi? Fark etmediyseniz ben anlatıyor olacağım.

Kısa kodlar kendilerine aktarılan tanımları fonksiyonunuza iletebilirler. Bu durumda $atts olarak belirtilen tanımlar bir dizge (array) olarak kullanılmaktadır. Bunun yanında çerçeve olarak kullanılan [kısakod][/kısakod] tarzındaki kısa kodlar için de $content tanımlaması eklenebilir. Bu da kısa kod açılış ve kapanış bölümleri arasında kalan içeriğin fonksiyonunuza iletilmesini sağlar.

$atts ve $content kullanımı

Yukarıda basit bir fonksiyon ile çok basit bir çıktı veren bir kısa kod oluşturduk. Ancak bu kısa koda ekstra tanımlamalar yapmak istediğimizde bunu yorumlayabilmemiz gerekmekte. Öncelikle bu verileri kullanabilmek için tanımlamamız gerekmekte. Bu kısımda ise shortcode_atts() fonksiyonu imdadımıza yetişiyor. Örnek üzerinden devam edelim ve benim-fonksiyonum kısa kodumuza veri1 ve veri2 adında tanımlamalar yapalım. Bunun yanında $content alanını da kullanalım ve değerlerimizi çıktımıza dökelim.

function benim_fonksiyonum($atts,$content=null){
	$veri = shortcode_atts( array(
		'veri1' => '',
		'veri2' => '',
	), $atts );

 return "Benim Fonksiyon Çıktım ".$veri['veri1']." ve ".$veri['veri2']." değerlerini içeriyor. Ek olarak Kısa kod içerisine ".$content." yazıldı.";
}
 
add_shortcode('benim-fonksiyonum','benim_fonksiyonum');

Yukarıda fonksiyonumuzu geliştirdik. Bu kısa kodun kullanımı şu şekilde olacaktır.

[benim-fonksiyonum veri1="Ahmet" veri2="Mehmet"]WpAdamı[/benim-fonksiyonum]

Ve çıktısı da “Benim Fonksiyon Çıktım Ahmet ve Mehmet değerlerini içeriyor. Ek olarak Kısa kod içerisine WpAdamı yazıldı.”

En basit ve en yalın haliyle WordPress Shortcode API bu şekilde kullanılır. Daha gelişmiş kodları daha önce paylaştığım içeriklerden bakabilirsiniz. Dahası kendi yeteneklerinizi kullanarak daha iyilerini de siz yazabilirsiniz. WordPress Codex alanındaki makale için buraya tıklayabilirsiniz.