Wikipedia:Technik/Skin/JS/jQuery

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.

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");

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

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);

.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 des style werden belassen und lediglich das CSS-Attribut font-weight wird zugewiesen.
  jQuery(".mw-userlink").css( { "font-size": "120%", "font-weight": "bold" } );

.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();

.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.

Allgemeines

Kernfunktionen (ab ovo)

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 (ab ovo)

jQuery.isArray(x)

Ist die Variable x ein JavaScript-Array?

jQuery.isDomElement(x)

Check whether x is a direct link to an element.

jQuery.isEmpty(x)

Ü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 oder Object sind die möglichen Typen. Der zurückgegebene Wert ist ein String in Kleinbuchstaben; im Zweifelsfall immer object.

Array

Überwiegend Kernfunktionen (ab ovo)

jQuery.compareArray()

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()

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()

Zwei oder mehr Objekte in einem neuen verschmelzen.

jQuery.isPlainObject(x)

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)

JS-Standard-Typ von x zurückgeben (String).

Boolean Number String Function Array Date RegExp oder Object

jQuery.parseJSON(obj)

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)

Whitespace laut RegExp oder aber Geschützte Leerzeichen vor und nach String s entfernen.

jQuery.trimLeft()

Trims whitespace from the left side of the string.

jQuery.trimRight()

Trims whitespace from the right side of the string.

jQuery.ucFirst()

Returns the string with the first character capitalized.

Weitere Datentypen

Überwiegend Kernfunktionen (ab ovo)

jQuery.escapeRE()

Returns a string for literal use in a regular expressions by escaping characters that have a special meaning in a regexp.

jQuery.now()

Momentane Uhrzeit als Anzahl der Millisekunden seit dem 1. Januar 1970 00:00:00.

jQuery.parseXML(data)

Ajax

Kernfunktionen (ab ovo)

jQuery.ajax()

Komplexe Methodik für synchrone und asynchrone Abfragen

.ajaxComplete()

.ajaxError()

.ajaxSuccess()

jQuery.get()

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

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.

• resources/src/jquery/jquery.client.js

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

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

Bis 2023 angebotene Schnittstelle zum Arbeiten mit HTTP-Cookies.

• Seit vielen Jahren abzulösen durch das Modul mediawiki.cookie.
• Anfang 2024 Unterstützung eingestellt.

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.

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, 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 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.

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.

  • options.expandText – Text, der zum Ausklappen angezeigt wird.

    Vorgabe: ein Attribut data-expandtext von $element oder sonst MediaWiki:collapsible-expand.

  • options.collapsed – true, wenn (zu Beginn) eingeklappt dargestellt werden soll.

    Vorgabe: Nur Elemente mit der Klasse mw-collapsible werden zu Beginn eingeklappt.

  • options.$customTogglers – Liste von jQuery-Elementen, die als toggler für dieses Element dienen können.

    Vorgabe: Wenn das Element eine id hat wie mw-customcollapsible-XXX, werden Elemente mit der class von mw-customtoggle-XXX zum toggler dafür.

  • 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 in div.mw-collapsible-content eingeschlossen werden. Kann nur mit einem eigenen toggler benutzt werden.

events

• beforeExpand.mw-collapsible
• beforeCollapse.mw-collapsible
• afterExpand.mw-collapsible
• afterCollapse.mw-collapsible

• resources/src/jquery/jquery.makeCollapsible.js

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 – mit true 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.18 jquery.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.util.escapeRegExp() aus 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 bei border="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

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
• jquery.mwExtension (zuvor jquery.mwPrototypes)
• 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
  • resources/src/jquery.tablesorter/jquery.tablesorter.js

Bei Bedarf wird weiterhin automatisch bereitgestellt:

• jquery.placeholder

Zusätzliche Module

• jquery.client
• jquery.color
• jquery.colorUtil
• jquery.effects.*** – deprecated
• jquery.expandableField
• jquery.form
• jquery.hoverIntent
• jquery.localize
• jquery.localize
• jquery.spinner
• jquery.tipsy – deprecated; OO.ui.PopupWidget()
• jquery.ui.*** – deprecated
• 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.