SideBarMenu

< Rechtestufen | Entwicklungs-HOWTO | Sicherheitsaspekte >

In Stud.IP wird mit der Zeit mehr und mehr Javascript für erweiterte und vereinfachte Bedienung oder auch einfach für besonders schöne Effekte benutzt.

Ab Oktober 2010 verwendet Stud.IP das meistbenutzte Javascript-Framework jQuery und sammelt eine eigene Bibliothek und eigene Funktionen in der Datei public/assets/javascript/application.js.

Code-Konventionen für JavaScript

Als Programmierer hat man sich im Grunde nur daran zu richten, dass der globale Namespace einigermaßen sauber gehalten wird (also globale Variablen müssen vermieden werden) und dass die Code-Konventionen eingehalten werden, die im Lifters005 zusammen gefasst sind. Die Code-Konventionen sind von Douglas Crockfords "Code Conventions for the JavaScript Programming Language" komplett übernommen.

Was den Namespace angeht, so sollen alle speziellen Stud.IP Funktionen unterhalb des STUDIP-Objektes angehängt werden. Programmiere ich also einige Funktionen für die News, fange ich an mit:

STUDIP.News = {
    openclose: function (id) {},
    open: function (id) {},
    close: function (id) {}
}

und fülle diese Methoden dann mit Leben. An diese Konvention sollten sich auch Plugin-Programmierer halten, wobei die noch speziell darauf zu achten haben, dass ihre Methodennamen auch tatsächlich eindeutig sind. Implementieren zwei unterschiedliche Plugins eine Methode STUDIP.go , so wird mindestens eines der beiden Plugins weinen. Sinnvoll ist es da, den eindeutigen Klassennamen des Plugins zwischen zu schieben, entweder über STUDIP.pluginclassname.go oder eventuell auch einfach nur pluginclassname.go.

Eigene Stud.IP Bibliothek

Für alle Javascript-Programmierer wird von Interesse sein, dass einige Funktionen schon in Stud.IP implementiert sind, die auch an anderer Stelle nützlich sein könnten. Der Vorteil liegt auf der Hand: der Code bleibt klein und kann später besser um Funktionalitäten erweitert werden.

Vorhandene Methoden

MethodeAnwendbar aufVerhaltenZu beachten
$.showAjaxNotification(position=left);Alle ElementeDem Element wird ein AJAX-Indikator vorangestellt.Der Indikator kann mittels des Parameters position="right" auch hinter dem Element positioniert werden. Der Indikator wird absolut positioniert, was zu Problemen bei Veränderungen von Elementen in der Umgebung des eigentlichen Elements führen kann.
$.hideAjaxNotification();Alle ElementeDer dem Element zugehörende AJAX-Indikator wird entfernt, sofern vorhanden.-

Vorhandene Verhaltsmuster über CSS-Klassen

KlasseAnwendbar aufVerhaltenZu beachten
.add_toolbar<textarea />Dem Element wird eine Menüleiste mit vereinfachten Formatiermöglichkeiten vorangestellt.Auf diese Art und Weise kann nur das Standard-Buttonset von Stud.IP verwendet werden.
.load_via_ajax<a />Eine angegebene URL (entweder metadata.url oder die URL des gegebenen Links) wird via AJAX in ein Element (entweder metadata.target oder das auf das gegebene Elemente folgende Element) geladen.Über metadata.indicator kann via CSS-Regel das Element angegeben werden, welches den AJAX-Indikator erhält. Über metadata können weitere Parameter für den Aufruf der URL angegeben werden.
.load_via_ajax.internal_message<a />Spezialfall für interne Nachrichten.Die Parameter werden an die Gegebenheiten in lib/sms_func.inc.php angepasst.
.resizable<textarea />Das Element kann durch einen Schieber am unteren Rand in der Höhe verändert werden.-

AJAX-Anfragen

