Membuat JQuery Plugin Splash Notice

Sering kita membuat aplikasi sederhana menggunakan jQuery, namun terkadang menghabisakan waktu jika yang kita buat aplikasi yang sama dan berulang – ulang, oleh karena itu pada kesempatan kali ini kita akan mengatasi salah satu permasalahan tersebut dengan membuat plugin. plugin jQuery yang akan kita buat kebetulan saya beri nama splash notice, maksudnya sama dengan splash screen, splash window, dll, namun ini hanya notice saja, dengan tampilan yang kurang lebih seperti ini:

Klik disini untuk mencobanya

Detail plugin:

• Cara kerja notice ini adalah akan muncul (fade in) di container yang telah kita tentukan, baik window atau element lainnya
• Posisi notice dapat di tengah atas atau di tengah-tengah container
• Terdapat pilihan apakah notice akan auto hide atau tidak
• Terdapat beberapa opsi diantaranya: mendefinisikan class pada element, memilih container, menentukan waktu lamanya element untuk auto hide
• Terdapat beberapa fungsi yang dapat digunakan, diantaranya, mengganti content notice pada saat running, menentukan ulang posisi notice dan menambahkan class pada element
• Kompatibel pada browser: IE6+, Chrome, Firefox, Safari, dll

Karena kode yang ditulis cukup panjang dan agar lebih memudahkan pembahasan, kita pecah kode tersebut menjadi dua bagian:

Bagian I

/** 
	JQuery Plugin Splash Notice
	oleh: agusph
	url	: www.agusph.com
*/

