Mercurial > hg > digilib-old

comparison client/doc/dokumentation_digilib.txt @ 20:d407cb901df4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial revision
author robcast
date Thu, 17 Jan 2002 15:29:55 +0100
parents
children
comparison
equal deleted inserted replaced
1:0ff3ede32060 20:d407cb901df4
1 DIGITAL DOCUMENT LIBRARY
2 ------------------------
3
4 Stand : 21. Januar 2001
5
6
7 Leitung : Gerd Grasshoff (gerd.grasshoff@philo.unibe.ch)
8
9 Autor : Christian Luginbühl (luginbuehl@student.unibe.ch)
10
11
12
13 Inhalt
14 ------
15
16 1. Einführung
17
18 2. digilib3.jsp
19
20 3. navigation3XXX.js
21
22 4. ScaleServlet.java
23
24
25
26 1. Einführung
27 -------------
28
29 Das Projekt Digital Document Library hat zum Ziel, "Dokumente" mit Hilfe eines
30 Browsers anschauen zu können. Diese Dokumente sind hochaufgelöste Bilddateien,
31 die auf einem Server gespeichert sind. Um der Benutzerin, dem Benutzer die
32 Möglichkeit einer raschen Konsultation der Daten liefern zu können, müssen diese
33 Bilddaten auf eine vernünftige Grösse verkleinert und in dieser Form dann an die
34 Anfragenden geschickt werden. Weiten sollen den Benutzenden Hilfsmittel zur
35 Verfügung stehen um in diesen Seiten zu navigieren. Diese Hilfsmittel bestehen
36 aus Funktionen um zwischen verschieden Seiten hin und her zu wechseln,
37 Ausschnitte aus einem Bild zu zoomen und der Möglichkeit Markierungen zu setzen.
38 Ein weiteres wichtiges Feature dieses Programms ist es, Referenzen ganz
39 bestimmter Seiten (inkl. Ausschnitte und Markierungen) auszugeben, die dann in
40 beliebigen anderen Dokumenten eingebaut werden können. Sofern die Lesenden
41 dieser Dokumente dann über einen Anschluss ins Internet verfügen, können diese
42 Referenzen direkt angeschaut werden und so die Digital Document Library als
43 grosse Quelltextsammlung gebraucht werden.
44
45 Das Programm nun ist ein Client/Server-Modell. Einerseits haben wir das User
46 -Interface (also den Client), wo die Darstellung und die Navigation aufgebaut
47 und berechnet werden. Dieser Teil des Programms umfasst im Prinzip zwei Dateien.
48 Mit der Frage des Layouts beschäftigt sich digilib3.jsp. Es ist die Datei, die
49 im Browser aufgerufen wird (mit den verschiedenen Parametern, die in Kapitel 2
50 erläutert werden) und die nötigen Aufrufe macht für die Skalierung der Bilddaten
51 und der entsprechenden Navigationselemente. Die zweite Datei des Clients ist
52 eine dynamisch ausgerufene JavaScript-Datei namens navigation3XXX.js, wobei die
53 XXX für die verschidenen Borwservarianten stehen. Da die Scriptsprache
54 JavaScript in den verschiedenen Browsern nicht ganz gleich implementiert ist,
55 ist es nötig diese Datei an die verschidenen Umgebungen anzupassen. Das Laden
56 dieser Dateien übernimmt digilib3.jsp, indem es erst abfragt, welchen Browser
57 von Client gebraucht wird und dann die entsprechende navigation-Datei vom Server
58 verlangt. Auf der Serverseite ist ein Programm namens ScaleServlet sehr wichtig.
59 Dieses Servlet handelt die Anfragen der Clients und macht die verschiedenen
60 Skalierungen an dem Bildern und schickt, dann den entsprechenden Ausschnitt an
61 den Client.
62
63 In den nächsten Kapitel sind die einzelnen Files mit ihren verschidenen
64 Parametern der Aufrufe erläutert.
65
66
67 2. digilib3.jsp
68 ---------------
69
70 Bei einem Request von digilib3.jsp werden auf der Serverseite die verschiedenen
71 Parameter des Aufrufs in die zurückgesendete Datei eingefüllt und dann vor allem
72 für den von 'digilib' ausgehenden Aufruf des ScaleServlets verwendet. Die
73 verschiedenen Parameter beim Request sind durch Pluszeichen voneinander
74 getrennt. Beispiel:
75
76 http://pene ... /digilib3.jsp?histast/eastwood-collection/AF+3+s1.2+r:3852+12/30
77 ------------------------------ - ---- ------ -----
78 Parameter 1 2 3 4 5
79
80 Die verschiedenen Parameter werden in digilib3.jsp in ein Array mit 11 Elementen
81 (1 - 11) aufgenommen. Folgend ist nun eine Auflistung aller Parameter und ihrer
82 Bedeutung. Es ist absolut zwingend, dass diese in der richtigen Reihenfolge
83 aufgerufen werden.
84
85 - att[1] = '<%= docuurl %>'
86
87 Dieser Parameter gibt den Pfad ohne Hostnamen zum Verzeichnis mit dem
88 gewünschten Werk an. Wichtig zu verstehen ist, dass hier nicht ein bestimmtes
89 Bild angesprochen wird, sondern nur ein Verzeichnis.
90
91 - att[2] = '<%= startPage %>'
92
93 Dies ist die Nummer des Bildes im von Parameter 1 gewählten Verzeichnis. Falls
94 dieser Parameter leer ist, wird er automatisch auf '1' gesetzt.
95
96 - att[3] = '<%= scalefact %>'
97
98 Scalefact gibt den Vergrösserungsfaktor der Bildes an, im Vergleich zur in
99 ScaleServlet angegebenen Standardgrösse. Die Syntax diese Parameters ist 'sx.x',
100 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
101 kann. Standardwert ist 's1.0'.
102
103 (Anm: Serverseitig wird an diesem Teil noch gearbeitet, damit die Standardgrösse
104 auf verschidenen Bildschirmen auch verschieden gross ist)
105
106 - att[4] = '<%= commandostring %>'
107
108 Gebraucht wird dieser Parameter dafür, dass die Bilder nicht aus dem
109 Browsercache genommen werden, sondern auf dem Server dann neu berechnet werden.
110 Bei einem "Zoom Out" wird hier eine Zufallszahl generiert. Die Syntax ist
111 'r:xxxx', wobei x irgend eine höchstens vierstellige Zahl. Standardwert ist r:1.
112
113 - att[5] = '<%= remarkcoord %>'
114
115 In diesem Parameter werden die Koordinaten der Markierungspunkte festgehalten.
116 Syntax ist 'xxx/yyy;zzz/ttt; ... aaa/bbb'. Die Koordinatenpaare um "/" geben an,
117 wo eine Markierung gesetzt werden soll, wobei Werte von 0 bis zur aktuellen
118 Bildgrösse erlaubt sind. Durch ";" werden die einzelnen Markierungen getrennt
119 (maximal 5 sind möglich). Standardwerte sind hier '' (leer) oder '0/0' (keine
120 Markierung wird gesetzt).
121
122 - att[6] = '<%= windowwidth %>' / att[7] = '<%= windowheight %>'
123
124 Windowwidth gibt an, wie breit/hoch das Bild auf dem Bildschirm ist. Standard
125 ist '' (leer).
126
127 - att[8] = '<%= xoffset %>' / att[9] = '<%= yoffset %>'
128
129 Diese Attribute haben zwei Bedeutungen. Falls att[10] und att[11] leer sind,
130 gibt xoffset bzw. yoffset an, um welchen Punkt im Bild gezoomt werden soll.
131 Falls att[10], att[11] nicht leer sind, geben sie die Koordinaten der linke
132 oberen Ecke des zu vergrössernden Bildausschnitts an. Standard ist hier ''
133 (leer).
134
135 - att[10] = '<%= width %>' / att[11] = '<%= height %>'
136
137 Falls diese Attribute verschieden von '' (leer) sind, geben sie die Breite/Höhe
138 des Bildaussschnittes an, der gezoom werden soll.
139
140
141 Die weiteren Funktionen von digilib3.jsp sind:
142
143 - Laden des navigation3XXX.js-Files für den entsprechenden Browser.
144 - Erstellen eines Framesets (kleiner Frame mit den Navigationsbuttons und
145 Frame mit dem Bild).
146 - Erstellen der Navigationsbuttons.
147 - Zusammenstellen der korrekten Parameterliste für den Aufruf von ScaleServlet.
148 - Erstellen der verschiedenen Layers mit dem Bild (Aufruf), den Markierungen und
149 den Zeichen für die Eckpunkte beim Vergrössern.
150 - Aufruf an navigation3XXX.js für Intialbefehle wie Setzen der Markierungspunkte.
151
152
153 3. navigation3XXX.js
154 --------------------
155
156 Navigation3XXX.js ist eine Sammlung von Funktionen zur Navigation in der Digital
157 Document Library. Die verschidenen Funktionen werden zum Beispiel durch klicken
158 auf einen in digilib3.jsp erstellten Navigationsknopf aufgerufen. Um
159 verschiedene Browser zu unterstützen (die Implementierung von Javascript und das
160 Document Object Model sind unterschiedlich), gibt es angepasste navigation3
161 -files, die von digilib3.jsp entsprechend des verwendeten Browsers geladen
162 werden. Momentan sind Versionen für Netscape Communicator 4.xx (navigation3.js)
163 und Netscape 6 (navigation3_n6.js) verfügbar. Bei der Programmierung des Clients
164 wurde darauf geschaut, dass digilib3.jsp für möglichst alle Browser das selbe
165 ist und somit nur navigation3XXX.js angepasst werden muss. Voraussetzung hierzu
166 ist, dass ein Brwoser mit Layern (<div>-Tags) umgehen kann. Nachstehend ist ganz
167 kurz erläutert, welche Funktionen in navigation3XXX.js welche Aufgaben erfüllen:
168
169 - genString(detail)
170
171 Anhand von 'detail' generiert diese Funktion die Parameterliste für einen Aufruf
172 eines neuen Bildes, eines Ausschnittes oder des Strings für eine
173 Referenzabfrage. 'detail' wird gebraucht, um die Anzahl der nötigen Parameter
174 für das Ausführen der aufrufenden Funktion zu bestimmen. Diese Funktion wird
175 immer indirekt, d.h. in anderen Funktionen von navigation3XXX.js aufgrufen und
176 liefert eine Stringrückgabe.
177
178 - Backpage(), Nextpage(), Page()
179
180 Diese Funktionen handeln die Navigation durch die Seiten eines Verzeichnisses.
181 Diese Funktionen werden mit einem Klick auf die Navigationsbuttons aufgerufen
182 und Laden eine neue Seite.
183
184 - Ref(refselect)
185
186 Hier wird ein PopUp-Fenster erzeugt, das die komplette URL der momentanen Seite
187 zurückgibt. Mit 'refselect' wird bestimmt, ob die Formatierung der Ausgabe in
188 HTML- oder LaTeX-Form sein soll. Diese Funktion wird mit dem "Ref"-Button
189 aufgerufen.
190
191 - Mark()
192
193 Diese Funktion plaziert eine Markierung auf dem Bild, wobei sie zuerst nur die
194 Maus-koordinaten bei einem Klick auf das Bild abfängt und dann die Funktion
195 'setmark()' aufruft. Es können bis zu fünf Markierungen auf ein Bild gesetzt
196 werden. Auch diese Funktion wird direkt über die Navbuttons aufgerufen.
197
198 - Zoomrect(), Zoomin(), Zoomout()
199
200 Direkt aufgerufene Funktionen die sich mit dem Zoomen innerhalb eines Bildes
201 beschäftigen. Die Rückgabe ist bei allen drei Funktionen ein Aufruf eines neuen
202 Bildes.
203
204 - Moveto()
205
206 Diese Funktion verändert das Zentrum bei einem schon gezoomten Bild. Die
207 geklickten Koordinaten entsprechen dann dem Zenrum des neuen Bildes bei gleicher
208 Vergrösserung. Dieses Feature wird in Zeichnungsprogrammen oft mit 'Pan'
209 betitelt. Direkter Aufruf und Aufruf des neuen Bildes sind gleich wie bei den
210 Zoom-Funktionen.
211
212 - Scaledef(scaledef)
213
214 Mit Scaledef wird die Bildgrösse im Vegleich zur in ScaleServlet.java
215 angegebenen Standardgrösse verändert. Der Parameter 'scaledef' gibt diesen
216 Faktor an. Eine Liste der möglichen Werte ist weiter oben angegeben. Auch hier
217 wird di Funktion direkt über die Auswahlliste im Navigationsframe aufgerufen und
218 auch hier wird ein neues Bild geladen.
219
220 - setmark()
221
222 Setmark wird indirekt von Mark() oder initScripts() aufgerufen und zeichnet sich
223 für die Positionierung der Markierungen verantwortlich. Die Funktion extrahiert
224 aus att[5] die einzelnen Koordinaten und setzt die Punkte. Wenn eine bestimmte
225 Reihenfolge bei den Punkten eingehalten werden soll, dann müssen sie auch immer
226 gleich in der Parameterliste aufgerufen werden. Die Funktion setmark gibt nichts
227 zurück.
228
229 - parseKeypress()
230
231 Diese Funktion dient dem Abfangen von Tastatureingaben, wobei die Tasten "n" für
232 nächste Seite und "b" für vordere Seite abgefragt werden. parseKeypress wird von
233 initScripts aufgerufen und hat keinen Rückgabewert.
234
235 - initScripts()
236
237 In dieser Funktion werden Vorkehrungen getroffen, die beim Anzeigen einer neuen
238 Seite getroffen werden müssen. Deshalb wird diese Funktion automatisch beim
239 Laden von digilib3.jsp aufgerufen. Insbesondere ruft diese Funktion
240 parseKeypress und setmark auf, wobei bei verschiedenen Browsertypen auch noch
241 andere Sachen hinzukommen (bei Netscape 6 wird zum Beispiel auch die
242 Clientgrösse berechnet und geschaut ob Scrollbalken gemacht werden müssen).
243
244
245 4. ScaleServlet.java
246 --------------------
247
248 Der Aufruf von ScaleServlet.java erfolgt grundsätzlich von digilib3.jsp und die
249 Parameterliste hat auch die selben Attribute (ausgenommen ist att[5] mit den
250 Koordinaten der Markierungspunkte. Bei Fragen über die einzelnen Bedeutungen der
251 Attribute sie hier also auf Kapitel 2 verwiesen. An dieser Stelle sei aber noch
252 etwas gesagt, über die Zusammensetzung der Parameterliste. ScaleServlet.java
253 kennt drei verschiden lange Parameterlisten, mit denen es arbeiten kann, wobei
254 die korrekte Zusammenstellung der Parameterliste in digilib3.jsp erfolgt.
255
256 - Kurz (att[1] - att[4])
257
258 Diese vier Parameter geben dem ScaleServlet die Aufgabe, ein Bild (bestimmt mit
259 att[1] und att[2]) auf die Standardgrösse zu skalieren und an den Client zu
260 senden. Att[3] gibt zusätzlich den Skalierungsfaktor an und att[4] verhindert
261 mit einer Zufallszahl, dass das Bild aus dem Browsercache geholt wird.
262
263 - Mittel (att[1] - att[4] + att[6] - att[9])
264
265 Diese Möglichkeit des Aufrufs wird gebraucht, um bezüglich des in att[8] und
266 att[9] bestimmten Mittelpunktes einen Ausschnitt zu vergrossen. Um den genannten
267 Punkt einzuordnen, wird die grösse des momentan angezeigten Bildes mit den
268 Parametern 6 und 7 mitgegeben.
269
270 - Lang (att[1] - att[4] + att[6]- att[11])
271
272 Ein Aufruf in dieser Form gibt dem Servlet an, einen Ausschnitt aus einem Bild
273 zu vergrössern und zurückzusenden. Folgt ein Aufruf in dieser Form, bekommen die
274 Parameter att[8] und att[9] die Werte der linken oberen Ecke und att[10]/[11]
275 die Breite/Höhe des Ausschnitts.
276
277
278 Aufgrund eines eingebauten Session-Managements im Servlet ist es möglich mit
279 digilib auch mehrfach in ein Bild hinein zu zoomen.
280
281 (Anm: Auch wenn dieses Session-Management seinen Zweck beim Anschauen der Bilder
282 sehr gut erfüllt, ist es dem ScaleServlet nicht möglich den Referenz-URLs
283 anzusehen, ob zuerst mehrfach hineingezoomt wurde und gibt unter Umständen
284 - eben wenn mehrfach hieingezoomt wurde vor der Generierung der Referenz - einen
285 falschen Ausschnitt zurück.)
286
287
288 ----------------------------------------------