Příručka:Vývoj rozšíření

From mediawiki.org
This page is a translated version of the page Manual:Developing extensions and the translation is 100% complete.
Languages:
Rozšíření:
Rozšíření MediaWiki

Každé rozšíření se skládá ze tří částí:

  1. Nastavení
  2. Provedení
  3. Lokalizace

Minimalistická struktura rozšíření bude vypadat takto:

MyExtension/extension.json
Ukládá instrukce nastavení. Název souboru musí být extension.json. (Před verzí MediaWiki 1.25 byly pokyny k nastavení v souboru MyExtension/MyExtension.php pojmenovaném podle přípony. Mnoho rozšíření má v tomto souboru PHP stále podložky zpětné kompatibility.)
MyExtension/includes/ (or MyExtension/src/)
Ukládá kód provedení PHP pro rozšíření.
MyExtension/resources/ (or MyExtension/modules/)
Ukládá prostředky na straně klienta, jako je JavaScript, CSS a LESS pro rozšíření.
MyExtension/i18n/*.json
Pro uložení souborů s překlady, pro lokalizaci vašeho rozšíření.

Při vývoji rozšíření nahraďte MyExtension výše názvem svého rozšíření. Použijte názvy UpperCamelCase pro jeho adresář a soubor(y) PHP. Toto je obecná konvence pojmenování souborů.[1] (Při zakládání nového repozitáře můžete začít úpravou rozšíření BoilerPlate.)

Při vývoji můžete chtít zakázat ukládání do mezipaměti nastavením $wgMainCacheType = CACHE_NONE a $wgCacheDirectory = false, jinak se systémové zprávy a další změny nemusí zobrazit.

Nastavení

Vaším cílem při psaní části nastavení je co nejvíce usnadnit instalaci rozšíření, takže uživatelé musí do LocalSettings.php přidat pouze tento řádek: 

wfLoadExtension( 'MyExtension' );

Pokud chcete, aby bylo vaše rozšíření uživatelsky konfigurovatelné, musíte definovat a zdokumentovat některé konfigurační parametry a nastavení vašich uživatelů by mělo vypadat nějak takto: 

wfLoadExtension( 'MyExtension' );
$wgMyExtensionConfigThis = 1;
$wgMyExtensionConfigThat = false;

K dosažení této jednoduchosti musí váš instalační soubor provést řadu úkolů (podrobně popsaných v následujících částech):

  • zaregistrovat jakýkoli obslužný program médií, funkci analyzátoru, speciální stránku, vlastní značku XML a proměnnou používané vaším rozšířením.
  • definovat a/nebo ověřit jakékoli konfigurační proměnné, které jste definovali pro své rozšíření.
  • připravit třídy používané vaším rozšířením pro automatické načítání
  • určit, které části vašeho nastavení by měly být provedeny okamžitě a co je třeba odložit, dokud nebude inicializováno a nakonfigurováno jádro MediaWiki
  • definovat jakékoli další háčky potřebné pro vaše rozšíření
  • vytvořit nebo zkontrolovat jakékoli nové databázové tabulky požadované vaším rozšířením.
  • nastavit lokalizaci pro vaše rozšíření
Osvědčeným postupem je přidat soubor README se základními informacemi o instalaci a konfiguraci rozšíření. Můžete použít prostý text nebo [syntaxi značek https://secure.phabricator.com/book/phabricator/article/remarkup/ Phabricator]. Podívejte se například na [stránku https://phabricator.wikimedia.org/diffusion/EPFM Phabricator Diffusion] pro Rozšíření:Page Forms . Pokud se používá markdown, přidejte příponu souboru .md. Podívejte se například na soubor README.md pro Parsoid na Phabricator Diffusion.

Registrace funkcí na MediaWiki

MediaWiki uvádí všechna rozšíření, která byla nainstalována na stránce Special:Version. Všechna rozšíření nainstalovaná na této wiki můžete například vidět na Special:Version.

Verze MediaWiki:
≥ 1.25

Chcete-li to provést, přidejte podrobnosti rozšíření na extension.json . Záznam bude vypadat nějak takto: 

{
	"name": "Example",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:Example",
	"description": "This extension is an example and performs no discernible function",
	"version": "1.5",
	"license-name": "GPL-2.0-or-later",
	"type": "validextensionclass",
	"manifest_version": 1
}


Mnoho polí je volitelných, ale přesto je dobré je vyplnit. manifest_version odkazuje na verzi schématu, do které je zapsán soubor extension.json . Dostupné verze jsou 1 a 2. Dokumentaci k této funkci najdete zde. Pokud nepotřebujete podporovat starší verzi MediaWiki, vyberte nejnovější verzi.

Kromě výše uvedené registrace musíte svou funkci také "zaháčkovat" do MediaWiki. Výše uvedené pouze nastaví stránku Special:Version. Způsob, jakým to uděláte, závisí na typu vašeho rozšíření. Podrobnosti naleznete v dokumentaci pro každý typ rozšíření:

Rozšíření:

Konfigurace uživatele vašeho rozšíření

Pokud chcete, aby váš uživatel mohl konfigurovat vaše rozšíření, budete muset zadat jednu nebo více konfiguračních proměnných. Je dobré dát těmto proměnným jedinečný název. Měli by také dodržovat konvence pro názvy MediaWiki (např. globální proměnné by měly začínat $wg).

Pokud se například vaše rozšíření jmenuje "MyExtension", možná budete chtít pojmenovat všechny konfigurační proměnné tak, aby začínaly $wgMyExtension. Je důležité, aby žádné jádro MediaWiki nezačínalo své proměnné tímto způsobem a vy jste odvedli rozumnou práci, abyste zjistili, že žádné z publikovaných rozšíření nezačíná své proměnné tímto způsobem. Uživatelé nebudou ochotni volit mezi vaším rozšířením a některými dalšími rozšířeními, protože jste zvolili překrývající se názvy proměnných.

Je také dobré zahrnout do poznámek k instalaci rozsáhlou dokumentaci všech konfiguračních proměnných.

Zde je příklad boiler plate, kterou lze použít pro začátek: 

{
	"name": "BoilerPlate",
	"version": "0.0.0",
	"author": [
		"Your Name"
	],
	"url": "https://www.mediawiki.org/wiki/Extension:BoilerPlate",
	"descriptionmsg": "boilerplate-desc",
	"license-name": "GPL-2.0-or-later",
	"type": "other",
	"AutoloadClasses": {
		"BoilerPlateHooks": "includes/BoilerPlateHooks.php",
		"SpecialHelloWorld": "includes/SpecialHelloWorld.php"
	},
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	},
	"callback": "BoilerPlateHooks::onExtensionLoad",
	"ExtensionMessagesFiles": {
		"BoilerPlateAlias": "BoilerPlate.i18n.alias.php"
	},
	"Hooks": {
		"NameOfHook": "BoilerPlateHooks::onNameOfHook"
	},
	"MessagesDirs": {
		"BoilerPlate": [
			"i18n"
		]
	},
	"ResourceModules": {
		"ext.boilerPlate.foo": {
			"scripts": [
				"resources/ext.boilerPlate.js",
				"resources/ext.boilerPlate.foo.js"
			],
			"styles": [
				"resources/ext.boilerPlate.foo.css"
			]
		}
	},
	"ResourceFileModulePaths": {
		"localBasePath": "",
		"remoteExtPath": "BoilerPlate"
	},
	"SpecialPages": {
		"HelloWorld": "SpecialHelloWorld"
	},
	"manifest_version": 2
}

Všimněte si, že po volání wfLoadExtension( 'BoilerPlate' ); globální proměnná $wgBoilerPlateEnableFoo neexistuje. Pokud proměnnou nastavíte např. v LocalSettings.php, pak se výchozí hodnota uvedená v extension.json nepoužije.

Další podrobnosti o tom, jak používat globální proměnnou uvnitř vlastních rozšíření, naleznete v Příručka:Konfigurace pro vývojáře .

Příprava kurzů pro automatické načítání

Pokud se rozhodnete pro implementaci svého rozšíření používat třídy, MediaWiki poskytuje zjednodušený mechanismus, který pomáhá PHP najít zdrojový soubor, kde se nachází vaše třída. Ve většině případů by to mělo eliminovat potřebu psát vlastní metodu __autoload($classname).

Chcete-li použít mechanismus automatického načítání MediaWiki, přidejte položky do pole AutoloadClasses . Klíčem každé položky je název třídy. Hodnota je soubor, ve kterém je uložena definice třídy. U jednoduchého rozšíření jedné třídy má třída obvykle stejný název jako rozšíření, takže vaše sekce automatického načítání může vypadat takto (rozšíření se jmenuje MyExtension): 

{
	"AutoloadClasses": {
		"MyExtension": "includes/MyExtension.php"
	}
}

Název souboru je relativní k adresáři, ve kterém je soubor extension.json.

U složitějších rozšíření je třeba zvážit jmenné prostory. Podrobnosti viz Příručka:Extension.json/Schema#AutoloadNamespaces.

Definování dalších háčků

Podívejte se na stránku Příručka:Háčky .

Přidávání databázových tabulek

Ujistěte se, že rozšíření nemění základní databázové tabulky. Místo toho by rozšíření mělo vytvořit nové tabulky s cizími klíči k příslušným tabulkám MW.

Varování Varování: Pokud je vaše rozšíření použito na jakékoli produkční wiki hostované ve WMF, postupujte podle Průvodce změnou schématu.

Pokud vaše rozšíření potřebuje přidat vlastní databázové tabulky, použijte háček LoadExtensionSchemaUpdates . Další informace o použití naleznete na stránce s příručkou.

Nastavit lokalizaci

Více vám řekneː

Přidat protokoly

V rámci MediaWiki se zaznamenávají veškeré akce uživatelů realizované v rámci wiki, neboť cílem je spolupráce a transparentnost. Podívejte se na stránku Příručka:Přihlášení do Special:Log jak se to dělá.

Zpracování závislostí

Předpokládejme, že rozšíření vyžaduje přítomnost dalšího rozšíření, například proto, že mají být použity funkce nebo databázové tabulky a v případě neexistence je třeba se vyhnout chybovým hlášením.

Například rozšíření CountingMarker vyžaduje přítomnost rozšíření HitCounters pro určité funkce.

Jedním ze způsobů, jak to určit, by bylo použití klíče vyžadováno v extension.json.

Další možností je použití ExtensionRegistry (dostupné od MW 1.25): 

	if ( ExtensionRegistry::getInstance()->isLoaded( 'HitCounters', '>=1.1' ) {
		/* do some extra stuff, if extension HitCounters is present in version 1.1 and above */
	}

