Benutzer:Schnark/js/rpc

Dieses Skript stellt ein Framework für Remote Procedure Calls in JavaScript zur Verfügung, wobei sich remote hier auf eine möglicherweise noch nicht geladene Datei bezieht, in der die Funktion definiert ist, die aufgerufen werden soll.

Benutzung

Bei der Verwendung muss sichergestellt werden, dass das Framework bereits geladen ist, bevor der erste Funktionsaufruf erfolgt. Am einfachsten ist es vermutlich, den Code zu komprimieren und mit einem Kommentar über die Herkunft in das benutzende Skript einzufügen.

Definition

Damit eine Funktion über dieses Skript aufgerufen werden kann, müssen zwei Punkte beachtet werden. Zum einen muss die Funktion ein jQuery-promise (oder etwas dazu kompatibles) zurückgeben. Falls du einfach nur einen Wert zurückgeben willst, kannst du den Wrapper rpc.ret verwenden, der einen beliebigen Wert in ein Promise verwandelt, das mit diesem Wert aufgelöst wird. Zum anderen muss die Funktion über rpc.define als RPC-Funktion definiert werden.

Verwendung

Bevor eine Funktion verwendet werden kann, muss angegeben werden, in welcher Datei sie sich befindet, dies geschieht über rpc.register. Anschließend kann über rpc.stub ein lokaler Stub erstellt werden, oder die Funktion über rpc.call direkt aufgerufen werden. Das Ladeverhalten kann über zwei Schnittstellen beeinflusst werden: rpc.preload dient dem Laden einer Datei, auch wenn sie noch nicht gleich benötigt wird, rpc.timeout gibt an, wie lange auf das Laden einer Datei gewartet werden soll.

Beispiel

Datei Benutzer:Name/extern.js

(function (rpc) {

function mwAPI (data) {
	return $.get(mw.util.wikiScript('api'), data);
}

function version () {
	return rpc.ret(1.1);
}

rpc.define('mwAPI', mwAPI);
rpc.define('version', version);

})(mw.libs.rpc);

Datei Benutzer:Name/aufruf.js

(function (rpc) {

rpc.register('mwAPI', 'Benutzer:Name/extern.js');
rpc.register('version', 'Benutzer:Name/extern.js');

var mwAPI = rpc.stub('mwAPI');

mwAPI({action: 'query', meta: 'siteinfo', format: 'json'}).done(function (result) {
	console.log(result);
}).fail(function (error) {
	console.log(error);
});

rpc.call('version').done(function (v) {
	console.log('Die Version ist ' + v);
});

})(mw.libs.rpc);

Funktionen und Variablen

Alle Funktionen und Variablen sind Elemente von rpc, das unter mw.libs.rpc zur Verfügung steht.

Funktion	Parameter	Bedeutung
register	name, datei	Die Funktion mit Namen name befindet sich in der Datei datei. Alternativ kann auch die volle URL angegeben werden. Liefert true im Erfolgsfall, false wenn unter diesem Namen schon eine Funktion existiert.
define	name, funktion	Stellt die Funktion funktion unter dem Namen name zum Aufruf bereit. Liefert true im Erfolgsfall, false wenn unter diesem Namen schon eine Funktion existiert.
preload	name	Lädt die Datei mit der Funktion des Namens name.
exists	name	Ermittelt, ob es eine Funktion mit Namen name gibt.
call	name, ...	Ruft die Funktion name auf, übergibt dieser alle weiteren Parameter, und gibt ein Promise zurück, das fast dem Rückgabewert der Funktion entspricht, zusätzlich aber mit den Fehlern 'missing' (falls register nicht aufgerufen wurde) oder 'timeout' zurückgewiesen werden kann.
stub	name	Liefert eine Funktion, die sich (fast) wie das Original verhält, zu den Abweichungen siehe call.
ret	wert	Gibt ein Promise zurück, das mit dem Wert wert aufgelöst wird.
Variablen		Bedeutung
timeout		Dauer in Millisekunden, nach der das Laden einer Datei als gescheitert angesehen wird (Standard: 5000).
version		Version des rpc-Skripts

Code

Der Javascript-Code befindet sich unter Benutzer:Schnark/js/rpc.js, ein QUnit-Test unter Benutzer:Schnark/js/rpc.js/test.js.