Jump to content

Gadget kuchyň

From mediawiki.org
This page is a translated version of the page Gadget kitchen and the translation is 100% complete.
Languages:

Vítejte v gadget kuchyni. Toto je návod, jak můžete psát a používat miniaplikace a uživatelské skripty v JavaScriptu.

Co jsou uživatelské skripty a gadgety?

MediaWiki umožňuje komukoli psát veřejný kód JavaScript pro okamžitou změnu chování softwaru. Tento kód lze sdílet s ostatními uživateli. Tento kód se nachází na stránkách wiki.

  • Uživatelský skript může upravovat původní autor (pokud je uložen ve jmenném prostoru User:) (uživatel) a kdokoli s uživatelským právem "edituserjs" (obvykle pouze administrátoři rozhraní). Kód je obvykle hostován na podstránce vaší uživatelské stránky. Příklady zahrnují: XTools/ArticleInfo.js a m:User:Hoo man/useful links.js. Uživatelské skripty jsou podobné osobním stránkám JavaScriptu, jako je například Special:MyPage/common.js, ale umožňují sdílení jednotlivých bloků kódu s ostatními uživateli.
  • Gadget je uživatelský skript, který byl "povýšen" správcem rozhraní přidáním do MediaWiki:Gadgets-definition. Přihlášení uživatelé mohou povolit miniaplikace na kartě "Gadgety" ve svých uživatelských nastaveních. Gadgety vytvářejí a spravují správci rozhraní.
  • Pro úplnost: K dispozici je také JavaScript pro celý web, který se nachází na adrese MediaWiki:Common.js a několika dalších stránkách. JavaScript na těchto stránkách ovlivňuje všechny a spouští se automaticky pro přihlášené i odhlášené uživatele. Správci rozhraní je mohou upravovat. Podrobné informace naleznete na stránce Příručka:Rozhraní/JavaScript .

Pokud používáte vlastní kopii MediaWiki, je nutné mít povolený $wgAllowUserJs , aby uživatelské skripty fungovaly, a nainstalovat rozšíření Gadgets , aby bylo možné jednotlivé skripty povýšit na gadget. Pro příjemnější vývojářský zážitek se ujistěte, že máte na wiki nainstalované rozšíření CodeEditor .

Napište svůj první uživatelský skript

V této části vytvoříte příklad uživatelského skriptu, který vypočítá odhadovanou dobu čtení wiki stránky.

  1. Ujistěte se, že jste přihlášeni.
  2. Navštivte stránku Special:MyPage/common.js. Tato stránka obsahuje váš osobní JavaScript, který se načítá při každém zobrazení stránky (s výjimkou Special:Preferences).
  3. Buď stránku vytvořte, nebo ji upravte, pokud již existuje.
  4. Zkopírujte následujících šest řádků a vložte je na stránku: 
    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. Klikněte na Zveřejnit změny.
  6. Jděte na libovolnou stránku. Podívejte se na název.

Tento příklad uživatelského skriptu je převzat z ChickTech High School Kickoff 2017/Tasks . Na této stránce najdete další příklady jednoduchých uživatelských skriptů.

Příklad složitějšího uživatelského skriptu

Podívejte se na MediaWiki:Tutorial-QuickRC.js, který používá mw.loader, mw.util, mw.html, mw.user z ResourceLoaderu, API akcí MediaWiki, dialogového okna jQuery UI, jQuery AJAX a vazby událostí jQuery.

Zkopírujte a vložte obsah souboru MediaWiki:Tutorial-QuickRC.js do svého souboru Special:MyPage/common.js.

Výsledek by měl být stejný jako výše, ale nyní můžete skript upravit, pohrát si s ním a nahradit ho něčím úplně jiným.

Kliknutím na tlačítko "Náhled" (nebo použitím klávesové zkratky, obvykle ⇧ Shift+Alt+P) v editoru se také spustí nejnovější verze skriptu. To je dobrý způsob, jak iterovat bez ukládání stránky. Nezapomeňte, že nic se neuloží, dokud nestisknete tlačítko "Publikovat stránku".

Načtení existujícího uživatelského skriptu

V předchozí části jste zkopírovali obsah uživatelského skriptu. V této části místo toho načtete existující skript MediaWiki:Tutorial-QuickRC.js.

  1. Ujistěte se, že jste přihlášeni.
  2. Navštivte stránku Special:MyPage/common.js. Tato stránka obsahuje váš osobní JavaScript, který se načítá při každém zobrazení stránky (s výjimkou Special:Preferences).
  3. Buď stránku vytvořte, nebo ji upravte, pokud již existuje.
  4. Zkopírujte následující text a vložte ho na stránku: 
    mw.loader.load( '//www.mediawiki.org/w/index.php?title=MediaWiki:Tutorial-QuickRC.js&action=raw&ctype=text/javascript' );
  5. Klikněte na "Publikovat změny". V sekci „Nástroje“ byste nyní měli mít odkaz s názvem "Rychlý seznam změn".
  6. Klikněte na "Rychlý seznam změn". Zobrazí se vyskakovací okno. Zobrazuje vám podmnožinu nedávných změn na tomto webu.