;(function($) {

    $.splashNotice = function(options) {

        var plugin = this,
			elm = [],
			defaults = {
				timeOut: 2000,
				position: 'topMiddle',
				autoHide: true,
				container: $('body'),
				elmClass: 'sn-element',
				msg: ''
			}

        var init = function() 
		{   
			if (typeof options === 'object') {
				plugin.settings = $.extend( {}, defaults, options );
			} else {
				plugin.settings = defaults;
				plugin.settings.msg = options;
			}

			plugin.tagName = plugin.settings.container[0].tagName.toLowerCase();
			var index = $('div.sn-element').length,
				$notice = [];
				
			elm = $notice[index] = $('<div>', {'id':'sn-notice'+index, 'class': plugin.settings.elmClass})
								.hide()
								.appendTo(plugin.settings.container);
			
			$notice[index].html(plugin.settings.msg);
			
			// calculate element position
			$notice[index].show();
			plugin.setPosition(plugin.settings.position);
			$notice[index].hide();
			
			// Show notice
			$notice[index].fadeIn('fast');
			
			// Hide notice
			if (plugin.settings.autoHide) {
				setTimeout(function()
				{
					$notice[index].fadeOut('fast', function() {$(this).remove()});
					
				}, plugin.settings.timeOut)
			}
			
			container = plugin.tagName == 'body' ? $(window) : plugin.settings.container;
				container.bind('resize scroll', function()
				{
					plugin.setPosition(plugin.settings.position);
				});
			
			return plugin;
        }
	}
}

Penjelasan Kode:
1. Mendefinisikan Variabel

var	plugin = this,
	elm = [],
	defaults = {
		timeOut: 2000,
		position: 'topMiddle',
		autoHide: true,
		container: $('body'),
		elmClass: 'sn-element',
		msg: ''
	}

• Daripada menggunakan this, objek plugin disimpan dalam variabel plugin, hal ini untuk mempermudah kita dalam mengidentifikasi objek plugin, terutama jika plugin yang kita buat kompleks
• Selanjutnya kita definisikan default parameter, yaitu:
  • timeOut digunakan untuk menentukan lamanya notice muncul, default 2000ms atau 2 detik, setelah itu notice menghilang. Parametet ini akan digunakan jika patameret autoHide bernilai true
  • position digunakan untuk menentukan posisi notice, apakah di tengah atas topMiddle atau di tegah – tengah container center
  • autoHide digunakan untuk menentukan apakah element notice akan otomatis menghilang fadeOut
  • container merupakan element dimana element notice akan ditempatkan, defaultnya adalah pada body
  • elmClass merupakan nama class untuk element notice, defaultnya adalah sn-notice
  • msg: notice / kata-kata yang ingin kita muncul

2. Mengintegrasikan default opsi dengan opsi dari user

if (typeof options === 'object') {
	plugin.settings = $.extend( {}, defaults, options );
} else {
	plugin.settings = defaults;
	plugin.settings.msg = options;
}

Jika opsi yang diberikan oleh user berupa objek, misal: $.splashNotice({msg: 'Sample Notice', timeOut: 2}), maka opsi tersebut akan digabungkan dengan opsi default dan disimpan ke objek settings, sehingga menjadi {msg: 'Sample Notice', timeOut: 2, position: 'top'}. Namun jika opsi yang diberikan berupa string misal $.splashNotice('Sample Notice') maka objek setting nilainya sama dengan opsi default dengan nilai msg sesaui yang diberikan user.

3. Membuat element notice

plugin.tagName = plugin.settings.container[0].tagName.toLowerCase();
var index = $('div.sn-element').length,
	$notice = [];
	
elm = $notice[index] = $('<div>', {'id':'sn-notice'+index, 'class': plugin.settings.elmClass})
							.hide()
							.appendTo(plugin.settings.container); 
$notice[index].html(plugin.settings.msg);

kita definisikan terlebih dahulu apa kontainer yang akan kita gunakan yaitu dengan mengidentifikasi nama tagnya (tagName) dan menyimpannya dalam variabel plugin.tagName. Hal ini diperlukan untuk menentukan lebar container. di beberapa versi jQuery penggunaan outerWidth() untuk objek window akan menimbulkan error.

Selanjutnya kita simpan element dalam bentuk objek array $notice[index], hal ini diperlukan dikarenakan jika disimpan dalam variabel biasa, akan menimbulkan masalah jika notice yang dibuat lebih dari satu secara bersamaan, disamping itu objek element kita simpan dalam variabel global elm, agar dapat digunakan di bagian lain

4. Membuat kalkulasi posisi horisontal

$notice[index].show();
plugin.setPosition(plugin.settings.position);
$notice[index].hide();

Kita letakkan plugin sesuai dengan posisi yang telah didefinisikan, kita perlu mengkalkulasi dimensi element, karena pertama kali dibuat, element masih tersembunyi, sehingga perlu dimunculkan terlebih dahulu, kemudian disembunyikan lagi, aktivitas ini tidak tampak oleh user. Karena fungsi ini digunakan lebih dari satu tempa, penghitungan posisi element kita buat di fungsi tersendiri, yang dibahas pada Bagian II.

5. Memunculkan Notice Kemudian Menyembunyikannya

$notice[index].fadeIn('fast');
			
// Hide notice
if (plugin.settings.autoHide) {
	setTimeout(function()
	{
		$notice[index].fadeOut('fast', function() {$(this).remove()});
		
	}, plugin.settings.timeOut)
}

Dengan efek fadeIn() kita munculkan element, selanjutnya jika opsi autoHide bernilai true, maka dengan fungsi setTimeOut() kita sembunyikan kembali element dengan jeda waktu yang telah ditentukan pada opsi timeOut. Oiya setelah disembunyikan, element akan dihapus.

6. Membuat Posisi Element Fixed

container = plugin.tagName == 'body' ? $(window) : plugin.settings.container;
container.bind('resize scroll', function()
{
	plugin.setPosition(plugin.settings.position);
});

return plugin;

Fungsi diatas bermanfaat untuk membuat element tetap berada di tempatnya ketika container discroll atau diresize. Posisi element notice di kalkulasi ulang ketika container di scroll atau diresize. Seperti pada penjelasan sebelumnya, posisi tersebut dikalkulasi ulang menggunakan fungsi terpisah, yang akan dibahas pada Bagian II. Tambahan: Property tagName yang telah kita buat sebelumnnya baru terasa manfaatnya saat ini ketika ingin mendefinisikan apakah element notice berada di body atau di element lain.

Selanjutnya kita atur nilai kembalian ke plugin, agar user dapat memanipulasi dengan mudah.

Bagian II

plugin.content = function(content)
		{
			elm.html(content);
			return plugin;
		}
		
		plugin.addClass = function(className)
		{
			elm.addClass(className);
			return plugin;
		}
		
		plugin.hide = function(callback)
		{
			elm.fadeOut('fast', function(){
				$(this).remove(); 
				if (typeof callback == 'function')
					callback();
				
			});	
		}
		
		plugin.setPosition = function(position)
		{
			if (plugin.tagName == 'body') {
				var container = $(window),
					cont_w = container.width(),
					cont_h = container.height();
			} else {
				var	container = plugin.settings.container,
					cont_w = container.outerWidth(),
					cont_h = container.outerHeight();
			}
			
			var	left_pos = ( (cont_w - elm.outerWidth()) / 2 )  + container.scrollLeft(), 
				top_pos = ( (cont_h - elm.outerHeight()) / 2 )  + container.scrollTop();
				
			switch (position) {
				case 'topMiddle':
					elm.css({'left': left_pos, 'top' : container.scrollTop()});
					break;
				case 'center':
					elm.css({'left': left_pos, 'top' : top_pos});
					break;
			}
		}
		
       init();
    }

})(jQuery);

1. Membuat Public Method Untuk Mengubah Content

plugin.content = function(content)
{
	elm.html(content);
	return plugin;
}

Ketika objek plugin sudah didefinisikan, kita tambahkan fitur agar user dapat mengubah content dari element notice. Fungsi diatas memberikan nilai kembalian ke plugin, agar dapat dikaitkan / dilanjutkan dengan memanggil method lain (method chaining).

