Mercurial > hg > digilib-old
diff client/doc/dokumentation_digilib.txt @ 21:a6ddb285964d vendor
First import of client module
author | robcast |
---|---|
date | Thu, 17 Jan 2002 15:29:55 +0100 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/client/doc/dokumentation_digilib.txt Thu Jan 17 15:29:55 2002 +0100 @@ -0,0 +1,288 @@ +DIGITAL DOCUMENT LIBRARY +------------------------ + +Stand : 21. Januar 2001 + + +Leitung : Gerd Grasshoff (gerd.grasshoff@philo.unibe.ch) + +Autor : Christian Luginbühl (luginbuehl@student.unibe.ch) + + + +Inhalt +------ + +1. Einführung + +2. digilib3.jsp + +3. navigation3XXX.js + +4. ScaleServlet.java + + + +1. Einführung +------------- + +Das Projekt Digital Document Library hat zum Ziel, "Dokumente" mit Hilfe eines +Browsers anschauen zu können. Diese Dokumente sind hochaufgelöste Bilddateien, +die auf einem Server gespeichert sind. Um der Benutzerin, dem Benutzer die +Möglichkeit einer raschen Konsultation der Daten liefern zu können, müssen diese +Bilddaten auf eine vernünftige Grösse verkleinert und in dieser Form dann an die +Anfragenden geschickt werden. Weiten sollen den Benutzenden Hilfsmittel zur +Verfügung stehen um in diesen Seiten zu navigieren. Diese Hilfsmittel bestehen +aus Funktionen um zwischen verschieden Seiten hin und her zu wechseln, +Ausschnitte aus einem Bild zu zoomen und der Möglichkeit Markierungen zu setzen. +Ein weiteres wichtiges Feature dieses Programms ist es, Referenzen ganz +bestimmter Seiten (inkl. Ausschnitte und Markierungen) auszugeben, die dann in +beliebigen anderen Dokumenten eingebaut werden können. Sofern die Lesenden +dieser Dokumente dann über einen Anschluss ins Internet verfügen, können diese +Referenzen direkt angeschaut werden und so die Digital Document Library als +grosse Quelltextsammlung gebraucht werden. + +Das Programm nun ist ein Client/Server-Modell. Einerseits haben wir das User +-Interface (also den Client), wo die Darstellung und die Navigation aufgebaut +und berechnet werden. Dieser Teil des Programms umfasst im Prinzip zwei Dateien. +Mit der Frage des Layouts beschäftigt sich digilib3.jsp. Es ist die Datei, die +im Browser aufgerufen wird (mit den verschiedenen Parametern, die in Kapitel 2 +erläutert werden) und die nötigen Aufrufe macht für die Skalierung der Bilddaten +und der entsprechenden Navigationselemente. Die zweite Datei des Clients ist +eine dynamisch ausgerufene JavaScript-Datei namens navigation3XXX.js, wobei die +XXX für die verschidenen Borwservarianten stehen. Da die Scriptsprache +JavaScript in den verschiedenen Browsern nicht ganz gleich implementiert ist, +ist es nötig diese Datei an die verschidenen Umgebungen anzupassen. Das Laden +dieser Dateien übernimmt digilib3.jsp, indem es erst abfragt, welchen Browser +von Client gebraucht wird und dann die entsprechende navigation-Datei vom Server +verlangt. Auf der Serverseite ist ein Programm namens ScaleServlet sehr wichtig. +Dieses Servlet handelt die Anfragen der Clients und macht die verschiedenen +Skalierungen an dem Bildern und schickt, dann den entsprechenden Ausschnitt an +den Client. + +In den nächsten Kapitel sind die einzelnen Files mit ihren verschidenen +Parametern der Aufrufe erläutert. + + +2. digilib3.jsp +--------------- + +Bei einem Request von digilib3.jsp werden auf der Serverseite die verschiedenen +Parameter des Aufrufs in die zurückgesendete Datei eingefüllt und dann vor allem +für den von 'digilib' ausgehenden Aufruf des ScaleServlets verwendet. Die +verschiedenen Parameter beim Request sind durch Pluszeichen voneinander +getrennt. Beispiel: + +http://pene ... /digilib3.jsp?histast/eastwood-collection/AF+3+s1.2+r:3852+12/30 + ------------------------------ - ---- ------ ----- + Parameter 1 2 3 4 5 + +Die verschiedenen Parameter werden in digilib3.jsp in ein Array mit 11 Elementen +(1 - 11) aufgenommen. Folgend ist nun eine Auflistung aller Parameter und ihrer +Bedeutung. Es ist absolut zwingend, dass diese in der richtigen Reihenfolge +aufgerufen werden. + +- att[1] = '<%= docuurl %>' + +Dieser Parameter gibt den Pfad ohne Hostnamen zum Verzeichnis mit dem +gewünschten Werk an. Wichtig zu verstehen ist, dass hier nicht ein bestimmtes +Bild angesprochen wird, sondern nur ein Verzeichnis. + +- att[2] = '<%= startPage %>' + +Dies ist die Nummer des Bildes im von Parameter 1 gewählten Verzeichnis. Falls +dieser Parameter leer ist, wird er automatisch auf '1' gesetzt. + +- att[3] = '<%= scalefact %>' + +Scalefact gibt den Vergrösserungsfaktor der Bildes an, im Vergleich zur in +ScaleServlet angegebenen Standardgrösse. Die Syntax diese Parameters ist 'sx.x', +wobei x.x für die Werte 0.6, 0.8, 1.0, 1.2, 1.4, 1.6, 2.0, 2.5 oder 3.0 stehen +kann. Standardwert ist 's1.0'. + +(Anm: Serverseitig wird an diesem Teil noch gearbeitet, damit die Standardgrösse +auf verschidenen Bildschirmen auch verschieden gross ist) + +- att[4] = '<%= commandostring %>' + +Gebraucht wird dieser Parameter dafür, dass die Bilder nicht aus dem +Browsercache genommen werden, sondern auf dem Server dann neu berechnet werden. +Bei einem "Zoom Out" wird hier eine Zufallszahl generiert. Die Syntax ist +'r:xxxx', wobei x irgend eine höchstens vierstellige Zahl. Standardwert ist r:1. + +- att[5] = '<%= remarkcoord %>' + +In diesem Parameter werden die Koordinaten der Markierungspunkte festgehalten. +Syntax ist 'xxx/yyy;zzz/ttt; ... aaa/bbb'. Die Koordinatenpaare um "/" geben an, +wo eine Markierung gesetzt werden soll, wobei Werte von 0 bis zur aktuellen +Bildgrösse erlaubt sind. Durch ";" werden die einzelnen Markierungen getrennt +(maximal 5 sind möglich). Standardwerte sind hier '' (leer) oder '0/0' (keine +Markierung wird gesetzt). + +- att[6] = '<%= windowwidth %>' / att[7] = '<%= windowheight %>' + +Windowwidth gibt an, wie breit/hoch das Bild auf dem Bildschirm ist. Standard +ist '' (leer). + +- att[8] = '<%= xoffset %>' / att[9] = '<%= yoffset %>' + +Diese Attribute haben zwei Bedeutungen. Falls att[10] und att[11] leer sind, +gibt xoffset bzw. yoffset an, um welchen Punkt im Bild gezoomt werden soll. +Falls att[10], att[11] nicht leer sind, geben sie die Koordinaten der linke +oberen Ecke des zu vergrössernden Bildausschnitts an. Standard ist hier '' +(leer). + +- att[10] = '<%= width %>' / att[11] = '<%= height %>' + +Falls diese Attribute verschieden von '' (leer) sind, geben sie die Breite/Höhe +des Bildaussschnittes an, der gezoom werden soll. + + +Die weiteren Funktionen von digilib3.jsp sind: + +- Laden des navigation3XXX.js-Files für den entsprechenden Browser. +- Erstellen eines Framesets (kleiner Frame mit den Navigationsbuttons und + Frame mit dem Bild). +- Erstellen der Navigationsbuttons. +- Zusammenstellen der korrekten Parameterliste für den Aufruf von ScaleServlet. +- Erstellen der verschiedenen Layers mit dem Bild (Aufruf), den Markierungen und + den Zeichen für die Eckpunkte beim Vergrössern. +- Aufruf an navigation3XXX.js für Intialbefehle wie Setzen der Markierungspunkte. + + +3. navigation3XXX.js +-------------------- + +Navigation3XXX.js ist eine Sammlung von Funktionen zur Navigation in der Digital +Document Library. Die verschidenen Funktionen werden zum Beispiel durch klicken +auf einen in digilib3.jsp erstellten Navigationsknopf aufgerufen. Um +verschiedene Browser zu unterstützen (die Implementierung von Javascript und das +Document Object Model sind unterschiedlich), gibt es angepasste navigation3 +-files, die von digilib3.jsp entsprechend des verwendeten Browsers geladen +werden. Momentan sind Versionen für Netscape Communicator 4.xx (navigation3.js) +und Netscape 6 (navigation3_n6.js) verfügbar. Bei der Programmierung des Clients +wurde darauf geschaut, dass digilib3.jsp für möglichst alle Browser das selbe +ist und somit nur navigation3XXX.js angepasst werden muss. Voraussetzung hierzu +ist, dass ein Brwoser mit Layern (<div>-Tags) umgehen kann. Nachstehend ist ganz +kurz erläutert, welche Funktionen in navigation3XXX.js welche Aufgaben erfüllen: + +- genString(detail) + +Anhand von 'detail' generiert diese Funktion die Parameterliste für einen Aufruf +eines neuen Bildes, eines Ausschnittes oder des Strings für eine +Referenzabfrage. 'detail' wird gebraucht, um die Anzahl der nötigen Parameter +für das Ausführen der aufrufenden Funktion zu bestimmen. Diese Funktion wird +immer indirekt, d.h. in anderen Funktionen von navigation3XXX.js aufgrufen und +liefert eine Stringrückgabe. + +- Backpage(), Nextpage(), Page() + +Diese Funktionen handeln die Navigation durch die Seiten eines Verzeichnisses. +Diese Funktionen werden mit einem Klick auf die Navigationsbuttons aufgerufen +und Laden eine neue Seite. + +- Ref(refselect) + +Hier wird ein PopUp-Fenster erzeugt, das die komplette URL der momentanen Seite +zurückgibt. Mit 'refselect' wird bestimmt, ob die Formatierung der Ausgabe in +HTML- oder LaTeX-Form sein soll. Diese Funktion wird mit dem "Ref"-Button +aufgerufen. + +- Mark() + +Diese Funktion plaziert eine Markierung auf dem Bild, wobei sie zuerst nur die +Maus-koordinaten bei einem Klick auf das Bild abfängt und dann die Funktion +'setmark()' aufruft. Es können bis zu fünf Markierungen auf ein Bild gesetzt +werden. Auch diese Funktion wird direkt über die Navbuttons aufgerufen. + +- Zoomrect(), Zoomin(), Zoomout() + +Direkt aufgerufene Funktionen die sich mit dem Zoomen innerhalb eines Bildes +beschäftigen. Die Rückgabe ist bei allen drei Funktionen ein Aufruf eines neuen +Bildes. + +- Moveto() + +Diese Funktion verändert das Zentrum bei einem schon gezoomten Bild. Die +geklickten Koordinaten entsprechen dann dem Zenrum des neuen Bildes bei gleicher +Vergrösserung. Dieses Feature wird in Zeichnungsprogrammen oft mit 'Pan' +betitelt. Direkter Aufruf und Aufruf des neuen Bildes sind gleich wie bei den +Zoom-Funktionen. + +- Scaledef(scaledef) + +Mit Scaledef wird die Bildgrösse im Vegleich zur in ScaleServlet.java +angegebenen Standardgrösse verändert. Der Parameter 'scaledef' gibt diesen +Faktor an. Eine Liste der möglichen Werte ist weiter oben angegeben. Auch hier +wird di Funktion direkt über die Auswahlliste im Navigationsframe aufgerufen und +auch hier wird ein neues Bild geladen. + +- setmark() + +Setmark wird indirekt von Mark() oder initScripts() aufgerufen und zeichnet sich +für die Positionierung der Markierungen verantwortlich. Die Funktion extrahiert +aus att[5] die einzelnen Koordinaten und setzt die Punkte. Wenn eine bestimmte +Reihenfolge bei den Punkten eingehalten werden soll, dann müssen sie auch immer +gleich in der Parameterliste aufgerufen werden. Die Funktion setmark gibt nichts +zurück. + +- parseKeypress() + +Diese Funktion dient dem Abfangen von Tastatureingaben, wobei die Tasten "n" für +nächste Seite und "b" für vordere Seite abgefragt werden. parseKeypress wird von +initScripts aufgerufen und hat keinen Rückgabewert. + +- initScripts() + +In dieser Funktion werden Vorkehrungen getroffen, die beim Anzeigen einer neuen +Seite getroffen werden müssen. Deshalb wird diese Funktion automatisch beim +Laden von digilib3.jsp aufgerufen. Insbesondere ruft diese Funktion +parseKeypress und setmark auf, wobei bei verschiedenen Browsertypen auch noch +andere Sachen hinzukommen (bei Netscape 6 wird zum Beispiel auch die +Clientgrösse berechnet und geschaut ob Scrollbalken gemacht werden müssen). + + +4. ScaleServlet.java +-------------------- + +Der Aufruf von ScaleServlet.java erfolgt grundsätzlich von digilib3.jsp und die +Parameterliste hat auch die selben Attribute (ausgenommen ist att[5] mit den +Koordinaten der Markierungspunkte. Bei Fragen über die einzelnen Bedeutungen der +Attribute sie hier also auf Kapitel 2 verwiesen. An dieser Stelle sei aber noch +etwas gesagt, über die Zusammensetzung der Parameterliste. ScaleServlet.java +kennt drei verschiden lange Parameterlisten, mit denen es arbeiten kann, wobei +die korrekte Zusammenstellung der Parameterliste in digilib3.jsp erfolgt. + +- Kurz (att[1] - att[4]) + +Diese vier Parameter geben dem ScaleServlet die Aufgabe, ein Bild (bestimmt mit +att[1] und att[2]) auf die Standardgrösse zu skalieren und an den Client zu +senden. Att[3] gibt zusätzlich den Skalierungsfaktor an und att[4] verhindert +mit einer Zufallszahl, dass das Bild aus dem Browsercache geholt wird. + +- Mittel (att[1] - att[4] + att[6] - att[9]) + +Diese Möglichkeit des Aufrufs wird gebraucht, um bezüglich des in att[8] und +att[9] bestimmten Mittelpunktes einen Ausschnitt zu vergrossen. Um den genannten +Punkt einzuordnen, wird die grösse des momentan angezeigten Bildes mit den +Parametern 6 und 7 mitgegeben. + +- Lang (att[1] - att[4] + att[6]- att[11]) + +Ein Aufruf in dieser Form gibt dem Servlet an, einen Ausschnitt aus einem Bild +zu vergrössern und zurückzusenden. Folgt ein Aufruf in dieser Form, bekommen die +Parameter att[8] und att[9] die Werte der linken oberen Ecke und att[10]/[11] +die Breite/Höhe des Ausschnitts. + + +Aufgrund eines eingebauten Session-Managements im Servlet ist es möglich mit +digilib auch mehrfach in ein Bild hinein zu zoomen. + +(Anm: Auch wenn dieses Session-Management seinen Zweck beim Anschauen der Bilder +sehr gut erfüllt, ist es dem ScaleServlet nicht möglich den Referenz-URLs +anzusehen, ob zuerst mehrfach hineingezoomt wurde und gibt unter Umständen +- eben wenn mehrfach hieingezoomt wurde vor der Generierung der Referenz - einen +falschen Ausschnitt zurück.) + + +---------------------------------------------- \ No newline at end of file