Jump to content

Handleiding: Extensies ontwikkelen

From mediawiki.org
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 u een extensie ontwikkelt, vervang MyExtension hierboven met de naam van uw extensie. Gebruik "UpperCamelCase" naamgeving voor uw bestandsmappen en PHP bestand(en); dit is de algemene Bestandsbenaming conventie.[1] (De extensie BoilerPlate is een goed startpunt voor uw 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

Uw 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 u de extensie door gebruikers wilt laten aanpassen, dan moet u 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 de installatiebestanden een aantal taken uitvoeren (gedetailleerd beschreven in de volgende secties):

  • registreert elke media-handler, parserfunctie, speciale pagina, zelfgemaakte XML tag en variabele die gebruikt wordt in uw extensie.
  • definieer en/of valideer elke configuratie variabele die u heeft gedefinieerd voor de extensie.
  • maak de klassen die gebruikt worden in de extensie klaar voor autoloading
  • bepaal welke onderdelen van de 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 de extensie
  • maak of controleer nieuwe database-tabellen de nodig zijn voor de extensie.
  • stel lokalisatie voor de 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. U kunt 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 u een oudere versie van de MediaWiki moet ondersteunen, kies de meest recente versie.

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

Extensies:

De extensie configureerbaar maken voor gebruikers

Als u gebruikers de extensie wilt laten configureren, dan moet u éé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 de extensie "MyExtension" heet, dan wilt u dat al uw variabelen beginnen met $wgMyExtension. Het is belangrijk wat u 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 uw variabelenamen overlappen met een andere extensie.

Het is ook een goed idee om uitgebreide documentatie voor alle configuratievariabelen in de 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 u 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 u ervoor kiest om klassen te gebruiken om de extensie te implementeren, dan biedt MediaWiki een versimpeld mechanisme om PHP te helpen met het vinden van het bronbestand waar de klasse staat. In de meeste gevallen hoeft u dan niet uw eigen __autoload($classname) methode te schrijven.

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

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

De bestandsnaam is gerelateerd aan de map waar uw extension.json bestand in staat.

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 Waarschuwing: als uw extensie gebruikt wordt op een WMF-gehoste wiki volg dan de Schema change guide.

Als uw extensie eigen tabellen moet toevoegen, gebruik de hook LoadExtensionSchemaUpdates . 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 u 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|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 wilt u wellicht de cache uitzetten met behulp van $wgMainCacheType = CACHE_NONE en $wgCacheDirectory = false, anders zullen systeemmeldingen waarschijnlijk niet weergeven worden.

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

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

Sla berichtdefinities in een lokalisatie JSON-bestand op, één voor elke taal waarin uw 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 kunt u 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 uw extension.json, definieer de locatie van uw berichtbestanden (bijv. in de map i18n/): 

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

Gebruik wfMessage in PHP

in uw 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.
    • 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/nl – 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. U hoeft uzelf niet te beperken tot het formatteren van tekst binnenin de tags. U 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.
  • 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.
    • 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 – U kunt 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.43 gebruiken dienen de REL1_43 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 {{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 de bestaande extensie te auto-categoriseren en te standaardiseren, zie Sjabloon:Extensie . om uw 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 uw 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 uw extensie namespaces toevoegt, dan wilt u 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

U moet publiek domein hulpdocumentatie voor functies van uw extensie beschikbaar maken. The convention is for extensions to have their user-focused help pages under a pseudo-namespace of Help:Extension:<ExtensionName>, with whatever subpages are required (the top level page will be automatically linked from the extension infobox if it exists). Help:CirrusSearch is een voorbeeld van goede documentatie. U moet gebruikers een link naar de documentatie geven via de functie addHelpLink() .

Updates releasen

Er zijn een aantal gemeenschappelijke benaderingen voor het vrijgeven van updates van extensies. These are generally defined according to the compatibility policy of the extension (master, rel, or ltsrel):

  • master - Releases kunnen worden getagged met versienummer op de master branch en documentatie op de homepage van de extensie waarin wordt beschreven welke versie van de extensie compatibel is met welke kernversie. De branches worden nog steeds automatisch gecreëerd en u kunt deze verwijderen als u ze niet wilt gaan gebruiken.
  • rel and ltsrel - Release by backporting changes to the REL1_* branches (either all changes, or only critical ones). Versienummers zijn over het algemeen niet nodig, tenzij de extensie afhankelijk is van een andere extensie (het versienummer kan dan worden opgegeven in de configuratie van de andere extensie om ervoor te zorgen dat incompatibele combinaties niet worden geïnstalleerd). Veel extensies houden jarenlang hetzelfde versienummer.

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 kunt u samenwerken met gebruikers en ontwikkelaars om bugs te vinden en toekomstige functionaliteiten toe te voegen aan de 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=6693837"