MediaWiki

Handleiding: Extensies ontwikkelen

This page is a translated version of the page Manual:Developing extensions and the translation is 100% complete.
Languages:
Extensies:
MediaWiki extensies

Elke extensie bestaat uit drie onderdelen:

  1. Instellen
  2. Uitvoering
  3. Lokalisatie

Een extensie bestaat minimaal uit drie bestanden, één voor elk onderdeel:

MyExtension/extension.json
Bevat de instel-instructies. Het bestand moet "extension.json" heten. (Voor MediaWiki 1.25 zaten de opzet instructies in een MyExtension/MyExtension.php bestand vernoemd naar de extensienaam. Veel extensies hebben 'backwards-compatibility' functies in dit PHP bestand.)
MyExtension/includes/ (or MyExtension/src/)
Bevat de uitvoer code voor de extensie.
MyExtension/resources/ (or MyExtension/modules/)
Slaat de bronnen aan de kant van de cliënt op zoals JavaScript, CSS en LESS voor de extensie.
MyExtension/i18n/*.json
Bevat lokalisatie informatie voor de extensie.

Als je een extensie ontwikkelt, vervang MyExtension hierboven met de naam van jouw extensie. Gebruik "UpperCamelCase" naamgeving voor je bestandsmappen en PHP bestand(en); dit is de algemene Bestandsbenaming conventie.[1] (De extensie BoilerPlate is een goed startpunt voor jouw extensie.)

Tijdens ontwikkelen is het handig om caching uit te zetten door $wgMainCacheType = CACHE_NONE en $wgCacheDirectory = false in te stellen, anders zullen systeem-meldingen en andere veranderingen wellicht niet weergeven worden

Instellen

Je doel bij het schrijven van het deel voor de setup is het zo eenvoudig mogelijk maken om de extensie te installeren, zodat gebruikers alleen deze regel hoeven toe te voegen aan LocalSettings.php: 

wfLoadExtension( 'MyExtension' );

Als je jouw extensie door gebruikers wilt laten aanpassen, dan moet je configuratieparameters definiëren en documenteren, de gebruikersinstellingen zien er dan ongeveer zo uit: 

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

Om deze eenvoud te bereiken, moeten je installatiebestanden een aantal taken uitvoeren (gedetailleerd beschreven in de volgende secties):

  • registreer elke media handler, parser functie, speciale pagina, zelfgemaakte XML tag en variabele die gebruikt wordt in jouw extensie.
  • definieer en/of valideer elke configuratie variabele die je hebt gedefinieert voor je extensie.
  • maak de klassen die gebruikt worden in je extensie klaar voor autoloading
  • bepaal welke onderdelen van je instellingen onmiddellijk uitgevoerd moeten worden en welke onderdelen uitgevoerd moeten worden nadat de MediaWiki core is ge-initialiseerd en geconfigureerd is
  • definieer bijgevoerde Hooks die nodig zijn voor je extensie
  • maak of controleer nieuwe database-tabellen de nodig zijn voor je extensie.
  • stel lokalisatie voor je extensie in
Het is goed om standaard een bestand README toe te voegen, in dat bestand kan dan de installatie en de configuratie van de extensie beschreven worden. U kunt het in gewone tekst schrijven of de Phabricator wiki syntaxis gebruiken. Voorbeeld bij Extension:Page Forms/nl : phabricator diffusion pagina. Als er markdown wordt gebruikt, voeg dan het achtervoegsel .md toe. Voorbeeld bij Parsoid : de README.md code van de phabricator diffusion pagina.

MediaWiki kenmerken registreren

MediaWiki laat alle geinstalleerde extensies zien op de Special:Version pagina. Je kan bijvoorbeeld alle extensies die geïnstalleerd zijn op deze wiki zien in Special:Version.

MediaWiki-versie:
≥ 1.25

Om dit te doen, voeg de details van de extensie toe aan extension.json . De regel is dan iets als dit: 

{
	"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
}


Veel velden zijn optioneel, maar het is verstandig om ze in te vullen. De manifest_version refereert naar de versie van het schema die in het extension.json bestand is geschreven. De beschikbare versies zijn 1 en 2. Lees voor documentatie over deze functie. Tenzij je een oudere versie van de MediaWiki moet ondersteunen, kies de meest recente versie.

Naast de hierboven geschreven registratie moet je ook je functionaliteit een "hook" geven in MediaWiki. Het bovenstaande installeert alleen de Special:Version pagina. De manier waarop je dit doet hangt af van you extensietype. Voor details, lees de documentatie voor elke extensietype:

Extensies:

Je extensie configureerbaar maken voor gebruikers

Als je gebruikers jouw extensie wilt laten configureren, dan moet je één of meerdere configuratievariabelen verschaffen. Het is slim om deze variabelen unieke namen te geven. Ze moeten ook de MediaWiki benamings conventies volgen(bijvoorbeeld: globale variabelen moeten beginnen met $wg).

Bijvoorbeeld, als jouw extensie "Mijn Extensie" heet, dan wil je dat al je variabelen beginnen met $wgMijnExtensie. Het is belangrijk wat je kiest, kies geen beginwaarde die door MediaWiki core variabelen worden gebruikt of door gepubliceerde variabelen van extensies. Gebruikers zullen het niet waarderen als ze moeten kiezen tussen extensies omdat je variabelenamen overlappen met een andere extensie.

Het is ook een goed idee om uitgebreide documentatie voor alle configuratievariabelen in je installatienotities te plaatsen.

Hier is een boilerplate voorbeeld dat kan gebruikt worden om te starten: 

{
	"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
}

Let op, na het aanroepen van wfLoadExtension( 'BoilerPlate' ); bestaat de globale variabele $wgBoilerPlateEnableFoo niet. Indien je de variabele een waarde geeft, bijvoorbeeld in LocalSettings.php dan wordt de standaardwaarde die in de extension.json wordt gegeven, niet gebruikt.

Lees Manual:Configuration for developers voor meer informatie over hoe globale variabelen binnen aangepaste extensies te gebruiken.

Klassen klaarmaken om automatisch in te laden

Als je ervoor kiest om klassen te gebruiken om je extensie te implementeren, dan biedt MediaWiki een versimpeld mechanisme om PHP te helpen met het vinden van het bronbestand waar je klasse staat. In de meeste gevallen hoef je dan niet je eigen __autoload($classname) methode te schrijven.

Om MediaWiki's autoloading mechanisme te gebruiken, voeg je vermeldingen toe aan het AutoloadClasses veld. De sleutel voor elke vermelding is de klassenaam; de waarde is het bestand dat de definitie van jouw klasse bevat. Voor een 1-klasse-extensie heeft de klasse meestal dezelfde naam als de extensie, dus je autoloading sectie zit er ongeveer zo uit(extensie is genaamd MyExtension): 

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

De bestandsnaam is gerelateerd aan de map waar je extension.json bestand in zit.

Overweeg namespaces bij meer complexere extensies. Lees Manual:Extension.json/Schema#AutoloadNamespaces voor details.

extra hooks definiëren

Zie Manual:Hooks .

Database-tabellen toevoegen

Controleer dat de extensie niet de kern database tabellen aanpast. Een extensie moet eigen tabellen aanmaken met foreign keys naar de bestaande tabellen.

  Waarschuwing: als je extensie gebruikt wordt op een WMF-gehoste wiki volg dan de Schema change guide.

Als je extensie eigen tabellen moet toevoegen, gebruik de LoadExtensionSchemaUpdates hook. Bekijk de handleidingpagina voor meer informatie over het gebruik.

Lokalisatie instellen

Zie:

Logs toevoegen

in Mediawiki worden alle gebruikersactie op een wiki gevolgd tbv transparantie en samenwerking. Bekijk Manual:Logging to Special:Log om te zien hoe je dit doet?

Afhankelijkheden

Als een extensie een andere extensie nodig heeft, bijvoorbeeld omdat die functionaliteit of database tabellen worden gebruikt moeten foutmelding vanwege het ontbreken ervan worden voorkomen.

Stel: extensie CountingMarker heeft de extensie HitCounters voor een bepaald functie nodig.

Een manier om dit te specificeren zou zijn met requires key in extension.json.

Een andere optie is het gebruik van ExtensionRegistry (beschikbaar vanaf MediaWiki 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' ) {
    ...
	}

Lokalisatie

Tijdens ontwikkelen wil je wellicht de cache uitzetten met behulp van $wgMainCacheType = CACHE_NONE en $wgCacheDirectory = false, anders zullen systeemmeldingen waarschijnlijk niet weergeven worden.

Als je wilt dat je extensie gebruikt wordt op meertalige wiki's, dan is het verstandig om lokalisatie te ondersteunen in je extensie.

Berichten opslaan in "<language-key>".json

Sla berichtdefinities in een lokalisatie JSON bestand op, één voor elke taal waarin je extensie vertaald is. De berichten worden opgeslagen met een berichtsleutel en het bericht zelf in standaard JSON format. Elk bericht ID moet kleine letters bevatten en mag geen spaties bevatten. Elke key moet beginnen met de naam van de extensie in kleine letters. Een voorbeeld hiervan kan je zien in de extensie MobileFrontend. Hier is een voorbeeld van een minimum JSON bestand (in dit geval "en.json":

en.json 

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

Berichtdocumentatie opslaan in "qqq".json

De documentatie voor berichtsleutels kan opgeslagen worden in het JSON bestand for de pseudo-taal met de code qqq. de documentatie voor het voorbeeld hierboven kan er zo uitzien:

qqq.json: 

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

lokalisatiebestand laden =

In je extension.json, definieer de locatie van je berichtbestanden (bijv. in de map i18n/): 

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

Gebruik wfMessage in PHP

in je installatie- en implementatiecode, vervang elke statisch bericht met een call naar wfMessage( $msgID, $param1, $param2, ... ). In klassen die IContextSource toepassen(alsook sommige subklassen van SpecialPage), kan in plaats daarvan $this->msg( $msgID, $param1, $param2, ... ) gebruiken. Voorbeeld: 

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

Gebruik mw.message in JavaScript

het is mogelijk om i18n functies in JavaScript te gebruiken. zie Handleiding:Messages API voor details.

Extensietypes

Extensies:

Extensies kunnen gecategoriseerd worden gebaseerd op de programmeertechnieken die gebruikt zijn om hun functionaliteit te tonen. De meeste complexe extensies gebruiken vaak meer dan 1 van de volgende technieken:

  • Subklassering: MediaWiki verwacht bepaalde extensies die als subklassen van een MediaWiki basisklassen geïmplementeerd worden.
    • Handleiding:Speciale pagina's – Subklassen van de SpecialPage klasse worden gebruikt om pagina's te bouwen waarvan de inhoud dynamisch gegenereerd wordt met behulp van ene combinatie van de huidige systeemstaat, input parameters en databasie queries. Zowel report en data invoer formulieren kunnen gegenereerd worden. Ze worden gebruikt voor rapportage- en administratiedoeleinden.
    • Skins – Skins veranderen het uiterlijk en gebruik van Mediawiki door de code die pagina's maakt aan te passen door een subklasse te maken van de MediaWiki SkinTemplate klasse.
  • Hooks – Een techniek voor speciale PHP code te injecteren op specifieke punten in MediaWikiprocessen. Ze worden veel gebruikt door MediaWiki's parser, de lokalisatie-engine, de extensiemanagementsysteem, and haar pagina-onderhoudsysteem.
    • Tag-functie associaties – XML style tags die gekoppeld zijn aan een PHPfunctie die HTML code teruggeeft. Je hoeft jezelf niet te limiteren tot het formateren van text binnenin de tags. Je hoeft het niet eens weer te geven. Veel tag-extensies gebruiken tekst als parameters die de generatie van HTML helpt bij het invoegen van google objecten, data-invoer formulieren, RSS feeds en uittreksels van geselecteerde wiki-artikelen.
  • Handleiding:Magische woorden – Een techniek voor het indexeren van een variëteit aan wiki tekst string aan een ID dat gekoppeld is aan een functie. zowelvariabelen enparser functies gebruiken beide deze techniek. Alle text die gekoppeld is aan dat id zal vervangen worden met de teruggave van de functie. de indexatie tussen de strings en het ID is opgeslagen in de $magicWords Array. De interpretatie van het id is een vrij ingewikkeld process - zie Handleiding:Magische woorden voor meer informatie.
    • Variable – Variabelen zijn een soort van misnaming. Variabelen zijn stukjes wikitekst die er uitzien als sjablonen maar die geen parameters hebben en die gekoppeld zijn aan hard-gecodeerde waardes. Standaard wiki-opmaak zoals {{PAGENAME}} of {{SITENAME}} zijn voorbeelden van variabelen. Ze krijgen hun naam van hun bronwaarden: een php-variabele of iets dat aan een variable gekoppeld kan worden, bijvoorbeeld een string, nummer, expressie of een teruggave van een functie.
    • Handboek:Parserfuncties – {{functionname: argument 1 | argument 2 | argument 3...}}. Soortgelijk aan tag-extensies, parserfuncties bewerken argumenten een geven een waarde terug. in tegenstelling tot tag-extensies, het resultaat van een parserfunctie is wikitekst.
  • API modulen – je kan eigen modules aan MediaWiki's action API koppelen, die door javascript, bots en clients aangeroepen kan worden.
  • Page content models – Als het nodig is om gegevens op te slaan in formaten anders dan wikitext, JSON, enz. maak dan een ContentHandler aan.

Andere core versies ondersteunen

Er zijn twee veelgebruikte conventies voor het ondersteunen van oudere versies van de MediaWiki:

  • Master: de master branch van de extensie is compatibel met zoveel mogelijk versies van de core. Dit zorgt voor een last bij het onderhouden (backward compatibiliteit moet lange tijd mogelijk zijn en aanpassingen aan de extensie moeten dus op meerdere versies van de MediaWiki getest worden), maar het zorgt wel dat ook websites met oudere MediaWiki versies voordelen hebben bij recent toegevoegde functionaliteit van de extensie.
  • Release branches: de release branches van een extensie zijn compatibel met de overeenkomende branches van de core, dus websites die MediaWiki 1.41 gebruiken dienen de REL1_41 branch van de extensie te gebruiken. (Voor extensies gehost op gerrit, deze branches worden automatisch aangemaakt bij de release d van een nieuwe versie van MediaWiki.) Dit zorgt voor een schonere code en een snellere ontwikkeling, maar gebruikers op een oudere versie van MediaWiki profiteren niet van het oplossen van fouten en nieuwe functionaliteit tenzij deze wijzigingen handmatig worden toegevoegd aan de oudere versie.

De onderhouders van een extensie dienen met de compatibility policy parameter van het sjabloon {{Sjabloon:Extensie }} aan te geven welke conventie er voor die extensie gevolgd wordt.

Licentie

MediaWiki is een open-source project en gebruikers worden aangemoedigd om MediaWiki extensions te maken onder een Open Source Initiative (OSI) goedgekeurde licentie compatibel met GPL-2.0 of hoger (Wikimedia's standaard software licentie).

Wij bevelen aan om een van de volgende compatibele licenties voor uw projecten in Gerrit, te kiezen:

Voor extensies die een compatibele licentie hebben, u kunt verzoeken om toegang als ontwikkelaar tot de MediaWiki bron repositories voor extensies. Om de licentie in code te specificeren door met "license-name" de korte naam door te geven, bijv. "GPL-2.0-or-later" of "MIT" te koppelen aan de lijst identifiers op spdx.org.


Publiceren

Om de documentatie van je bestaande extensie te auto-categoriseren en standaardiseren, zie Sjabloon:Extensie . om je nieuwe extensie aan deze Wiki toe te voegen:


Een ontwikkelaar die de eigen code deelt in de MediaWiki code repository kan verwachten:

Feedback / Kritiek / Review van de code
Review en commentaar door andere ontwikkelaars over zaken als framework gebruik, veiligheid, efficiëntie en bruikbaarheid.
Optimaliseren, verbeteren
Andere ontwikkelaars kunnen uw code aanpassen om het te verbeteren, optimaliseren, op te schonen, te voldoen aan standaarden over bijvoorbeeld codeer conventies, aanpassen voor nieuwe framework classes en methoden en vertalingen.
Verbeterde toegang voor wiki systeembeheerders
Als u besluit om uw code op de wiki te zetten,mag een andere ontwikkelaar besluiten het te verplaatsen naar de MediaWiki code repository omdat het daar eenvoudiger te onderhouden is. U kunt dan een Ontwikkelaarsaccount aanmaken om het beheer ervan te blijven doen.
Toekomstige versies van andere ontwikkelaars.
Er worden automatisch nieuwe branches van uw code aangemaakt als er een nieuwe versie van MediaWiki uitkomt. U dient deze branches te backporten als u oudere versies wilt blijven ondersteunen.
Het overnemen van uw code in een andere extensie met hetzelfde of vergelijke doelen, het overnemen van de beste functies van elke extensie.
Credit
Het bedanken voor uw werk wordt ook in toekomstige versies gedaan, ook bij elke extensie die uw code heeft overgenomen.
Dat betekent ook dat u dat zelf moet aangeven, geef de credits aan degenen waar u wat code van heeft overgenomen.

Als u zich niet gemakkelijk voelt bij het uitvoeren van een van deze acties, plaats uw code dan niet in de repository. Ongeacht waar u uw code neerzet, zien we graag dat u een samenvattingspagina op de wiki aanmaakt voor uw extensie zodat iedereen kan lezen over uw extensie, en waar het te downloaden is.

Inzetten en registreren

Als het je bedoeling is de extensie op de Wikimedia websites te gebruiken (inclusief mogelijk Wikipedia), dan is aanvullend onderzoek nodig op gebied van performance en veiligheid. raadpleeg Writing an extension for deployment .

Als je extensie namespaces toevoegt, dan wil je wellicht de standaard namespaces van de extensie registeren; soortgelijk, als er database-tabellen of -velden worden toegevoegd, dan kan dat bij database field prefixes geregistreerd worden.

Weet dat het beoordelen en gebruiken van nieuwe extensies op de Wikimedia websites lang kan duren, in enkele gevallen heeft het meer dan 2 jaar geduurd.[4]

Hulpdocumentatie

You moet public-domain hulpdocumentatie voor capaciteiten van je extensie beschikbaar maken. Help:CirrusSearch is een goed voorbeeld. Je moet gebruikers een link naar de documentatie geven via de addHelpLink() functie.

Ondersteuning bieden / samenwerken

extensie-ontwikkelaars moeten een account maken op Wikimedia's Phabricator , en een nieuw project voor de extensie aanvragen. Dit biedt een publiek forum waar gebruikers problemen en suggesties kunnen bieden, en je kan samenwerken met gebruikers en ontwikkelaars om bugs te vinden en toekomstige functionaliteiten toe te voegen aan je extensie.

Zie ook

Learn by example


Referenties

  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/nl&oldid=6349626"