Currently (as of February 2024, MediaWiki 1.41.0) the name of the extension-to-be-checked needs to exactly match the name in their extension.json.[2][3]

Example: if you want to check the load status of extension "OpenIDConnect", you have to use it with a space 

	if ( ExtensionRegistry::getInstance()->isLoaded( 'OpenID Connect' ) {
    ...
	}

Lokalizace

Při vývoji můžete chtít zakázat obě mezipaměti nastavením $wgMainCacheType = CACHE_NONE a $wgCacheDirectory = false, jinak se změny systémových zpráv nemusí projevit.

Pokud chcete, aby bylo vaše rozšíření používáno na wiki, které mají vícejazyčnou čtenářskou obec, budete muset do svého rozšíření přidat podporu lokalizace.

Ukládat zprávy v <language-key>.json

Uložte definice zpráv do lokalizačního souboru JSON, jednu pro každý jazykový klíč, do kterého je vaše rozšíření přeloženo. Zprávy se ukládají pomocí message key a zprávy samotné pomocí standardního formátu JSON. Každé ID zprávy by mělo být malé a může neobsahovat mezery. Každý klíč by měl začínat malým názvem rozšíření. Příklad najdete v rozšíření MobileFrontend. Zde je příklad minimálního souboru JSON (v tomto případě en.json):

en.json 

{
	"myextension-desc": "Adds the MyExtension great functionality.",
	"myextension-action-message": "This is a test message"
}

Dokumentaci zpráv uložte do souboru qqq.json

Dokumentace ke klíčům zpráv může být uložena v souboru JSON pro pseudojazyk s kódem qqq. Dokumentace k výše uvedenému příkladu může být:

qqq.json: 

{
	"myextension-desc": "The description of MyExtension used in Extension credits.",
	"myextension-action-message": "Adds 'message' after 'action' triggered by user."
}

Načtěte lokalizační soubor

V souboru extension.json definujte umístění souborů zpráv (např. v adresáři i18n/): 

{
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	}
}

