a35 - Web-Oberfläche für allegro-Datenbanken
a35 : Plattformunabhängige Browser-Oberfläche für allegro-Datenbanken
Konzept und Installation
2018-08-12


Vorwort
Das ab 2012 entwickelte Web-Interface a35 arbeitet auf der Basis von HTML5 + JavaScript + CSS3 im Browser sowie PHP + allegro-FLEX im Server. a35 bietet damit für die Oberfläche das gesamte, jedem Web-Entwickler vertraute Potential von HTML5. Fremdkomponenten, wie z.B. Java, MySQL oder XML, werden nicht verwendet.
 
Hauptziel von a35 ist es, eine Web-Oberfläche für das Arbeiten mit einer Katalogdatenbank zu schaffen. Auch als Web-OPAC kann es dienen, wenn auch ein zeitgemäßes OPAC-System für Endnutzer heute nach verbreiteter Meinung mehr erfordert, als die Indextechnik von allegro leisten kann. Dafür kann VuFind zum Einsatz kommen oder beluga oder vergleichbare Discovery Systeme, die ihre Daten von allegro per MARC-Export erhalten. Diese Systeme kosten allerdings serverseitig deutlich mehr personellen Aufwand.

Zu den Grundsätzen der Oberfläche von a35 siehe Abschnitt "Design-Konzept".



Installation: Was braucht man, wohin damit?

Man braucht eine avanti-Installation für den Zugriff zu den Datenbanken und natürlich einen Webserver für den Zugang über das Internet.

Die aktuelle Version des a35-Gesamtpakets, mit allen nötigen Programmen und Dateien (bis auf den Webserver, i.d.R. Apache), holt man sich hier:

 http://www.allegro-b.de/download/a35.zip

In diesem Paket stecken drei Ordner mit Unterordnern, in jedem davon erklärt eine Datei README, wozu die Dateien gut sind und wohin sie gehören:

1. allegro  : Diese Dateien und Programme (acon, avanti u.a.) gehören in den Programm- bzw. Datenordner auf dem  
                                 Arbeitssystem, d.h. wo man die allegro-Software und die Datenbanken installiert hat
                                 (Windows-Hauptprogramm: a99, a35-Programme: avanti und acon). 

2. www      : HTML- und Skript-Ordner (.php, .js, .css, .htm und .job) zur Installation auf dem Webserver. 
                                 Der Inhalt: Ein Ordner db, er gehört für XAMPP unter Windows in \xampp\htdocs , für Apache in /var/www/html
                                 Der Webserver braucht physisch nicht derselbe Server zu sein wie für 1., denn die Kommunikation 
                                 zwischen Webserver und Datenserver läuft über TCP/IP.

3. doku     : Einige wichtige Texte, u.a. HOWTO mit den wichtigsten Schritten zur Installation

Für Windows sind die Programme acon.exe  und avanti.exe mit im Installations-"Gesamtpaket".
Die Linux-Programme, vor allem avanti und acon, sind hier:
 http://www.allegro-b.de/download/linux-prog.tar.gz

Inhalte der Ordner, hier mit geeigneten Beispielnamen für Linux  (Windows: \ statt / )
Programm- und DatenOrdner 
(Windows oder Linux)

ProgDir = c:\allegro bzw. /var/allegro    
Hier Programme avanti + acon etc.

DataDir z.B. = ProgDir/db    
darin für jede Datenbank ein Unterordner:

DataDir/demo2    Demo-Datenbank

DataDir/name      Eigene Datenbank(en)
(z.B.  namekatalog)
Statt der echten Daten können es auch Kopien sein, die man regelmäßig aktualisiert.

Der Ordner  DataDir kann auch woanders liegen statt unter  ProgDir, er muß nur für die Programme zugänglich sein.

avanti

<-- TCP/IP -->

z.B. Port 4949
s.u..










HTML- und Script-Ordner  bei dem Webserver
WebDir = ...\htdocs oder  .../html

Unter Linux z.B.
WebDir = /var/www/html (auch Document Root genannt)
a35DirWebDir/db    Ordner für a35-Scripte;
  hier liegt auch  ajax4.php (universell f. alle Datenbanken)

a35Dir/demo    Skripte für Demo-Datenbank
a35Dir/demo/demojobs    Jobs speziell für Demo-Datenbank

a35Dir/opac    Skripte für Katalog-Datenbank, hier Einstellungen in  a35ini.php und ajax4ini.php
a35Dir/opac/katjobs
   Jobs speziell für  katalog-Datenbank,
Der Name $Jobdir="demojobs"/ bzw.  ="katjobs/" muss in ajax4ini.php stehen

