Rozšíření:Gadgets

Příručka k rozšířením MediaWiki

Gadgets Stav rozšíření: stabilní
Implementace	MyWiki , Speciální stránka , API
Popis	Jeho prostřednictvím si může uživatel v rámci svého uživatelského nastavení povolit na stránkých wiki nejrůznější "udělátka" (gadgety), založené na javascriptu.
Autoři	Daniel Kinzler (Duesentriebdiskuse)
Zásady kompatibility	Vydání snímků současně s MediaWiki. Hlavní vývojová větev není zpětně kompatibilní.
MediaWiki	1.19+
Licence	GNU General Public License 2.0 nebo novější
Stáhnout	Stáhněte si rozšíření Git [?]: Procházení úložiště (Phabricator · GitHub) Kontrola kódu Gerrit Zobrazení historie Git Stáhněte si zdrojový soubor tarball README
Příklad	Wikimedia Commons: Přehled gadgetů, uživatelské předvolby (klikněte na "Gadgets". Musíte být samozřejmě přihlášeni.)
Parametry $wgGadgetsDefinitionsUseCodeEditor $wgGadgetsRepo $wgGadgetsDefinitionsUseCodeMirror
Použité háčky (hooks) BeforePageDisplay CodeEditorGetPageLanguage CodeMirrorGetMode ContentHandlerDefaultModelFor DeleteUnknownPreferences GetPreferences PreferencesGetIcon PreferencesGetLegend ResourceLoaderRegisterModules UserGetDefaultOptions getUserPermissionsErrors wgQueryPages
Přeložte rozšíření Gadgets, používá-li lokalizaci z translatewiki.net
Problémy	Otevřené úkoly · Nahlásit chybu

Rozšíření Gadgets, umožňuje uživatelům využívat nejrůznější "gadgety", založené na CSS a JavaScriptu, která v obsahu wiki stránek použili tvůrci obsahu.

Tvoří je tzv. snippety. Kousky kódu - snippety , psané v CSS a JavaScriptu, jsou umístěné v rámci jmenného prostoru MediaWiki. Každá "udělátko" (gadget) je definováno coby samostatná řádka wikikódu v obsahu stránky MediaWiki:Gadgets-definition, kde je uveden jeho název a popis, za kterým následuje seznam snippetů s CSS a JS kódem, se kterým bude pracovat – viz níže uvedená část věnovaná použití kódu.

Protože jde o stránky co se nachází ve jmenném prostoru MediaWiki, mohou kód gadgetů a snippetů upravovat pouze uživatelé ze skupiny správci rozhraní – angl. interface admins (od verze 1.32). V téhle skupině by tedy měli být pouze prověření a zkušení uživatelé, kterým komunita kolem wiki opravdu velmi důvěřuje, protože JavaScriptu umožňuje napsat kód, kterým by se dalo jejich důvěry snadno zneužít.

Instalace

Toto rozšíření je součástí MediaWiki 1.18 a vyšší. Zbývající konfigurační pokyny je stále nutné dodržovat.

• Stáhněte soubor/y a vložte je do adresáře pojmenovaného Gadgets ve vaší složce extensions/.
  Vývojáři a přispěvatelé kódu by si místo toho měli nainstalovat rozšíření from Git pomocí:

  cd extensions/
  git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Gadgets
  

• Na konec vašeho souboru LocalSettings.php přidejte následující kód:

  wfLoadExtension( 'Gadgets' );
  

• Dokončeno – Přejděte na stránku Special:Version vaší wiki a zkontrolujte, zda bylo rozšíření úspěšně nainstalováno.

Konfigurace

$wgGadgetsRepo	Zda definovat gadgety v MediaWiki:Gadgets-definition nebo prostřednictvím stránek, jako například MediaWiki:Gadgets/yourGadgetName.json. Pokud je JSON, vytvoří také model obsahu GadgetDefinition. Režim "Json" je ve vývoji a zatím není připraven k použití.
$wgSpecialGadgetUsageActiveUsers	Nastavuje, zda se mají zobrazovat statistiky aktivních uživatelů na účtu Special:GadgetUsage.	true

Použití

Výběr některých gadgetů v uživatelských preferencích na de.wikipedia

Jakmile existuje na stránce MediaWiki:Gadgets-definition definice alespoň jednoho funkčního „udělátka” (gadgetu), začne se všem uživatelům na stránce Special:Preferences zobrazovat nová záložka s názvem „Udělátka”. Tam si může každý uživatel nastavit, jaké z dostupných udělátek chce na stránkách wiki využívat. Přehled „udělátek”, definovaných na stránce MediaWiki:Gadgets-definition, generuje také speciální stránka Special:Gadgets, kde se zobrazují také odkazy na stránky (neexistující) s nápovědou i použité snippety, do kterých lze potřebný kód snadno vložit a případně i dál, podle potřeby upravovat. Statistiky ohledně využití „udělátek” pak najdete na stránce Special:GadgetUsage.