Použijte wfMessage v PHP

V kódu nastavení a implementace nahraďte každé doslovné použití zprávy voláním wfMessage( $msgID, $param1, $param2, ... ). Ve třídách, které implementují IContextSource (stejně jako některé další, jako jsou podtřídy SpecialPage), můžete místo toho použít $this->msg( $msgID, $param1, $param2, ... ). Příklad: 

wfMessage( 'myextension-addition', '1', '2', '3' )->parse()

Použijte mw.message v JavaScriptu

V JavaScriptu je možné používat i funkce i18n. Podrobnosti najdete na Příručka:Zprávy API .

Typy rozšíření

Rozšíření:

Rozšíření lze kategorizovat na základě technik programování použitých k dosažení jejich účinku. Většina složitých rozšíření bude používat více než jednu z těchto technik:

  • Podtřída: MediaWiki očekává, že určité druhy rozšíření budou implementovány jako podtřídy základní třídy poskytované MediaWiki:
    • Příručka:Speciální stránky – Podtřídy třídy SpecialPage se používají k vytváření stránek, jejichž obsah je dynamicky generován pomocí kombinace aktuálního stavu systému, vstupních parametrů uživatele a databázových dotazů. Lze generovat zprávy i formuláře pro zadávání dat. Používají se jak pro reportovací, tak pro administrativní účely.
    • Příručka:Zobrazení – Vzhledy mění vzhled a dojem z MediaWiki změnou kódu, který zobrazuje stránky podtřídou třídy MediaWiki SkinTemplate .
  • Příručka:Háčky – Technika pro vkládání vlastního kódu PHP do klíčových bodů zpracování MediaWiki. Jsou široce používány analyzátorem MediaWiki, jeho lokalizačním jádrem, systémem správy rozšíření a systémem údržby stránek.
    • Asociace tag-funkce – XML značky stylu, které jsou spojeny s funkcí php, která vydává HTML kód. Nemusíte se omezovat na formátování textu uvnitř značek. Nemusíte to ani zobrazovat. Mnoho rozšíření značek používá text jako parametry, které řídí generování HTML, které vkládá objekty Google, formuláře pro zadávání dat, kanály RSS, úryvky z vybraných článků wiki.
  • Příručka:Kouzelná slovíčka – Technika mapování různých textových řetězců wiki na jediné id, které je spojeno s funkcí. Tuto techniku používají jak proměnné, tak funkce parseru. Veškerý text namapovaný na toto id bude nahrazen návratovou hodnotou funkce. Mapování mezi textovými řetězci a id je uloženo v poli $magicWords. Interpretace id je poněkud složitý proces – více informací najdete na stránce Příručka:Kouzelná slovíčka .
    • Variable – Proměnné jsou něco jako nesprávné pojmenování. Jsou to kousky wikitextu, které vypadají jako šablony, ale nemají žádné parametry a byly jim přiřazeny pevně zakódované hodnoty. Standardní značky wiki jako {{PAGENAME}} nebo {{SITENAME}} jsou příklady proměnných. Své jméno získávají ze zdroje své hodnoty: Proměnná php nebo něco, co by bylo možné přiřadit k proměnné, např. řetězec, číslo, výraz nebo návratová hodnota funkce.
    • Příručka:Parsovací funkce – {{functionname: argument 1 | argument 2 | argument 3...}}. Podobně jako u rozšíření značek zpracovávají funkce analyzátoru argumenty a vrací hodnotu. Na rozdíl od rozšíření značek je výsledkem funkcí analyzátoru wikitext.
  • API moduly – do api|action API MediaWiki můžete přidat vlastní moduly, které mohou být vyvolány JavaScriptem, roboty nebo klienty třetích stran.
  • Page content models – Pokud potřebujete ukládat data v jiných formátech než wikitext, JSON atd., můžete vytvořit nový ContentHandler .

