aus "Stud.IP-Entwicklerdokumentation"

Entwickler: Javascript in Stud.IP

< Rechtestufen | Entwicklungs-HOWTO | Sicherheitsaspekte >

Auf dieser Seite... (ausblenden)

  1. 1. Code-Konventionen für JavaScript
  2. 2. Eigene Stud.IP Bibliothek
    1. 2.1 Vorhandene Methoden
    2. 2.2 Vorhandene Verhaltsmuster über CSS-Klassen
    3. 2.3 AJAX-Anfragen
    4. 2.4 URLHelper in Javascript
  3. 3. Das jQuery-Framework in Stud.IP
  4. 4. Weitere verwendete JS-Bibliotheken
    1. 4.1 Prototype Framework (Link)
    2. 4.2 script.aculo.us UI Framework (Link)
    3. 4.3 TableKit (aufbauend auf Prototype) (Link)
    4. 4.4 jQuery (Link)
    5. 4.5 jQuery-Plugins
    6. 4.6 jQuery UI (Link)
    7. 4.7 jQuery UI Multiselect (Link)
    8. 4.8 jQuery Tools: Validator (Link)
    9. 4.9 JS-L10n (Link)
    10. 4.10 Altlasten
  5. 5. Javascript in älteren Stud.IP-Versionen
  6. 6. Unit-Tests für JavaScript

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.

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

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

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

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

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

2.4  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:

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

4.  Weitere verwendete JS-Bibliotheken

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

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

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

4.4  jQuery (Link)

Derzeit wird die aktuelle jQuery Version 1.5 verwendet.

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

4.6  jQuery UI (Link)

4.7  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:

4.8  jQuery Tools: Validator (Link)

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

4.9  JS-L10n (Link)

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

4.10  Altlasten

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

6.  Unit-Tests für JavaScript

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

URL: https://docs.studip.de/develop/Entwickler/HowToJavascript
Zuletzt geändert am 18.09.2013 15:46 Uhr