AJAX-Anfragen sollten über jQuery mit den Methoden .load .get oder .ajax durchgeführt werden. Die meisten AJAX-Aufrufe haben einen AJAX-Indicator, der dem Nutzer mitteilt, dass gerade etwas geladen wird. Falls dieser Indicator ungebeten sein sollte, kann man die AJAX-Methode einbetten wie folgt:

STUDIP.ajax_indicator = false;
$('#dynamischer_bereich').load(url);
STUDIP.ajax_indicator = true;

URLHelper in Javascript

Das Objekt STUDIP.URLHelper bietet für Javascript ähnliche Funktionalität wie der URLHelper in PHP. Dennoch darf man nicht vergessen, dass beide URLHelper gänzlich unabhängig voneinander sind und nicht miteinander kommunizieren können. Wozu braucht man dann einen URLHelper in Javascript? Zum Beispiel, um:

  • Einen Link zu generieren, wo eine Javascript-Datei sonst nicht wüsste, wie die Adresse des Servers ist. Schreiben Sie also STUDIP.URLHelper.getURL("about.php"), um einen URI-kodierten Pfad zu http://www.studip......de/about.php zu bekommen, oder STUDIP.URLHelper.getURL("about.php"), um das selbe als nicht URI-kodiert zu erhalten.
  • Variablen zu einer beliebigen URL hinzuzufügen, ohne sich Gedanken darüber zu machen, welche Variablen schon in der URL sind und welche nicht. Also wird aus STUDIP.URLHelper.getURL(alte_url, {hallo: "welt"}) ein http:.../about.php?hallo=welt, egal ob alte_url schon einen Wert für hallo angegeben hatte oder auch nicht. Auch muss man sich dann keine Gedanken darüber machen, ob man den Parameter mit "?" oder einem "&" anhängt. Beachten Sie zudem, dass Parameter in der alte_url weniger Priorität haben als Parameter im zweiten Argument.
  • Variablen dauerhaft (also solange die HTML-Seite in Benutzung ist) zu generierten URLs hinzuzufügen. Das geht mit der Methode STUDIP.URLHelper.addLinkParam("hallo", "welt"). Nach diesem Aufruf wird jedes STUDIP.URLHelper.getURL("about.php") zum Beispiel http://..../about.php?hallo=welt zurück geben. Mit dieser Methode werden auch Parameter aus der abgegebenen URL überschrieben, also STUDIP.URLHelper.getURL("about.php?hallo=ich") würde trotzdem Welt als Inhalt des Parameters hallo wider geben. Nicht so jedoch mit STUDIP.URLHelper.getURL("about.php", {hallo: "ich"}), wobei der zweite Parameter wieder einmal Priorität hat.
  • Variablen dauerhaft von generierten URLs abzuziehen, wenn sie denn vorher drin gewesen sein sollten. Dazu gibt man analog zu oben addLinkParam("hallo", "") an und der Parameter hallo wird stets als zwingend leer angesehen und auch aus bestehenden URLs gestrichen, wenn vorher vorhanden.
  • Alle Hyperlinks eines Abschnittes des Dokumentes mit aktuellem Parameter zu versehen. Nach einem oder mehreren addLinkParam-Aufrufen könnte man STUDIP.URLHelper.updateAllLinks("#container"); aufrufen, wodurch alle Links innerhalb des CSS-Selektors "#container" einmal durch die STUDIP.URLHelper.getURL(...) Methode ersetzt werden und dadurch aktuelle Parameter bekommen. Gibt man keinen Selektor an, werden die Links des ganzen Dokuments ersetzt.

Das jQuery-Framework in Stud.IP

Zur Zeit (Stud.IP 2.1) wird jQuery 1.5 und jQuery-UI 1.8.7 verwendet. Von jQuery-UI sind alle Funktionen bis auf die Tabs in Stud.IP geladen. Und die Tabs hauptsächlich deswegen nicht, weil es in Stud.IP andere Möglichkeiten gibt, die Tabs zu implementieren. Auf dieses Feature sollte man also aus Designgründen auch in Plugins verzichten.