a35Dir/scripts    Universelle Skripte, vor allem  a35.js 
a35Dir/scripts/jobs    Universelle Jobdateien

Die Demo-Datenbank wird nicht unbedingt gebraucht, aber sie ist nützlich zum Testen, weil sie auf jeden Fall sofort funktionieren sollte.

In folgenden Dateien sind Einstellungen unbedingt nötig:
  1. avanti.con   im Ordner ProgDir   und    
  2. ajax4ini.php und a35ini.php (im Ordner a35Dir/demo) und in den entsprechenden Ordnern für weitere Datenbanken   

In rot ist zu sehen, welche Angaben in diesen Dateien übereinstimmen müssen. In grün, welche für die jeweilige Datenbank sonst noch angepaßt werden können, aber nicht immer müssen.

1.  avanti.con : gehört ins ProgDir, also wo avanti(.exe) und acon(.exe) liegen
Wichtig: Diese Datei gibt es nur einmal, sie enthält die Angaben, die avanti für alle zu bedienenden Datenbanken braucht.
Wenn man diese Datei ändert, dann avanti neu starten.  Die Datei enthält ihre Dokumentation!

 [general]
port = 4949 # über diesen Port kommuniziert avanti mit dem Webserver, s.u.
prefork = 1
AnonymousAccess = yes
max_cputime = 120
# Aktivieren, wenn man eine LOGdatei will: [s. Original der Datei für mehr Doku]
# logfile = /var/log/a35/ava.log
# loglevel = all,!io
...
# für jede zu bedienende Datenbank ein Abschnitt nach diesem Muster:

[demo] [symbolischer Name der Datenbank]
 directory = /var/allegro/db/demo2 (Linux) oder c:\allegro\db\demo2 (Windows)
access = 3
konfiguration = a
indexparameter = cat
# Nutzerkennungen und Passwörter, access 1 = Nur lesen, 3 = lesen und schreiben
opac = OPAC:1
master = AVANTI:3

2. ajax4ini.php : im Paket im Ordner DataDir/demo und in den entsprechenden für andere Datenbanken

Wird nur von  ajax4.php  gebraucht.
Diese Datei wurde auch für die ältere Schnittstelle  PHPAC gebraucht, hatte aber dort den Namen  ajax3ini.php.
Darin Einstellungen für die Skripte zu einer konkreten Datenbank; d.h. jede Datenbank braucht ein Exemplar davon.

Man macht am besten für jede andere Datenbank zuerst eine Kopie von html/db/demo

Folgende Einstellungen sind in  ajax4ini.php   wichtig:

$UTF=1; // Datenbank ist intern ASCII, Ausgabe soll UTF-8 sein
// Wenn intern UTF-8, dann diesen Befehl weglassen!

// Serveradresse und Port: IP oder Name
$Server = "127.0.0.1";  // bzw. IP eines anderen Servers, dort müssen dann avanti und acon liegen  
$Port = "4949";  //  Wie in avanti.con. Dieser Port muß auf den Servern geöffnet sein

// Wo liegen die Programme? (auf demselben Server, wo die Datenbank liegt!,
// das ist nicht unbedingt auf dem Webserver
$ProgDir="c:\allegro";  unter Linux z.B. $ProgDir="/var/allegro"; 

// symbolischer DB-Name wie in avanti.con (s.o.), nicht der reale Name und Ort auf dem Datenbankserver
$DB="demo";

// user und password wie in avanti.con (des users, der den job starten soll)
$ID="master/AVANTI";   // bzw. opac/OPAC, wenn keine Schreibzugriffe notwendig

$SP="a0";       // Sortierposition in Kurzzeilen für Ergebnislisten (daraus wird im Job: #uSP )

$Dispar="d-html"; // Anzeigeparameter für die Datensätze, hier d-html.apr. (display parameter file)

// Wo liegen die Jobs? (relativer Pfad im a35Dir/demo,  hier also .../demo/ajaxjobs , der jeweiligen Datenbank)
$Jobdir="ajaxjobs/"; 

-------------------------------------

Notwendige Dateien im ProgDir (auf dem Datenserver, d.h. wo die Datenbank liegt)

avanti.exe   (LINUX:  avanti)  Serverprogramm
avanti.con   Liste der Datenbanken, die  avanti  kennen soll  (s.o.)
acon.exe     (LINUX:  acon)  Programm zur Ausführung von Job-Dateien (Typ .job)  
al.job       Admin-Job + Hilfetext al-help.txt  (Hilfsfunktionen; Start unter Linux:  ./acon -jal)
uifsger      Texte für die Meldungen der Programme avanti und acon

