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. Deskripsi ini juga berlaku saat Anda membuat komponen, terutama yang dipakai dalam proyek Anda sendiri.

1. Komponen Aplikasi ¶

Komponen aplikasi 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) 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.

2. 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.

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

3. Widget ¶

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.

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 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:

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 controller.

4. Aksi ¶

Aksi harus diperluas dari CAction atau turunan kelasnya. Metode utama yang perlu diimplementasikan untuk sebuah filter adalah IAction::run.

5. Filter ¶

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.

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.

6. Controller ¶

Controller yang didistribusikan sebagai extension harus diturunkan dari CExtController, bukan dari CController. Alasan utama karena CController menganggap file tampilan controller 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 controller. Oleh karena itu, lebih mudah dalam menditribusikan kembali controller karena file tampilan tetap bersama dengan file kelas controller.

7. Validator ¶

Validator harus diturunkan dari CValidator dan mengimplementasikan metode CValidator::validateAttribute.

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

8. Perintah Konsol ¶

Perintah konsol harus diperluas dari CConsoleCommand dan mengimplementasikan metode CConsoleCommand::run. Secara opsional, kita dapat menimpa CConsoleCommand::getHelp untuk menyediakan beberapa informasi bantuan menarik mengenai perintah.

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';
    }
}

9. Module ¶

Silahkan merujuk ke seksi tentang module bagaimana membuat sebuah module.

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

10. 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.