Help:Gadget Coding

This page is an help page to help to code a javascript APIs. It will be filled (at first) by a detailed usecase, and will compile the relevant documentation pages found on the way.

Documentations

Javascript APIs

Mediawiki coding APIs

Usecases

Usecase One : evolving a gadget

The plan is to code a gadget to build a request to the Leonore, database of the french archives. I'll start with the code of the Reasonator gadget, who adds a link in the tools list in a wikipage.

Analysis

  
/*
 * Simple gadget to add a link to reasonator in the Tools section on items.
 */
 
( function ( mw, $ ) {
	var entityId = mw.config.get( 'wbEntityId' );
	if ( !entityId ) {
		return;
	}
	// Add portlet link for item
	mw.util.addPortletLink(
		'p-tb',
		'//tools.wmflabs.org/reasonator/?' + $.param( {
			q: entityId,
			lang: mw.config.get( 'wgUserLanguage' )
		} ),
		'Reasonator',
		't-reasonator',
		'This Wikidata item in reasonator'
	);
}( mediaWiki, jQuery ) );

live comment : use <source> to insert source code in a wikipage, <code> is for inline wikicode it seems

The other input of this work, the url given by Pyb that shows the url form he wants to build from an entity : [1].

At first sight, this means we want to query a little bit of informations about the person (or persons) named lenoir, those informations beeing given in the url as parameters : the type of request : RETROUVER (retrieve) as a value to the parameter ACTION, and the REQ parameter is the request iteself. Without understanding everything, (leloir) gives the string to find in the database, and NOM,NOM2,NOM-JF,NOM-MARI,SURNOM,NOTES are the name of the fields that will be displayed on the result (in french). We want in the ouptput page the name, the maiden name and the notes about the person.

I don't care about those fields, the part I want to change in the url is just lenoir. I'll rewrite the url : http://www.culture.gouv.fr/public/mistral/leonore_fr?ACTION=RETROUVER&REQ=((<requestedstring>):NOM,NOM2,NOM-JF,NOM-MARI,SURNOM,NOTES)]

API quest

The reasonator script uses information about an entity. It retrieve its in this line : var entityId = mw.config.get( 'wbEntityId' ); It uses the mw object. This object seems documented on mediawiki.org. I have trouble finding what I want, I might have to code a little more than I expected. Get datas below the entity id in Wikibase seems at the moment not totally implemented in the javascript wikibase extensions libraries.

I think of two options :

getting the datas in the html of the page, which is the faster
writing code to get the dataset of this entity in json throw Wikidata url for its Wikibase instance and work in javascript to find what I want.

I choose the first one, as it will be faster, needing no call to the server, the data is already here. I'll have to use firebug or the development tools on my navigator to find the information I need to query the datas of the loaded page. Using the "code inspector tool", I click on the item label. It does not work as I expected. I use the same tool using Firebug : I get an xpath

/html/body/div[3]/div[3]/div[4]/div/h1/span/span

and a CSS expression :

html.client-js body.mediawiki div#content.mw-body div#bodyContent.mw-body-content div#mw-content-text.mw-content-ltr div#wb-item-Q192498.wb-entity h1#wb-firstHeading-Q192498.wb-firstHeading span.wb-property-container-value span.wb-value

To get the text from this expression, it's easy, you just have to use the jQuery libray basic functionality :

$( "html.client-js body.mediawiki div#content.mw-body div#bodyContent.mw-body-content div#mw-content-text.mw-content-ltr div#wb-item-Q192498.wb-entity h1#wb-firstHeading-Q192498.wb-firstHeading span.wb-property-container-value span.wb-value" ).text()

The only trick is to change the Qid in this string, which can be achieved by splitting the string into pieces and use the string concatenation operator in javascript, "+"

 "html.client-js body.mediawiki div#content.mw-body div#bodyContent.mw-body-content div#mw-content-text.mw-content-ltr div#wb-item-" + entityId + ".wb-entity h1#wb-firstHeading-" + entityId + "span.wb-property-container-value span.wb-value"

Quick and dirty but this will probably do.

Finishing

After a couple trial and mistake :

( function ( mw, $ ) {
	var entityId = mw.config.get( 'wbEntityId' );
	if ( !entityId ) {
		return;
	}

	// to remember, css selector found in a sample page
	// html.client-js body.mediawiki div#content.mw-body div#bodyContent.mw-body-content div#mw-content-text.mw-content-ltr div#wb-item-Q192498.wb-entity h1#wb-firstHeading-Q192498.wb-firstHeading span.wb-property-container-value span.wb-value

	// building the CSS selector which depends on the entity ID, and querying the corresponding label in the DOM
	name_to_query = $("html.client-js body.mediawiki div#content.mw-body div#bodyContent.mw-body-content " +
	"div#mw-content-text.mw-content-ltr div#wb-item-"
	+ entityId + 
	".wb-entity h1#wb-firstHeading-"
	+ entityId +
	".wb-firstHeading span.wb-property-container-value span.wb-value").text();


	// sample query link
	// link http://www.culture.gouv.fr/public/mistral/leonore_fr?ACTION=RETROUVER&REQ=((leloir):NOM,NOM2,NOM-JF,NOM-MARI,SURNOM,NOTES)


	// Add portlet link for item
	mw.util.addPortletLink(
		'p-tb',
		// link building
		'http://www.culture.gouv.fr/public/mistral/leonore_fr?' + $.param( {
			ACTION: "RETROUVER",
			REQ: "((" + name_to_query + "):NOM,NOM2,NOM-JF,NOM-MARI,SURNOM,NOTES)"
		} ),
		'Leonore',
		't-leonore',
		'This item label search in the Leonore database'
	);
}( mediaWiki, jQuery ) );

Final result : User:TomT0m/Leonore.js