Auf dem DataDir (z.B. c:\allegro\db\demo2  bzw.  /var/db/demo2 ) ODER ebenfalls auf dem ProgDir:
Konfiguration, z.B. $a.cfg oder a.cfg -- sie enthält alle Angaben zur Datenstruktur, vor allem das Kategorienschema
Indexparameter, z.B. cat.api mit Hilfstabellen  i.apt, o.apt, ucodes.apt, swl1.apt
Parameterdateien: d-khtm.apr + ad-utf.@pt oder d-html.apr, dazu , d-k.apt, d-htm.apt u.a.

Im Webserver-Ordner für die Datenbank, z.B. c:\xampp\html\db\demo  bzw. /var/www/html/db/demo :
Der Inhalt des Ordners  html/demo  aus  a35inst.zip
(Der Name, hier demo, ist zugleich der symbolische Name der Datenbank; er muß nicht identisch sein mit dem Namen des Datenordners, hier demo2 )
Anzupassen sind für eine eigene Datenbank im Minimum nur ajax4ini.php und a35ini.php, siehe oben sowie unten unter "Technisches Konzept".

------------------------------------

Wichtig: 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 der Dienst und wird fortan stets beim Hochfahren des Systems automatisch gestartet.

Unter Linux startet man avanti direkt vom Programmordner aus (nicht von woanders) als Hintergrundprogramm mit dem Befehl

 ./avanti &

Auch unter Linux kann man es so einrichten, daß der Server stets beim Hochfahren des Systems gestartet wird:
Man legt im ordner  /etc/init.d  eine ausführbare Datei  avanti  an, in der nur steht:

cd /var/allegro        (wenn dies der Ordner ist, wo avanti liegt)
./avanti &

Die Datei a35ini.php liegt im Ordner a35Dir, für jede Datenbank separat im jeweils eigenen Verzeichnis.
Sie ist mit include eingebunden in die drei Startdateien  a35-pc.php, a35-tab.php, a35-app.php.

Wichtige Inhalte von a35ini.php :  

$dbTitle="a35 Demo Version";  // erscheint in der Kopfzeile des Browsers

$db="demo";   // Name des Ordners in  a35Dir, wo die genannten Skripte liegen (damit ajax4.php dies erfährt)

// Für die Kopfzeile der Startseite selbst, wenn man dafür die Textverson nimmt, s.u.

$dbHead='<span style="font-family:Verdana; color:rgb(204, 0, 0); font-weight:bold; font-size:20px"><i>allegro-B</i> - Demo Version</span> ';

// Varianten der Head-Darstellung der PC Version für die drei Oberflächen;
// nur jeweils eine davon aktivieren; diese wird dann in a35-pc.php etc. hinzugeladen

// $headpc= 'a35_head_pc2.php';    //  Navigation mit eigener graphischer Gestaltung
$headpc= "a35_head_pc2.php";  // Textversion Head - Navigation mit simplen Textbuttons

// Varianten der Head-Darstellung der TAB Version

// $headtab= 'a35_head_tab1.php';    //  Navigation mit eigener graphischer Gestaltung
$headtab= "a35_head_tab2.php"; // Textversion Head - Navigation mit simplen Textbuttons

// Varianten der Head-Darstellung der MOBILE Version

// $headmobile= 'a35_head_mobile1.php';   // Navigation mit eigener graphischer Gestaltung
$headmobile= "a35_head_mobile2.php";   // Textversion Head - Navigation mit simplen Textbuttons

Außerdem die  <SELECT> -Liste der anzubietenden Indexregister.


Design-Konzept

a35 ist eine Weboberfläche, die flexibel an unterschiedliche Basiswebpräsentationen anpassbar ist: PC, Tablet, Smartphone ("App"):

Die Hauptelemente der Oberfläche befinden in drei PHP-Dateien: a35-pc-cont.php, a35-tab-cont.php, a35-app.php

Die Job-Skripte für die eigentliche Datenbankarbeit sind davon unabhängig, d.h. für alle drei Oberflächen gleich.

Bei der Arbeit mit einer Datenbank gibt es vier Arten von Information, die oft alle gleichzeitig sichtbar sein sollten, weil sie logisch zusammenhängen:

Ergebnislisten : geordnete Übersicht (Kurzliste) der Ergebnisse eines Suchbefehls
Indexsuche : geordnete Übersichten (Register) von Namen , Titeln, Schlagwörtern etc. zur Auswahl (browsing)
Titeldaten : Metadaten, jeweils ein Datensatz zu einem ausgewählten Objekt (z.B. Buch, PDF-Datei, Website)
Extras : Funktions- und Arbeitsdaten, z.B. Eingabeformulare, Hilfetexte, eigene Menüs