Definice „udělátka” - gadgetu

Každá řádka na stránce MediaWiki:Gadgets-definition, která začíná znakem "*" (hvězdička – asterisk), se interpretuje jako definice „udělátka” (gadgetu) a může vypadat kupř. takto:

* mygadget [parametry] | názvy stránek se snippety

První pole (v příkladu "mygadget") je interní název gadgetu. Popisek stránky nastavení pochází ze stránky s rozhraním (MediaWiki:Gadget-mygadget), kam lze napsat vlastní název a krátký popis, což také umožňuje použití wikitextového značení.

Interní název musí začínat základním latinským písmenem ([A-Za-z]) a může být následován libovolným počtem písmen, číslic ([0-9]), pomlček (-), podtržítek (_) a teček (.). Důvodem tohoto omezení je, že interní název musí být platný jako název HTML formuláře, jako klíč zprávy rozhraní MediaWiki a jako název modulu ResourceLoader.

Parametry:

[ResourceLoader | parametr1 | parametr2 | ... parametrN]

Příznak ResourceLoader je povinný, pokud gadget neobsahuje pouze styly. Možnosti, které jsou "flags" (vlajky, praporky), stačí mít k zapnutí napsaný pouze jejich název. Za možnostmi, které vyžadují hodnotu, následuje znaménko rovnosti a seznam hodnot oddělených čárkami. Všechny prázdné znaky jsou volitelné a lze je vynechat.

[ResourceLoader | myflag | mykey = value1, value2, value3 ]

Příklady:

* mygadget[ResourceLoader]|mygadget.js|mygadget.css

nebo

* mygadget[ResourceLoader|package]| mygadget.js | mygadget-Foo.js | mygadget-data.json | mygadget-template.vue | mygadget.css

nebo

* mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css

Použití jmenného prostoru definic gadgetů

Verze MediaWiki:

≤ 1.41

Existují dva způsoby, jak definovat gadgety v závislosti na hodnotě $wgGadgetsRepoClass. Pokud je to 'MediaWikiGadgetsDefinitionRepo' (výchozí hodnota), seznam dostupných gadgetů je definován na MediaWiki:Gadgets-definition. Alternativně jsou definice gadgetů definovány na stránkách ve jmenném prostoru Definice gadgetu, když je $wgGadgetsRepoClass nastaveno na 'GadgetDefinitionNamespaceRepo'. (Na MediaWiki 1.39+ je místo toho použita hodnota '\\MediaWiki\\Extension\\Gadgets\\GadgetDefinitionNamespaceRepo'.)

Migrace stávajících definic gadgetů zatím není podporována, takže po změně této možnosti ztratíte dříve definované gadgety.

Vytvoření stránky Gadget definition:mygadget a vložení níže uvedeného kódu JSON na ni má stejný účinek jako mygadget[ ResourceLoader | rights=foo, bar ] | mygadget.js | mygadget.css.

{
	"settings": {
		"rights": [ "foo", "bar" ],
		"default": false,
		"package": false,
		"hidden": false,
		"skins": [],
		"actions": [],
		"category": ""
	},
	"module": {
		"scripts": [ "mygadget.js" ],
		"styles": [ "mygadget.css" ],
		"datas": [],
		"peers": [],
		"dependencies": [],
		"codexIcons": [],
		"messages": [],
		"type": ""
	}
}

Ve výše uvedeném příkladu jsou použity hodnoty Gadget:Mygadget.js a Gadget:mygadget.css.

Parametry

Možnosti

