Tutorial: xajax in xtcommerce

Aus xtc-wiki

(by Hendrik Koch, 08.2009)

Ajax wird im Allgemeinen mittels exstierender Bibliotheken (Frameworks) eingebunden. Eine der bekanntesten Ajax Frameworks ist xajax (http://xajaxproject.org/). Dieses Tutorial beschreibt wie xajax, und darauf basierend ajax-Features, in xtcommerce eingebunden werden.

[Bearbeiten] Problematik Einbindung xajax

Damit eine Erweiterung, ein Modul, xajax verwenden kann bringt es im Allgemeinen sein eigenes Exemplar der xajax-Bibliothek mit.

Problematisch wird es wenn hinterher ein zweites xajax-Modul installiert werden muß, welches ebenfalls eine xajax-Bibliothek mitbringt und parallel integriert. Es treten ernste Konflikte auf.

Wenn die Module vom gleichen Programmierer stammen sind die Konflikte noch relativ leicht aufzulösen da ein Programmierer stets auf gleiche Weise die xajax-Bibliothek einbindet. Bei Modulen unterschiedlicher Programmierer ist das schon deutlich schwieriger.

Von vorn herein günstiger ist es wenn die xajax-Bibliothek einmal integriert wird und die Module nur noch darauf aufbauen.

Im folgenden wird eine Lösung vorgestellt wie man einmalig xajax in xtcommerce integriert in Form eines fertigen Moduls. Anschließend wird beschrieben, anhand eines simplen Beispielmoduls, wie man die neuen xajax-Features nutzen kann. Erstellt man mehrere xajax-Module lassen sich auf diese Weise die o.g. Konflikte von vorn herein vermeiden.

[Bearbeiten] imd_xajax

Die Grundeinbindung der xajax-Biblothek liegt als fertiges Modul vor (s.u., download) und kann mit wenigen Handgriffen installiert werden.

Installationsanleitung (liegt auch dem Modul bei)

Betroffene Dateien:

 xajax.common.php                           *
 xajax.server.php                           *
 includes/header.php
 includes/classes/class.inputfilter.php
 includes/xajax_core/                (DIR)  *
 includes/xajax_js/                  (DIR)  *
 includes/xajax_imd/                 (DIR)  *

* hinzugekommene Dateien  
   

Dateien new_files/ und new_dirs/ in das Dateisystem der xtcommerce-Installation einkopieren.

includes/header.php

Finde:

   // require theme based javascript
   require('templates/'.CURRENT_TEMPLATE.'/javascript/general.js.php');

Füge davor ein:

   // Include XAJAX JS Library
   require ('xajax.common.php');                            // imdxajax
   if ($imdxajax) {
     $imdxajax->printJavascript('includes/');
   }

includes/classes/class.inputfilter.php

Finde:

   unset ($source[$key]);

Ersetze durch:

   if ($key != 'xajaxargs') {                     // imdxajax
     unset ($source[$key]);
   }

Die xajax-Bibliothek ist nun eingebunden und kann genutzt werden.

[Bearbeiten] imd_xajax Beispielmodul

Auf Mausklick erscheint eine Alertbox welche Client und Serverzeit miteinander vergleicht. Das Modul heißt „exservertime“.

Im Ordner includes/imd_xajax/ werden zwei Moduldateien angelegt. Diese werden im laufenden Betrieb automatisch gefunden und integriert.

1. includes/xajax_imd/exservertime.xajax.server.inc.php

Dies ist die serverseitige ajax-Funktion womit der Client die Lokalzeitzeit des Servers abruft und eine Alertbox initiieren lässt.

 // Beispielmodul
 function exservertime_get_servertime($clienttime) {
   
   $ctime_text = "clienttime: $clienttime";
   $stime_text = "servertime: ".date('D d. M H:i:s');
   
   $ret = 'imdxajax '.IMDXAJAX_VERSION.' '.IMDXAJAX_VERSION_XAJAX;
   $ret.= "\n".$ctime_text."\n".$stime_text;
   
   $objResponse = new xajaxResponse();
   $objResponse->alert( $ret );
   return $objResponse;
 }

Es können beliebig viele Funktionen eingetragen werden. Zur Vermeidung von Namenskonflikten sollten alle Funktionen den Modulnamen enthalten. Wie die Funktion selbst zu erstellen ist, ist der xajax-Dokumentation zu entnehmen. http://xajaxproject.org/en/docs-tutorials/

2. includes/xajax_imd/exservertime.xajax.common.inc.php

Deklaration der Serverfunktionen

// Beispielmodul
$imdxajax->registerFunction('exservertime_get_servertime');

Für jede Funktion aus1. wird hier eine Zeile mit dem Funktionsnamen eingetragen.

Anmerkung: Durch das erstellen zweier neuer Dateien wird die spätere Modulinstallation erleichtert. Einkopieren von fertigen Dateien ist weniger aufwändig als Patchanleitungen auszuführen.

Die serverseitigen Funktionen stehen nun. Jetzt muß in den Shop noch ein Javascriptaufruf erfolgen der die Funktion zu Ausführung bringt. Auf der index.html des Templates wird ein Link platziert.

Datei templates/<eigenes_template>/index.html Folgenden html-Code einfügen:

   <!-- ---- exservertime beginn ------------------------ -->
   <a href="#" onClick="xajax_exservertime_get_servertime( new Date().toLocaleString() );">
     exservertime_test
   </a>
   <!-- ---- exservertime end ------------------------ -->

Zu beachten ist. Für den Javascriptaufruf ist dem Funktionsnamen ein „xajax_“ voranzustellen. Aus

exservertime_get_servertime
wird
xajax_exservertime_get_servertime

Im Shop erscheint nun ein Link "exservertime_test". Ein Klick darauf sollte eine Meldung hervorrufen welche Server- und Client-Systemzeit anzeigt.

[Bearbeiten] Zusammenfassung Integration eigener xajax-Funktionen

1. Anlage Dateien (einmalig)
includes/xajax_imd/meinmodul.xajax.server.inc.php
includes/xajax_imd/meinmodul.xajax.common.inc.php

2. Anlage Funktion
meinmodul.xajax.server.inc.php: Funktion: meinmodul_meinfunktionsname()
meinmodul.xajax.common.inc.php: $imdxajax->registerFunction(meinmodul_meinfunktionsname');

3. Anlage Aufrufe in Template/Shop
Aufruf: xajax_meinmodul_meinfunktionsname()

[Bearbeiten] Modulbau

xajax-Module werden 2-teilig ausgeliefert.

1. imd_xajax-Modul
2. Modul

Das Hauptmodul setzt die vorige Installation imd_xajax vorraus. Das Hauptmodul beinhaltet die Dateien
includes/xajax_imd/meinmodul.xajax.server.inc.php
includes/xajax_imd/meinmodul.xajax.common.inc.php
welche einfach einkopiert werden (geringerer Installationsaufwand).

Bei Installation weiterer Module kann die vorige Installation imd_xajax entfallen.

Anlage: Download imdxajax1.1