Použití skriptu na jiné wiki Wikimedie

Pokud chcete použít skript na jiném webu Wikimedie (například na anglické Wikipedii místo MediaWiki.org), provedete stejné kroky jako výše: Řeknete ResourceLoaderu, aby načetl váš kód. Navštívíte svůj common.js na anglické Wikipedii a přidáte následující: 

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

Uživatelský skript, který jste právě vytvořili výše, můžete také načíst změnou MediaWiki:Tutorial-QuickRC.js v předchozím řádku na User:VašeJméno/VašScript.js (nahraďte VašeJméno a VašScript odpovídajícím způsobem). To v první řadě vyžaduje, abyste kód svého uživatelského skriptu neukládali přímo do proměnné Special:MyPage/common.js, ale na samostatnou podstránku vaší uživatelské stránky.

To také pomáhá uchovávat kód na jednom místě, takže musíte aktualizovat kód pouze na jednom místě.

Vývoj uživatelských skriptů a gadgetů

Tato část uvádí zdroje, které jsou buď potřebné, nebo užitečné pro nejednoduché uživatelské skripty.

ResourceLoader

Gadgety musí používat ResourceLoader. ResourceLoader je klíčová funkce MediaWiki, která inteligentně poskytuje uživatelům a čtenářům JavaScriptové a CSS prvky. Protože jsou gadgety kódovány v JavaScriptu, jako programátor gadgetů budete muset komunikovat s ResourceLoaderem.

Váš gadget by měl načíst užitečné moduly ResourceLoader.

Codex

Codex je oficiální vývojový systém pro Wikimedia . Poskytuje jednotnou sadu nástrojů, pokynů a komponent, které pomáhají vývojářům a designérům vytvářet konzistentní, přístupná a lokalizovaná uživatelská rozhraní napříč projekty Wikimedie. Knihovnu lze použít v uživatelských skriptech.

API akcí MediaWiki

V kontextu webových stránek MediaWiki je možné k Action API přistupovat z JavaScriptu prostřednictvím JavaScript API mw.Api. (mw.ForeignApi pro povolené požadavky mezi weby, např. mezi wikinami WMF.) Další informace získáte na stránce API.

Pokud váš gadget odesílá požadavky API přímo, přidejte do adresy URL API parametr "?callback=?", pokud se pokoušíte odeslat požadavek API, který by porušoval zásadu stejného původu (např. odeslání požadavku na Commons API z Wikipedie). Tím se spustí použití JSONP a vynutí se určitá omezení.

VisualEditor

Výukový program konkrétně pro miniaplikace ve VisualEditoru naleznete v sekci VisualEditor/Gadgety.

Ladění uživatelských skriptů a gadgetů

  • Gadgety jsou obvykle zhuštěny, minimalizovány a agregovány pomocí ResourceLoaderu. Použijte parametr URI debug=true (samozřejmě před nímž je uvedeno ? nebo &) k zobrazení nekomprimované verze stránky a k načtení "původního zdrojového kódu" vašeho gadgetu. Více informací naleznete také v článku Vývoj s ResourceLoaderem.
  • Naučte se, jak používat nástroje pro vývojáře ve vašem prohlížeči (například jak zakázat mezipaměť v prohlížeči). Viz příslušná dokumentace: Chrome/Chromium, Firefox, Internet Explorer, Opera, Safari.
  • Pokud má existující gadget problémy, můžete také použít stránku Special:Gadgets k nalezení umístění zdrojového kódu gadgetu.

Soukromí a externí obsah

Neměli byste načítat externí zdroje, které by mohly poškodit soukromí uživatelů. Na wiki stránkách Wikimedie jsou následující domény považovány za bezpečné:

  • *.wiktionary.org
  • *.wikimedia.org
  • *.wikibooks.org
  • *.wikisource.org
  • *.wikiversity.org
  • *.wikinews.org
  • *.wikiquote.org
  • *.wikidata.org
  • *.wikivoyage.org
  • www.mediawiki.org
Existovala úloha Jenkins (pracovní kód), která automaticky kontrolovala gadgety na tento princip, ale tato úloha nebyla aktivně spuštěna od roku 2022.

Spouštění kódu při načítání stránky

Viz též: Manual:JavaScript hooks

Běžný úkol spouštět kód ihned po načtení stránky má několik úskalí, do kterých se dostanou i zkušení editoři.

  • Zaprvé, když váš kód pracuje s prvky DOMu, spusťte ho při načtení stránky. Jinak se váš kód může spustit příliš brzy. Obecný způsob, jak to udělat, je použít funkci $() v jQuery, která dělá totéž co $(document).ready().
  • Pokud ale váš kód pracuje s obsahovou částí stránky (prvek #mw-content-text), měli byste místo toho použít háček 'wikipage.content'. Tímto způsobem váš kód úspěšně znovu zpracuje stránku, když bude asynchronně aktualizována a háček bude znovu spuštěn. Existuje spousta nástrojů, které to dělají, od náhledu úprav až po automatickou aktualizaci seznamu sledovaných položek.
  • Ujistěte se, že pracujete pouze s potomky elementu $content, který vaše obslužná funkce přijímá, a ne s celou stránkou. Jinak se může stát, že budete muset stejný kód pro stejné prvky spustit vícekrát. Všimněte si, že háček 'wikipage.content' může být spuštěn mnohokrát.
  • Buďte opatrní ohledně toho, co se nachází v argumentu $content obslužné funkce. Neměli byste předpokládat, že je to prvek #mw-content-text. Může se jednat o malou část stránky, například při zobrazení náhledu.

Kód, který pracuje s obsahem stránky a vyhýbá se výše zmíněným nástrahám, může vypadat takto: 

mw.hook( 'wikipage.content' ).add( ( $content ) => {
	const $target = $content.find( '.targetClass' );
	if ( $target.length ) {
		// Dělejte věci s $target
	}

	// Prováděte některé operace pouze tehdy, když je v argumentu #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 );
	}
} );

Pokud váš kód pracuje s obsahem stránky a přidává obslužné rutiny událostí k elementům DOM, pak namísto připojování k 'wikipage.content' a hledání elementů, ke kterým se při jeho spuštění připojí posluchači událostí, můžete použít delegaci událostí: připojte jeden posluchač událostí k elementu mimo oblast obsahu nebo k celému document, ale události filtrujte pomocí selektoru (viz dokumentace k jQuery). To znamená, že místo $content.find( '.targetClass' ).on( 'click', ... ) můžete napsat $( document ).on( 'click', '.targetClass', ... ).

Zaznamenávání metrik

Některé vychytávky jsou vážný byznys. Když se s vaším gadgetem začnete vážně zabývat, možná budete chtít využít analytické účely, například k měření míry prokliku na konkrétní prvky uživatelského rozhraní, které gadget přidá na stránku.

Hlavní stránka: Gadget kitchen: recording metrics

Různé

Nevýhody a problémy gadgetů

  • Gadgety vyvíjejí členové komunity. K dnešnímu dni se pro gadgety na stránkách Wikimedie nevyžaduje žádná formální kontrola kódu (viz phab:T71445). Řiďte se prosím osvědčenými postupy uvedenými na této stránce.
  • Na stránkách Wikimedia není proces, jak "povýšit" uživatelský skript na gadget na kartě "Gadgety" v uživatelských nastaveních, vždy jasný. Budete muset najít správce rozhraní a možná mu budete muset poskytnout pokyny k nasazení.
  • Wikimedia postrádá systematický proces pro opětovné použití, úpravu a přispívání do stávajících uživatelských skriptů a gadgetů.

Nápady, na čem pracovat

Někteří členové komunity Wikimedia se mohou podělit o své nápady, které by chtěli vidět implementované někým jiným.

Nasazení nebo povolení miniaplikace

Pokud se má váš uživatelský skript stát gadgetem (viz definice výše) na wiki, je třeba provést následující kroky:

  • Kroky pro autora uživatelského skriptu:
    • Najměte si zkušeného vývojáře, který zkontroluje kód vašeho gadgetu. Neexistuje žádný formální postup, jak to udělat.
    • Zeptejte se členů komunity, zda nemají nějaké obavy ohledně povolení gadgetu na wiki. Pro samotný web MediaWiki.org by to byl Projekt:Village Pump.
    • Najměte si administrátora webu s právy rozhraní. Viz stránka Special:ListUsers/interface-admin na vaší wiki.
  • Kroky pro správce rozhraní:
    • Zkopírujte soubory JS a CSS do jmenného prostoru MediaWiki: jmenného prostoru na vaší wiki a ujistěte se, že názvy stránek mají předponu Gadget-.
      Příklad: MediaWiki:Gadget-userfeedback.js
    • Definujte gadget na stránce MediaWiki:Gadgets-definition vaší wiki. To zahrnuje použité moduly, závislosti, názvy souborů JS a CSS atd. To uživatelům umožní povolit gadget na stránce Special:Preferences vaší wiki.
      Příklad: userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css
    • Vytvořte stránku pro gadget ve jmenném prostoru MediaWiki: s předponou Gadget-. Tím se na stránce Special:Preferences vaší wiki vygeneruje štítek pro gadget.
      Příklad: MediaWiki:Gadget-userfeedback

Přispívání do uživatelských skriptů

Pokud uživatelský skript vytvořil jiný uživatel, můžete k němu přispívat. Můžete to udělat tak, že si vytvoříte kopii uživatelského skriptu jako podstránku vaší vlastní uživatelské stránky. Pak nahraďte původní uživatelský skript, který jste povolili, skriptem, který je uživatelskou stránkou ve vašem souboru common.js. Pokračujte v úpravách vaší kopie skriptu dle libosti. Pokud chcete, aby skript obsahoval změny, které jste provedli ve své kopii skriptu, měli byste poslat příkaz ping autorovi skriptu na diskusní stránce původního uživatelského skriptu se stránkou, která obsahuje vaše změny, a požádat ho o přidání změn. Pokud uživatel již není aktivní, měli byste informovat komunitu o existenci vaší verze skriptu odkazem na skript v seznamu skriptů vaší wiki.

Související stránky

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