Jeder der Bereiche braucht seine eigenen Schalt- und Eingabeelemente, die ihm jeweils auch optisch unmittelbar zugehören sollten. Z.B. die Eingabefelder für Suchbefehle bzw. der Einstiegspunkt im Index sollten Bestandteile dieser Bereiche sein. Als einfachstmöglicher Designansatz ergab sich daraus die Aufteilung der verfügbaren Fläche in vier Quadranten: (jeder hat ein internes, dreibuchstabiges Label)
EXT / INT : Titeldaten Umschaltbar mit F5 : "extern" / "intern"  INF : Extras für jeweils benötigte Aufgaben, auch Hilfetexte, Menüs
ERG : Ergebnislisten mit Eingabefeld für Suchbefehle REG : Indexsuche in Registern, wie sie für allegro typisch sind.
FRE : Popup-Feld für beliebige Inhalte, erscheint mittig FRR : Popup-Feld, erscheint unten rechts

Während einer Sitzung sieht die PC-Variante so aus: (hier zum Ausprobieren:  http://www.allegro-b.de/db/demo/a35-pc.php )

Oben rechts kann man die Varianten für Tablet und Mobiltelefon auswählen.
PC-Version der Oberfläche


Die gesamte Struktur dieser Oberfläche steckt in der Datei a35-pc-cont.php, in der man die Anordnung und alle Einzelheiten leicht modifizieren kann, auch das Menü oben in der Mitte. Die zu Anfang erscheinenden Inhalte (s.o.) der vier Quadranten stehen in der Datei a35start.htm, einfach mal reinschauen! Sie wird gleich zu Beginn geladen, bevor man etwas eingeben kann. Das rot umrandete Feld ist der Eingabeschlitz für Suchwörter und Befehle.
Tip: Mit F2 obere und untere Hälfte vertauschen. 

Für kurzzeitig wichtige Dinge gibt es die Felder mit den Labels FRE,  FRR und FRL, die bei Bedarf in der nötigen Größe mittig bzw. rechts/links unten eingeblendet werden. 
Beispiel: das Login-Menü  a35login.htm : (im Menü  Sitzung / Login-Menü):

login


Warum so und nicht anders? 

Wichtigster Grundsatz ist, die verfügbare Fläche für zusammengehörige Information voll auszunutzen, d.h. logisch zusammenhängende Vorgänge nicht in eine Folge von mehreren verschiedenen Anzeigebildern zu zerlegen - fast immer sind es mindestens drei: Eingabe von Suchbegriffen -> Ergebnisliste -> Einzeltitel.
a35 zeigt dagegen ein stehendes Bild, das nur in sich aktualisiert wird - wie eine Desktop-Anwendung. Dies ist der besondere Vorteil der AJAX-Technik

Die Anordnung der Quadranten ergab sich aus folgenden Überlegungen:
1. In aller Regel ist das Endergebnis einer Suche ein einzelner Datensatz, d.h. eine Objektbeschreibung , denn gesucht wird ja zumeist nach ganz bestimmten, einzelnen Objekten, und jeder Datensatz beschreibt ein solches. Dafür braucht man ein Anzeigefeld. Es ist links oben:  das ist die intuitiv zumeist wichtigste Position einer Anzeige. Dieses Feld hat zwei Inhalte,  EXT und INT genannt, diese zeigen jeweils eine externe und eine interne Darstellung eines einzelnen Datensatzes, zwischen denen man mit F5 umschaltet.
2. Meistens findet eine Suche aber zuerst mehrere Objekte! Das Feld ERG mit der Ergebnisliste zur Auswahl zwischen den gefundenen Objekten erscheint unter dem Feld EXT/INT, damit für das Auge der Weg von den Kurzdaten in der Liste zur vollständigen Angabe eines Satzes möglichst kurz ist, aber beides bequem im Blick bleiben kann. Ein in der Liste angeklickter Satz  wird dann also in EXT / INT gezeigt. 
3. Das Registerfeld REG als Hilfsmittel zur Bildung von Ergebnismengen steht aus demselben Grund direkt rechts neben dem Ergebnislistenfeld.
4. So bleibt der Bereich rechts oben übrig für Menüs, Formulare, Hilfetexte und beliebige andere Inhalte (Feld INF), die gerade gebraucht werden. 

In den einzelnen Bereichen (außer REG) kann man, unabhängig voneinander, zu den vorher dort erschienenen Anzeigen zurückblättern (Buttons [<] und [>] ).  In EXT und ERG gibt es einen unscheinbaren Button [ L ]; damit wird die Liste der während der Sitzung vorher dort erschienenen Inhalte aufgemacht. So kann man schnell zu anderen Sätzen und Ergebnislisten gezielt zurückgehen, ohne den Back-Button des Browsers und ohne erneuten Suchvorgang..

Hinweis: Sowohl der Datensatz wie auch Hilfetexte und Formulare werden manchmal recht lang, wobei man gern möglichst viel davon im Blick hätte. Daher sind diese zwei Quadranten oben angeordnet, und mit F12 kann man die beiden unteren Quadranten schnell mal wegblenden, um mehr von den oberen Inhalten zu sehen. Mit F2 dagegen kann man auch jederzeit oben und unten vertauschen, wenn man dies intuitiv besser findet. Dann sind also das rote Eingabefeld und die Kurzliste links oben, die Anzeige des ausgewählten Satzes darunter. Bei Größenänderung des Browserfensters passen sich die Quadranten automatisch an. Die Anordnung und Gestaltung der Quadranten ist trotz alledem, da mit HTML5 + CSS realisiert, vom Anwender für eigene Anpassungen in a35-*.php  modifizierbar. Ferner könnte an der linken und/oder rechten Seite noch ein Bereich für Navigation o.a. hinzukommen.

Zwei Varianten der Startdatei a35-pc.php sind verfügbar, zu besichtigen bei der Demo-Bank:

a35-tab.php Version für Tablets
a35-app.php
:  Version für mobile Endgeräte (Smartphones)

Die PHP-Skripte hierfür sind fast alle dieselben, es handelt sich im wesentlichen um geänderte Präsentationsformen der Oberflächenelemente: die vier „Quadranten“ der PC-Version werden hierbei nicht gleichzeitig sichtbar, sondern unter „Tabs" bzw. in einem „Accordion“ angeordnet; man sieht dann jeweils nur den Inhalt eines Quadranten. Die Umschaltung zwischen den Bereichen erfolgt an einigen Stellen im Ablauf automatisch, ansonsten durch Mausklicks auf die Tabs.



Technisches Konzept

a35 bietet einen Kernbestand von allgemeinen und universellen JavaScript- und PHP-Funktionen, die unverändert für jede Datenbank zum Einsatz kommen können. Spezifische Einstellungen werden in der Datei ajax4ini.php vorgenommen (Modifikation der  av_ini.php  von phpac).
Einige wenige Export-Parameterdateien sind nötig; für die A-Konfiguration werden sie bereitgestellt (Dateityp .apr) und können modifiziert werden. Sie gehören in den Ordner der Datenbank im DataDir oder in das ProgDir zu avanti und acon, nicht zu den HTML-Dateien.

Neue Funktionen bindet man auf standardisierte Weise ein. Dabei werden normalerweise keine Kenntnisse in JavaScript und PHP benötigt, FLEX-Jobs aber sind unentbehrlich - schließlich kann man nur damit auf die Datenbank zugreifen. Mehr dazu in einer englischsprachigen Einführung.
Auch die mitgelieferten  FLEX-Jobs für die Zugriffe zur Datenbank können geändert und erweitert werden, d.h. man muß auch die Standards nicht als unabänderlich hinnehmen.

Dateien des Standardumfangs (weitere Kommentare in den README-Dateien.)
Zunächst diejenigen, die auf dem Startverzeichnis zu liegen haben (Typen .php und .htm)

  • a35-pc.php (bzw. die Varianten -tab für Tablet und -app für Smartphone)
  • Datenbankspezifische Einstellungen stehen in a35ini.php (siehe oben)
  • Die Startdateien a35-*.php können zugleich als Beispiele und Vorlage für eigene Gestaltungen dienen,
    sie enthalten die Oberfläche, wie sie beim Start aussehen soll. Das Layout verändert sich während der Laufzeit nicht, sondern wird dynamisch mit Inhalten gefüllt (AJAX-Prinzip)
  • Nach dem Start wird zuerst die Datei  a35start.htm geladen, die man beliebig ändern kann, um zu Beginn in den vier Quadranten sinnvolle Dinge erscheinen zu lassen, z.B. auch Bilder. Wahlweise kann man statt dessen einstellen, daß ein Job  _begin.job  ausgeführt wird (in a35-pc.php ...).
  • a35examp.htm zeigt an Beispielen, wie geeignete Links bzw. Formulare konstruiert sein müssen; diese rufen z.B. als  action  die JavaScript-Funktion reqLoad() bzw. reqForm() auf  (in a35.js )
  • Formularelemente, deren Inhalte an einen Job übergeben werden sollen, müssen ein Attribut id der Form  id="Vuxy" bzw.  id="Vnnn" bzw. id="Dname"  haben, xy sind zwei beliebige Buchstaben (daraus wird im Job dann die Variable #uxy bzw. das Datenfeld  #nnn),
  • $-Variablen: Mit  id="Dname" kann man auch Angaben einbauen, die dann im Job in  $name  landen
  • Eigene Oberflächenelemente, in die per FLEX-Job etwas geschrieben werden soll, müssen in a35-*.php ein id haben mit einem 3stelligen großbuchstabigen Label, z.B. id="ABC". Die Funktion receivE() in  a35.js  erledigt dann das Einfügen des auf  _!_ABC  folgenden Textes (beliebiges HTML) in dieses Element, d.h. man braucht sich darum nicht einzeln zu kümmern. Siehe unten Bemerkungen zu  a35erg.job  usw.
  • Die genannten Funktionen übergeben via  ajax4.php  an das Programm  acon den Jobnamen mit  ?JOB=... sowie alle Variablen aus dem Formular mit &Vuxy=... bzw. &Dname=...
  • acon führt den Job dann aus. Alles, was  acon  mit write und export-Befehlen ausgibt, wird an den Webserver gegeben und kommt in  a35.js im Browser als lange Zeichenfolge an, dort wird es abgearbeitet: Was auf _!_ABC folgt, wird in der Browser-Anzeige in der Feld mit id="ABC" eingestellt. Das macht die universelle Funktion  receivE()  in a35.js.
  • a35.js  enthält weitere JavaScript-Funktionen, mit denen FLEX-Jobs aufgerufen und deren Ergebnisse verarbeitet werden können.
  • Alles CSS ist gesammelt in db/scripts/a35css.php. (!)
  • Alle datenbankspezifischen Jobs müssen in ein Unterverzeichnis, das in ajax4ini.php mit  $Jobdir="..." anzugeben ist (s.u.)

a35erg.job, um ein Beispiel zu nehmen,

  • wird wie jeder .job über das Skript ajax4.php gestartet und steckt auch hinter dem roten Eingabefeld,
  • erhält vom ajax4.php die Variablen: aus Vuxy wird im Job #uxy, aus Dname wird $name d.h. im Job hat man diese Variablen ohne eigenes Zutun zur Verfügung, ferner #uIP mit der IP-Nummer des Browsers und #uID (codiertes Passwort) wenn der Nutzer sich vorher eingeloggt hat.
  • produziert Output mit write- und export-Befehlen). Dieser Output ist eine lange Zeichenfolge, die durch Labels _!_ABC gegliedert ist.
  • Ein solches Label adressiert z.B. das Element id="ERG" im aufrufenden HTML-Code, hier also a35-pc.php, dann kommt der auf _!_ERG folgende Text bis zur nächsten Markierung _!_ in das betr. Element (das wäre Quadrant 3 in <div id="ERG">). Das erledigt die universelle Rückkehrfunktion  receivE() in a35start.php. Für eigene Erweiterungen kann man hier Sonderbehandlungen einbauen (im Abschnitt unter switch(label) ).

Weitere wichtige Jobs
a35ind.job zeigt einen Registerauszug in Quadrant 4 (Label _!_REG in a35-*.php )
a35get.job besorgt einen Datensatz und zeigt ihn in Quadrant 1 (Label _!_EXT )
(ACHTUNG: Hierin können lokale Anpassungen nötig sein für die Präsentation, Verlinkung z.B. zum WorldCat, Google Booksearch u.a.) Eingebaut ist auch, daß der angezeigte Satz zum Editieren oder als Kopie für einen neuen Satz bereitgestellt werden kann, oder auch zum Löschen. Alles unter Voraussetzung der Schreibberechtigung, s. a35id.job)
Unter dem Label _!_INT kann dieser Job zusätzlich eine andere Darstellung des Datensatzes liefern, normalerweise die interne, kategorisierte Form, die dann mit F5 im Quadranten 1 sichtbar wird.
a35admin.htm  Ausbaufähiges Menü mit Admin-Funktionen, zum Aufruf einiger der folgenden:
a35id.job  Login etc. (alle Funktionen, gestartet über a35admin.htm )
a35gre.job  Globale Ersetzungen (analog zu a99, aber als Job für acon eingerichtet)
presto.job  Aktuellen Datensatz zur Bearbeitung bereitstellen, Internformat
form1.job  denselben Satz in einem Formular bereitstellen (nur als Beispiel)
freeform.job  Ein Formular aus einer .frf-Datei generieren (das einfachste Verfahren)
prsave.job  Speicherung des bearbeiteten Satzes (gilt für jede solche Bearbeitungsform)
a35del.job  den aktuellen Satz aus der Datenbank löschen
a35fts.job  Volltextsuche ausführen, Ergebnismenge anzeigen wie bei normaler Suche
a35org.job  Index erneuern etc. ,wie a99 (Eingeben: h a35org.htm )
a35par.job  Eine Parameterdatei auswählen, bearbeiten und zurückspeichern
a35bat.job  Eine Batchdatei (oder shell script) ausführen lassen (Eingeben: h a35bat.txt )
a35sperr.job  Den aktuellen Satz oder die Satztabelle sperren
weitere Jobdateien können hinzukommen und den Funktionsumfang beliebig erweitern, ohne weiteren PHP- oder JavaScript-Code..

a35.js  liegt in db/scripts

  • es enthält die universellen JavaScript-Funktionen, die man für a35 braucht. Eingriffe sind nicht nötig:
  • cReqObj() : Ein "request object" anlegen (für die Ajax-Technik)
  • reqLoad(i) : Aus einem Hyperlink den Satz mit der internen Nr. i laden, startet dann a35get.job
  • reqRes(S) : Eine Suchanfrage S ausführen lassen (z.B. S="PER shakesp? and tit drama") startet a35erg.job
  • reqInd(R) : Einen Registerabschnitt anzeigen lassen (z.B. R="per shakesp"), startet a35ind.job
  • reqForm() : Aus einem Formular einen Job starten (s. a35-pc.php : <form id=... ) , startet  prsave.job
    (entnimmt alle V- und D-Variablen des Formulars und liefert sie an den Job)

und in db/scripts liegen ferner
jquery-min.js  notwendige interne JavaScript-Funktionen aus dem bekannten jquery-Paket
a35css.php  enthält die CSS-Formatanweisungen

Über die Kombination ajax4.php + ajax4ini.php  "redet"  a35.js  im Browser mit der Datenbank:

  • ajax4.php ist ein universelles (für alle Datenbanken gültiges) Skript, das nicht selber etwas ausgibt.
  • ajax4.php wird nur aus  a35.js  aufgerufen.
  • Es startet jeweils via  avanti+acon  einen Job, z.B. a35get.job, dessen Name ihm mit  ?JOB=   übergeben wird, und
  • reicht die Variablen   Vuxy und Dname  an diesen Job weiter. Sie kommen im Job an als  #uxy bzw. $name .
  • Was der Job mit write- und export-Befehlen ausgibt, empfängt  ajax4.php  und sendet es weiter an den Browser,
    d.h. nur der Job produziert den gesamten Output, nicht ajax4.php selber
  • In  ajax4.php  selbst braucht man nicht einzugreifen.  Nur in ajax4ini.php  (s.o.) sind einige Angaben zur Datenbank nötig (z.T. dieselben wie bei PHPAC in av_ini.php).

