Manual:Ajax

From MediaWiki.org
Jump to: navigation, search
This page contains changes which are not marked for translation.

Language: English  • 日本語

MediaWiki offers a deprecated Ajax interface for use by extensions. Ajax is a term for using JavaScript to load parts of a page on demand. MediaWiki 1.16 shipped JQueryjQuery, accordingly use of Sajax is discouraged.

Therefore, Javascript code should instead use jQuery.ajax() (or the mediawiki.api javascript module). One would perform a MediaWiki API query over AJAX (instead of Manual:$wgAjaxExportListManual:$wgAjaxExportList).

Details[edit | edit source]

Asynchronous requests[edit | edit source]

An asynchronous request sends some data to the server, and continues execution. Some time later, the server might return a response (depending on the type of request); in which case the response will be passed to a Javascript function for handling. Another function may be supplied to handle the case that the request fails for some reason. Below is an example call to the login API by posting the username and password.

mw.loader.using( 'mediawiki.api', function () {
	( new mw.Api() ).get( {
		action: 'query',
		lgname: 'foo',
		lgpassword: 'foobar'
	} ).done( function ( data ) {
		alert( data );
	} );
} );

Alternatively, you can use jQuery's functions directly:

$.ajax({
        // request type ( GET or POST )
	type: "GET",
        
        // the URL to which the request is sent
	url: mw.util.wikiScript('api'),
        
        // data to be sent to the server
	data: { action:'query', format:'json', lgname:'foo', lgpassword:'foobar' },
        
        // The type of data that you're expecting back from the server
	dataType: 'json',
        
        // Function to be called if the request succeeds
	success: function( jsondata ){
		alert( jsondata.result );
	}
});

The function "mw.util.wikiScript" is available since 1.18 onwards.

synchronous request[edit | edit source]

The other kind of request sends some data to the server, and waits for the response. This means that the Javascript will be blocked until the server returns some data, or the request fails for some reason. The following example retrieves the "What links here" list of a templates:

whatLinksHere = JSON.parse(
    $.ajax({
        url:mw.util.wikiScript('api'),
        data: { action: 'query', format: 'json', list: 'embeddedin', eititle: 'Template:' + templateName, eilimit: 500 },
        async:false
    })
    .responseText
);

// ... usage ...
for (i=0; i<whatLinksHere.query.embeddedin.length; i+=1) {
    alert(whatLinksHere.query.embeddedin[i]);
}

(JSON.parse() is a Javascript standard function that returns an object from its string representation in JSON format.)

Limitations[edit | edit source]

Due to the same origin policy, it is difficult for a script on an external site to retrieve data from a wiki that is hosted on a different domain — for example, one cannot directly retrieve data from http://en.wikipedia.org/wiki/ to http://example.org/wiki/. Newer browsers support an explicit instruction to permit this access via cross-origin resource sharing but this will only work with servers that are configured to issue the appropriate headers, and the user must be using a recent browser that recognises it. Developers with concerns about legacy browsers can't rely on CORS yet.

It is possible to circumvent the Same-Origin policy using JSONP instead of plain JSON which will work in older browsers (including Internet Explorer 6).

$.ajax({
    url: '//www.mediawiki.org/w/api.php?format=jsonty&action=query&meta=siteinfo&siprop=general&callback=?',
    data: {
        format: 'json'
    },
    dataType: 'jsonp'
}).done( function ( data ) {
    ...
} );

Related deprecated functionality[edit | edit source]

Sajax is an ancient Ajax library that (as of September 2012) is still part of core code and is used by some extensions. Don't use it, use jQuery.ajax() instead. Some extensions, whether using Sajax or not, make Ajax calls through the obsolete AjaxDispatcher by invoking index.php?action=ajax&rs=something.... They should instead make MediaWiki APIManual:API requests to API modules api.php?action=something.

See also[edit | edit source]

External links[edit | edit source]

General information on XMLHttpRequest: