jQuery im Wiki-Projekt
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.
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.
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.
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
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) |
Die Suche entspricht derjenigen über CSS-Selektoren.
classname
)$erg = $(document).find(".classname");
meins
) – ein valides HTML-Dokument sollte maximal ein solches Element enthalten.$erg = $(document).find("#meins");
table
)$erg = $(document).find("table");
div
) einer Klasse$erg = $(document).find("div.classname");
$erg = $(document).find("div.classname A");
$erg = $(document).find("h1,h2,h3,h4,h5,h6");
$erg
) enthalten sind$erg2 = $erg.find("div.classname");
Das Ergebnis von .find() etc. ist ein neues Objekt vom jQuery-Typ, das sich auch als Array nutzen lässt.
$
zu beginnen, um ihre besondere Eigenart zu verdeutlichen.null
– auch wenn nichts gefunden wurde.$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)
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 Index i
.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:
f
aus.f
erhält zwei Argumente f(i,e)
– optional können diese ausgewertet werden; Index und das Element.this
ist das gefundene DOM-Element; das müsste identisch mit e
sein. Sie können mit $(e)
oder $(this)
in ein jQuery-Objekt umgewandelt werden.f
den Wert false
zurück, wird die Iteration beendet.$erg[i]
.x
enthalten?slice()
für Arrays.Außerdem gibt es .prevAll().
$erg.size()
– es hatte das gleiche Ergebnis wie $erg.length
und verursacht mehr Aufwand.s = $meins.attr("eigenschaft");
none
) zu$meins.attr("eigenschaft", "none");
– es kann auch ein Objekt mit gleich mehreren Zuweisungen angegeben werden.jQuery("A.external").attr("target", "_blank");
null
$meins.attr("eigenschaft", null);
style
-Eigenschaft zu, oder ein Paket mit mehreren einzelnen Eigenschaften.jQuery(".mw-userlink").css("font-weight", "bold");
.attr("style", "font-weight:bold")
– aber alle anderen vorhandenen Eigenschaften des style
werden belassen und lediglich das CSS-Attribut font-weight
wird zugewiesen.jQuery(".mw-userlink").css( { "font-size": "120%", "font-weight": "bold" } );
$erg.text("Neuer Text.");
jQuery(".mw-rollback-link").text("Kommentarlos weghauen!");
s = $meins.text();
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.
Das neu geschaffene Element-Objekt wird in die vorhandene Seitenstruktur eingepasst; auch ein ganzer Satz von Objekten an mehreren Stellen.
Es gibt mehrere Möglichkeiten, neu geschaffene oder sonst frei verfügbare Elemente an geeigneter Stelle in das DOM einzufügen:
$erg.hide()
macht das Element nur unsichtbar; es kann dann mit $erg.show()
wieder sichtbar gemacht werden.display
zurückgegriffen und zwischen none
oder Entfernung der CSS-Property umgeschaltet.$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.$erg.empty()
löscht alle in den $erg
-Elementen enthaltenen Inhalte (auch Texte), lässt aber die geleerten $erg
-Elemente zurück.$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.Durch die Anwender selbst definierte Ereignisse können verwendet werden:
Anwendungsbeispiel siehe „Abhängigkeit mehrerer Skripte“.
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:
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.
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.
void()
throw new Error(msg);
Überwiegend Kernfunktionen[1] (ab ovo)
isNaN(n)
(is Not-a-Number?)window
Objekt (eines anderen Browser-Fensters)?Boolean Number String Function Array Date RegExp
oder Object
sind die möglichen Typen. Der zurückgegebene Wert ist ein String in Kleinbuchstaben; im Zweifelsfall immer object
.Überwiegend Kernfunktionen[1] (ab ovo)
0
…), falls nicht: -1
(Optional: ab Index i).f(i,e)
– optional können diese ausgewertet werden; Index und das Element.jQuery.param( { a: x, b: "Wert" } )
"a=" + x + "&b=Wert"
.Boolean Number String Function Array Date RegExp
oder Object
JSON.parse()
JSON.stringify()
Überwiegend Kernfunktionen[1] (ab ovo)
Analyse des momentan benutzen Browsers und seiner Fähigkeiten.
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.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.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' |
Kein Standardmodul, gesondert laden
Kein Standardmodul, gesondert laden
Bis 2023 angebotene Schnittstelle zum Arbeiten mit HTTP-Cookies.
mediawiki.cookie
.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.null
)$.removeCookie()
empfohlen.Ehemalige Unterstützung für JSON-Strukturen auf älteren Browsern (MediaWiki-Eigenentwicklung).
JSON
nicht verfügbar war.JSON.stringify()
Unterstützung für jStorage – strukturierte Datenverwaltung in Web Storage, eine einfache Datenbank im Browser mit key/value-Zuordnungen.
Simple placeholder-based localization
<html:msg key="message-key" />
elements or elements with title-msg="message-key"
or alt-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.Element ein- und ausklappbar machen.
Jedes gefundene jQuery-Objekt (insbesondere vom Block-Typ div, ol, p, table, ul
) kann mit dieser Eigenschaft ausgestattet werden.
collapseText
– Text, der zum Einklappen angezeigt wird.
data-collapsetext
von $element oder sonst MediaWiki:collapsible-collapse.expandText
– Text, der zum Ausklappen angezeigt wird.
data-expandtext
von $element oder sonst MediaWiki:collapsible-expand.collapsed
– true
, wenn (zu Beginn) eingeklappt dargestellt werden soll.
mw-collapsible
werden zu Beginn eingeklappt.$customTogglers
– Liste von jQuery-Elementen, die als toggler für dieses Element dienen können.
id
hat wie mw-customcollapsible-
XXX, werden Elemente mit der class
von mw-customtoggle-
XXX zum toggler dafür.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 in div.mw-collapsible-content
eingeschlossen werden. Kann nur mit einem eigenen toggler benutzt werden.Nachrichtenkasten im Kopf der Seite anzeigen; MediaWiki-Eigenentwicklung.
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.options
ist ein Objekt, das den Nachrichtentext und die Optionen aufnimmt:
.message
– Nachrichtentext
.id
– individueller Selektor.parent
– (optional) Umgebungscontainer; Standard: "body"
.insert
– (optional) Standard: "prepend"
– sonst "append"
.group
– (optional) Standard: "default"
.replace
– (optional) Standard: false
– mit true
werden alle vorherigen Nachrichtenboxen dieser .group
gelöscht.target
– (optional) Bezugselement für .insert
– "js-messagebox"
Allgemeine Hilfsfunktionen; MediaWiki-Eigen-/Weiterentwicklung aus den Kindertagen der Modulorganisation und Bibliotheksfunktionen. Damals der jquery-Funktionsbibliothek gleichrangig hinzugefügt.
jquery.mwExtension
(seit MW 1.19; unter MW 1.17 und 1.18 jquery.mwPrototypes
)mw.util.escapeRegExp()
aus mw.RegExp.escape()
"0
", wie er etwa bei border="0"
vorkommt." "
) wird nicht als „leer“ angesehen.v === "" || v === 0 || v === "0" || v === null || v === false || v === undefined
s.replace( /^\s+/, "" )
s.replace( /\s+$/, "" )
s.charAt( 0 ).toUpperCase() + s.substr( 1 )
resources/src/jquery/jquery.mwExtension.js
Aktivitätsanzeige, etwa für Ajax (Throbber)
resources/src/jquery/jquery.spinner.js
Arbeiten mit markiertem Text und der Cursor-Position in Eingabefeldern für Text; insbesondere auch für den Wikitext.
jquery.textSelection
– MediaWiki-Eigen-/Weiterentwicklung.resources/src/jquery/jquery.textSelection.js
Testsystem: JavaScript Unit Testing Framework – en:QUnit / qunitjs.com
resources/lib/jquery/jquery.qunit.js
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.
mw.loader.using()
sicherstellen, dass diese bereitgestellt sind.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.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
jquery.mwExtension
jquery.tabIndex
jquery.textSelection
Hinzu kommen noch verschiedene
jquery.ui
.*** – sofern der Wikitext bearbeitet wirdund 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
jquery.client
jquery.color
jquery.colorUtil
jquery.effects.***
jquery.expandableField
jquery.form
jquery.hoverIntent
jquery.localize
jquery.localize
jquery.spinner
jquery.tipsy
jquery.ui.***
jquery.wikiEditor.***
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.
(alle englisch, sofern nicht gesondert angegeben)
Externe Links
get()
ist mehrdeutig:
.get()
– im SuchergebnisjQuery.get()
– Ajax