Die Jobdateien können in einem Unterordner des HTML-Ordners der Datenbank liegen. Dessen Name muß ebenfalls in ajax4ini.php   stehen, z.B.
$Jobdir="abcjobs/"; sonst werden die Jobdateien direkt im HTML-Ordner gesucht. Nachteil: dort wären sie von außen sichtbar. Um sie gegen direkten Lesezugriff zu sichern, richtet man im $Jobdir-Ordner eine  .htaccess ein mit entspr. Inhalt, ebenso im db/scripts-Ordner.
Wenn eine Jobdatei nicht im  $Jobdir  gefunden wird, dann wird sie in  db/scripts/jobs  gesucht, wo die universellen Jobs liegen.


Parameterdateien (evtl. spezifisch für die Datenbank und deren CFG)

Diese Dateien enthalten ihre eigenen Kommentare.

Ort: im Datenordner , z.B. c:\allegro\demo2 bzw. /var/db/demo2, oder wo das Programm  acon  liegt, z.B. in c:\allegro bzw. /var/allegro)

d-html.apr oder d-khtm.apr + d-k.apt : Anzeigeparameter, es können auch andere sein. Verwendet in a35get.job

a35erg.apr : Parameter für die Ergebnis-Kurzliste  (datenbankspezifisch)
 