Název	Hodnota	Popis	Od verze
ResourceLoader	žádná	Označí skripty gadgetu jako kompatibilní s ResourceLoader .	1.17 (r76527)
dependencies	Názvy modulů oddělené čárkami	Tyto moduly budou načteny před spuštěním skriptů tohoto gadgetu. Viz seznam výchozích modulů.	1.17 (r76639)
rights	Názvy oprávnění oddělené čárkami	Zpřístupní gadget (a zobrazí ho v nastavení) pouze uživatelům, kteří mají zadaná oprávnění.	1.18 (r85268)
hidden	žádná	Skrýt gadget na stránce Nastavení. Toto lze použít dvěma způsoby: Povolit miniaplikaci ve výchozím nastavení bez možnosti jejího zakázání (jako modulární alternativa k Common.js). Všimněte si, že je třeba přidat obojí: hidden | default pro načtení modulu pro všechny uživatele. Gadgety, které nejsou určeny pro koncové uživatele, ale spíše jsou určeny k načítání jinými gadgety. Například umožnit dvěma gadgetům opakované použití stejného interního kódu nebo zaregistrovat "core" (jádro) část gadgetu, která se načítá pouze na určitých stránkách.	1.28
skins	Názvy vzhledů oddělené čárkami	Zpřístupnit gadget (a zviditelnit ho v nastavení) pouze uživatelům, kteří používají zadané vzhledy. Před verzí MediaWiki 1.32 se bral v úvahu vzhled nastavený v preferencích uživatele, nikoli aktuálně zobrazený (jako při přidání ?useskin=monobook do URL adresy, T199478). Od verze 1.39 není modul ResourceLoader registrován na vzhledech, na kterých není gadget k dispozici, takže gadget nelze na tyto vzhledy načíst jako závislost ani pomocí přepínače mw.loader.load() (T236603). Použití skins je až krajní možnost a mělo by být omezeno na specializovaný kód. Například kód, který se při absenci standardizovaných API spoléhá na manipulaci s DOM a který nelze implementovat pomocí Core modulů.	1.19 (r100509)
actions	Názvy akcí oddělené čárkami	Zpřístupní gadget pouze pro zadané akce na stránce. Např. actions = edit, history pro načtení gadgetu pouze při úpravách a na stránkách historie. Zadání akce edit ji také načte na action=submit. Neplatné akce deaktivují gadget, protože jej nelze nikde spustit.	1.38 (gerrit:747112)
categories	Názvy kategorií oddělené čárkami	Zpřístupní gadget pouze v určených kategoriích. Např. categories = Archived, Maintenance pro načtení gadgetu pouze na stránkách v kategorii Category:Archived nebo Category:Maintenance. Více na stránce: Template gadgets	1.42 (gerrit:1005092)
namespaces	Čísla jmenných prostorů oddělená čárkami	Zpřístupní gadget pouze v zadaných jmenných prostorech. Např. namespaces = 0, 2 pro načtení gadgetu pouze v hlavním prostoru a uživatelském jmenném prostoru.	1.41 (gerrit:624517)
contentModels	Modely obsahu odděleného čárkami	Zpřístupní gadget na stránkách s danými modely obsahu. Např. contentModels = wikitext pro načtení gadgetu pouze na stránkách wikitextu.	1.41 (gerrit:922062)
default	žádná	Povolí miniaplikaci ve výchozím nastavení pro všechny (včetně IP adres). Registrovaní uživatelé si ji stále mohou zakázat ve svých preferencích.	1.18 (r85902)
package	žádná	Označí tento gadget jako zabalený. V tomto režimu bude spuštěna pouze první stránka JavaScriptu. Další stránky lze importovat pomocí funkce require(). Tento režim také umožňuje použití stránek JSON, které jinak nelze zahrnout.	1.38
type	styles (výchozí nastavení pro gadgety pouze s CSS) nebo general (výchozí nastavení jinak)	Pro moduly, které upravují styl pouze prvků, které jsou již na stránce (např. při úpravě vzhledu, rozvržení nebo obsahu článku), použijte hodnotu styles. To způsobí, že soubory CSS modulu budou zahrnuty z HTML stránky, místo aby byly načteny pomocí JavaScriptu. Podrobnosti naleznete na stránce Průvodce migrací/ResourceLoader (uživatelé)#Typ gadgetu. Použitím parametru styles se nenačtou žádné zadané soubory JavaScriptu. Pro gadgety, které upravují styl elementů pomocí JavaScriptu a CSS, jsou vyžadovány dvě samostatné definice gadgetů.	1.28
peers	Názvy gadgetů oddělené čárkami	Tyto gadgety s CSS budou načteny s tímto gadgetem. Tyto gadgety budou načteny před jakýmikoli závislostmi a jejich styly budou použity, i když je JavaScript zakázán. Podrobnosti naleznete na stránce Průvodce migrací/ResourceLoader (uživatelé)#Gadget peers.	1.29
codexIcons	Comma-separated codex icon names	Tyto ikony Codexu budou načteny s tímto gadgetem, viz Seznam všech ikon. Budou k dispozici ze souboru o velikosti icons.json vygenerovaného v balíčku.	1.45 (gerrit:1108823)
supportsUrlLoad	žádná | true | false	Zpřístupní gadget k načtení s parametrem dotazu URL ?withgadget.	1.38

Odstraněné možnosti