Kleine Änderungen am Aussehen von jQuery-UI sind auf einer Parallelseite? dokumentiert.

Weitere verwendete JS-Bibliotheken

Prototype Framework (Link)

Das Prototype Framework wird seit Stud.IP Version 1.11 nicht mehr verwendet und befindet sich nur aus Gründen der Kompatibilität zu vorhandenen Plugins, die noch Prototype verwenden, in Stud.IP. Prototype darf nicht mehr verwendet werden und wird in der nächsten Version aus Stud.IP entfernt.

script.aculo.us UI Framework (Link)

Das script.aculo.us UI Framework wird seit Stud.IP Version 1.11 nicht mehr verwendet und befindet sich nur aus Gründen der Kompatibilität zu vorhandenen Plugins, die noch script.aculo.us verwenden, in Stud.IP. script.aculo.us darf nicht mehr verwendet werden und wird in der nächsten Version aus Stud.IP entfernt.

TableKit (aufbauend auf Prototype) (Link)

TableKit wurde zum clientseitigen Sortieren von Tabellen verwendet. Da es auf Prototype aufbaut, darf TableKit nicht mehr verwendet werden und wird in der nächsten Version aus Stud.IP entfernt.

jQuery (Link)

Derzeit wird die aktuelle jQuery Version 1.5 verwendet.

jQuery-Plugins

Metadata (Link)

Damit können die in HTML-Elementen gespeicherten data-*-Attribute einfach ausgelesen werden. Sobald alle Browser den diesbezüglichen HTML5-Standard implementieren, wird das Metadata-Plugin entfernt (bzw. nur für Progressive Enhancement verwendet).

Placehold (Link)

Das placeholder-Attribut wird nicht in allen Browsern unterstützt. Dieses Plugin ermöglicht dennoch dessen Verwendung. Damit kann man also Texteingabefelder einfach mit einem placeholder-Attribut garnieren und erhält dann das gewünschte Verhalten:

<input type="text" name="email" placeholder="E-Mail-Adresse">

TableSorter (Link)

Dieses Plugin stellt ähnliche Möglichkeiten wie das vormalige TableKit-Plugin (s.o.) zur Verfügung und ermöglicht das flexible client-seitige Sortieren von Tabellen.

jQuery UI (Link)

jQuery UI Multiselect (Link)

Das jQuery-UI-Multiselect-Plugin wandelt "multiple select inputs" in sexier aussehende Äquivalente um. Das Plugin wurde in den folgenden Changesets gepatchet:

jQuery Tools: Validator (Link)

Diese Bibliothek stellt eine barrierefreie dynamische Validierungslogik für Formularfelder bereit. Genaueres ist hier dokumentiert: Wiki

JS-L10n (Link)

Diese Bibliothek wird verwendet, um lokalisierte Strings in JS verwenden zu können. Weiteres ist bereits im Wiki dokumentiert.

Altlasten

  • md5.js - wird nur noch im Chat benutzt.

Javascript in älteren Stud.IP-Versionen

Bis einschließlich Version 1.11 wurde in Stud.IP nicht jQuery verwendet, sondern Prototype und Scriptaculous. Verwenden Sie für AJAX und alle anderen optischen Effekte die von dieser Bibliothek vorgefertigten Funktionen, die hier dokumentiert sind:

http://api.prototypejs.org/

http://wiki.github.com/madrobby/scriptaculous/

Für den Aufbau des Javascript-Namespace und die Code-Konventionen gilt das selbe wie oben schon erwähnt.

Unit-Tests für JavaScript

JavaScripts dürfen und sollten auch mit Unit-Test ausgestattet werden. Wie das geht, steht auf einer eigenen Seite.

Letzte Änderung am 18.09.2013 15:46 Uhr von fl00.