Handleiding: Extensies ontwikkelen

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page Manual:Developing extensions and the translation is 94% complete.

Outdated translations are marked like this.
Other languages:
العربية • ‎български • ‎Deutsch • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎italiano • ‎日本語 • ‎한국어 • ‎Latina • ‎Nederlands • ‎polski • ‎português • ‎português do Brasil • ‎русский • ‎سنڌي • ‎中文
Gnome-preferences-other.svg Extensions:Manual:Extensions DevelopmentManual:Developing extensions Tag extensionsManual:Tag extensions Parser functionsManual:Parser functions HooksManual:Hooks Special pagesManual:Special pages SkinsManual:Skins Magic wordsManual:Magic words APIAPI:Extensions
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/MyExtension_body.php
Bevat de Uitvoer code voor de extension. De bestandsnaam MyExtension_body.php is gebruikelijk maar niet verplicht. als je extensie complex is en meerdere PHP bestanden bevat, dan word je aangeraden om de bestanden in een subfolder genaamd MyExtension/includes te plaatsen (alhoewel de BoilerPlate-extensie en de voorbeeldextensie deze regel niet volgen). Bijvoorbeeld, bekijk de Template:$1 extensie.
MyExtension/i18n/*.json
bevat lokalisatie informatie voor de extensie.
Oorspronkelijk bestonden extensies uit één bestand, wellicht vind je nog voorbeelden van deze verouderde stijl.

Als je een extensie ontwikkelt, vervang "MyExtension" hierboven met de naam van jou extensie. Gebruik "UpperCamelCase" naamgeving voor je bestandsmappen en PHP bestand(en); dit is de algemene Bestandsbenaming conventie.[1] (The BoilerPlate extension is a good starting point for your extension. You can also consider using MWStew for generating your extension boilerplate. Also check out the cookiecutter template for MediaWiki extensions on GitHub.)

De drie onderdelen van een extensie, opzet,uitvoering en lokalisatie, alsook de extensie types en licentie geven en het publiceren van jou extensie worden beschreven in de volgende secties op deze pagina.

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

Intellen

Je doel in het instellen is het samenvoegen van je setup zodat gebruikers alleen je opzetbestand in LocalSettings.phpManual:LocalSettings.php hoeven te zetten, zoals hier:

wfLoadExtension( 'MyExtension' );

Als je jou 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):

  • 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

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. Het is goed als jou extensie ook op deze pagina weergeven wordt. Dit doe je door een invoer aan $wgExtensionCreditsManual:$wgExtensionCredits toe te voegen voor elke media handler, parser functie, speciale pagina, custom XML tag, and variabele die gebruikt wordt door jou extensie. De invoer ziet er ongeveer zo uit:

{
	"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+",
	"type": "validextensionclass",
	"manifest_version": 1
}

Zie Manual:$wgExtensionCreditsManual:$wgExtensionCredits voor details over wat deze velden doen. 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.jsonextension.json bestand is geschreven. Voor nu wordt alleen versie 1 ondersteund (MediaWiki 1.26.x en 1.27.x).

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:

Gnome-preferences-other.svg Extensions:Manual:Extensions DevelopmentManual:Developing extensions Tag extensionsManual:Tag extensions Parser functionsManual:Parser functions HooksManual:Hooks Special pagesManual:Special pages SkinsManual:Skins Magic wordsManual:Magic words APIAPI:Extensions

Je extensie configureerbaar maken voor gebruikers

Als je gebruikers jou 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 jou extensie "extensie die niks doet" heet, dan wil je dat al je variabelen beginnen met $ednd of $EDND. Het is niet belangrijk wat je kiest zolang geen van de MediaWiki core variabelen zo beginnen en je hebt gecheckt dat gepubliceerde extensievariabelen zo beginnen. 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.

Waarschuwing Waarschuwing: om register_globalsRegister globals zwakheden te voorkomen, zorg er altijd voor dat al je configuratievariablen in je extensie in je installatie bestand worden meegegeven. Constructies zoals if ( !isset( $wgMyLeetOption ) ) $wgMyLeetOption = somevalue; beschermen niet tegen register_globals!

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": "MIT",
	"type": "other",
	"AutoloadClasses": {
		"BoilerPlateHooks": "BoilerPlate.hooks.php",
		"SpecialHelloWorld": "specials/SpecialHelloWorld.php"
	},
	"config": {
		"BoilerPlateEnableFoo": true
	},
	"callback": "BoilerPlateHooks::onExtensionLoad",
	"ExtensionMessagesFiles": {
		"BoilerPlateAlias": "BoilerPlate.i18n.alias.php"
	},
	"Hooks": {
		"NameOfHook": [
			"BoilerPlateHooks::onNameOfHook"
		]
	},
	"MessagesDirs": {
		"BoilerPlate": [
			"i18n"
		]
	},
	"ResourceModules": {
		"ext.boilerPlate.foo": {
			"scripts": [
				"modules/ext.boilerPlate.js",
				"modules/ext.boilerPlate.foo.js"
			],
			"styles": [
				"modules/ext.boilerPlate.foo.css"
			]
		}
	},
	"ResourceFileModulePaths": {
		"localBasePath": "",
		"remoteExtPath": "BoilerPlate"
	},
	"SpecialPages": {
		"HelloWorld": "SpecialHelloWorld"
	},
	"manifest_version": 1
}

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 AutoloadClassesManual:$wgAutoloadClasses veld. De sleutel voor elke vermelding is de klassenaam; de waarde is het bestand dat de definitie van jou 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": "MyExtension_body.php"
	}
}

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

extra hooks definiëren

Zie Manual:HooksManual:Hooks.

Database-tabellen toevoegen

Waarschuwing 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 LoadExtensionSchemaUpdatesManual:Hooks/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:LogManual:Logging to Special:Log om te zien hoe je dit doet?

Uitvoering

De techniek voor het schrijven van het implementatiegedeelte hangt af van welk deel van MediaWiki jij wilt uitbreiden:

Zie ook Extensions FAQExtensions FAQ, Developer hubDeveloper hub

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. een voorbeeld hiervan kan je zien in 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."
}

Berichten definiëren

  • Assign each message a unique, lowercase, no space message id; e.g.
  • Geef elk bericht een unieke, kleine lettersm, geen spatie bericht id; bijvoorbeelduploadwizard-desc
  • voor elke tekststring weergegeven aan de gebruiker, definieer een bericht.
  • MediaWiki ondersteunt berichten met parameters and die capaciteit moet gebruikt worden wanner een bericht onafhankelijk is van de informatie die gegenereerd wordt op het moment van runtime. Dummy Parameters worden aangegeven met $n, waar n de index van de placeholder is; bijvoorbeeld:
"mwe-upwiz-api-warning-was-deleted": "There was a file by this name, '$1', but it was deleted and you can not reupload the file. If your file is different, try renaming it."

Berichtdocumentaitie definiëren

Elk bericht dat je definieert moet een geassocieerde berichtdocumentatie invoer hebben berichtdocumentatie in 'qqq.json bijvoorbeeld

"uploadwizard-desc": "Description of extension. It refers to [//blog.wikimedia.org/blog/2009/07/02/ford-foundation-awards-300k-grant-for-wikimedia-commons/ this event], i.e. the development was paid with this $300,000 grant."

lokalisatiebestand laden =

In je installatie/opzet routine, 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 IContextSourceManual:RequestContext 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 Manual:Messages APIManual:Messages API voor details.

Extensietypes

Gnome-preferences-other.svg Extensions:Manual:Extensions DevelopmentManual:Developing extensions Tag extensionsManual:Tag extensions Parser functionsManual:Parser functions HooksManual:Hooks Special pagesManual:Special pages SkinsManual:Skins Magic wordsManual:Magic words APIAPI:Extensions

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.
    • Special pagesManual:Special pages – Subklassen van de SpecialPageManual:SpecialPage.php 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.
    • SkinsManual: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.
  • HooksManual: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 associatiesManual:Tag extensionsXML 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.
  • Magic wordsManual:Magic words – 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 Manual:Magic wordsManual:Magic words voor meer informatie.
    • VariableManual: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}}Help:Variables of {{SITENAME}}Help:Variables 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.
    • Parser functionsManual:Parser functions{{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 modulenAPI:Extensionsya kan eigen modules aan MediaWiki's web API koppelen, die door javascript, bots en clients aangeroepen kan worden.


Andere core versies ondersteunen

There are two widespread conventions for supporting older versions of MediaWiki core:

  • Master: the master branch of the extension is compatible with as many old versions of core as possible. This results in a maintenance burden (backwards-compatibility hacks need to be kept around for a long time, and changes to the extension need to be tested with several versions of MediaWiki), but sites running old MediaWiki versions benefit from functionality recently added to the extension.
  • Release branches: release branches of the extension are compatible with matching branches of core, e.g. sites using MediaWiki 1.27 need to use the REL1_27 branch of the extension. (For extensions hosted on gerrit, these branches are automatically created when new versions of MediaWiki are released.) This results in cleaner code and faster development but users on old core versions do not benefit from bugfixes and new features unless they are backported manually.

Extension maintainers should declare with the compatibility policy parameter of the {{Extension}} template which convention they follow.


Licentie

MediaWiki is an open-source project and users are encouraged to make any MediaWiki extensions under an Open Source Initiative (OSI) approved license compatible with GPL-2.0+ (Wikimedia's standard software license).

We recommend adopting one of the following compatible licenses for your projects in Gerrit:

For extensions that have a compatible license, you can request developer access to the MediaWiki source repositories for extensions. To specify the licence in code and with "license-name" a key should be used to provide it's short name, e.g. "GPL-2.0+" or "MIT" adhering to the list of identifiers at spdx.org.

Publiceren

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


A developer sharing their code on the MediaWiki wiki or code repository should expect:

Feedback / Criticism / Code reviews
Review and comments by other developers on things like framework use, security, efficiency and usability.
Developer tweaking
Other developers modifying your submission to improve or clean-up your code to meet new framework classes and methods, coding conventions and translations.
Improved access for wiki sysadmins
If you do decide to put your code on the wiki, another developer may decide to move it to the MediaWiki code repository for easier maintenance. You may then request commit access to continue maintaining it.
Future versions by other developers
New branches of your code being created by other developers as new versions of MediaWiki are released.
Merger of your code into other extensions with duplicate or similar purposes — incorporating the best features from each extension.
Credit
Credit for your work being preserved in future versions — including any merged extensions.
Similarly, you should credit the developers of any extensions whose code you borrow from — especially when performing a merger.

Any developer who is uncomfortable with any of these actions occurring should not host their code directly on the MediaWiki wiki or code repository. You are still encouraged to create a summary page for your extension on the wiki to let people know about the extension, and where to download it. You may also add the {{Extension exception}} template to your extension requesting other developers refrain from modifying your code, although no guarantees can be made that an update will be made if deemed important for security or compatibility reasons. You may use the current issues noticeboard if you feel another developer has violated the spirit of these expectations in editing your extension.


Inzetten en registreren

If you intend to have your extension deployed on Wikimedia sites (including possibly Wikipedia), additional scrutiny is warranted in terms of performance and security. raadpleeg Review queueReview queue.

Als je extensie namespaces toevoegt, dan will je wellicht zijn standaard namespaces registeren; soortgelijk, als database-tabellen of -velden toevoegt, dan wil je die wellicht registreren bij database table and field registrationdatabase table and field registration.

Hulpdocumentatie

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

Ondersteuning bieden / samenwerken

extensie-ontwikkelaars moeten een account maken op Wikimedia's PhabricatorPhabricator, 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


Referenties