MediaWiki

Gadget kitchen

This page is a translated version of the page Gadget kitchen and the translation is 99% complete.
Outdated translations are marked like this.
Languages:

Selamat datang di gadget kitchen. Tutorial ini menjelaskan cara membuat dan menggunakan gadget serta skrip pengguna dalam JavaScript.

Apa itu gadget dan skrip pengguna?

MediaWiki memungkinkan siapa saja untuk menulis kode JavaScript publik guna langsung mengubah perilaku perangkat lunak. Kode ini dapat dibagikan dengan pengguna lain. Kode ini terletak di halaman wiki.

  • Skrip pengguna dapat diedit oleh penulis aslinya (jika disimpan dalam ruang nama Pengguna:) dan oleh siapa saja yang memiliki hak pengguna "edituserjs" (biasanya hanya pengurus antarmuka). Kode tersebut biasanya disimpan pada subhalaman dari halaman pengguna Anda. Misalnya: XTools/ArticleInfo.js dan m:User:Hoo man/useful links.js. Skrip pengguna mirip dengan halaman JavaScript pribadi seperti Special:MyPage/common.js, tetapi memungkinkan potongan kode tertentu untuk dibagikan dengan pengguna lain.
  • Gadget adalah skrip pengguna yang telah "dipromosikan" oleh seorang pengurus antarmuka dengan menambahkannya ke MediaWiki:Gadgets-definition. Pengguna yang sudah masuk log dapat mengaktifkan gadget di tab "Gadgets" dalam preferensi pengguna mereka. "Gadget dibuat dan dikelola oleh pengurus antarmuka."
  • Untuk kelengkapan: Ada juga JavaScript di seluruh situs yang terletak di MediaWiki:Common.js serta beberapa halaman lainnya. JavaScript di halaman-halaman tersebut memengaruhi semua orang dan dijalankan secara otomatis baik untuk pengguna yang keluar log maupun yang masuk log. Pengurus antarmuka dapat mengubahnya. Baca Manual:Interface/JavaScript untuk informasi lebih detail.

Jika Anda menjalankan salinan MediaWiki sendiri, $wgAllowUserJs perlu diaktifkan agar skrip pengguna dapat berfungsi, dan ekstensi Gadgets harus dipasang untuk memungkinkan promosi skrip individu menjadi gadget. Untuk pengalaman pengembangan yang lebih baik, pastikan ekstensi CodeEditor terpasang di wiki Anda.

Membuat skrip pengguna pertamamu

Di bagian ini, kamu akan membuat contoh skrip pengguna yang menghitung perkiraan waktu membaca sebuah halaman wiki.

  1. Pastikan kamu sudah masuk log.
  2. Kunjungi Special:MyPage/common.js. Halaman ini menyimpan JavaScript pribadimu yang dimuat pada setiap tampilan halaman (kecuali untuk Special:Preferences).
  3. Buat halaman tersebut atau sunting jika sudah ada.
  4. Salin enam baris berikut dan tempelkan ke dalam halaman: 
    const numWords = $( '#mw-content-text > div' ).text().split( ' ' ).length;
const headerWords = $( 'h1' ).text().split( ' ' ).length;
const totalWords = numWords + headerWords;
const timeInMinutes = totalWords / 200;
const header = $( 'h1' ).text();
$( 'h1' ).text( header + ' (it will take you ' + timeInMinutes + ' minutes to read this page)' );
  5. Klik "Terbitkan perubahan".
  6. Buka halaman mana saja dan perhatikan judulnya.

Contoh skrip pengguna ini diambil dari ChickTech High School Kickoff 2017/Tasks . Ada lebih banyak contoh skrip pengguna sederhana di halaman tersebut.

Contoh skrip pengguna yang lebih kompleks

Periksa MediaWiki:Tutorial-QuickRC.js yang menggunakan mw.loader, mw.util, mw.html, mw.user dari ResourceLoader, MediaWiki Action API, dialog jQuery UI, jQuery AJAX, dan pengikatan event jQuery.