fts.@pr : Parameter für die Ergebnis-Kurzliste der Volltextsuche (universell)

cat.api : Index-Parameter (und dazu  i.apt, o.apt, ucodes.apt, swl1.apt )

e-unihtm.apr, e-unicod.apr, utf.apr: Umcodierungsparameter

ad-utf.apt, d-html.apt, ucodes.apt
: Umcodier- und Hilfstabellen

Wenn man nicht mit dem Standardschema a.cfg arbeitet, braucht man eigene Anzeige- und Indexparameter. Letztere wird man schon haben, daran wäre nichts zu ändern, die Anzeigeparameter jedoch muß man eigens erarbeiten. Man kann sie schrittweise mit einfachen Anfängen entwickeln. Die .apt-Dateien kann man nur verwenden, wenn man in der eigenen Datenbank mit dem OstWest-Code arbeitet (angepaßter ASCII-Code). Arbeitet man in der Datenbank mit dem Windows-ANSI-Code oder mit UTF-8, muß man entsprechend andere Tabellendateien verwenden, z.B. aw-utf.apt  statt ad-utf.apt. Das erfordert Kenntnisse der Export-Parametrierung (Kap. 10 des Systemhandbuchs).

Berechtigungen für Schreibzugriffe

Eine Startseite namens ha35.htm, abzurufen auch mit dem Fragezeichen-Symbol oben rechts, enthält einen Link Login, mit dem die Datei a35login.htm abgerufen wird. Diese zeigt 4 Buttons: [Identifizieren], [Registrieren], [Passwort ändern] und [Logout]. Jeder startet das Skript a35id.job, in dem sämtliche Funktionen ausgeführt werden. Wichtig sind dann folgende Punkte:

  • Voraussetzungen:
    1. Der User, der avanti gestartet hat, besitzt Schreibrecht im Datenordner
    2. für die in ajax4ini.php mit $ID= angegebene Kennung besteht in  avanti.con  eine Berechtigung >0.
  • Am Datenordner im DataDir hängt ein Unterordner  users
  • Darin legt der Admin für jeden User xyz (frei wählbarer Name ohne Leerzeichen) eine Datei xyz an, in der zunächst nur *** steht. 
  • Den Namen xyz teilt der Admin demjenigen User mit, der im System so heißen soll
  • Der Nutzer xyz kann sich dann sofort registrieren: Im Info-Feld auf „Login“ klicken, dann auf den Button [Registrieren]. Danach wird *** ersetzt durch das eingegebene, aber codierte Passwort.
  • Schon kann sich der Nutzer jederzeit mit dem Namen xyz und dem selbstgewählten Passwort identifizieren und erhält bis zum Sitzungsende Schreibrecht. Die "Sitzung" endet mit dem Verlassen der a35-Seite oder dem Ende des Tages oder der Funktion „Logout“, je nachdem, was zuerst kommt.
  • Soll ein registrierter User Admin-Rechte haben, ist zu seiner Passwortdatei eine Zeile zu ergänzen, in der nur "admin" steht. Er kann damit per Browser neue User zulassen:  Ein Admin startet mit Eingabe von  h a35admin.htm  (in das rote Eingabefeld) ein Menü, auf dem ein Button [New User] ist. Die neue Userdatei im Ordner users wird dabei von a35nwu.job angelegt.

