Als erste Einführung siehe: Wie arbeitet a35?

a35 : Plattformunabhängige Browser-Oberfläche für allegro-Datenbanken
Konzept und Installation
2020-04-15


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. Nur FLEX ist allegro-spezifisch, weil notwendig für die Zugriffe auf die Datenbank.
 
a35 schafft eine Web-Oberfläche für das Arbeiten mit einer Katalogdatenbank, nicht nur für das Suchen darin. Auch als Web-OPAC kann es  dienen, obwohl ein zeitgemäßes OPAC-System für Endnutzer nach heutigem Verständnis mehr erfordert, als die Indextechnik von allegro leisten kann. Wahlweise ist dafür VuFind oder "beluga" verwendbar oder vergleichbare Discovery Systeme. Diese können Daten von allegro per MARC-Export erhalten. Solche Systeme kosten allerdings serverseitig deutlich mehr KnowHow, Performance und personellen Aufwand. Es sind reine Suchsysteme, sie zeigen nicht den tagesaktuellen Stand der Daten. Dafür und für die ständige Arbeit an den Daten ist a99, auch unter Windows-10, noch nicht ersetzbar.

Zu den Grundsätzen der frei modifizierbaren Oberfläche von a35 siehe Abschnitt Design-Konzept.
Eine englischsprachige Einführung in die wichtigsten Komponenten bietet  acon and FLEX.
 

Drei ganz verschiedene Beispiele:

    Standard-DemoBank, Oberfläche für PC  http://www.allegro-b.de/db/demo/ ,
       für Smartphone: http://www.allegro-b.de/db/demo/a35-app.php
    Ephemera-Katalog (Oxford):  https://allegro.bodleian.ox.ac.uk/johnson/
    Datenbank für polnische Sprache:  http://www.allegro-b.de/db/pol/


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. Diese zwei Komponenten können auf zwei verschiedenen Plattformen liegen oder auf derselben.

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 zwei Ordner mit Unterordnern, in jedem davon erklärt eine Datei README, wozu die Dateien gut sind und wo man modifizieren kann:

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: z.B.  c:\allegro
                                 Hier liegen die a35-Programme: avanti und acon; die Dateien avanti.con und uifsger. - Plus 2 Ordner Demo-Datenbanken.  

2. www      : HTML- und Skript-Ordner (.php, .js, .css, .htm und .job) zur Installation auf dem Webserver, also evtl. einem anderen System.
                                 Der Inhalt: Ein Ordner
  db, er gehört z.B. für XAMPP (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.

Für Windows sind die Programme acon.exe  und avanti.exe mit im Installations-"Gesamtpaket" (inst-all.exe).
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, avanti.con etc.

DataDir z.B. = ProgDir/db    oder  sonstwo/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  muss für die Programme im ProgDir zugänglich sein, besonders für acon .

avanti

<-- TCP/IP -->

z.B. Port 4949
s.u..










HTML- und Script-Ordner  auf 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
 ajax4.php : universell f. alle Datenbanken, erledigt die Kommunikation zwischen  
   Datensystem und Web-System), und
   scripts/a35.js   enthält alle JavaScript-Funktionen für a35.

a35Dir/demo    Skripte für Demo-Datenbank
a35Dir/demo/demojobs    Jobs speziell für Demo-Datenbank
  Hier legt man Ordner für eigene Datenbanken an, z.B.
a35Dir/opac    Skripte für Katalog-Datenbank, hier Einstellungen in
  a35ini.php  : für a35-pc.php
  ajax4ini.php : für jax4.php
a35Dir/opac/katjobs :  Jobs speziell für  katalog-Datenbank,
Der Name $Jobdir="katjobs" muss in ajax4ini.php stehen

a35Dir/scripts    Universelle Skripte, vor allem  a35.js
a35Dir/scripts/jobs    JobSkripte, die für alle Datenbanken funktionieren

Die Demo-Datenbank wird nicht notwendig 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 jeweils in den entsprechenden Ordnern für weitere Datenbanken   

In rot ist unten zu sehen, welche Angaben in diesen Dateien übereinstimmen müssen. In grün, welche für die jeweilige Datenbank sonst noch angepasst 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 und acon für alle zu bedienenden Datenbanken brauchen.
Wenn man avanti.con ändert, dann avanti neu starten.  Die Datei enthält ihre eigene Dokumentation!

 [general]
port = 4949 # über diesen Port kommuniziert avanti mit dem Webserver, s.u.
prefork = 1
AnonymousAccess = yes
max_cputime = 120
# Folgende 2 Zeilen aktivieren, wenn man eine LOGdatei will: [in avanti.con steht 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 Demo-Datenbank] Diesen für eigene Datenbank kopieren und dann anpassen
 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 a35dir/demo und in den entsprechenden für andere Datenbanken
(Nu
r ajax4.php braucht diese Datei)

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 parallele Kopie von  a35dir/demo und ändert darin dann die ajax4ini.php.

Folgende Einstellungen sind in  ajax4ini.php   wichtig:

$UTF=1; // Datenbank ist intern ASCII, Ausgabe soll UTF-8 sein. Nur 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 muss auf den Servern geöffnet sein

// Wo liegen die Programme? 
Auf demselben Server, wo die Datenbank liegt!, Das ist nicht unbedingt auf dem Webserver. Beipiele:
$ProgDir="c:\allegro";  unter Linux z.B. $ProgDir="/var/allegro"; 
Daraus kann  acon  entnehmen, wo Parameterdateien etc. liegen, wenn sie nicht im  DataDir  zu finden sind.