Salin dan tempel isi dari MediaWiki:Tutorial-QuickRC.js ke dalam Special:MyPage/common.js mu.

Hasilnya seharusnya sama seperti di atas, tetapi sekarang kamu dapat memodifikasi skrip, bereksperimen dengannya, atau mengganti sepenuhnya dengan sesuatu yang lain.

Mengklik "Pratinjau" (atau menggunakan pintasan papan ketik, biasanya ⇧ Shift+Alt+P) di editor juga akan menjalankan versi terbaru dari skrip. Ini adalah cara yang baik untuk menguji perubahan tanpa menyimpan halaman. Ingat, tidak ada yang tersimpan hingga kamu menekan "Terbitkan halaman".

Memuat skrip pengguna yang sudah ada

Di bagian sebelumnya, Anda telah menyalin isi dari sebuah skrip pengguna. Di bagian ini, kamu akan memuat skrip MediaWiki:Tutorial-QuickRC.js yang sudah ada sebagai gantinya.

  1. Pastikan kamu sudah masuk log.
  2. Kunjungi Special:MyPage/common.js. Halaman ini menyimpan JavaScript pribadimu yang dimuat pada setiap tampilan halaman (kecuali untuk Special:Preferences).
  3. Buat halaman tersebut atau sunting jika sudah ada.
  4. Salin teks berikut dan tempelkan ke halaman: 
    mw.loader.load( '//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript' );
  5. Klik "Terbitkan perubahan". Kamu sekarang harus memiliki tautan di bagian "Perkakas" yang disebut "Pengganti Cepat".
  6. Klik "Quick changelog". Kamu akan melihat jendela pop-up. Ini menampilkan sebagian dari perubahan terbaru di situs ini.

Menggunakan skrip di Wiki Wikimedia lain

Jika kamu ingin menggunakan skrip di situs Wikimedia lain (misalnya Wikipedia bahasa Inggris alih-alih MediaWiki.org), ikuti langkah yang sama seperti di atas: beri tahu ResourceLoader untuk memuat kodemu. Kunjungi common.js mu di Wikipedia bahasa Inggris, lalu tambahkan teks berikut: 

mw.loader.load( '//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript' );

Kamu juga dapat memuat skrip pengguna yang baru saja Anda buat di atas dengan mengganti MediaWiki:Tutorial-QuickRC.js pada baris sebelumnya dengan Pengguna:YourName/YourScript.js (gantikan YourName dan YourScript sesuai kebutuhan). Ini mengharuskan kamu untuk tidak menyimpan kode skrip pengguna di Special:MyPage/common.js itu sendiri, melainkan di subhalaman terpisah dari halaman penggunamu."

Ini juga membantu menyimpan kode di satu tempat, sehingga Anda hanya perlu memperbarui kode di satu lokasi.

Mengembangkan skrip pengguna dan gadget

Bagian ini mencantumkan sumber daya yang diperlukan atau berguna untuk skrip pengguna yang tidak sederhana.

ResourceLoader

Gadget harus menggunakan ResourceLoader. ResourceLoader adalah fitur inti MediaWiki yang secara cerdas mendistribusikan aset JavaScript dan CSS kepada pengguna serta pembaca. Karena Gadget dikodekan dalam JavaScript, sebagai pengembang Gadget, kamu pasti akan berinteraksi dengan ResourceLoader.

Gadget kamu harus memuat modul ResourceLoader yang berguna.

OOUI

OOUI adalah pustaka JavaScript dengan elemen antarmuka pengguna (misalnya jendela pop-up) yang dirancang khusus untuk digunakan di MediaWiki. Pustaka Menggunakan OOUI di MediaWiki#Gadgets dapat digunakan dalam gadget.

MediaWiki Action API

Dalam konteks situs MediaWiki, Action API dapat diakses dari JavaScript melalui API JavaScript mw.Api. (mw.ForeignApi untuk permintaan lintas situs yang diizinkan, misalnya antara wiki WMF.) Lihat API untuk informasi lebih lanjut.