Podpora dalších základních verzí

Existují dvě rozšířené konvence pro podporu starších verzí jádra MediaWiki:

  • Master: Hlavní větev rozšíření je kompatibilní s co největším počtem starých verzí jádra. To má za následek zátěž na údržbu (hacky se zpětnou kompatibilitou je třeba udržovat po dlouhou dobu a změny rozšíření je třeba testovat na několika verzích MediaWiki), ale weby se starými verzemi MediaWiki těží z funkcí, které byly nedávno přidány do rozšíření.
  • Uvolněné větve: Uvolněné větve nástavby jsou kompatibilní s odpovídajícími větvemi jádra, např. stránky používající MediaWiki 1.41 musí používat REL1_41 větev rozšíření. (U rozšíření hostovaných na gerrit jsou tyto větve automaticky vytvořeny, když jsou vydány nové verze MediaWiki.) Výsledkem je čistší kód a rychlejší vývoj, ale uživatelé na starých základních verzích nemají prospěch z oprav chyb a nových funkcí, pokud nejsou backported ručně.

Správci rozšíření by měli pomocí parametru compatibility policy šablony {{Extension }} deklarovat, jakou konvenci dodržují.

Licence

MediaWiki je projekt s otevřeným zdrojovým kódem a uživatelům se doporučuje, aby si přijali jakékoli MediaWiki extensions v rámci licence Open Source Initiative (OSI) schválené kompatibilní s GPL-2.0-or-later (standardní softwarová licence Wikimedie).

