yii/docs/guide/id/extension.create.txt

Membuat Extension
================

Karena tujuan extension adalah agar dipakai oleh pengembang pihak ketiga, diperlukan
beberapa usaha tambahan untuk membuatnya. Berikut ini adalah beberapa pedoman umum:

* Extension harus berdiri sendiri. Yakni, ketergantungan internalnya harus
  minimal. Ini akan memusingkan bagi para penggunanya jika sebuah extension masih harus
  menginstalasi paket, kelas atau file sumber tambahan.
* File yang dimiliki extension harus diatur pada direktori yang sama di mana
  namanya adalah nama extension.
* Kelas dalam extension harus diawali dengan huruf untuk menghindari konflik
  penamaan dengan kelas dalam extension lainnya.
* Extension harus disertai dengan rincian instalasi dan dokumentasi API.
  Tujuannya untuk mengurangi waktu dan usaha yang diperlukan oleh pengembang lain
  saat mereka menggunakan esktensi.
* Extension harus menggunakan lisensi yang sesuai. Jika Anda ingin menjadikan
  extension Anda dipakai baik oleh proyek open-source dan closed-source,
  Anda dapat menggunakan lisensi seperti BSD, MIT, dll., bukan GPL karena kalau GPL
  mengharuskan kode yang dipakainya juga open-source.

Berikut ini, kita akan melihat bagaimana untuk membuat sebuah extension baru, berdasarkan
pada pengkategorian dalam [tinjauan](/doc/guide/extension.overview).
Deskripsi ini juga berlaku saat Anda membuat komponen, terutama yang dipakai
dalam proyek Anda sendiri.

Komponen Aplikasi
-----------------