2. Membuat Public Method Untuk Menambahkan Class

plugin.addClass = function(className)
{
	elm.addClass(className);
	return plugin;
}

Pada kondisi tertentu, kita ingin merubah tapilan dari element notice, misal ketika proses simpan sedang berjalan, kemudian gagal, maka notice berubah warna menjadi merah, atau jika proses simpan berhasil, notice akan berwarna hijau, untuk itu perlu dibuat fungsi untuk menghandle keperluan tersebut. Fungsi diatas akan menambahkan class pada element notice.

3. Membuat Public Method Untuk Menyembunyikan Element Notice

plugin.hide = function(callback)
{
	elm.fadeOut('fast', function(){
		$(this).remove(); 
		if (typeof callback == 'function')
			callback();
		
	});	
}

Ketika option autoHide diset dengan nilai false, maka element notice akan muncul terus, untuk dapat menyembunyikannya, kita buat fungsi hide. Fungsi ini juga menyediakan argumen bernama callback yaitu fungsi yang akan dieksekusi ketika proses menyembunyikan element notice fadeOut telah selesai. Contoh ada di bagian bawah tulisan ini.

4. Membuat Fungsi Untuk Melakukan kalkulasi Posisi Element Notice

plugin.setPosition = function(position)
{
	if (plugin.tagName == 'body') {
		var container = $(window),
			cont_w = container.width(),
			cont_h = container.height();
	} else {
		var	container = plugin.settings.container,
			cont_w = container.outerWidth(),
			cont_h = container.outerHeight();
	}
	
	var	left_pos = ( (cont_w - elm.outerWidth()) / 2 )  + container.scrollLeft(), 
		top_pos = ( (cont_h - elm.outerHeight()) / 2 )  + container.scrollTop();
		
	switch (position) {
		case 'topMiddle':
			elm.css({'left': left_pos, 'top' : container.scrollTop()});
			break;
		case 'center':
			elm.css({'left': left_pos, 'top' : top_pos});
			break;
	}
}

Fungsi ini bermanfaat baik untuk plugin itu sendiri maupun untuk user. Ketika user memanggil fungsi untuk mengubah content dari element notice plugin.content, maka dimensi element juga akan berubah, untuk itu, user wajib memanggil kembali fungsi ini untuk menempatkan posisi element notice kembali ke posisi semula.

Menentukan Container

if (plugin.tagName == 'body') {
	var	container = $(window),
		cont_w = container.width(),
		cont_h = container.height();
} else {
	var	container = plugin.settings.container,
		cont_w = container.outerWidth(),
		cont_h = container.outerHeight();
}

Disini property tagName kita gunakan kembali untuk menentukan element container. Seperti sebelumnya telah disampaikan, untuk beberapa versi jQuery, kalkulasi outerWidth() pada objek window akan menimbulkan error, oleh karena itu kita bedakan container yang akan kita gunakan.

Membuat kalkulasi posisi vertikal

var	left_pos = ( (cont_w - elm.outerWidth()) / 2 )  + container.scrollLeft(), 
	top_pos = ( (cont_h - elm.outerHeight()) / 2 )  + container.scrollTop();

left_post digunakan untuk mengatur posisi horizontal element notice, kita kalkulasikan dengan memperhitungkan lebar dari element dan posisi horizontal dari scrollbar, sedangkan top_pos digunakan untuk mengatur posisi vertikal element notice, untuk posisi di tengah-tengah container, kita kalkulasikan dengan memperhitungkan tinggi dari element dan posisi vertikal dari scrollbar.

Untuk posisi di paling atas window, posisi sama dengan posisi vertikal scrollbar, sedangkan untuk posisi ditengah-tengah window, kita kalkulasikan dengan memperhitungkan tinggi element dan posisi vertikal scrollbar. . Untuk memahami bagaimana cara mengkalkulasi posisi top_pos tersebut, dapat membaca artikel Memahami JQuery ScrollTop, ScrollLeft, Window Width dan Window Height.

Uji Coba

Silakan mencoba plugin yang telah kita buat dengan mengikuti contoh berikut:

$.splashNotice('Test Splash Notice');

$.splashNotice({msg:'Auto hide one second', timeOut: 1000, position: 'center'});

$.splashNotice({msg:'Disable auto hide', autoHide: false});

$notice1 = new $.splashNotice({msg:'<strong>Processing...</strong>', 
			container: $form1.parent(), 
			autoHide: false, 
			elmClass:'form-notice'
		});
		
setTimeout(function()
{

$notice1.content('<strong>Saved</strong>')
		.addClass('form-notice-saved')
		.setPosition('topMiddle');
}, 1500);

Silakan download source codenya disini.

Demikian tutorial singgkat membuat plugin JQuery sederhana berupa splash notice, semoga bermanfaat.