Pro vaše projekty v Gerritu doporučujeme přijmout jednu z následujících kompatibilních licencí:

U rozšíření, která mají kompatibilní licenci, můžete požádat vývojáře o přístup ke zdrojovým úložištím MediaWiki pro rozšíření. Pro specifikaci licence v kódu a s "license-name" by měl být použit klíč, který poskytne její krátký název, např. "GPL-2.0-or-later" nebo "MIT" v souladu s seznam identifikátorů na spdx.org.


Publikování

Chcete-li autokategorizovat a standardizovat dokumentaci vašeho stávajícího rozšíření, přečtěte si prosím Template:Extension . Chcete-li přidat nové rozšíření do této Wiki:


Vývojář sdílející svůj kód v úložišti kódu MediaWiki by měl očekávat:

Zpětná vazba / Kritika / Recenze kódu
Recenze a komentáře ostatních vývojářů k věcem, jako je [použití rámce https://doc.wikimedia.org/], zabezpečení, efektivita a použitelnost.
Vývojářské ladění
Ostatní vývojáři upravující váš příspěvek, aby vylepšili nebo vyčistili váš kód, aby vyhovoval novým třídám a metodám rámce, kódovacím konvencím a překladům.
Vylepšený přístup pro správce systému wiki
Pokud se rozhodnete umístit svůj kód na wiki, jiný vývojář se může rozhodnout, pro snadnější údržbu, jej přesunout do úložiště kódu MediaWiki. Poté můžete vytvořit Účet vývojáře a pokračovat v jeho údržbě.
Budoucí verze od jiných vývojářů
Nové větve vašeho kódu se vytvářejí automaticky s vydáním nových verzí MediaWiki. Pokud chcete podporovat starší verze, měli byste se vrátit na tyto větve.
Začlenění vašeho kódu do jiných rozšíření s duplicitními nebo podobnými účely – začlenění nejlepších funkcí z každého rozšíření.
Zásluhy
Poděkování za zachování vaší práce v budoucích verzích – včetně všech sloučených rozšíření.
Podobně byste měli připsat zásluhy vývojářům všech rozšíření, jejichž kód si půjčujete – zejména při sloučení.

Žádný vývojář, kterému je nepříjemná jakákoli z těchto akcí, by neměl být hostitelem v úložišti kódu. Stále se doporučuje vytvořit souhrnnou stránku pro vaše rozšíření na wiki, aby lidé věděli o rozšíření a kde si jej mohou stáhnout.

Nasazení a registrace

Pokud máte v úmyslu své rozšíření nasadit na stránky Wikimedie (včetně případně Wikipedie), je zaručena další kontrola z hlediska výkonu a zabezpečení. Konzultujte Psaní rozšíření pro nasazení .

Pokud vaše rozšíření přidává jmenné prostory, možná budete chtít zaregistrovat jeho výchozí jmenné prostory. Podobně, pokud přidá databázové tabulky nebo pole, možná je budete chtít zaregistrovat v Předpony databázových polí .

Uvědomte si prosím, že kontrola a nasazení nových rozšíření na stránkách Wikimedie může být extrémně pomalé a v některých případech trvalo více než dva roky.[4]

Dokumentace nápovědy

Měli byste poskytnout dokumentaci nápovědy k veřejné doméně pro funkce poskytované vaším rozšířením. Nápověda:CirrusSearch je dobrým příkladem. Měli byste uživatelům poskytnout odkaz na dokumentaci prostřednictvím funkce addHelpLink() .

Poskytování podpory / spolupráce

Vývojáři rozšíření by si měli otevřít účet na Wikimedii Phabricator a požádat o nový projekt pro rozšíření. To poskytuje veřejné místo, kde mohou uživatelé odesílat problémy a návrhy, a vy můžete spolupracovat s uživateli a dalšími vývojáři na třídění chyb a plánování funkcí vašeho rozšíření.

Související odkazy

Learn by example


Poznámky pod čarou

  1. ↑ mailarchive:wikitech-l/2011-August/054839.html
  2. ↑ https://www.mediawiki.org/wiki/Topic:Xyjw7nhfzaas5r5z
  3. ↑ https://phabricator.wikimedia.org/T356596
  4. ↑ phabricator:T148848
Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Developing_extensions/cs&oldid=6349612"