[Komponen aplikasi](/doc/guide/basics.application#application-component)
harus mengimplementasikan interface(antar muka) [IApplicationComponent] atau diperluas dari
[CApplicationComponent]. Metode utama yang perlu diimplementasikan ada di
[IApplicationComponent::init] komponen yang melakukan beberapa pekerjaan
inisialisasi. Metode ini dipanggil setelah komponen dibuat dan nilai properti awal
(yang ditetapkan dalam [konfigurasi aplikasi](/doc/guide/basics.application#application-configuration))
diterapkan.

Secara default, komponen aplikasi dibuat dan diinisialisasi hanya saat aplikasi
diakses untuk pertama kali saat penanganan permintaan. Jika komponen aplikasi
perlu segera dibuat begitu setelah instance aplikasi dibuat, maka aplikasinya akan
memerlukan pengguna untuk mendaftar ID-nya di dalam properti [CApplication::preload].


Behavior
--------

Untuk membuat sebuah behavior, kita harus mengimplementasikan interface(antar muka) [IBehavior]. Untuk alasan kemudahan,
Yii menyediakan kelas dasar [CBehavior] yang sudah mengimplementasikan antar muka ini dan
menyediakan tambahan beberapa metode lugas. Kelas-kelas turunan pada umumnya memerlukan implementasi
metode ekstra yang ditujukan agar tersedia bagi komponen yang terlampirkan.

Ketika mengembangkan behavior-behavior untuk [CModel] dan [CActiveRecord], kita juga dapat
memperluas [CModelBehavior] dan [CActiveRecordBehavior]. Kelas-kelas ini menawarkan
fitur tambahan yang khusus dibuat untuk [CModel] dan [CActiveRecord].
Sebagai contoh, kelas [CActiveRecordBehavior] mengimplementasikan satu set metode untuk merespon
event siklus yang terdapat di objek ActiveRecord. Selanjutnya kelas turunan bisa
meng-override metode-metode ini untuk menyimpan kode yang dikustomisasi yang akan berpartisipasi dalam siklus AR.

Kode berikut memperlihatkan contoh behavior ActiveRecord. Ketika dilampirkan
ke objek AR dan ketika objek AR sedang disimpan dengan memanggil `save()`, behavior akan menyetel
secara otomatis atribut `create_time` dan `update_time` dengan cap waktu saat ini.

~~~
[php]
class TimestampBehavior extends CActiveRecordBehavior
{
	public function beforeSave($event)
	{
		if($this->owner->isNewRecord)
			$this->owner->create_time=time();
		else
			$this->owner->update_time=time();
	}
}
~~~


Widget
------

[Widget](/doc/guide/basics.view#widget) harus diturunkan dari [CWidget] atau
anak kelasnya.

Cara termudah pembuatan widget baru adalah dengan menurunkan widget yang sudah ada dan
meng-override metodenya atau mengganti nilai standar propertinya. Sebagai contoh, jika
Anda ingin menggunakan gaya CSS lebih bagus untuk [CTabView], Anda dapat mengkonfigurasi
properti [CTabView::cssFile] saat menggunakan widget. Anda juga dapat memperluas [CTabView]
seperti berikut agar Anda tidak perlu lagi mengkonfigurasi properti saat menggunakan widget.

~~~
[php]
class MyTabView extends CTabView
{
	public function init()
	{
		if($this->cssFile===null)
		{
			$file=dirname(__FILE__).DIRECTORY_SEPARATOR.'tabview.css';
			$this->cssFile=Yii::app()->getAssetManager()->publish($file);
		}
		parent::init();
	}
}
~~~

Dalam contoh di atas, kita menimpa metode [CWidget::init] dan menempatkan
URL [CTabView::cssFile] ke gaya standar CSS baru kita jika properti
belum ditentukan. Kita menempatkan file gaya CSS baru di bawah direktori yang sama
dengan file kelas `MyTabView` agar bisa dipaketkan sebagai sebuah
extension. Karena file gaya CSS tidak bisa diakses oleh Web, kita perlu
mempublikasinya sebagai sebuah asset.

Untuk membuat widget baru dari awal, kita perlu mengimplementasikan dua metode:
[CWidget::init] dan [CWidget::run]. Metode pertama dipanggil saat kita
menggunakan `$this->beginWidget` untuk menyisipkan widget dalam sebuah view(tampilan), dan
metode kedua dipanggil saat kita memanggil `$this->endWidget`.
Jika kita ingin menangkap dan memproses konten yang ditampilkan diantara kedua
pemanggilan metode ini, kita dapat memulai [membufer output](http://us3.php.net/manual/en/book.outcontrol.php)
pada [CWidget::init] dan mengambil output yang di-buffer pada [CWidget::run]
guna pemrosesan selanjutnya.

Widget sering terkait dengan penyertaan CSS, JavaScript atau file sumber lain
dalam halaman yang menggunakan widget. Kita menyebut file-file ini *assets* karena
tempatnya bersama dengan file kelas widget dan biasanya tidak bisa diakses oleh
pengguna Web. Agar file-file ini bisa diakses oleh Web, kita perlu mempublikasikannya
dengan menggunakan [CWebApplication::assetManager], seperti yang ditampilkan dalam snippet kode di atas.
Selain itu, jika kita ingin menyertakan file CSS atau JavaScript dalam halaman saat ini,
kita perlu mendaftarkannya dengan menggunakan [CClientScript]:

~~~
[php]
class MyWidget extends CWidget
{
	protected function registerClientScript()
	{
		// ...terbitkan file CSS atau JavaScript di sini...
		$cs=Yii::app()->clientScript;
		$cs->registerCssFile($cssFile);
		$cs->registerScriptFile($jsFile);
	}
}
~~~

Widget juga dapat memiliki file tampilan sendiri. Jika seperti itu, buat direktori bernama
`views` di bawah direktori yang berisi file kelas widget, dan simpan semua file
tampilan di sana. Dalam kelas widget, untuk me-render tampilan widget, gunakan
`$this->render('NamaTampilan')`, yang mirip dengan apa yang dilakukan dalam sebuah kontroler.

Aksi
----

[Aksi](/doc/guide/basics.controller#action) harus diperluas dari [CAction]
atau turunan kelasnya. Metode utama yang perlu diimplementasikan untuk sebuah filter
adalah [IAction::run].

Filter
------
[Filter](/doc/guide/basics.controller#filter) harus diturunkan dari [CFilter]
atau anak kelasnya. Metode utama yang perlu diimplementasikan untuk sebuah filter
adalah [CFilter::preFilter] dan [CFilter::postFilter]. Yang pertama dipanggil sebelum
aksi dijalankan sementara yang filter kedua setelahnya.

~~~
[php]
class MyFilter extends CFilter
{
	protected function preFilter($filterChain)
	{
		// logika diterapkan sebelum aksi dijalankan
		return true; // false jika aksi seharusnya tidak dijalankan
	}

	protected function postFilter($filterChain)
	{
		// logika diterapkan setelah aksi dijalankan
	}
}
~~~

Parameter `$filterChain` adalah tipe [CFilterChain] yang berisi informasi
tentang aksi yang saat ini disaring.


Kontroler
---------
[Kontroler](/doc/guide/basics.controller) yang didistribusikan sebagai extension
harus diturunkan dari [CExtController], bukan dari [CController]. Alasan utama
karena [CController] menganggap file tampilan kontroler ditempatkan di bawah
`application.views.ControllerID`, sementara [CExtController] menganggap file tampilan
ditempatkan di bawah direktori `views` yang tidak lain adalah subdirektori
dari direktori yang berisi file kelas kontroler. Oleh karena itu, lebih mudah
dalam menditribusikan kembali kontroler karena file tampilan tetap bersama dengan
file kelas kontroler.


Validator
---------
Validator harus diturunkan dari [CValidator] dan mengimplementasikan metode
[CValidator::validateAttribute].

~~~
[php]
class MyValidator extends CValidator
{
	protected function validateAttribute($model,$attribute)
	{
		$value=$model->$attribute;
		if($value has error)
			$model->addError($attribute,$errorMessage);
	}
}
~~~

Perintah Konsol
---------------
[Perintah konsol](/doc/guide/topics.console) harus diperluas dari
[CConsoleCommand] dan mengimplementasikan metode [CConsoleCommand::run].
Secara opsional, kita dapat menimpa [CConsoleCommand::getHelp] untuk menyediakan
beberapa informasi bantuan menarik mengenai perintah.

~~~
[php]
class MyCommand extends CConsoleCommand
{
	public function run($args)
	{
		// $args berisi array argumen baris perintah untuk perintah ini
	}

	public function getHelp()
	{
		return 'Usage: how to use this command';
	}
}
~~~

Modul
-----
Silahkan merujuk ke seksi tentang [modul](/doc/guide/basics.module#creating-module) bagaimana membuat sebuah modul.

Petunjuk umum untuk mengembangkan modul adalah bahwa ia harus berdiri sendiri. File sumber (seperti CSS, JavaScript, gambar) yang dipakai oleh modul harus didistribusikan bersamaan dengan modul. Dan modul harus menerbitkannya agar bisa diakses oleh Web.


Komponen Generik
----------------
Mengembangkan extension komponen generik mirip dengan pembuatan sebuah kelas. Sekali lagi, komponen
juga harus berdiri sendiri agar dapat dipakai dengan mudah oleh pengembang yang lain.


<div class="revision">$Id: extension.create.txt 1423 2009-09-28 01:54:38Z qiang.xue $</div>