====== JavaScript ======

Bei DSAo-Md wird JavaScript eingesetzt, um

  * die Benutzerfreundlichkeit zu steigern,
  * die Belastung des Servers zu verringern.

Bei DSAo-Md wird JavaScript nicht eingesetzt, um

  * Eye-Candy zu bieten (was in einer hohen CPU-Belastung des Clients resultieren würde)


Es sollte klar sein, dass DSAo-Md auch ohne JavaScript uneingeschränkt benutzbar bleiben sollte. Benutzer, die JavaScript deaktiviert haben, sind bei uns ebenso willkommen wie alle anderen, daher wird es primär immer darum gehen, Features ohne JavaScript umzusetzen, und erst darüber hinaus über Verbesserungen durch JavaScript nachzudenken.

===== Dateien einbinden =====

Um JavaScript benutzen zu können, müssen zunächst die Bibliotheken und eine aktionsspezifische JavaScript-Datei eingebunden werden.
Um die Bibliothek Prototype braucht man sich keine Sorgen machen, diese wird automatisch eingebunden, wenn eine JavaScript-Datei eingebunden wird.

Zunächst mal also eine Datei hinzufügen (im Controller), in diesem Fall wurde die Seite /game/desk/show aufgerufen:

<code php>
// Fügt die JavaScript-Datei /htdocs/js/game/desk/show.js hinzu
$this->_addJsFile();

// Fügt die JavaScript-Datei /htdocs/js/game/desk/action.js hinzu
$this->_addJsFile('action');

// Datei: /htdocs/js/game/controller/action.js
$this->_addJsFile('action', 'controller');

// Datei: /htdocs/js/module/controller/action.js
$this->_addJsFile('action', 'controller', 'module');

// Aber auch sowas ist möglich:
// Datei: /htdocs/js/module/controller.js
$this->_addJsFile(false);

// Datei: /htdocs/js/module.js
$this->_addJsFile(false, false);

// oder gar:
// Datei: /htdocs/js/module/controller/directory/action.js
$this->_addJsFile('directory/action.js', 'controller', 'module');
</code>

Für alles weitere sei auf die inline-Dokumentation verwiesen.

Nun wollen wir vielleicht noch Teile der Scriptaculous-Bibliothek einbinden:

<code php>
$this->getView()->addScriptaculousFiles(arrray('controls', 'slider'));
</code>

Dieses bindet die 'controls'- und die 'slider'-Scripts ein. Wird kein Parameter übergeben, so wird die komplette Bibliothek eingebunden.

Eine Liste aller Scripts gibt es in der [[http://github.com/madrobby/scriptaculous/wikis|Dokumentation von Scriptaculous]].

===== JavaScript-Dateien schreiben =====

Nun also zum Coden selbst.

==== Prototype-Syntax ====

Wer sich mit der Prototype-Syntax noch nicht auskennt, sollte schleunigst einen Blick in die [[http://www.prototypejs.org/api|API-Dokumentation]] werfen.

==== Sprachverwaltung ====

Im Controller können Texte für JavaScript wie folgt übergeben werden:

<code php>
$this->getView()->addJsTexts(array
  'message_id_1',
  'message_id_2',
  ));
</code>

In der Java-Script Datei kann dann über die Variablen 'message_id_1' und 'message_id_2' auf die Texte zugegriffen werden. Einfach, oder?

==== Events ====

Über die Namenskonventionen habe ich mich bereits in den [[.:konventionen:programmierung|Programmierstandards]] ausgelassen.

Eventhandler werden als solche durch ein angehängtes 'Handler' gekennzeichnet.

===== Initialisierung =====

Die Initialisierung der Events läuft über zwei Schritte:

<code javascript>
// JS-Events initialisieren, sobald Seite geladen
Event.observe(window, 'load', someInitHandler);
</code>

Das 'some' in 'someInitHandler' sollte natürlich durch einen passenden Namen (Modul-, Controller- oder Aktionname?). Und dann der Handler:

<code php>
/**
 * someInitJsHandler()
 *
 * Initialisiert JS-Events und Variablen
 *
 * @param event Event Prototype-Event
 * @return void
 */
function someInitHandler(event)
{
  // Initialisierungsaufgaben
}
</code>

Das war's soweit.

==== Ajax ====

Es würde zu weit führen, das Ajax-Request und -Response-Konzept von Prototype zu erklären. Daher möchte ich hier nur wieder auf das [[http://www.prototypejs.org/learn/introduction-to-ajax|Ajax-Tutorial]] von Prototype verweisen, sowie auf die Beispiele des Spieltisches, auf dem ich schon einige Ajax-Abfrage realisiert habe.

Vorausgesetzt, die Abfrage wurde ordnungsgemäß an den Server abgesetzt, schauen wir uns nun mal die Serverseite an:

<code php>
// Falls Ajax-Anfrage
if ($this->isXmlHttpRequest())
{
  // Falls bei der Anfrage eine Callback-Funktion uebergeben wurde
  if ($this->getRequest()->getParam('callbackHandler'))
  {
    $this->getView()->getAjaxResponse()->setCallbackHandler
      ($this->getRequest()->getParam('callbackHandler'));
  }
}
</code>

So heißt es in Dsao_Controller_Abstract::init(). Es kann also der Parameter 'callbackHandler' von JavaScript übergeben werden, dieser wird dann in der Antwort wiederum mitgeschickt. Dies ist nötig, da die Antworten des Servers immer zunächst an eine zentrale Funktion weitergeleitet wird, die u.a. Fehlermeldungen usw. anzeigen lässt (vermutlich ist hier zum späteren Zeitpunkt noch ein flexiblereres System zum Umgang mit Fehlern nötig).

Auch über PHP kann ein Callback-Handler gesetzt werden (der den direkt übergebenen überschreibt!):

<code php>
$this->getView()->getAjaxRespone()->setCallbackHandler('someResponder');
</code>

Im Controller bzw. in der Aktion kann über $this->isXmlHttpRequest() jederzeit getestet werden, ob eine Ajax-Anfrage vorliegt, und dementsprechende Operationen durchführt werden. Aber alles andere bleibt weitestgehend gleich, Variablen und Meldungen können weiterhin an Smarty übergeben werden, dort werden sie dann einfach komfortabel vom Controller später wieder abgefragt, wenn die Ajax-Antwort gebaut wird.