// 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? (im Ordner der jeweiligen Datenbank, für  a35Dir/demo  ist es z.B.  .../demo/ajaxjobs ), so anzugeben:
$Jobdir="ajaxjobs/"; 

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

Notwendige Programme und Dateien im ProgDir (auf dem Datenserver, d.h. wo Datenbank und Programme liegen, z.B. c:\allegro)

avanti.exe   (LINUX:  avanti)  Serverprogramm
avanti.con   Liste der Datenbanken, die  avanti  kennen soll  (siehe oben). Eigene muss man hier eintragen.
acon.exe     (LINUX:  acon)  Programm zur Ausführung von Job-Dateien (Typ .job)  
al.job       Admin-Job + Hilfetext al-help.txt  (Hilfsfunktionen; Start in Linux-Konsole:  ./acon -jal)
uifsger      Texte für die Meldungen der Programme avanti und acon

Im DataDir (z.B. c:\allegro\db\demo2  bzw.  /var/db/demo2 ) ODER ebenfalls im ProgDir liegen:
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, ferner d-k.apt, d-htm.apt u.a. eigene

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 muss nicht identisch sein mit dem Namen des Datenordners DataDir, 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, dass 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/demo  etc. für jede Datenbank separat im jeweils eigenen Verzeichnis genau wie ajax4ini.php.
a35ini.php  ist mit  include  eingebunden in die drei Startdateien  a35-pc.php, a35-tab.php, a35-app.php.
ajax4ini.php  wird eingelesen von ajax4.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 Textversion 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; beliebig zu modifizieren!
// nur jeweils eine davon  in a35-pc.php etc. aktivieren, darin steht : 

// $headpc= 'a35-head-pc1.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 drei unterschiedliche Endgeräte anpassbar ist: PC, Tablet, Smartphone ("App"):

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

Die FLEX-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
Die Elemente FRE und FRR kommen nur bei Bedarf zum Vorschein. Ihr Inhalt ist frei gestaltbar - oft ist es ein kleines Menü oder Formular.

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. 

Das Menü oben in der Mitte steckt aber in  a35-pc-menu.php . Seine Struktur und Funktionsweise ist leicht zu durchschauen und zu modifizieren. Neue, eigene FLEX-Jobs kann man am leichtesten hier einbauen. Oder vorhandene, die man nicht braucht, rausnehmen.

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 Browser-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 ja mindestens drei: Eingabe von Suchbegriffen -> Ergebnisliste -> Einzeltitel.
a35 zeigt dagegen keine Abfolge, sondern 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 Formulare, Hilfetexte, Weitere Menüs und beliebige andere Inhalte (Feld INF), die gerade gebraucht werden. 

In den einzelnen Quadranten (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 (der tut's nämlich nicht) 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 dennoch, 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.
Interessant für Web-Programmierer:
Im Prinzip kann man sich eigene Oberflächen beliebig konstruieren, in denen man die Labels für die Bereiche auf dieselbe Art einbaut wie in a35-pc-cont.php
Zwei solche Varianten der Startdatei a35-pc.php sind verfügbar, zu besichtigen bei der Demo-Bank:

a35-tab.php Version für Tablets  (eingebunden wird  a35-tab-cont.php)
a35-app.php
:  Version für mobile Endgeräte (Smartphones) (hierin sind die Labels bereits mit enthalten).

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 muss 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, dass 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, dass 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 mit srch(.exe), Ergebnismenge anzeigen wie bei normaler Suche
a35srch.job  Volltextsuche per FLEX ausführen, Ergebnismenge anzeigen in externem Fenster (kopierbar)
      (hierzu gibt es eine Variante  srch.job, die man mit acon in einem Kommandofenster ausführen kann)
a35org.job 
Index erneuern etc. ,wie a99 (Eingeben im roten Rahmen: h a35org )
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..
Wer FLEX kann, hat hier freie Hand.

a35.js  liegt in db/scripts  (darin braucht man nichts zu ändern)
  • 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)
  • reqLink(i) : Aus einem Link (z.B. in der Ergebnisliste) 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, der den Datensatz speichert)

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, und zwar so:

  • 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 a35Dir/-Ordners der Datenbank liegen. Dessen Name muss 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: jeweils .xpr / .xpi, wenn man x.cfg statt a.cfg hat)
 
fts.@pr : Parameter für die Ergebnis-Kurzliste der Volltextsuche mit a35fts.job (universell)
Ohne a35 auf der Konsole gibt es eine Variante  srch.job, die man  mit  acon  starten kann, z.B. so:
            acon -jsrch -ddemo2\cat*.ald [-ee-1[=exportdatei]] -rsuchbegriff 

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 muss 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 (angepasster ASCII-Code). Arbeitet man in der Datenbank mit dem Windows-ANSI-Code oder mit UTF-8, muss man entsprechend in den Exportparametern 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

Mit dem Login-Button oben rechts oder vom Menü "Sitzung/Login" wird die Datei a35login.htm abgerufen. Dieses 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 Datenbank-Kennung, z.B. demo, besteht in  avanti.con  eine Berechtigung >0.
  • Am Datenordner im DataDir hängt ein Unterordner  users  (Beispiel in  demo2
  • 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 / 2020-04-15