PHP - Schnittstelle

---

Mit  PHPAC  wurde erstmals 2002 ein in PHP programmiertes Web-OPAC-Grundmodell bereitgestellt.
Es trat neben ein schon älteres, in Perl programmiertes Modell namens acwww25.
Die Zielvorstellungen bei  PHPAC  waren:

1. Alle für die Katalogbenutzung notwendigen Funktionen, plus Datenerfassung und Korrektur.

2. Einfaches Installieren, möglichst wenige Dateien, geringer Anpassungsbedarf.
    Wirklich notwendig ist, wenn man das Standardschema verwendet, nur die Anpassung einer einzigen Datei: av_ini.php.
    Dazu wenige Zeilen in der Konfig-Datei des Servers:  avanti.con
    Die wichtigsten Inhalte beider Dateien siehe Anhang.

3. Leichte Umstellung auf ein anderes Kategorienschema, d.h. möglichst wenig Abhängigkeit vom Datenschema.

4. Hinreichende Dokumentation, um Veränderungen und einen weiteren Ausbau zu unterstützen.

Es gab dazu auch schon eine Übersicht, aus der man die Funktionen der verschiedenen Dateien ersehen konnte, also der PHP-Skripte und Parameterdateien. Die Übersicht ist etwas abstrakt, deshalb wird sie hier um eine illustrierte Darstellung ergänzt.

Viele Web-Kataloge wurden bereits mit diesem Modell realisiert, einige Musterdatenbanken sind auf dem allegro-Server zur Ansicht verfügbar. Aus den bisherigen Erfahrungen wurden einige Verbesserungen herausdestilliert. Es handelt sich mehr um Details, nicht um grundlegende Veränderungen. Im folgenden werden die unterschiedlichen Bilder gezeigt, die man in einem solchen Katalog zu sehen bekommt, und es wird kurz beschrieben, wie diese Bilder zustandekommen. Wer phpac schon kannte, wird ein paar Modifikationen im Erscheinungsbild bemerken.


1. Die Startseite: index.htm 


Diese Datei kann völlig frei gestaltet werden. Zu übernehmen braucht man nur das Formular mit den zwei Elementen <select> (Auswahlbox) und <input> (Eingabefeld), doch auch den Inhalt von <select> kann man ändern. Eine ganz andere Gestaltung sieht man z.B. bei der DemoBank zum Neutralformat. (Dabei wird, anders als im Normalmodell, nicht in ein Register gesprungen, sondern eine Mehrfach-Suche durchgeführt. Dazu wird nicht page.php, sondern zx.php aufgerufen.)

Der Link "Neue Daten erfassen" wird nur gebraucht, wenn über phpac auch Dateneingabe ermöglicht werden soll. Es wird dann edrec.php mit Satznummer 0 aufgerufen - ein leeres Formular erscheint.
Hinter  ? ? ?  steckt ein Link zur Datei tellme.htm, die man gleichfalls frei gestalten kann, um alle nötige Information zum Katalog bereitzustellen.

Damit alles weitere funktioniert, muß man den avanti-Server korrekt installiert und in seiner Datei  avanti.con  die betr. Datenbank eingetragen haben. In der Datei  av_ini.php  muß dann der symbolische Name der Datei stehen, wie er in die  avanti.con  eingetragen ist. Die Datei av_ini.php wird von allen PHP-Skripten eingebunden. Darin stehen viele modifizierbare Variablen, darunter die Überschriften etc. für die anderen Seiten, aber auch allgemeine Funktionen sowie CSS-Anweisungen. Am wichtigsten ist die Funktion sendjob(), die von allen Skripten  benutzt wird, um Aufträge an den avanti-Server abzuschicken. Der Server liefert dann meistens fertigen HTML-Text, der nur noch an den Endnutzer auszuliefern ist. Selbstverständlich ist av_ini.php kommentiert, so daß man sehen kann, was dort in welcher Weise geändert werden muß, kann, darf oder sollte.

Aus dem Formular heraus wird das PHP-Skript  page.php  aufgerufen. Diesem werden die Parameter urG und urS übergeben. So sieht der Aufruf aus, den man auch in beliebige andere Seiten einbauen kann, um dasselbe zu erreichen:
   page.php?urG=sym&urS=startpkt
Dabei ist  sym  der symbolische Name eines Registers und startpkt eine Zeichenfolge, die angibt, an welcher Stelle das Register aufzublättern ist. Das sieht dann so aus:
Wählt man z.B. bei der DemoBank das Register "Personennamen" und gibt "shakesp" ein (der Anfang eines Namens genügt!), kommt dieses heraus, produziert vom Skript page.php mit dem Aufruf  .../page.php?urG=per&urS=shakesp


2. Indexfenster



Der Fensterinhalt wird aufbereitet in av_page.php, genauer gesagt macht es avanti mit dem  export-Befehl, wobei eine Parameterdatei namens h-php.apr zum Einsatz kommt. Diese ist unabhängig vom konkret verwendeten Kategorienschema und muß nicht angepaßt werden, sie liegt bei der Datenbank. Sie enthält einige Hilfsfunktionen, die größte ist der Aufbau einer Registerseite, wie oben zu sehen.. 