Název	Parametry	Popis	Od verze	Odstraněno
top	žádný	Způsobí, že se gadget načítá shora. Toto by se mělo používat střídmě, ale může být potřeba pro některé inicializační záležitosti, jako je registrace pluginů ve VisualEditoru.	1.22 (gerrit:75506)	1.29
requiresES6	žádný	Povolí použití syntaxe ES6 (ES2015) v gadgetu. Povolení této možnosti znamená, že se pro gadget přeskočí ověření syntaxe na straně serveru. Všechny gadgety vyžadující ES6 se načítají společně v jednom webovém požadavku, což izoluje selhání způsobená neplatnou nebo nepodporovanou syntaxí pouze na tyto gadgety, aniž by to ovlivnilo ostatní gadgety a funkce softwaru MediaWiki. Doporučuje se použít nástroj jako ESLint, aby se zajistilo použití pouze platné syntaxe ES6. Konflikt s default.	1.40 (gerrit:758086)	1.42
targets	desktop, mobile nebo desktop, mobile (výchozí)	Nastavte cílovou ResourceLoader pro gadget. Nepoužívejte targets, ale v nezbytně nutném případě použijte skins.	1.21 (gerrit:60954)	1.42

Pro své gadgety můžete zadat další závislosti, například:

* mygadget[ResourceLoader|dependencies=jquery.ui, jquery.effects.clip]|mygadget.js|mygadget.css

Zde požádáme ResourceLoader, aby načetl moduly jquery.ui a jquery.effects.clip s kódem mygadget. Upozorňujeme, že gadgety nemohou záviset na skriptech ze stránek, statických souborech nebo externích URL adresách, pouze na modulech, které jsou již registrovány v ResourceLoaderu. Aby skript ze stránky závisel na jiném skriptu ze stránky, měl by být každý z nich gadget, který se zaregistruje jako modul v ResourceLoaderu. Poté lze pomocí následující syntaxe nastavit závislosti:

* childgadget[ResourceLoader|dependencies=ext.gadget.parentgadget]|childgadget.js

Chcete-li povolit miniaplikaci ve výchozím nastavení, použijte "default":

* mygadget[ResourceLoader|default|dependencies=mediawiki.util]|mygadget.js|mygadget.css

Chcete-li, aby byl gadget dostupný pouze uživatelům s příslušnými oprávněními, nastavte parametr rights, například:

* ImprovedDeletion [rights=delete] | ImprovedDeletion.js

Díky tomu je gadget k dispozici pouze uživatelům, kteří mohou stránky mazat.

Upozorňujeme, že omezení jsou založena na oprávněních, nikoli na uživatelských skupinách, jako jsou administrátoři nebo byrokraté. Zde je několik skutečných příkladů:

* modrollback [ResourceLoader |rights=rollback] |modrollback.js
* geonotice [ResourceLoader |default |rights=viewmywatchlist] |geonotice.js
* Ajax_sysop [ResourceLoader |rights=patrol, rollback, markbotedits, delete]|Ajax_sysop.js

Stránky

Zbývající pole v definičním řádku odkazují na zdrojové stránky JavaScript, CSS, JSON (od verze 1.38) a Vue.js (od verze 1.45), které tvoří modul gadgetu. Ty jsou uloženy ve jmenném prostoru MediaWiki jako zprávy rozhraní (v tomto příkladu MediaWiki:Gadget-mygadget.js a MediaWiki:Gadget-mygadget.css). Názvy stránek musí končit na .css, .js, .json, .vue.

Gadget může používat libovolný počet zdrojových stránek, např.:

 * frobinator[ResourceLoader]|frob.js|frob.css|pretty.css
 * l33t[ResourceLoader]|l33t.js
 * foobar[ResourceLoader|package]|foo.js|bar.js|foobar-data.json
 * foo[ResourceLoader|package|dependencies=vue,@wikimedia/codex]|codextest.js|codextest-main.vue|codextest-ChangeNameDialog.vue

Upozorňujeme, že pokud váš kód obsahuje řetězce, které by mohly být interpretovány jako syntax wiki (např. kód podpisu ~~~~), můžete kód uzavřít do ‎<nowiki>...‎</nowiki> a tyto tagy umístit do komentářů JavaScriptu nebo CSS, aby nebyly při použití interpretovány.

Příklad viz 12. a poslední řádek kódu MediaWiki:Gadget-formWizard-core.js.

Sekce

Seznam miniaplikací v MediaWiki:Gadgets-definition lze rozdělit do sekcí pomocí řádků, které začínají a končí dvěma nebo více znaky "=" (rovná se), a které uzavírají název systémové zprávy definující název sekce, například:

 == interface-gadgets ==
 ...
 == editing-gadgets ==
 ...

Tím by se definovaly dvě nové sekce s názvy definovanými na stránkách MediaWiki:Gadget-section-interface-gadgets a MediaWiki:Gadget-section-editing-gadgets.

Oblíbená udělátka

Viz meta:Gadgets pro gadgety, které jsou oblíbené v komunitách Wikimedie.

Související odkazy

• Special:Gadgets – uvádí všechny gadgety a stručný popis každého z nich
• Správce gadgetů
• Extension:Widgets
• Kousky kódu - snippety