Wikiup:Technik/Skin/JS/jQuery
Die JavaScript-Bibliothek jQuery enthält viele Hilfsfunktionen, die in WMF-Projekten verfügbar sind. Darüber hinaus entstanden in letzter Zeit zusätzliche Module im Rahmen weltweiter Wikiprojekte, die sich nahtlos in die Sammlung einfügen.
Für das fundamentale jQuery-Objekt kann auch kurz ein $
benutzt werden; verständlicher ist vielleicht die Langform jQuery
.
Im Rahmen dieser Seite wird immer jQuery
vorangestellt, wenn das globale jQuery-Objekt (eigentlich: eine Funktion) gemeint ist; ein vorangestellter Punkt als Beginn eines Funktionsnamens bedeutet, dass die Funktion auf eine einzelne Objekt-Instanz anzuwenden ist, also etwa ein vorangegangenes Suchergebnis.
Anspruch dieser Seite ist es nicht, eine vollständige deutsche Übersetzung der API-Dokumentation von jQuery zu liefern; Programmierbeispiele sind jeweils dort zu finden.
$ oder jQuery
In Mediawiki werden die beiden Objekte $
und jQuery
einander gleichgesetzt. Damit sollten sie eigentlich immer dasselbe Objekt bezeichnen. Gleichwohl kann es in trickreichen Situationen (asynchrone Prozesse, setTimeout) und bei nicht restlos standardkonform arbeitenden Browsern dazu kommen, dass es sich um zwei Kopien mit unterschiedlichem Inhalt handelt.
Es ist üblich, zur sicheren Programmierung den eigenen Code in eine Funktion einzuschließen:
( function ( mw, $ ) {
"use strict";
/* Mein Zeugs */
} ( window.mediaWiki, window.jQuery ) );
Hierdurch entstehen zwei lokale Variablen mw
und $
, die die globalen Objekte window.mediaWiki
und window.jQuery
eindeutig abbilden. Die globalen window.mw
und window.$
werden dadurch maskiert. Im Inneren darf dann nur noch $
benutzt werden, um Inkonsistenzen zu vermeiden und damit die Suche nach Zeichenketten gesichert ist.
jQuery für das DOM
Eine wesentliche Komponente unterstützt das Arbeiten mit dem Document Object Model (DOM), also der Struktur von in HTML geschriebenen Seiten. Es gibt Funktionen, mit denen das DOM durchsucht werden kann, und darüber hinaus solche, die Veränderungen des DOM erleichtern. Die dazu erforderlichen Basis-Funktionen sind im Allgemeinen von vornherein geladen.[1]
Für einige besonders oft benötigte Funktionen nachfolgend einige kurze Hinweise; ansonsten siehe api.jquery.com für vollständige Darstellungen und Programmbeispiele.
document ready
Eine der meistbenutzten Funktionen ist:
jQuery(document).ready(MeineFunktion);
Sie bewirkt, dass MeineFunktion
erst dann ausgeführt wird, wenn das document
grundsätzlich geladen wurde und die Elemente der Basis-Seite bekannt sind. (Siehe dazu Ablauf im Kontext)
Eine unscheinbare Kurzform wäre:
$(MeineFunktion);
Das sollte man jedoch nur benutzen, wenn man der einzige Programmierer ist und sich gut auskennt; dieses für das Verständnis wichtige Ereignis wird sonst zu leicht übersehen.
Außerdem gibt es die Funktion
- jQuery.isReady()
- Wurde das DOM fertig gelesen?
jQuery und DOM
Für die nachstehenden Standardfälle werden die in jedem Browser verfügbaren DOM-Funktionen und die in Wiki-Projekten nutzbaren jQuery-Funktionen gegenübergestellt.
DOM | jQuery |
---|---|
document.getElementById("ident") | $(document).find("#ident") |
– | $(document).find(".classname") |
createElement(tagName) | jQuery("<div>") |
createTextNode(data) | – |
parent.appendChild(newChild) | $parent.append($newChild) |
insertBefore(newChild,refChild) | $refChild.insertBefore($newChild) |
removeChild(oldChild) | $oldChild.remove() |
element.getAttribute("eigenschaft") | $element.attr("eigenschaft") |
element.setAttribute("eigenschaft",wert) | $element.attr("eigenschaft",wert) |
Element suchen
Die Suche entspricht derjenigen über CSS-Selektoren.
- .find(selector)
-
- Finde alle HTML-Elemente, die „Kinder“ des Ausgangsobjekts sind; beispielsweise einer Klasse (hier:
classname
)$erg = $(document).find(".classname");
- Finde das Kind-Element mit einer bestimmten ID (hier:
meins
) – ein valides HTML-Dokument sollte maximal ein solches Element enthalten.$erg = $(document).find("#meins");
- Finde alle spezifischen HTML-Elemente (hier:
table
)$erg = $(document).find("table");
- Finde alle spezifischen HTML-Elemente (hier:
div
) einer Klasse$erg = $(document).find("div.classname");
- Finde alle Elemente zu einem komplexen CSS-Selektor (hier: alle A-Links in jedem DIV classname)
$erg = $(document).find("div.classname A");
- Finde alle Überschriften
$erg = $(document).find("h1,h2,h3,h4,h5,h6");
- Finde alle spezifischen Elemente, die in einem früheren Ergebnis (hier:
$erg
) enthalten sind$erg2 = $erg.find("div.classname");
- Finde alle HTML-Elemente, die „Kinder“ des Ausgangsobjekts sind; beispielsweise einer Klasse (hier:
Das Ergebnis von .find() etc. ist ein neues Objekt vom jQuery-Typ, das sich auch als Array nutzen lässt.
- Es hat sich eingebürgert, die Namen der Variablen solcher Objekte mit einem
$
zu beginnen, um ihre besondere Eigenart zu verdeutlichen. - Das Objekt ist nie
null
– auch wenn nichts gefunden wurde. - Mit einer Abfrage auf
$erg.length
lässt sich feststellen, wie viele Elemente das Ergebnis enthält.
mw.util.$content enthält vorbereitet den Inhaltsbereich der Seite (also ohne die Portal/Skin-Umrandung) und erlaubt daher ein gezieltes Durchsuchen.
Die gesamte Seite erhält man durch: $(document)
- .children(selector)
- Wie .find() – aber begrenzt auf die unmittelbaren Kinder
- tree-traversal
- Weitere Verwandtschaftsbeziehungen
Suchergebnis auswerten
Das Ergebnis von .find()
ist eine Art von Array.
$erg.length
ist die Anzahl der Elemente.$erg[i]
ist der DOM-Node des Elements mit Indexi
.
Auf das gefundene Element oder den Satz mehrerer Elemente lassen sich verschiedene Funktionen anwenden, etwa Eigenschaften abfragen oder setzen, ein Element löschen oder an eine andere Stelle im Dokument verbringen.
Außerdem gibt es folgende Funktionen:
- .each(f)
- Führe für jedes Element die Funktion
f
aus. f
erhält zwei Argumentef(i,e)
– optional können diese ausgewertet werden; Index und das Element.this
ist das gefundene DOM-Element; das müsste identisch mite
sein. Sie können mit$(e)
oder$(this)
in ein jQuery-Objekt umgewandelt werden.- Gibt die Funktion
f
den Wertfalse
zurück, wird die Iteration beendet. - .eq(i)
- Reduziere das Suchergebnis auf das Element i; für i<0 zählt der Index vom Ende aus.
- Die Zählung der Elemente beginnt mit 0.
- .filter()
- Reduziere das Suchergebnis auf Elemente, die die Filterbedingung erfüllen.
- .get(i)
- DOM-Node des Elements mit Index i; für i≥0 entsprechend
$erg[i]
. - Für i<0 zählt der Index vom Ende aus.
- Wenn i weggelassen wurde, wird ein Array mit DOM Nodes zurückgegeben; auch ohne oder mit nur einem Node.
- .is(x)
- Ist eines der Elemente des Ergebnisses in
x
enthalten? - .map()
- Anwendung einer Funktion auf jedes Element im $erg.
- .slice()
- Wie JS
slice()
für Arrays.
Außerdem gibt es .prevAll().
- Nicht mehr unterstützt wird
$erg.size()
– es hatte das gleiche Ergebnis wie$erg.length
und verursacht mehr Aufwand.
Element-Eigenschaften
- .attr()
-
- Frage eine Eigenschaft eines HTML-Elements ab
s = $meins.attr("eigenschaft");
- Weise diesem Element eine Eigenschaft (hier:
none
) zu$meins.attr("eigenschaft", "none");
– es kann auch ein Objekt mit gleich mehreren Zuweisungen angegeben werden. - Weise mehreren Elementen gleichzeitig diese Eigenschaft zu
jQuery("A.external").attr("target", "_blank");
- Element-Eigenschaft löschen durch Zuweisung von
null
$meins.attr("eigenschaft", null);
- Frage eine Eigenschaft eines HTML-Elements ab
- .css()
-
- Weise eine einzelne
style
-Eigenschaft zu, oder ein Paket mit mehreren einzelnen Eigenschaften.jQuery(".mw-userlink").css("font-weight", "bold");
Wäre gleichbedeutend mit.attr("style", "font-weight:bold")
– aber alle anderen vorhandenen Eigenschaften desstyle
werden belassen und lediglich das CSS-Attributfont-weight
wird zugewiesen.jQuery(".mw-userlink").css( { "font-size": "120%", "font-weight": "bold" } );
- Weise eine einzelne
- .hasClass(c)
-
- Gehört dieses Element zur Klasse c?
- .is(selector)
-
- Erfüllt mindestens ein Element die Selektionsbedingung?
- .prop()
-
- Frage den Momentanzustand von Steuerelementen ab oder setze ihn; auch für bestimmte binäre Eigenschaften (boolean) von Elementen.
- .html()
-
- Setze den neuen Text für ein bereits bekanntes und definiertes Element; HTML-Syntax wird interpretiert.
- .text()
-
- Setze den neuen Text für ein bereits bekanntes und definiertes Element; HTML-Syntax wird escaped.
$erg.text("Neuer Text.");
- Setze den neuen Text für mehrere Elemente gleichzeitig, sofern vorhanden
jQuery(".mw-rollback-link").text("Kommentarlos weghauen!");
- Frage den Text für ein Element ab
s = $meins.text();
- Setze den neuen Text für ein bereits bekanntes und definiertes Element; HTML-Syntax wird escaped.
- .val()
-
- Frage den Inhalt von Steuerelementen für Text oder Auswahl ab oder setze ihn.
Neues Element erschaffen
Beispiel:
$abschnitt = jQuery("<div />");
$strong = jQuery("<strong />");
$strong.text("Text in Fettschrift.");
$abschnitt.append($strong);
Zwei neue (leere) HTML-Elemente werden geschaffen: $abschnitt
und $strong
– der Textinhalt von $strong
wird gesetzt, anschließend $strong
in den $abschnitt
eingefügt.
Auch eine längere als HTML-Quelltext eines umschließenden HTML-Elements formatierte Zeichenkette ließe sich so in ein jQuery-Objekt umwandeln.
- .clone()
- Vollständige Kopie (deep copy) von einem oder einem Satz von Elementen erzeugen.
- .pushStack()
- Komplexe Operation
Seite verändern
Das neu geschaffene Element-Objekt wird in die vorhandene Seitenstruktur eingepasst; auch ein ganzer Satz von Objekten an mehreren Stellen.
Element einfügen
Es gibt mehrere Möglichkeiten, neu geschaffene oder sonst frei verfügbare Elemente an geeigneter Stelle in das DOM einzufügen:
Elemente löschen
- .hide()
$erg.hide()
macht das Element nur unsichtbar; es kann dann mit$erg.show()
wieder sichtbar gemacht werden.- Es wird auf den style
display
zurückgegriffen und zwischennone
oder Entfernung der CSS-Property umgeschaltet. - .detach()
$erg.detach()
koppelt wie$erg.remove()
die Elemente vom DOM ab, jedoch bleiben die Elemente von$erg
vollständig erhalten und können an anderer Stelle wieder eingefügt werden.- .empty()
$erg.empty()
löscht alle in den$erg
-Elementen enthaltenen Inhalte (auch Texte), lässt aber die geleerten$erg
-Elemente zurück.- .remove()
$erg.remove()
trennt alle Elemente von$erg
vom DOM, löscht ihre Inhalte und koppelt Events ab. Das betrifft neben$erg
selbst auch die enthaltenen Kind-Objekte.
Ereignisse (Events)
Durch die Anwender selbst definierte Ereignisse können verwendet werden:
- .bind()
- Handler-Funktionen an eines oder mehrere Elemente binden.
- .trigger()
- Handler-Funktionen für diese/s Element/e auslösen.
Anwendungsbeispiel siehe „Abhängigkeit mehrerer Skripte“.
- .unbind()
- .bind() aufheben.
Die Methode .live() war veraltet und wurde im Dezember 2014 mit jQuery 1.9 entfernt; jetzt ist .on() zu nutzen. Fortgeschrittene können mit .queue(), .dequeue() und .stop() arbeiten.
Außerdem gibt es vorbereitete Funktionen für die üblichen Ereignisse auf einem Dokument, Fenster oder Formular, beispielsweise:
Typen-Philosophie
Jede JavaScript-Funktion ist immer auch ein Objekt; allerdings liefert typeof
bei ihnen function
und nicht object
. Zum Konzept von jQuery gehört, dass es zunächst als eine Funktion deklariert ist. Dieses ergibt ein globales Funktionsobjekt, das erstmal wie etwa jQuery(document)
aufgerufen werden kann.
Gleichzeitig werden Komponenten dieses globalen Funktionsobjekts definiert, die ihrerseits wieder Funktionen sind; jQuery.cookie()
wäre ein Beispiel hierfür.
Das Suchergebnis, etwa
var $erg = jQuery(document).find(".cl");
ist eine Instanz (eine Art abgeleitetes Objekt) vom Typ jQuery und erbt von der globalen Definition alle passenden Funktionen. Damit ist $erg.attr()
möglich. Hinzu kommt, dass das Suchergebnis auch ein Array
ist und mögliche DOM-Elemente $erg[i]
zugreifbar sind.
Das globale Funktionsobjekt jQuery
ist gleichgesetzt mit $
und sollte im Browser-Kontext auch an window
angebunden sein, so dass es selbst bei mehrfachen Threads nur ein einziges geteiltes globales Funktionsobjekt geben müsste.
jQuery für JavaScript
Ein Teil der unter dem Dach von jQuery vorhandenen Funktionen hat nicht direkt etwas mit HTML zu tun, sondern hilft bei allgemeinen Programmieraufgaben.
Einige häufig benötigte Funktionen sind hier dargestellt.
Allgemeines
- jQuery.noop()
- Mache nichts; entspräche
void()
- jQuery.error(msg)
throw new Error(msg);
- Kann bewirken, dass msg in der Fehlerkonsole dargestellt wird, und bricht dann die Bearbeitung dieses Skripts ab.
Typ-Abfragen
Überwiegend Kernfunktionen[1] (ab ovo)
- jQuery.isArray(x)
- Ist die Variable x ein JavaScript-Array?
jQuery.isDomElement(x)[2]- Check whether x is a direct link to an element.
jQuery.isEmpty(x)[2]- Überprüfe, ob eine Variable „leer“ ist.
- jQuery.isEmptyObject(x)
- Ist x ein Objekt und ohne Inhalt?
- jQuery.isFunction(x)
- Ist x eine Funktion?
- jQuery.isNaN(n)
- Erweiterung der Standard-JS-Funktion
isNaN(n)
(is Not-a-Number?) - jQuery.isNumeric(s)
- Ist der String s eine Zahlendarstellung?
- jQuery.isPlainObject(x)
- Ist x ein Objekt, das nicht von anderen abgeleitet ist?
- jQuery.isWindow(x)
- Ist x ein
window
Objekt (eines anderen Browser-Fensters)? - jQuery.isXMLDoc()
- jQuery.type(x)
- JS-Standard-Typ des Ausdrucks x zurückgeben.
Boolean Number String Function Array Date RegExp
oderObject
sind die möglichen Typen. Der zurückgegebene Wert ist ein String in Kleinbuchstaben; im Zweifelsfall immerobject
.
Array
Überwiegend Kernfunktionen[1] (ab ovo)
jQuery.compareArray()[2]- jQuery.inArray(e, a, i)
- Ist Element e im Array a enthalten? Und falls ja: an welcher Stelle (
0
…), falls nicht:-1
(Optional: ab Index i). - jQuery.isArray(x)
- Ist die Variable x ein JavaScript-Array?
- jQuery.grep(elems, callback, inv)
- jQuery.makeArray()
- jQuery.map()
- jQuery.merge(first, second)
Objekt
jQuery.compareObject()[2]- Compares two objects for it’s properties and values (recursive).
- .each(f)
- Führe für jedes Element des Objekts die Funktion f aus.
- f erhält zwei Argumente
f(i,e)
– optional können diese ausgewertet werden; Index und das Element. - jQuery.extend()[1]
- Zwei oder mehr Objekte in einem neuen verschmelzen.
- jQuery.isPlainObject(x)[1]
- Ist x ein Objekt, das nicht von anderen abgeleitet ist?
- jQuery.param(obj)
- Komponenten des Objekts obj in URL-String umsetzen.
jQuery.param( { a: x, b: "Wert" } )
- liefert
"a=" + x + "&b=Wert"
.
- Insbesondere dazu geeignet, im Parameter-Objekt Default-Werte vorzubelegen und im Verlauf der Prozedur ggf. zu überschreiben und zu ergänzen, zum Schluss in einer URL auszuwerten.
- Inhalte werden URL-kodiert. Sind die Werte Basistypen wie Zeichenketten oder Zahlen, ist das Ergebnis naheliegend. Das Objekt wird jedoch „serialisiert“, so dass Komponenten, die Arrays oder selbst Objekte sind, in einer speziellen Form dargestellt werden.
- .serialize()
- Parameter von Formular-Elementen in URL-String umsetzen.
- jQuery.type(x)[1]
- JS-Standard-Typ von x zurückgeben (String).
Boolean Number String Function Array Date RegExp
oderObject
- jQuery.parseJSON(obj)[1]
- Objekt aus JSON generieren.
- Bei neueren Browsern gibt es eingebaute Standardfunktionen:
JSON.parse()
- als Gegenstück
JSON.stringify()
- Siehe dazu auch jquery.json als frühere Lösung.
String
- jQuery.trim(s)[1]
- Whitespace laut RegExp oder aber Geschützte Leerzeichen vor und nach String s entfernen.
jQuery.trimLeft()[2]- Trims whitespace from the left side of the string.
jQuery.trimRight()[2]- Trims whitespace from the right side of the string.
jQuery.ucFirst()[2]- Returns the string with the first character capitalized.
Weitere Datentypen
Überwiegend Kernfunktionen[1] (ab ovo)
jQuery.escapeRE()[2]- Returns a string for literal use in a regular expressions by escaping characters that have a special meaning in a regexp.
- jQuery.now()[1]
- Momentane Uhrzeit als Anzahl der Millisekunden seit dem 1. Januar 1970 00:00:00.
- jQuery.parseXML(data)[1]
Ajax
- jQuery.ajax()
- Komplexe Methodik für synchrone und asynchrone Abfragen
- .ajaxComplete()
- .ajaxError()
- .ajaxSuccess()
- jQuery.get()[3]
- Einfache Abfrage mittels HTTP-GET – Spezialisierung von jQuery.ajax()
- jQuery.getJSON()
- Beste Methode für API-Abfragen; Spezialisierung von jQuery.get()
- jQuery.getScript()
- Code von URL abrufen (ohne Cache) und sofort ausführen.
- Nicht ratsam. Sicherheitsrisiken; Geschwindigkeit, Nachvollziehbarkeit
- jQuery.post()
- HTTP-POST-Methode, etwa für Edits mit der API – Spezialisierung von jQuery.ajax()
Spezielle Methodik
- jQuery.param()
- String-Format eines Objekts; etwa für eine URL
ResourceLoader-Module
jquery.client
Analyse des momentan benutzen Browsers und seiner Fähigkeiten.
- Kein Standardmodul, gesondert laden
Etabliert ein Objekt jQuery.client
, mit dem sich die übermittelte Browserkennung nach Browser-Version und Betriebssystem in standardisierter Form auswerten lassen.
Kein Teil der jQuery-Bibliothek, sondern MediaWiki-Eigenentwicklung.
Zu den Kernfunktionen gehört(en) außerdem:
jQuery.support
mit der Möglichkeit einer Abfrage, ob eine bestimmte Funktionalität vom aktuellen Browser unterstützt wird (ohne dass der Anwender sich über den Browser selbst Gedanken machen muss). Inzwischen aber nur noch für interne Zwecke genutzt; nicht mehr zur Anwendung empfohlen.- Früher das Objekt
jQuery.browser
mit Informationen über die Browser-Version. Seit 2009 war es „deprecated“; mit jQuery 1.9 im Herbst 2014 ist es nicht mehr vorhanden. Durch.name
lässt sich dies weitgehend ersetzen.
- jQuery.client.profile(signature)
- signature – Spezifizierte Browserkennung (optional); sonst lokale Auswertung
- Liefert Objekt, wie unten
- jQuery.client.test(map, profile, exactMatchOnly)
- Test gegen eine support map
Komponente | Typ | Beispiel | Werte |
---|---|---|---|
.name |
string | 'firefox' | 'camino', 'chrome', 'firefox', 'iceweasel', 'netscape', 'konqueror', 'lynx', 'msie', 'opera', 'safari', 'ipod', 'iphone', 'blackberry', 'ps3', 'rekonq', 'android' |
.version |
string | '16.0' | |
.versionBase |
string | '16' | |
.versionNumber |
number | 16 | |
.layout |
string | 'gecko' | 'gecko', 'konqueror', 'msie', 'trident', 'edge', 'opera', 'webkit' |
.layoutVersion |
number | 20100101 | |
.platform |
string | 'linux' | 'win', 'mac', 'linux', 'sunos', 'solaris', 'iphone' |
jquery.color
Kein Standardmodul, gesondert laden
- jQuery.getColor()
jquery.colorUtil
Kein Standardmodul, gesondert laden
- jQuery.colors
- einige Farbnamen (Objekt)
- jQuery.getColorBrightness()
- jQuery.getRGB()
- jQuery.hslToRgb()
- jQuery.rgbToHsl()
jquery.cookie
Arbeiten mit HTTP-Cookies.
- Standardmäßig geladen, jedoch nicht zu Beginn; Modul:
jquery.cookie
– in den letzten Jahren in unterschiedlichen Programmierungen im Internet kursierend, aber immer mit gleicher Funktion.
- jQuery.cookie(name)
- Wert des Cookies name lesen.
- jQuery.cookie(name, wert, eigenschaften)
- Einem existierenden oder neuen Cookie name den wert zuweisen.
- eigenschaften – Objekt (optional) mit Angaben zur Lebensdauer usw.; Komponenten optional
expires
– in Tagen (Zahl) oder Ablaufdatum (Date
)path
– Einschränkung auf bestimmte Seiten; "/
" für die gesamte Domain.secure
–true
wenn Übertragung des Cookies nur über HTTPS (etc.) erlaubt.domain
– Domain für den Cookie; aus Sicherheitsgründen könnte allerdings der Browser eine Zuweisung an eine andere Domain als die aktuelle verweigern.
- eigenschaften – Objekt (optional) mit Angaben zur Lebensdauer usw.; Komponenten optional
- jQuery.cookie(name,
null
) - Cookie name löschen.
- Veraltet; zukünftig möglicherweise nicht mehr unterstützt. Umstellung auf
$.removeCookie()
empfohlen. - jQuery.removeCookie(name)
- Cookie name löschen.
jquery.json
Ehemalige Unterstützung für JSON-Strukturen auf älteren Browsern (MediaWiki-Eigenentwicklung).
- jQuery.toJSON()
- Stellte die Funktionalität bereit, wenn
JSON
nicht verfügbar war. - Nachfolger:
JSON.stringify()
- Dabei handelt es sich um eine seit JavaScript 1.7 (ECMAScript 5.1) standardisierte Funktion, die mit IE8, FF3.5, Opera10.5 und Safari4.0 verfügbar wurde.
- Mit MW 1.25 (Anfang Oktober 2014) ist dieses Modul nicht mehr vorhanden,[4] nachdem seit Mitte September 2014 der Support für IE7 als letztem Vertreter eingestellt wurde.
jquery.jStorage
- Seit August 2016 ist das Modul deprecated, stattdessen sollte mediawiki.storage eingesetzt werden. Im Dezember 2021 wurde es aus der Bereitstellung entfernt.
Unterstützung für jStorage – strukturierte Datenverwaltung in Web Storage, eine einfache Datenbank im Browser mit key/value-Zuordnungen.
- jQuery.jStorage.storageAvailable()
- jQuery.jStorage.getItem()
- wie DOM
- jQuery.jStorage.removeItem()
- wie DOM
- jQuery.jStorage.setItem()
- wie DOM
jquery.localize
Simple placeholder-based localization
- Call on a selection of HTML which contains
<html:msg key="message-key" />
elements or elements withtitle-msg="message-key"
oralt-msg="message-key"
attributes.<html:msg />
elements will be replaced with localized text, elements with title-msg and alt-msg attributes will receive localized title and alt attributes.
jquery.makeCollapsible
Element ein- und ausklappbar machen.
Jedes gefundene jQuery-Objekt (insbesondere vom Block-Typ div, ol, p, table, ul
) kann mit dieser Eigenschaft ausgestattet werden.
- $element.makeCollapsible(options)
- $element ein- und ausklappbar machen.
- options – Objekt (optional)
Optionale Komponenten können belegt werden:- options.
collapseText
– Text, der zum Einklappen angezeigt wird.- Vorgabe: ein Attribut
data-collapsetext
von $element oder sonst MediaWiki:collapsible-collapse.
- Vorgabe: ein Attribut
- options.
expandText
– Text, der zum Ausklappen angezeigt wird.- Vorgabe: ein Attribut
data-expandtext
von $element oder sonst MediaWiki:collapsible-expand.
- Vorgabe: ein Attribut
- options.
collapsed
–true
, wenn (zu Beginn) eingeklappt dargestellt werden soll.- Vorgabe: Nur Elemente mit der Klasse
mw-collapsible
werden zu Beginn eingeklappt.
- Vorgabe: Nur Elemente mit der Klasse
- options.
$customTogglers
– Liste von jQuery-Elementen, die als toggler für dieses Element dienen können.- Vorgabe: Wenn das Element eine
id
hat wiemw-customcollapsible-
XXX, werden Elemente mit derclass
vonmw-customtoggle-
XXX zum toggler dafür.
- Vorgabe: Wenn das Element eine
- options.
plainMode
–true
, wenn der plain mode benutzt werden soll, um das Element einklappbar zu machen. Das bedeutet, die ganze Tabelle und Liste einzuklappen statt alles außer der ersten Zeile, und jedes Listenelement einzeln einklappbar. Andere Elemente sollen nicht indiv.mw-collapsible-content
eingeschlossen werden. Kann nur mit einem eigenen toggler benutzt werden.
- options.
- options – Objekt (optional)
- events
-
- beforeExpand.mw-collapsible
- beforeCollapse.mw-collapsible
- afterExpand.mw-collapsible
- afterCollapse.mw-collapsible
jquery.messageBox
Nachrichtenkasten im Kopf der Seite anzeigen; MediaWiki-Eigenentwicklung.
- removed in MediaWiki 1.20 – zu ersetzen durch mw.util.jsMessage() – im Unterschied zu jener sind mehrere Nachrichten gleichzeitig möglich. Dies wird inzwischen durch
mw.notification
ermöglicht. Dieses ist dann aber nur für kleine und unbedeutende Benachrichtigungen konzipiert, die lediglich einige Sekunden sichtbar bleiben. Für wichtige Informationen ist keine Bibliotheksfunktion verfügbar. - Nachfolger für wikibits jsMsg()
- Dokumentation zum Nachvollziehen früherer Programmierung.
- messageBoxNew(options)
- messageBox(options)
options
ist ein Objekt, das den Nachrichtentext und die Optionen aufnimmt:.message
– Nachrichtentext- Aus Sicherheitsgründen sollten die Inhalte zur Vermeidung von Cross-Site-Scripting immer escaped werden.
.id
– individueller Selektor.parent
– (optional) Umgebungscontainer; Standard:"body"
.insert
– (optional) Standard:"prepend"
– sonst"append"
.group
– (optional) Standard:"default"
.replace
– (optional) Standard:false
– mittrue
werden alle vorherigen Nachrichtenboxen dieser.group
gelöscht.target
– (optional) Bezugselement für.insert
–"js-messagebox"
jquery.mwExtension
- Seit Ende Juni 2015 sind alle diese Funktionen und die Module deprecated.
Allgemeine Hilfsfunktionen; MediaWiki-Eigen-/Weiterentwicklung aus den Kindertagen der Modulorganisation und Bibliotheksfunktionen. Damals der jquery-Funktionsbibliothek gleichrangig hinzugefügt.
- War bis Ende Juni 2015 standardmäßig geladen gewesen, jedoch nicht zu Beginn; Modul:
jquery.mwExtension
(seit MW 1.19; unter MW 1.17 und 1.18jquery.mwPrototypes
)
- jquery.compareArray()
- Compares two arrays and returns a boolean for whether they are in fact the same.
- jquery.compareObject()
- Compares two objects for it’s properties and values (recursive).
- jquery.escapeRE()
- Returns a string for literal use in a regular expressions by escaping characters that have a special meaning in a regexp.
- Jetzt:
mw.RegExp.escape()
- jquery.isDomElement()
- Check whether a passed a variable is a direct link to an element.
- jquery.isEmpty(x)
- Überprüfe, ob eine Variable x „leer“ ist.
- Unterstützt boolean, String, Array und Object.
- Neben den Basistypen (etwa false, null, undefined) wird auch als „leer“ erkannt ein Array oder Objekt ohne eigene Elemente sowie der String
"0
", wie er etwa beiborder="0"
vorkommt. - Ein String, der nur Whitespace enthält (etwa
" "
) wird nicht als „leer“ angesehen. v === "" || v === 0 || v === "0" || v === null || v === false || v === undefined
- jquery.trimLeft (s )
- Trims whitespace from the left side of the string.
- Ersatz:
s.replace( /^\s+/, "" )
- jquery.trimRight (s )
- Trims whitespace from the right side of the string.
- Ersatz:
s.replace( /\s+$/, "" )
- jquery.ucFirst (s )
- Returns the string with the first character capitalized.
- Ersatz:
s.charAt( 0 ).toUpperCase() + s.substr( 1 )
resources/src/jquery/jquery.mwExtension.js
jquery.spinner
Aktivitätsanzeige, etwa für Ajax (Throbber)
- Kein Standardmodul, gesondert laden
- Nachfolger für wikibits
- jQuery.createSpinner()
- jQuery.injectSpinner()
- jQuery.removeSpinner()
resources/src/jquery/jquery.spinner.js
jquery.textSelection
Arbeiten mit markiertem Text und der Cursor-Position in Eingabefeldern für Text; insbesondere auch für den Wikitext.
- Standardmäßig geladen, jedoch nicht zu Beginn; Modul:
jquery.textSelection
– MediaWiki-Eigen-/Weiterentwicklung.
- jQuery.encapsulateSelection()
- Selektierten Text mit Text umschließen oder ersetzen.
- jQuery.getCaretPosition()
- jQuery.getSelection()
- Nachfolger für wikibits
- jQuery.scrollToCaretPosition(options)
- jQuery.setContents()
- jQuery.setSelection(options)
resources/src/jquery/jquery.textSelection.js
jquery.qunit
Testsystem: JavaScript Unit Testing Framework – en:QUnit / qunitjs.com
- Kein Standardmodul, gesondert laden
resources/lib/jquery/jquery.qunit.js
Herkunft und Verfügbarkeit
Die Kernbibliothek hat seit 1. März 2012 (MW 1.19) die Version 1.7.1 (zuvor mit MW 1.18 war es 1.6.4).[1] Mit MW 1.20 wird bei Bedarf laufend aktualisiert (auch komponentenweise; 1.8 kann vorausgesetzt werden). Mediawiki verteilt die jQuery-Updates binnen weniger Wochen oder Monate; zu brandaktuellen jQuery-Entwicklungen wäre im Einzelfall der letzte Stand zu prüfen.
Neben der Kernbibliothek sind in der allgemeinen jQuery-Welt Zusatz-Elemente entstanden, dort Plugins genannt. Speziell für Wiki-Projekte wurden ebenfalls Erweiterungen geschrieben; diese sind natürlich nicht in der Dokumentation api.jquery.com zu finden. Mit dem ResourceLoader von MediaWiki werden all diese in Form von „Modulen“ verwaltet.
- Viele Funktionen stehen auf Wikiprojekten automatisch zur Verfügung.
- Eine große Zahl ist von Anfang an benutzbar; sie werden vorstehend auch als ab ovo bezeichnet.
- Andere werden zwar standardmäßig geladen, sind jedoch möglicherweise noch nicht mit Beginn der Skriptverarbeitung verfügbar. Aktivitäten, die solche Module voraussetzen, sollten mit
mw.loader.using()
sicherstellen, dass diese bereitgestellt sind.
- Weitere müssen gesondert angefordert werden. Auch dies kann mittels
mw.loader.using()
erreicht werden; deshalb ist es letztlich egal, ob in der momentanen Konfiguration der MediaWiki-Software ein Modul automatisch oder per Extra-Anweisung geladen wird – die Verfügbarkeit ist so oder so vor der Benutzung zu gewährleisten.
Standard-Module
Mit MW 1.18 (Anfang 2012) werden auf normalen Seiten immer geladen, sind jedoch möglicherweise noch nicht mit Beginn der Skriptverarbeitung verfügbar:
jquery.autoEllipsis
jquery.byteLength
jquery.byteLimit
jquery.checkboxShiftClick
jquery.cookie
jquery.highlightText
jquery.makeCollapsible
jquery.messageBox
(zuvor jquery.mwPrototypes)jquery.mwExtension
jquery.tabIndex
jquery.textSelection
Hinzu kommen noch verschiedene
jquery.ui
.*** – sofern der Wikitext bearbeitet wird
und bis 2013 standardmäßig unter Vector
jquery.collapsibleTabs
Automatisch werden zugeladen, wenn in der Seite entsprechende Elemente enthalten sind:
jquery.tablesorter
Bei Bedarf wird weiterhin automatisch bereitgestellt:
jquery.placeholder
Zusätzliche Module
jquery.client
jquery.color
jquery.colorUtil
– deprecatedjquery.effects.***
jquery.expandableField
jquery.form
jquery.hoverIntent
jquery.localize
jquery.localize
jquery.spinner
– deprecated; OO.ui.PopupWidget()jquery.tipsy
– deprecatedjquery.ui.***
jquery.wikiEditor.***
Eher intern
Teils von vornherein geladen, teils später oder erst auf Anforderung:
jquery.appear
jquery.async
jquery.delayedBind
jquery.qunit
jquery.suggestions
Siehe GIT zu weiteren Modulen; möglicherweise noch nicht Bestandteil der momentanen Version der Wiki-Software.
Weitere Informationen
(alle englisch, sofern nicht gesondert angegeben)
- Wikiup:Technik/Skin/JS#jQuery.ready (deutsch)
- Wikiup:Technik/Skin/GUI#jQuery (deutsch)
- doc.wikimedia.org – Automatisch generierte Dokumentation zu MW-Modulen
- Quellcodes aller Module
- /lib – Standardbibliothek
- jquery.chosen
- jquery.effects
- jquery.ui – deprecated
- /src – Ergänzungen durch MediaWiki
- /lib – Standardbibliothek
Externe Links
- api.jquery.com – englischsprachige Dokumentation
Anmerkungen
- ↑ a b c d e f g h i j k l m n Kernbibliothek: resources/lib/jquery/jquery.js – vor allen anderen Skripten geladen
- ↑ a b c d e f g h Deprecated, siehe jQuery.mwExtension
- ↑
Die Funktion
get()
ist mehrdeutig:- $erg
.get()
– im Suchergebnis jQuery.get()
– Ajax
- $erg
- ↑ jquery.json module has been deprecated and will be removed; please use json (gerrit:145679)