Auf einer solchen Registerseite hat man mehrere Möglichkeiten:

2.1. Eine andere Stelle aufblättern: Man wählt u.U. ein anderes Register und gibt einen anderen Startpunkt ein. Dadurch wird wieder  page.php  aufgerufen, um einen anderen Registerabschnitt zu zeigen.

2.2. Vor- und zurückblättern: Dazu klickt man auf "Eine Seite weiter" bzw. "Eine Seite zurück". Dahinter steckt jeweils ein Aufruf von page.php; man sieht es genau (unten in der Statuszeile), wenn man mit der Maus darauf zielt.

2.3. Einzelne Zeile anklicken. Dabei gibt es drei Arten von Zeilen:

 

Tip: Auf einer Indexseite werden regulär 18 ZeZeilen gezeigt. Die Zahl ist aber variabel: wenn man zum Aufruf von  page.php  noch &urA=30 ergänzt, erhält man z.B. 30 Zeilen ab Startpunkt, mit &urA=-30 sind es 30 Zeilen oberhalb des Startpunkts - so wird das Rückwärtsblättern ermöglicht.
In av_ini.php kann man den Standardwert 18 ändern, und zwar mit dem Befehl  $uRA = ....


3. Ergebnisliste
Eine Ergebnisliste erscheint in einem etwas kleineren Fenster [neu] und sieht immer so aus:

 
Für diese Anzeige wird die Parameterdatei d-khtm.apr benutzt (Einstellung $Dispar in ac_ini.php). Die eigentlich wichtigen Teile stehen aber in der Datei d-k.apt. (Diese wird auch in d-krtf.apr und d-kdos.apr für Windows bzw. DOS eingebunden und ist damit plattformunabhängig.) Man muß sich also nur um  d-k.apt kümmern, wenn man Änderungen machen will (weitere Datenfelder zeigen, Anordnung verändern,...) oder eine ganz eigene Version. Das ist normalerweise nicht schwer; es stehen Kommentare drin und man erkennt das Strickmuster, wie die Ausgabe eines Feldes gemacht wird. Alles Schwierige ist allgemeingültig gelöst und muß nicht verstanden werden (hierarchische und verknüpfte Sätze!).
Unten kann man, wie bei der Ergebnis-Kurzanzeige, eine E-Mail-Adresse eingeben, dann bekommt man die Daten zugeschickt. Dies erledigt wieder das Skript  t-mail.php, benötigt werden darin Exportparameter  d-mail.apr oder andere, die man evtl. dafür erstellt.
Oben rechts sieht man den Link "Edit/Bearbeiten" und unten einen Button zum Löschen des Satzes (für diese Dinge muß eine Einstellung in der Datei  av_ini.php  gesetzt sein sowie in av_grec.php, man findet Kommentare dazu).
Eingebunden in die Parameterdateien (*.apr) ist jeweils die Codierungstabelle ad-utf.apt für Unicode, denn die ganze Oberfläche ist in UTF-8 codiert.

5. Bearbeitungsformular  [Nur wenn man Editierfunktionen bereitstellen will]
Wenn man auf "Edit/Bearbeiten" klickt, sieht man dieses Formular:


Produziert wird dieses Formular von dem Skript  edrec.php. Darin kann man relativ leicht die Gestaltung verändern, z.B. andere Felder hinzunehmen. Die zwei Buttons [Wieder speichern] und [Als neuen Satz speichern] rufen das Skript  write.php auf. Dieses braucht nicht angepaßt zu werden, es übernimmt alle im Formular vorgesehenen Felder, ordnet sie dann in den Datensatz ein und speichert ihn als veränderten bzw. neuen Satz.

6. Kombinierte Suche
Klickt man im ersten Bild oder auf der Registeranzeige oben links auf "Neue Suche", kommt folgendes: (dahinter steckt detail.php)


Dieses Suchformular (Wir sagen nicht "Maske", sondern treffender "Formular" - und so heißt es ja auch innerhalb HTML) wird komplett von dem Skript  detail.php  hergestellt. Gebraucht wird dazu die schon erwähnte Parameterdatei mit den Hilfsfunktionen, h-php.apr. Die Namen der Register und der Restriktionen werden aus der Index-Parameterdatei der Datenbank entnommen. Dieselben Namen sieht man auch im Programm a99 bzw. alcarta im Fernglas-Menü. Auch in die  detail.php  kann man ansonsten freizügig gestaltend eingreifen, obwohl sie unverändert mit jedem Schema funktionieren sollte..
[Registereinblick] verzweigt zum Skript  page.php, und [Suchbefehl ausführen] zu  rset.php. Man kann also von dieser Startseite aus sowohl in den Registern blättern (dann wird nur das erste Eingabefeld ausgewertet) wie auch eine kombinierte Suche machen.


