Struktur folder plugin QGIS adalah susunan direktori dan file wajib yang harus dipenuhi agar sebuah ekstensi berbasis Python dapat dikenali, dibaca, dan dimuat dengan sempurna oleh aplikasi Sistem Informasi Geografis QGIS. Setiap plugin minimal harus memiliki file utama seperti __init__.py, metadata.txt, file antarmuka .ui, serta logika pemrograman plugin.py yang tersimpan rapi dalam direktori profil pengguna atau repositori resmi.
Pengembang yang mengabaikan hierarki direktori ini akan mendapati plugin mereka gagal muncul di menu Plugin Manager QGIS. Oleh karena itu, pemahaman mendalam mengenai fungsi setiap komponen file menjadi fondasi krusial sebelum menulis baris kode pertama.
Komponen File dalam Struktur Folder Plugin QGIS
Sebuah direktori plugin standar di dalam folder profiles/default/python/plugins/ berisi kombinasi file skrip Python, metadata teks, ikon grafis, dan antarmuka pengguna berbasis Qt Designer. Berikut adalah rincian komponen file penyusunnya:
| Nama File / Folder | Tipe | Fungsi Utama dalam QGIS |
|---|---|---|
metadata.txt |
File Teks | Menyimpan informasi identitas plugin (nama, versi, deskripsi, author, kompatibilitas QGIS). |
__init__.py |
Skrip Python | Titik masuk utama (entry point) yang menginisialisasi plugin saat QGIS pertama kali memuatnya. |
plugin.py (Nama Bebas) |
Skrip Python | File inti yang berisi logika bisnis, koneksi tombol, dan algoritma pemrosesan spasial. |
plugin_dialog.ui |
File Qt UI | Desain antarmuka grafis (GUI) jendela pop-up yang dibuat menggunakan Qt Designer. |
icon.png |
File Gambar | Ikon visual berukuran 24x24 piksel yang tampil pada toolbar dan menu QGIS. |
resources.py |
Skrip Python | File hasil kompilasi resource file (.qrc) yang memuat aset ikon dan file eksternal. |
Sintaks Dasar File metadata.txt
File metadata.txt wajib ada dan dibaca oleh QGIS untuk menampilkan data plugin pada jendela Plugin Manager. Tanpa file ini, direktori plugin akan diabaikan total oleh sistem.
[general]
name=Contoh Plugin QGIS
qgisMinimumVersion=3.0
description=Deskripsi singkat mengenai fungsi utama plugin.
version=1.0
author=Nama Pengembang
[email protected]
icon=icon.png
experimental=True
deprecated=False
Langkah Teknis Pembuatan Struktur Folder
- Buka direktori penyimpanan plugin QGIS di komputer Anda. Pada sistem operasi Windows, lokasi default berada di
C:\Users\NAMA_USER\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\. - Buat folder baru dengan nama unik yang merepresentasikan plugin Anda, misalnya
ketik_nama_plugintanpa spasi. - Di dalam folder tersebut, buat file teks bernama
metadata.txtdan isi dengan konfigurasi dasar sesuai contoh sintaks di atas. - Buat file
__init__.pykosong dan file utama logika plugin, contohnyamain_plugin.py. - Tambahkan file ikon berformat PNG berukuran 24x24 piksel untuk memperjelas identitas tombol pada toolbar QGIS.
- Buka aplikasi QGIS, masuk ke menu Plugins > Manage and Install Plugins > Installed, lalu pastikan nama plugin Anda muncul dan berikan centang untuk mengaktifkannya.
Troubleshooting Lapangan
Kendala paling sering terjadi saat menyusun direktori plugin adalah kesalahan penamaan fungsi inisialisasi di dalam file __init__.py. QGIS secara spesifik mencari fungsi bernama classFactory(iface). Jika fungsi ini salah ketik atau tidak didefinisikan, QGIS akan memunculkan pesan error saat memuat plugin atau plugin sama sekali tidak terdeteksi di dalam daftar.
Pastikan juga versi QGIS Minimum pada file metadata.txt selaras dengan aplikasi QGIS yang sedang Anda gunakan untuk menghindari penolakan muat akibat perbedaan pustaka API PyQt.