Bir eklenti (Plug-in) yazarken nelere dikkat etmeliyiz?
Bir javaScript eklentisi yazarken dikkat edilmesi gereken en önemli hususlardan birisi de o eklentisinin ANATOMİsidir.
Anatomi, Yunancada çıkarmak anlamına gelen ana ve kesmek anlamına gelen tomeden türetilmiş bir kelimedir.
wikipedia.org
The Anatomy
İşte tüm projelerime başladığım şablon. Merak etmeyin, adım adım ve inceleyerek ilerleyeceğiz.
(function (root, factory) {
if ( typeof define === 'function' && define.amd ) {
define(['boz'], factory(root));
} else if ( typeof exports === 'object' ) {
module.exports = factory(require('boz'));
} else {
root.myPlugin = factory(root, root.boz);
}
})(typeof global !== "undefined" ? global : this.window || this.global, function (root) {
'use strict';
//
// Variables
//
var myPlugin = {}; // Object for public APIs
var supports = !!document.querySelector && !!root.addEventListener; // Feature test
var settings; // Placeholder variables
// Default settings
var defaults = {
someVar: 123,
initClass: 'js-myplugin',
callbackBefore: function () {},
callbackAfter: function () {}
};
//
// Methods
//
// @todo add plugin methods here
/**
* Handle events
* @private
*/
var eventHandler = function (event) {
// @todo Do something on event
};
/**
* Destroy the current initialization.
* @public
*/
myPlugin.destroy = function () {
// If plugin isn't already initialized, stop
if ( !settings ) return;
// Remove init class for conditional CSS
document.documentElement.classList.remove( settings.initClass );
// @todo Undo any other init functions...
// Remove event listeners
document.removeEventListener('click', eventHandler, false);
// Reset variables
settings = null;
};
/**
* Initialize Plugin
* @public
* @param {Object} options User settings
*/
myPlugin.init = function ( options ) {
// feature test
if ( !supports ) return;
// Destroy any existing initializations
myPlugin.destroy();
// Merge user options with defaults
settings = boz.extend( defaults, options || {} );
// Add class to HTML element to activate conditional CSS
document.documentElement.classList.add( settings.initClass );
// @todo Do stuff...
// Listen for click events
document.addEventListener('click', eventHandler, false);
};
//
// Public APIs
//
return myPlugin;
});
Bağımlılıklar “Dependencies”
Söylemekte fayda var: Bu isteğe bağlıdır
Projelerimde genellikle iki ek dosya kullanırım. Bunlardan birincisi: ClassList.js[eklenecek] polyfill(destek)’i (desteğidir). Peki bu destek ne işe yarar? Diğer yazılarımızda da bahsettiğimiz gibi bu destek Internet Explorer için geliştirilmiştir. ClassList desteğini IE10+ dan IE8+ ‘ya yükseltmenize olanak sağlar. Tabi bu durum kişiye özeldir. Projelerinizin en düşük hangi Explorer sürümünü çalıştırması gerektiği ile doğru orantılıdır. O nedenle kullanmak pek tabi size (kodlayıcıya) kalmış bir durumdur.
Bir diğer ek dosyamız ise, boz.js[eklenecek] dir. Boz.js benim tarafımdan kodlanmış olan ufak bir kütüphanedir. Böylelikle her seferinde aynı kodları yazmaktan kurtuluyor ve bu kütüphanedeki hazır fonksiyonları çağırıp işin içinden çıkıyorum. Şunu belirtmeliyim ki bunu veya benzerlerini de kullanıp kullanmamak gene kodlayıcının arzusuna kalmış bir istisnai durumdur.
Biz yazımıza her iki durumu da dahil ederek devam edeceğiz. Böylelikle kullanmak istemediğiniz hususları es geçebilirsiniz.
Hadi başlayalım!
UMD Wrapper
Namı değer UMD Sarıcı. Bunu şöyle izah edelim, projelerinize (eklenti vs. fark etmez) UMD sarıcı – Universal Module Definition (UMD) sarmalayıcı– kullanarak yola çıkarsanız komut dosyalarınızın hem AMD hem de Common JS ile uyumlu olduğunu bildirmiş olursunuz. Bununla birlikte yazdığınız kodlamaların [önemli]“Hem değişken hem de fonksiyonların” geleneksel (GLOBAL) bir modül deseni olarak çalıştığı anlamına gelir. Yani yazdığınız bir eklenti bir başka eklenti veya kod’un etkisi altında kalmaz.
Bunu şöyle düşünün, ilk okulu bitiren bir çocuk senelerce uğraşıp bir takım bilgiler öğreniyor. Fakat Üniversite mezunu ağabeyi ile bir noktada bilgi çatışmasına giriyorlar. Birinin ak dediğine diğeri kara diyor. Şu halde 3. bir tekil şahıs hangisinin dediğine inanacaktır? Tabi ki hem yaşça büyük olduğu hem de daha üst mertebede eğitim aldığı için ağabeye inanılacaktır. Şimdi o küçük çocuğun düştüğü anlamsal çatışmaları düşünün. Kendisi bile neye inanacağını sapıtacak ve en sonunda ağabeyinin dediğine ayak uyduracak fakat hiç bir zaman kafasındaki çelişki sönümlenmeyecektir.
– vanillajs.wordpress.com
İşte sizin yazdığınız kod içerisinde bir değişkenin değeri “10” iken bir başkasının veya sizin yazdığınız herhangi bir başka eklenti vb. (etc.) kodlamalarda aynı isimdeki başka bir değişkenin değeri “0” kabul edildiğini düşünün. Mantıksal bir çelişki açığa çıkacaktır. Fakat MAKİNE DİLİ‘n de çelişkiye yer yoktur. O değişkenlerden hangisi Üniversite Mezunu ise veya referansı oraya dayanıyorsa onun dediği olur.
Pek tabi eşitlik olması durumunda akış şeması devreye girer ve SON SÖZÜ son konuşan söyler. Yani kısacası son gülen iyi güler ve kodlama sırasında en son olanın dediği olur.
Tabi biz şimdiye dek hep değişkenlerden bahsettik. Bu durumun aynısını fonksiyonlar içinde düşünebilirsiniz.
Neyse biz konumuza dönelim, biliyorum fazlaca saçmaladım 😛
İşte kodlamanın o kısmı:
(function (root, factory) {
if ( typeof define === 'function' && define.amd ) {
define(['boz'], factory(root));
} else if ( typeof exports === 'object' ) {
module.exports = factory(require('boz'));
} else {
root.myPlugin = factory(root, root.boz);
}
})(typeof global !== 'undefined' ? global : this.window || this.global, function (root) {
// Plugin stuff...
});
1myPlugin burada yazacağınız eklentinin adını tanımlar. Bunu kendi isteğinize ve arzunuza göre değiştirebilirsiniz.
2boz yukarıda da bahsettiğim üzere yardımcı bir eklenti ve bu eklentinin çalışması için gereken ön koşul. Eğer boz tanımlanmamışsa eklenti çalışmayacaktır.
3 Bir tarayıcıda her zaman için root = window kabul edilmeyebilir. Yani her şeyin kökü pencere olmalıdır. Ama böyle bir takım hatalar (bug) gerçekleşebilir. Bu hatayı engellemek için aşağıdaki satır kodlamayı ekiyoruz.
typeof global !== 'undefined' ? global : this.window
Use Strict use strict
use strict aslında tarayıcıya bir takım kurallar açısından daha katı olmasını söyler. Yani yapılan kural dışı kodlamalar, senaryolar ve geliştirilen fonksiyonlar açısından oluşabilecek hoş görü (istisnai durum) dışında davran ve kendi kurallarının (dil) dışına çıkma. Daha da kısaltacak olursak kabul edilebilir hata payını azaltıyor.
Kulağa saçma geliyor. Bunu neden kullanılır ki? Aslında bu durum sizi daha iyi, daha kaliteli, daha hatasız bir kod yazmaya zorlayacak. Eğer amacınız bu ise use-strict kullanmanızda fayda var diyelim ve devam edelim.
Variables
Namı değer değişkenler. Ama şunu ifade etmeliyim ki bu çeviri bana biraz saçma geliyor. Onun yerine yazılabilirler denilse daha iyi olurmuş. Tabi bu durum zaten güçlükle anlaşılan ifadeleri daha da karmaşıklaştırabilir. En iyisi bırakalım değişkenler olarak kalsın 🙂
//
// Variables
//
var myPlugin = {}; // Object for public APIs
var supports = !!document.querySelector && !!root.addEventListener; // Feature test
var settings; // Placeholder variables
// Default settings
var defaults = {
someVar: 123,
initClass: 'js-myplugin',
callbackBefore: function () {},
callbackAfter: function () {}
};
Tekrar tekrar söylemekte fayda var. Unutmayalım ki buradaki, myPlugin yazdığımız eklentinin adıdır. Bunu kendinize göre değiştirmeniz gerekir.
[önemli] myPlugin ‘i burada bir değişken olarak tanımladık fark ettiyseniz. Bunun sebebi yazdığımız eklenti deki toplanan tüm verilerin RETURN değeri ile SARMALAYICI yani UMD ‘nin dışına çıkarmasıdır.
Yani lafın özü, günün sonunda (sembolik olarak) yazdığımız { } bu süslü parantezlerin dışına hangi isimde ve hangi verilerin çıktığıdır ki, biz de o satırda tam olarak bunu yapıyoruz.
[önemli] bu tanımlamayı yapmamış olsaydık. Dışarıdan hiç bir değişkene veya fonksiyona ulaşamazdık.
[örnek] myPlugin.init(); fonksiyonunu dışarıdan erişilebilecek (PUBLIC) olarak kodladık. Fakat yukarıdaki tanımlamayı yapmamış olsaydık, bu fonksiyonunun dışarıdan kullanılması mümkün olmayacaktı.
Event Handler
Namı değer etkinlik izleyiciler. “Bir eklentinin olmazsa olmaz fonksiyonlarıdır.” demek pekala mümkün:
Herhangi bir olay dinleyicisini –tıklamak, kaydırmak, pencereyi yeniden boyutlandırmak, zoom yapmak vb. etc.- eventHandler yönteminden geçiririz ki içinde bir takım mantıksal sorgulamalar yapabilelim.
Her türlü girişi buraya yazabilirsiniz. Örneğin, ben click olayı dinleyicilerimi document ögesine yerleştirmeyi seviyorum ve ardından tıklanan ögenin önemsediğim ögelerden biri olup olmadığını kontrol ediyorum. (Yani tıklanan öge benim aradığım öge mi onu sorguluyorum)
Örnek 1.0
var eventHandler = function (event) {
var toggle = boz.getClosest(event.target, '[data-ornek]');
if ( toggle ) {
// Prevent default click event
if ( toggle.tagName.toLowerCase() === 'a') {
event.preventDefault();
}
// Eklenti deki diğer fonksiyonlar.
myPlugin.someMethod();
}
};
Burada mantıksal olarak şunları sağladık: document yani sayfadaki herhangi bir yere tıklandığı zaman eventHandler fonksiyonumuzu çalıştırdık. Bu fonksiyonun içinde ise, önce tıklanan elemanın ‘[data-ornek]’ etiketine sahip olup olmadığını kontrol ettik. Eğer bu etikete sahip bir eleman var ise deyip, o elemanın bir LİNK “a” olup olmadığını kontrol ettik. Eğer bir “LINK” ise preventDefault(); fonksiyonu ile normal tarayıcı davranışını reddetmesini emrettik. Kısacası link’e ait yeni sayfa açma işlemi iptal olacak. Ve hemen ardından someMethod(); isimli kendi fonksiyonumuzu çalıştırdık.
Eğer bu fonksiyon içerisine, bir sayfadan veri çekmeyi işlersek. Browser’da sayfa yenilemeden içerikleri değiştirebileceğimiz basit bir yol olacaktır 🙂
İsterseniz tüm olay türlerini tek bir işleyiciye aktarabilir ve olay türüne göre eylemin seyrini belirlemek için bazı mantıkları kullanabilirsiniz.
Örnek 1.1
var eventHandler = function (event) {
if ( event.type === 'scroll' ) {
myPlugin.scrollMethod();
}
if ( event.type === 'click' ) {
myPlugin.clickMethod();
}
};
Burada, gelen tüm eylemleri bir fonksiyonda topladık. Ve gelen olay türüne göre ayrıştırıp ona göre bir fonksiyon çalıştırdık. Örneğin, event.type === ‘scroll’ olayın bir scroll yani kaydırma olduğunu belirtiyor.
Destroy Method
Yani az çok anlaşılmıştır. Eklentiyi yok etmek. Çalışmaz hale getirmek.
Bu, aslında herhangi bir nedenle yeniden başlatmanız gerektiğinde veya başka bir komut dosyasından her şeyi durdurmanız gerektiğinde yararlıdır.
/**
* Destroy the current initialization.
* @public
*/
myPlugin.destroy = function () {
// If plugin isn't already initialized, stop
if ( !settings ) return;
// Remove init class for conditional CSS
document.documentElement.classList.remove( settings.initClass );
// @todo Undo any other init functions...
// Remove event listeners
document.removeEventListener('click', eventHandler, false);
// Reset variables
settings = null;
};
Initialize
Namı değer başlatmak. “Yazdığımız eklentinin çalışmasını başlatmak” olarak tercüme edebiliriz.
Bir diğer tanım: Manuel (EL ile) başlatmak.
Bazen yazdığınız bir algoritmanın (eklenti vs. etc.) kendi kendine sayfanın yüklenmesiyle birlikte otomatikman çalışmasını istemeyebilirsiniz. Bunun kontrolünün elinizde olmasını isteyebilirsiniz. Sizin istediğiniz zamanda ve/veya istediğiniz şartlar sağlandığında çalışması veya en azından bunu destekliyor olabilme-si-niz, istendik bir durumdur. Böylesi durumlarda “manuel initialize” etmek gerekmektedir.
Bu durum projelerinizde (örneğin bir web sayfası hazırlamak) size çok büyük esneklikler sağlar. Çünkü her eklentinin her sayfada çalışması gerekmez. [önemli] *Hatta bazı sayfalarda çalışması gerekli iken bazı sayfalarda ise çalışmaması gerekebilir.
/**
* Initialize Plugin
* @public
* @param {Object} options User settings
*/
myPlugin.init = function ( options ) {
// feature test
if ( !supports ) return;
// Destroy any existing initializations
myPlugin.destroy();
// Merge user options with defaults
settings = boz.extend( defaults, options || {} );
// Add class to HTML element to activate conditional CSS
document.documentElement.classList.add( settings.initClass );
// @todo Do stuff...
// Listen for click events
document.addEventListener('click', eventHandler, false);
};
Burada dikkat edilmesi gereken öncelikle, gerekli web ve JavaScript API’lerinin desteklendiğinden emin olmak için bir kontrol yazılmış olması. Buradaki durumumda document.querySelectorve window.addEventListenerbizim için gerekli olan API’ler. Bunlar yukarıda (değişken olarak) yazdığımız, supports betiğinin başlangıcındaki değişkende tanımlanır.
Örnek 2.0
var supports = !!document.querySelector && !!root.addEventListener;
Eklentimizin başında yazdığımız bu değişkeni başlatma fonksiyonumuzun içinde kontrol ediyoruz.
Örnek 2.1
if ( !supports ) return;
(Çok basit bir tabirle hızlı geçmek istiyorum burayı) Eğer o ve o ‘ndan herhangi birisi yok ise, fonksiyondan boş çık! Doğal olarak eklentimizden de boş bir veri ile çıkış sağlanacaktır.
Ardından, iç –içe– çakışmaları önlemek veya olay dinleyicilerini çoğaltmak için betiğin /VARSA/ mevcut tüm başlatmalarını imha ediyoruz.
Örnek 2.2
myPlugin.destroy();
Sonra herhangi bir kullanıcı ayarını (eğer girilmiş ise) varsayılan değerler ile değiştiriyoruz: <abkz.> extend
settings = boz.extend( defaults, options || {} );
Yeri gelmişken ondan da bahsedelim,
Örnek 2.3
Bir kullanıcı ayarları şöyle yapar:
myPlugin.init({
someVar: 456,
initClass: 'js-change-me',
anyVar: true,
});
Diğer Adımlar
Bu kısımda artık ana başlıklar altında değilde, kısa kısa püf noktaları vererek ilerleyeceğiz. Bu nedenle hepsini birleştirip, Diğer Adımlar adı altında sergiliyoruz.
1 Eklenti çalıştırıldıktan sonra DOM ögelerinden istediklerimize mesela (BODY) bir CSS sınıfı ekliyoruz. Bunun amacı ola ki eklentimiz herhangi bir nedenle hata verir ve/veya çalışmaz ise, bu durumda eklenecek olan sınıf o elemente eklenmaz ve bizde anlarız ki eklentimiz çalışmıyor. Buna bağlı olarak esnek bir CSS yazabiliriz. Böylelikle istenmedik CSS hatalarının da önüne geçmiş oluruz.
Örnek 3.0
document.documentElement.classList.add( settings.initClass );
2 bir sonraki olarak yaptığımız şey: olay dinleyicilerimizi kurarız (ayarlarız),
Örnek 3.1
document.addEventListener('click', eventHandler, false);
3 [önemli] Eklenti başlatılır başlatılmaz çalışması gereken (Bizim bu örneğimizde yer almayan) diğer tüm yöntemler de burada çağrılmalıdırlar.
Örnek 3.2
myPlugin.herhangiIslev();
myPlugin.moreFunc();
// ... daha fazla
4 [önemli] Eklenti dışında kullanılacak olan yöntemlerinizi dışarı çıkartın ( Return your public methods )!
Bu eklentideki dışarı çıkartacağımız son ve tek şey myPlugin‘ dir. Ki bu durumdan daha önce de bahsetmiştik. Bu değişkeni bu isimle dışarı çıkartmak aslında bize o isimi bir ÖN-EK olarak kullanacağımızı ifade ediyor. Bu ön-ek’i kullanarak eklentimizin içindeki –PUBLIC-, metodları dışarıdan çalıştırabiliriz.
return myPlugin;
Evet arkadaşlar böylelikle eklentimizin de yazımızın da sonuna geldik.
Yazım hatalarının ve (kimi yerde İngilizce, kimi yerde Türkçe) kullanmamın kusuruna bakmayın. Naçizane bazı terimleri tercüme etmek imkansız veya bazılarının da anlaşılabilmesi için orijinal hali ile kalması gerekir…
Sayfa başında eklediğimiz full sürümü bir de sonuna ekleyerek kapanışı yapalım:
Full Code: Anatomy of The JavaScript Plugin’s
(function (root, factory) {
if ( typeof define === 'function' && define.amd ) {
define(['boz'], factory(root));
} else if ( typeof exports === 'object' ) {
module.exports = factory(require('boz'));
} else {
root.myPlugin = factory(root, root.boz);
}
})(typeof global !== "undefined" ? global : this.window || this.global, function (root) {
'use strict';
//
// Variables
//
var myPlugin = {}; // Object for public APIs
var supports = !!document.querySelector && !!root.addEventListener; // Feature test
var settings; // Placeholder variables
// Default settings
var defaults = {
someVar: 123,
initClass: 'js-myplugin',
callbackBefore: function () {},
callbackAfter: function () {}
};
//
// Methods
//
// @todo add plugin methods here
/**
* Handle events
* @private
*/
var eventHandler = function (event) {
// @todo Do something on event
};
/**
* Destroy the current initialization.
* @public
*/
myPlugin.destroy = function () {
// If plugin isn't already initialized, stop
if ( !settings ) return;
// Remove init class for conditional CSS
document.documentElement.classList.remove( settings.initClass );
// @todo Undo any other init functions...
// Remove event listeners
document.removeEventListener('click', eventHandler, false);
// Reset variables
settings = null;
};
/**
* Initialize Plugin
* @public
* @param {Object} options User settings
*/
myPlugin.init = function ( options ) {
// feature test
if ( !supports ) return;
// Destroy any existing initializations
myPlugin.destroy();
// Merge user options with defaults
settings = boz.extend( defaults, options || {} );
// Add class to HTML element to activate conditional CSS
document.documentElement.classList.add( settings.initClass );
// @todo Do stuff...
// Listen for click events
document.addEventListener('click', eventHandler, false);
};
//
// Public APIs
//
return myPlugin;
});
Vanilla JavaScript 