DOWNLOAD

avanti

Die aktuelle Version und einige ältere des avanti-Servers holt man sich so:

Linux:   http://allegro-b.de/downloads/avanti64.gz/
Für Windows befindet sich avanti.exe im "Gesamtpaket", d.h. jeder Anwender hat es.
Die erste Installation auf einer Plattform macht man z.B. Schritt für Schritt nach der Anleitung von C. Schönberger .

phpac

Das Paket phpac bekommt man hier:

http://allegro-b.de/downloads/phpac/phpac.zip  

Die Installation geht so: Das Archiv  phpac.zip  entpacken in irgendein Verzeichnis. Dies dient nur als Zwischenlager für die Dateien. Man erhält dort die folgenden Unterverzeichnisse, deren Inhalte man anschließend an die jeweiligen Ziele kopiert:

php:   Auf ein Unterverzeichnis des Webserver-Dokumentenbereichs.
       Dieses dient danach als Startadresse für den Web-OPAC.
       Lokale Einstellungen sind zumindest in  av_ini.php  nötig.

avlib: (optional) Einige allgemeine PHP-Funktionen. Diese kann man für eigene Entwicklungen nutzen.
       Dokumentation: ref_av.htm

param: Auf das eigene Datenbankverzeichnis. Modifikationen nur nötig, wenn man nicht den
       Standard A.CFG verwendet (s.o.).

Tip: Wer eine schon laufende Anwendung aktualisieren will, braucht nur die Dateien  page.php und  pag.php auszutauschen sowie die Parameterdatei  h-php.apr. Optional von den anderen Dateien nur diejenigen, die man selber nicht verändert hat, z.B.  rset.php und  av_rset.php. 
 

---

Anhang :  avanti.con  und  av_ini.php, und Notwendige Dateien
In Lila ist zu sehen, welche Angaben in beiden Dateien übereinstimmen müssen

avanti.con   (auf dem ProgDir, d.h. wo  avanti.exe  liegt, z.B.  c:\allegro)
                         Wichtig: Wenn man diese Datei ändert, dann avanti neu starten.
[general]
port = 4948
prefork = 1
AnonymousAccess = yes
max_cputime = 120
# logfile = c:\temp\ava.log
# loglevel = all,!io

#    für jede bereitzustellende Datenbank ein Abschnitt nach diesem Muster:
[demo]
directory = c:\allegro\demo2
access = 3
konfiguration = a
indexparameter = cat
opac = OPAC:1
admin = AZBYCX:3

av_ini.php   (gehört zu den PHP-Skripten der Datenbank, z.B. in  c:\xampp\htdocs\demo )
$UTF=1;   // Datenbank ist intern ASCII, Ausgabe soll UTF-8 sein

$Server = "localhost";  // hier kann die Adresse eines anderen Servers stehen
$Port = "4948";         // Derselbe Wert wie in der avanti.con

$DB = "demo";       // symb. Datenbankname
$ID = "admin/AZBYCX";   // User / Pw für den Zugriff (wie in avanti.con)

$Dispar = "d-khtm";  // Parameter für die Titelanzeige
// falls Schreibzugriff erlaubt sein soll:
$CM = "u";           // c = Codiertes Pw, u = uncodiert, r = read-only Modus (default)
$CW = "abcdef";      // bei DIESER Datenbank ist $CM='u', also uncodiert

Alle weiteren Werte sind optional. Kommentare in av_ini.php der DemoBank.

Notwendige Dateien auf dem ProgDir (auf demselben Rechner, wo die Datenbank liegt)
avanti.exe   Server  (unter UNIX/LINUX ohne .exe)
acon.exe     Programm zur Ausführung der Jobs
avanti.con   Liste der Datenbanken, die der Server kennen soll
uifsger      Textmeldungen

Auf dem DbDir (z.B. c:\allegro\demo2) ODER ebenfalls auf dem ProgDir
Konfiguration, z.B.  $a.cfg  --  sicherheitshalber immer auf dem DbDir, für die anderen auch ProgDir möglich
Indexparameter, z.B. cat.api mit  i.apt, o.apt, swl1.apt
Parameterdateien  h-php.apr, h-edit.apr, ad-utf.apt, d-khtm.apr, d-k.apt, d-htm.apt

Auf dem html-Verzeichnis für die Datenbank, z.B. c:\xampp\htdocs\demo
Der gesamte Inhalt des PHPAC-Unterverzeichnisses  php
Anzupassen ist im Minimum nur  av_ini.php, wenn aLF zum Einsatz kommt, auch  av_mini.php in gleicher Weise.

avanti-Server als Dienst installieren   (Mit Administrator-Rechten auszuführen)
Auf einer Windows-Plattform genügt dazu folgender Befehl, zu geben auf dem Verzeichnis, wo  avanti.exe  liegt:

avanti -install

Schon läuft er und wird fortan stets beim Hochfahren des Systems automatisch gestartet.