Jika gadget Anda membuat permintaan API secara langsung, tambahkan parameter "?callback=?" ke URL API jika Anda mencoba melakukan permintaan yang melanggar kebijakan same-origin (misalnya, melakukan permintaan ke API Commons dari Wikipedia). Ini akan memicu penggunaan JSONP dan memberlakukan beberapa pembatasan.

VisualEditor

Lihat VisualEditor/Gadgets untuk tutorial khusus tentang gadget VisualEditor.

Debugging gadget dan skrip pengguna

Privasi dan konten eksternal

Anda sebaiknya tidak memuat sumber daya eksternal yang dapat membahayakan privasi pengguna. Di wiki Wikimedia, domain berikut dianggap aman:

  • *.wiktionary.org
  • *.wikimedia.org
  • *.wikibooks.org
  • *.wikisource.org
  • *.wikiversity.org
  • *.wikinews.org
  • *.wikiquote.org
  • *.wikidata.org
  • *.wikivoyage.org
  • www.mediawiki.org
Dulu ada pekerjaan Jenkins (job kode) yang otomatis memeriksa gadget berdasarkan prinsip ini, tetapi sudah tidak dijalankan lagi sejak 2022.

Menjalankan kode saat halaman dimuat

Tugas umum menjalankan kode segera setelah halaman dimuat memiliki beberapa kendala yang bahkan dapat menjebak pengguna berpengalaman.

  • Pertama-tama, ketika kode Anda berinteraksi dengan elemen DOM, jalankan saat halaman dimuat. Jika tidak, kode Anda mungkin berjalan terlalu cepat. Cara umum untuk melakukannya adalah dengan menggunakan fungsi $() dari jQuery, yang memiliki fungsi yang sama seperti $(document).ready().
  • Namun, jika kode Anda berinteraksi dengan bagian konten halaman (elemen #mw-content-text), sebaiknya gunakan hook 'wikipage.content' sebagai gantinya. Dengan cara ini, kode Anda akan dapat memproses ulang halaman dengan sukses ketika halaman diperbarui secara asinkron dan hook dipicu kembali. Ada banyak tool yang melakukan ini, mulai dari pratinjau suntingan hingga pembaruan otomatis daftar pantauan.
  • Pastikan untuk hanya bekerja dengan turunan elemen $content yang diterima oleh fungsi penangan Anda, bukan seluruh halaman. Jika tidak, Anda mungkin menjalankan kode yang sama untuk elemen yang sama berulang kali. Perlu diperhatikan bahwa hook 'wikipage.content' dapat dipicu sangat banyak kali.
  • Berhati-hatilah dengan apa yang masuk dalam argumen $content pada fungsi penangan. Jangan berasumsi bahwa itu adalah elemen #mw-content-text. Itu bisa saja hanya sebagian kecil dari halaman, misalnya saat halaman dipratinjau.

Kode yang berinteraksi dengan konten halaman dan menghindari kendala yang telah disebutkan sebelumnya dapat terlihat seperti ini: 

mw.hook( 'wikipage.content' ).add( ( $content ) => {
	const $target = $content.find( '.targetClass' );
	if ( $target.length ) {
		// Lakukan sesuatu dengan $target.
	}

	// Hanya lakukan beberapa operasi jika argumen tersebut adalah #mw-content-text.
	if ( $content.is( '#mw-content-text' ) ) {
		const $note = $( '<div>' )
			.addClass( 'myScript-note' )
			.text( 'MyScript has successfully processed the content!' );
		$content.prepend( $note );
	}
} );

Jika kodemu berinteraksi dengan konten halaman dan menambahkan penanganan event ke elemen DOM, daripada mengaitkan ke 'wikipage.content' dan mencari elemen untuk menambahkan event listener setiap kali dipicu, kamu dapat menggunakan event delegation: tambahkan satu event listener ke elemen di luar area konten atau ke seluruh document, tetapi saring event berdasarkan selektor (lihat dokumentasi jQuery). Dengan kata lain, daripada menulis $content.find( '.targetClass' ).on( 'click', ... ), kamu bisa menulis $( document ).on( 'click', '.targetClass', ... ).

Recording metrics

Some gadgets are serious business. When your gadget gets serious, you might want to instrument it for analytics purposes, for example to measure the click rate of specific UI elements added to a page by the gadget.

Halaman utama: Gadget kitchen: recording metrics


Lain-lain

Kelemahan dan masalah gadget

  • Gadget dikembangkan oleh anggota komunitas. Hingga saat ini, tidak ada proses tinjauan kode formal yang diwajibkan untuk gadget di situs Wikimedia (lihat phab:T71445). Harap ikuti praktik terbaik yang tercantum di halaman ini.
  • Di situs Wikimedia, proses untuk "mempromosikan" skrip pengguna menjadi gadget di tab "Gadgets" dalam preferensi pengguna tidak selalu jelas. Anda perlu mencari seorang pengurus antarmuka dan mungkin harus memberikan instruksi penerapan kepada mereka.
  • Wikimedia belum memiliki proses sistematis untuk menggunakan kembali, memodifikasi, dan berkontribusi pada skrip pengguna dan gadget yang sudah ada.

Ide untuk dikerjakan

Beberapa anggota komunitas Wikimedia mungkin membagikan ide mereka tentang fitur yang ingin mereka lihat diimplementasikan oleh orang lain.

Menerapkan atau mengaktifkan gadget

Jika skrip penggunamu ingin dijadikan gadget (lihat definisi di atas) di sebuah wiki, langkah-langkah berikut perlu dilakukan:

  • Langkah-langkah untuk penulis skrip pengguna:
    • Cari pengembang berpengalaman untuk meninjau kode gadgetmu. Tidak ada proses formal untuk melakukannya.
    • Diskusikan dengan anggota komunitas untuk memastikan tidak ada keberatan sebelum mengaktifkan gadget di wiki. Untuk situs MediaWiki.org sendiri, diskusi dapat dilakukan di Project:Village Pump.
    • Cari pengurus situs yang memiliki hak antarmuka. Lihat halaman Special:ListUsers/interface-admin di wiki Anda.
  • Langkah-langkah untuk pengurus antarmuka:
    • Salin file JS & CSS Anda ke dalam ruang nama MediaWiki: di wiki Anda, dan pastikan nama halaman memiliki prefiks Gadget-.
      Contoh: MediaWiki:Gadget-userfeedback.js
    • Definisikan gadget tersebut pada halaman MediaWiki:Gadgets-definition di wiki Anda. Itu mencakup modul yang digunakan, dependensi, nama file JS dan CSS, serta lainnya. Hal ini akan memungkinkan pengguna untuk mengaktifkan gadget di halaman Special:Preferences wiki Anda.
      Contoh: userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css
    • Buat halaman untuk gadget di ruang nama MediaWiki: dengan awalan Gadget-. Ini akan menghasilkan label untuk gadget di halaman Special:Preferences di wiki Anda.
      Contoh: MediaWiki:Gadget-userfeedback

Berkontribusi pada Skrip Pengguna

Jika sebuah skrip pengguna dibuat oleh pengguna lain, kamu mungkin dapat berkontribusi dalam pengembangannya. Kamu dapat melakukannya dengan menyalin skrip pengguna sebagai subhalaman di halaman penggunamu sendiri. Kemudian gantilah skrip pengguna asli yang telah kamu aktifkan dengan yang ada di halaman penggunamu di common.js. Lanjutkan dengan mengedit salinan skrip sesuai keinginanmu. Jika kamu ingin skrip asli memuat perubahan yang telah kamu buat pada salinan skrip kamu, sebaiknya ping penulis skrip tersebut di halaman diskusi skrip pengguna asli. Sertakan tautan ke halaman yang berisi perubahanmu dan minta mereka untuk menambahkan perubahan tersebut. Jika pengguna tersebut sudah tidak aktif, sebaiknya beri tahu komunitas bahwa versi skrip kamu tersedia dengan menautkannya ke daftar skrip di wiki kamu.

Halaman terkait

Retrieved from "https://www.mediawiki.org/w/index.php?title=Gadget_kitchen/id&oldid=7558543"