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

Deze pagina is een handleiding voor het ontwikkelen van extensies voor MediaWiki. Voordat u begint, blader eens door de lijst met extensies om te zien of er al een extensie bestaat voor uw doel.

De ontwikkeling van een extensie bestaat uit de volgende onderdelen:

  1. Instellen
  2. Implementatie
  3. Lokalisatie
  4. Publicatie

Instellen

Om een nieuwe extensie op te zetten, begint u met het opzetten van een lokale ontwikkelomgeving voor MediaWiki , en volgt u de instructies om de extensie BoilerPlate te installeren en te kopiëren.

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

Structuur

Een minimale extensie heeft de volgende structuur:

MyExtension/extension.json
Bevat de instel-instructies. De bestandsnaam moet extension.json zijn. (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 uit te voeren 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.
MyExtension/README.md
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. Gebruik of platte tekst of Markdown. 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.

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]

Registratie

MediaWiki-versie:
≥ 1.25

Het bestand extension.json bevat de configuratiegegevens voor de extensie. Hier is een voorbeeld van een minimale extension.json: 

{
	"name": "MyExtension",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:MyExtension",
	"description": "This extension is an example.",
	"version": "1.5",
	"license-name": "GPL-2.0-or-later",
	"type": "validextensiontype",
	"manifest_version": 2
}

Veel velden zijn optioneel, maar het is verstandig om ze in te vullen. Voor een meer volledig voorbeeld van extension.json, zie de extensie BoilerPlate.

De manifest_version refereert naar de versie van het schema die in het extension.json bestand is geschreven. De documentatie van deze functie Tenzij u een oudere versie van de MediaWiki moet ondersteunen, kies de meest recente versie.

Zodra u een bestand extension.json heeft ingesteld voor uw extensie, verschijnt de extensie op uw lokale pagina Special:Version.

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.

De extensie configureerbaar maken voor gebruikers

Idealiter zouden gebruikers uw extensie kunnen installeren door slechts één tegel 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;

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 naamgevingsconventies 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 voorbeeld van hoe een configuratie-variabele in extension.json wordt ingesteld: 

{
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	}
}

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 Configuration for developers voor meer informatie over hoe globale variabelen binnen aangepaste extensies te gebruiken.

Classes klaarmaken om automatisch in te laden

Als u ervoor kiest om classes 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 class 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 classname; de waarde is het bestand dat de definitie van uw class bevat. Voor een extensie met maar 1 class heeft de class 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.

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 */
	}

Momenteel (vanaf februari 2024, MediaWiki 1.41.0) moet de naam van de te controleren extensie precies overeenkomen met de naam in hun extension.json.[2][3]

Voorbeeld: als u de laadstatus van extensie OpenIDConnect wilt controleren, moet u deze gebruiken met een spatie 

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

Implementatie

Voor een overzicht van de codearchitectuur, structuur en conventies voor extensies, zie Best practices for extensions .

Extensie-punten

MediaWiki core biedt verschillende manieren voor extensies om het gedrag, de functionaliteit en het uiterlijk van een wiki te veranderen. De meeste extensies gebruiken meer dan één van deze extensie-punten. Voor een volledige lijst van extensie-punten die in extension.json worden ondersteund, zie de schemareferentie .

Algemeen

  • Hooks : Aangepaste code toevoegen op belangrijke punten in de kerncode van MediaWiki, zoals wanneer een gebruiker inlogt of een pagina opslaat. Extensies kunnen pok nieuwe hooks definiëren.
  • API-modules : Definieer API-modules gebaseerd op de Action API of de REST API . Deze modules kunnen worden aangeroepen door bots en clients.
  • Jobs : Voeg jobs toe aan MediaWiki's JobQueue om procesintensieve taken asynchroon uit te voeren, zoals het verzenden van e-mails voor het doen van meldingen.

Pagina's

  • Een speciale pagina tonen : Speciale pagina's bieden dynamisch gegenereerde inhoud, vaak gebaseerd op systeemstatus, database-queries en gebruikersinvoer.
  • En pagina-actie uitvoeren : De URL-parameter action genereert een aangepaste pagina op basis van de huidige pagina, meestal om informatie te verstrekken (zoals paginageschiedenis) of om een actie uit te voeren (zoals het bewerken van de pagina). Naast de standaardacties die worden aangeboden door de MediaWiki core, kunnen extensies een nieuwe pagina-actie definiëren.
  • Een trackingcategorie toevoegen : Helpt gebruikers om pagina's met vergelijkbare kenmerken te vinden door pagina's automatisch aan aangepaste categorieën toe te voegen.

Inhoud

  • Wiki opmaak uitbreiden : Extensies kunnen gebruikersvriendelijke functionaliteit toevoegen aan de wikitext-opmaak van MediaWiki met behulp van template syntaxis ({{...}}) of tags (‎<example />). Deze uitbreidingen worden gebruikt om inhoud te genereren en om te communiceren met MediaWiki tijdens de opbouw van pagina's.
  • Een content-model ondersteunen : Standaard kunnen wiki-pagina's worden opgeslagen met behulp van een paar standaard content-modellen, zoals wikitext en JSON. Extensies kunnen ondersteuning bieden voor nieuwe content-modellen door een content-handler toe te voegen.
  • Een media-type ondersteunen : Extensies kunnen de standaardset ondersteunde mediabestandstypen uitbreiden door een media-handler toe te voegen.

Moderatie hulpmiddelen

Authenticatie

  • Een provider toevoegen : Extensies kunnen ondersteuning toevoegen voor nieuwe inlog-mechanismen en sessiebeheermethoden.

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 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.

Registeren attributen voor andere extensies

Met attributen kunnen extensies iets registreren, zoals een module, met een andere extensie. Extensies kunnen bijvoorbeeld gebruik maken van attributen om een plug-in module te registreren met de extensie VisualEditor. Voor meer informatie, zie Extension registration .

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 classes die IContextSource toepassen (alsook sommige subclasses van SpecialPage), kunt u 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.

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. De conventie is dat extensies hun gebruikersgerichte helppagina's hebben onder een pseudo-namespace van Help:Extension:<ExtensionName>, met welke subpagina's dan ook die nodig zijn (de pagina op het hoogste niveau wordt automatisch gelinkt vanuit de infobox van de extensie als deze bestaat). 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 en ltsrel – Release door wijzigingen in de REL1_*-branches terug te zetten (alle wijzigingen, of alleen kritieke). 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.

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.

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

Leren door voorbeelden


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=7488802"