Besteht Schreibberechtigung, setzt a35get.job über die Datenanzeige im INT-Feld drei Links: "Edit - Copy - Delete". Diese starten presto.job bzw. a35del.job. Der presto.job erzeugt ein Bearbeitungsformular im Feld INF . Das Formular hat nur ein einziges Eingabefeld, in dem der ganze Satz mit allen Feldern steht - wie beim alten Programm PRESTO. Darüber ein Button [Speichern], und das besorgt das Skript prsave.job. Analog zu presto.job kann es andere Skripte geben, um selbstgestaltete Formulare einzurichten, wobei alle Möglichkeiten von HTML5 ausnutzbar sind. Als Muster wird form1.job mitgeliefert, darin Kommentare zur Methodik.  
Viel bequemer ist das Verfahren mit einer FreeForm-Datei, als Beispiel wird buch.frf im a35-Paket mitgeliefert. Solche Dateien müssen bei der Datenbank im DataDir liegen. Sie werden vom Job  freeform.job  zu einem HTML-Formular umgewandelt und mit den gewünschten Inhalten eines Satzes gefüllt.


Grafikdateien

Mitgeliefert und standardmäßig benötigt werden nur wenige  Icons, z.B. close.png, finbut.png, up.ico, down.ico.
Sie liegen in a35Dir/img

Nur optional: gbs.png, wcat.png. Diese kann man in die Anzeige von Datensätzen einbauen, wie es in a35get.job zu sehen ist, um eine Verlinkung zur Google Buchsuche bzw. zum WorldCat bereitzustellen. Ansonsten können in allen .php-Bereichen beliebige Grafikelemente zum Einsatz kommen, nicht nur in den head-Dateien.



b-eversberg@gmx.de / 2018-08-12