|
36
|
1 <html>
|
|
|
2 <head>
|
|
|
3 <title>Documentation: digilib-client</title>
|
|
|
4 </head>
|
|
|
5 <body bgcolor="#FFFFFF">
|
|
|
6 <h1>Dokumentation: digilib-client</h1>
|
|
|
7
|
|
|
8 <h3>Table of contents</h3>
|
|
|
9
|
|
|
10 <h4>1 Introduction</h4>
|
|
|
11
|
|
|
12 <h4>2 Files</h4>
|
|
|
13
|
|
|
14 <b> 2.1 digilib.jsp<br>
|
|
|
15 2.2 dlImage.jsp<br>
|
|
|
16 2.3 navigation_XX.js<br>
|
|
|
17 2.4 dlMenu.html<br>
|
|
|
18 2.5 Modules<br></b>
|
|
|
19 2.5.1 pdfMaker.js<br>
|
|
|
20 2.5.2 pagesTotal.js
|
|
|
21
|
|
|
22 <h4>3 Future</h4>
|
|
|
23
|
|
|
24 <h4>4 Information</h4>
|
|
|
25
|
|
|
26 <b> 4.1 Supported browsers and platforms<br> </b>
|
|
|
27
|
|
|
28 <hr>
|
|
|
29
|
|
|
30 <h3>1 Introduction</h3>
|
|
|
31
|
|
|
32 <p>
|
|
|
33 Digilib is a client-server-software that transforms high-resolution images to
|
|
|
34 formats that are acceptable for internet network connetions. the client software
|
|
|
35 is based on HTML and JavaScript so that everybody can use it with a normal
|
|
|
36 browser. To see in full detail which browsers and platforms are supported check
|
|
|
37 chapter 4.1. This software provides lots of features like zooming areas of
|
|
|
38 pictures, setting marks to the pictures, jumping to different pictures while
|
|
|
39 always being able to generate URLs so that people can distibute these and
|
|
|
40 everybody can see the same picture with ist marks.<br>
|
|
|
41 It has been put lots of attention providing files that are as intependant of
|
|
|
42 each other as possible so that embedding it in other kind of pages will be as
|
|
|
43 simple as it can be. Stuff like providing modules or a different menubar are
|
|
|
44 just some of the stuff you can easily do without having to change the files
|
|
|
45 provided.
|
|
|
46 </p>
|
|
|
47 <p>
|
|
|
48 Some of the the client-files contain JSP code, to do some serverside
|
|
|
49 configuration. Because of the fact that the serverside software has to use a
|
|
|
50 java module for the web-server there is no need to install more stuff than what
|
|
|
51 is needed by the server-scripts.
|
|
|
52 </p>
|
|
|
53 <p>
|
|
|
54 This software is still work in progress and it is quite probable that lots of
|
|
|
55 stuff will change in the future, so check this file with every new version of
|
|
|
56 software you downloaded.
|
|
|
57 </p>
|
|
|
58
|
|
|
59 <h3>2 Files</h3>
|
|
|
60
|
|
|
61 <p>
|
|
|
62 There are quite some files the client software needs to run all the interactive
|
|
|
63 user-interface. To give you a detailed view of the files there is a subsection
|
|
|
64 provided in this document explaining what each file does and how it interacts
|
|
|
65 with the others.
|
|
|
66 </p>
|
|
|
67
|
|
|
68 <h4>2.1 digilib.jsp</h4>
|
|
|
69
|
|
|
70 <p>
|
|
|
71 This is the file you will request from the server and which will call the
|
|
|
72 other files. The main purposes of this file are:
|
|
|
73 </p>
|
|
|
74
|
|
|
75 <ul>
|
|
|
76 <li>User authentication when wanting to access restriced documents. Check out
|
|
|
77 the serverside documentation for detailed explanation of how to set it
|
|
|
78 up.</li>
|
|
|
79 <li>Converting the query-string to the servlet style parameters (because of some
|
|
|
80 historical reasons the two parameter-sets are not equal and a project at the
|
|
|
81 Univerity of Berne based on digilib requires the first kind of parameters. So
|
|
|
82 for the moment we have to live with it...)</li>
|
|
|
83 <li>Building the frameset for the different frames like the one actually holding
|
|
|
84 the image, one for navigation, etc.. It's up to the developer of a certain
|
|
|
85 application to change it to its needs.</li>
|
|
|
86 </ul>
|
|
|
87
|
|
|
88 <p>
|
|
|
89 The crutial point in this file is the way the query on the URL (get-method) is
|
|
|
90 made. After <kbd>digilib.jsp?</kbd> there is a comma-separated list of parameters. It is
|
|
|
91 to say that principally all of them are optional, but the first of them
|
|
|
92 describing the url of the image-directory should really be set.<br>
|
|
|
93 Here is the list of the diffenent attributes in
|
|
|
94 <kbd>digilib.jsp?[att0]+[att1]+[att2]+[att3]+[att4]+ ... +[att8]</kbd>:
|
|
|
95 </p>
|
|
|
96
|
|
|
97 <table border="0" align="center" width="95%">
|
|
|
98 <tr>
|
|
|
99 <td width="8%" valign="top">[att0]</td>
|
|
|
100 <td>Directory where the image can be found (check the documentation for
|
|
|
101 serverside).</td>
|
|
|
102 </tr>
|
|
|
103 <tr>
|
|
|
104 <td width="8%" valign="top">[att1]</td>
|
|
|
105 <td>The page number (equals the index of the image in the sorted directory).</td>
|
|
|
106 </tr>
|
|
|
107 <tr>
|
|
|
108 <td width="8%" valign="top">[att2]</td>
|
|
|
109 <td>The dimension relative to the visible height/width in the frame (1.0 means
|
|
|
110 that the image fits exactly into the frame, while 2.0 means twice that
|
|
|
111 size).</td>
|
|
|
112 </tr>
|
|
|
113 <tr>
|
|
|
114 <td width="8%" valign="top">[att3]</td>
|
|
|
115 <td>Attribute to pass extra options to the servlet (for example 'fit' means
|
|
|
116 that normally not resized gif-images will be scaled).</td>
|
|
|
117 </tr>
|
|
|
118 <tr>
|
|
|
119 <td width="8%" valign="top">[att4]</td>
|
|
|
120 <td>Here are the marks passed separated by ';', while the coordinates are
|
|
|
121 separated with '/'. The cooridnates are in a relative format (0.0 -
|
|
|
122 1.0).<br>
|
|
|
123 Example ... +0.33/0.5;0.25/0.25+ ... means that there are two marks one a
|
|
|
124 third from the left and half down the image and the second a quarter from
|
|
|
125 left and top of the image.</td>
|
|
|
126 </tr>
|
|
|
127 <tr>
|
|
|
128 <td width="8%" valign="top">[att5]</td>
|
|
|
129 <td>Relative (0.0 - 1.0) value giving the most left pixels visible in the
|
|
|
130 zoomed image.</td>
|
|
|
131 </tr>
|
|
|
132 <tr>
|
|
|
133 <td width="8%" valign="top">[att6]</td>
|
|
|
134 <td>Dito with the topmost pixels.</td>
|
|
|
135 </tr>
|
|
|
136 <tr>
|
|
|
137 <td width="8%" valign="top">[att7]</td>
|
|
|
138 <td>Gives the visible width of the image (also 0.0 - 1.0).</td>
|
|
|
139 </tr>
|
|
|
140 <tr>
|
|
|
141 <td width="8%" valign="top">[att8]</td>
|
|
|
142 <td>Same with the height.</td>
|
|
|
143 </tr>
|
|
|
144 </table>
|
|
|
145
|
|
|
146 <p>
|
|
|
147 It is important to understand that all cooridnates that are used by digilib are
|
|
|
148 passed as relative values where the width/height of an image is 1. This way it
|
|
|
149 is possible that the images are displayed the same way on all kind of different
|
|
|
150 screen-sizes and so making opening the possibility of sharing a url between
|
|
|
151 people that will see the same on their screens.
|
|
|
152 </p>
|
|
|
153
|
|
|
154 <h4>2.2 dlImage.jsp</h4>
|
|
|
155
|
|
|
156 <p>
|
|
|
157 The parameterlist in dlImage.jsp is quite the same as in digilib.jsp but is
|
|
|
158 represented in another format. As in chapter 2.1 we are discussing here the
|
|
|
159 parameterlist. The parameters are no longer separated with the plus-sign put
|
|
|
160 with an ampersand '&', which is the official way of passing different parameters
|
|
|
161 through the URL. The parameters have all a name followed by a value, like <kbd>
|
|
|
162 .../dlImage.jsp?fn=histbot/botany&pn=3& ... </kbd>. I will give you now a list of
|
|
|
163 parameters dlImage.jsp understands by default by indication the name and its
|
|
|
164 equivalent in digilib.jsp and if needed some special comments. It is possible
|
|
|
165 and the somehow the aim of dlImage to pass more parameters to this file for
|
|
|
166 additional functionality. Check out section 2.5.1 where is a good example of how
|
|
|
167 to modify dlImage.jsp for adding new functionality.
|
|
|
168 </p>
|
|
|
169
|
|
|
170 <table border="0" align="center" width="95%">
|
|
|
171 <tr>
|
|
|
172 <td width="8%" valign="top">fn</td>
|
|
|
173 <td>= att0</td>
|
|
|
174 </tr>
|
|
|
175 <tr>
|
|
|
176 <td width="8%" valign="top">pn</td>
|
|
|
177 <td>= att1</td>
|
|
|
178 </tr>
|
|
|
179 <tr>
|
|
|
180 <td width="8%" valign="top">ws</td>
|
|
|
181 <td>= att2</td>
|
|
|
182 </tr>
|
|
|
183 <tr>
|
|
|
184 <td width="8%" valign="top">mo</td>
|
|
|
185 <td>= att3</td>
|
|
|
186 </tr>
|
|
|
187 <tr>
|
|
|
188 <td width="8%" valign="top">mk</td>
|
|
|
189 <td>= att4</td>
|
|
|
190 </tr>
|
|
|
191 <tr>
|
|
|
192 <td width="8%" valign="top">wx</td>
|
|
|
193 <td>= att5</td>
|
|
|
194 </tr>
|
|
|
195 <tr>
|
|
|
196 <td width="8%" valign="top">wy</td>
|
|
|
197 <td>= att6</td>
|
|
|
198 </tr>
|
|
|
199 <tr>
|
|
|
200 <td width="8%" valign="top">ww</td>
|
|
|
201 <td>= att7</td>
|
|
|
202 </tr>
|
|
|
203 <tr>
|
|
|
204 <td width="8%" valign="top">wh</td>
|
|
|
205 <td>= att8</td>
|
|
|
206 </tr>
|
|
|
207 <tr>
|
|
|
208 <td width="8%" valign="top">dx</td>
|
|
|
209 <td>Width of the frame containing the to be displayed image in pixels.</td>
|
|
|
210 </tr>
|
|
|
211 <tr>
|
|
|
212 <td width="8%" valign="top">dy</td>
|
|
|
213 <td>Dito with the height.</td>
|
|
|
214 </tr>
|
|
|
215 </table>
|
|
|
216
|
|
|
217 <p>
|
|
|
218 DlImage.jsp can react in two completely different ways on a request. When
|
|
|
219 requesting the file it checks whether the width and height of the frame are
|
|
|
220 passed as parameters in the URL. This is not the case on every first view of a
|
|
|
221 session. If the dimensions are not set, then dlImage sends a dummy page to the
|
|
|
222 client, calculates the width and height of the frame (which is only possible
|
|
|
223 with a correct html-file) and resends the request to dlImage.jsp this time with
|
|
|
224 the indicated dimensions.
|
|
|
225 </p>
|
|
|
226 <p>
|
|
|
227 The other way dlImage.jsp reacts is its noraml reaction. This means that it
|
|
|
228 parses the parameterslist and fills in some default values if they are missing
|
|
|
229 (check out the source-code to see them). Then the file is going to include some
|
|
|
230 script files that do offer the functionality. Part of these JavaScript-files are
|
|
|
231 browser dependant, some are not. The most important files are named with
|
|
|
232 navigation_XX.js where XX is a shortcut for the browser. The other files (the
|
|
|
233 ones not browser-dependant) are some sample modules that are discussed in
|
|
|
234 section 2.5.<br>
|
|
|
235 Then it is time to build the actual HTML for the frame. There is one layer
|
|
|
236 holding the picture (the way the parameters should be passed is described in the
|
|
|
237 serverside dokumentaion). The layers named 'dotX' are the layers holding the
|
|
|
238 marks, the ones named 'eckX' are the corners when zooming a rectangle.<br>
|
|
|
239 Last but not least the parameters are passed to the navigation-script or the the
|
|
|
240 module using them (<kbd><body bgcolor="#666666" onload='init_XXXXX("<%= fn ...
|
|
|
241 ")'></kbd>).
|
|
|
242 </p>
|
|
|
243
|
|
|
244 <h4>2.3 navigation_XX.js</h4>
|
|
|
245
|
|
|
246 <p>
|
|
|
247 Let's look at the crucail points about navigation_XX.js-files. Most important is
|
|
|
248 that the parameters passed to the init-function are stored in an array globally
|
|
|
249 accesible (the code in init shows this). The name of the array is 'att'. There
|
|
|
250 is also a function called 'loadPicture' that puts together a new URL
|
|
|
251 (dlImage.jsp?...) for loading a new picture or another part of the same. Then we
|
|
|
252 have lots of functions dealing with different parts of the digilib
|
|
|
253 functionality:
|
|
|
254 </p>
|
|
|
255
|
|
|
256 <table border="0" align="center" width="95%">
|
|
|
257 <tr>
|
|
|
258 <td width="10%" valign="top">backPage</td>
|
|
|
259 <td>Loading the previous picture in the directory.</td>
|
|
|
260 </tr>
|
|
|
261 <tr>
|
|
|
262 <td width="10%" valign="top">nextPage</td>
|
|
|
263 <td>Loading the next picture in the directory.</td>
|
|
|
264 </tr>
|
|
|
265 <tr>
|
|
|
266 <td width="10%" valign="top">page</td>
|
|
|
267 <td>Loading a picture in the same directory by index.</td>
|
|
|
268 </tr>
|
|
|
269 <tr>
|
|
|
270 <td width="10%" valign="top">digicat</td>
|
|
|
271 <td>Loading a new window containing thumbnails of images in the directoy (some
|
|
|
272 closely related project called 'digicat').</td>
|
|
|
273 </tr>
|
|
|
274 <tr>
|
|
|
275 <td width="10%" valign="top">ref</td>
|
|
|
276 <td>Generating HTML- or LaTeX-style links for the special part of picture
|
|
|
277 including marks to build into other documents. The URL is made with
|
|
|
278 <kbd>digilib.jsp?...+... </kbd>.</td>
|
|
|
279 </tr>
|
|
|
280 <tr>
|
|
|
281 <td width="10%" valign="top">mark</td>
|
|
|
282 <td>Sets a mark to the current picture.</td>
|
|
|
283 </tr>
|
|
|
284 <tr>
|
|
|
285 <td width="10%" valign="top">zoomArea</td>
|
|
|
286 <td>Zooms an area of the current picture.</td>
|
|
|
287 </tr>
|
|
|
288 <tr>
|
|
|
289 <td width="10%" valign="top">zoomPoint</td>
|
|
|
290 <td>Zooms in around the selected point on the picture.</td>
|
|
|
291 </tr>
|
|
|
292 <tr>
|
|
|
293 <td width="10%" valign="top">moveTo</td>
|
|
|
294 <td>Moves the center of a image area to this point while maintaining the same
|
|
|
295 zooming grade (sometimes this is known as 'pan').</td>
|
|
|
296 </tr>
|
|
|
297 <tr>
|
|
|
298 <td width="10%" valign="top">scale</td>
|
|
|
299 <td>Scales an image relative to the dimensions of the image-frame (normally
|
|
|
300 the image fits right into it).</td>
|
|
|
301 </tr>
|
|
|
302 </table>
|
|
|
303
|
|
|
304 <p>
|
|
|
305 The other functions are helpers that are should not be directly accessed from
|
|
|
306 outside the frame.
|
|
|
307 </p>
|
|
|
308
|
|
|
309 <h4>2.4 dlMenu.html</h4>
|
|
|
310
|
|
|
311 <p>
|
|
|
312 This file generates the navigation-frame with buttons and menus. From this point
|
|
|
313 the calls are made to navigation_XX.js. Please consider this frame as a sample
|
|
|
314 the we at the University of Berne are currently using. If you are good in
|
|
|
315 graphics design feel free to create your own buttons.<br>
|
|
|
316 The files related to dlMenu.html are in a subdirectory called 'buttons' where
|
|
|
317 the gif-images are stored and also the menu.js-scripts handling the menus.
|
|
|
318 </p>
|
|
|
319
|
|
|
320 <h4>2.5 Modules</h4>
|
|
|
321
|
|
|
322 <p>
|
|
|
323 The modules form a very important part of the whole project. This software aims
|
|
|
324 to be easy to upgrade with new functionality. Because of the fact that
|
|
|
325 JavaScript is not a full featured programming language modularisation in so
|
|
|
326 that intuitive and simple. Still we have found a way of providing enough freedom
|
|
|
327 to build new modules and adding features to digilib. The example of two sample
|
|
|
328 modules (that are nevertheless useful), we would like to show how we think one
|
|
|
329 should implement another module to add new functionality.
|
|
|
330 </p>
|
|
|
331
|
|
|
332 <h5>2.5.1 pdfMaker.js</h5>
|
|
|
333
|
|
|
334 <p>
|
|
|
335 In the subdirectory 'modules' is a very simple module called pdfMaker.js. This
|
|
|
336 very basic module only has one function (makePDF) that does nothing more than
|
|
|
337 giving a prompt where one can enter a number of image-indices and call a
|
|
|
338 serverside script that creates a PDF-file with the different picures. To make
|
|
|
339 this module work it has first to be loaded by dlImage.jsp. Because it is
|
|
|
340 browser-independant there is only one version of it. Aften being loaded it has
|
|
|
341 access to the whole 'att'-array which is quite stupidely shown in makePDF by
|
|
|
342 giving the index of the currently displayed image as default value.<br>
|
|
|
343 One other thing that has to be done is to enter a new button to navigation.html
|
|
|
344 so that the new function can be called... quite logic i know.
|
|
|
345 </p>
|
|
|
346
|
|
|
347 <h5>2.5.2 pagesTotal.js</h5>
|
|
|
348
|
|
|
349 <p>
|
|
|
350 'pagesTotal.js' is a lot more complicated than the first module and shows some
|
|
|
351 more things to think of when making a module. It aims to show the current
|
|
|
352 pagenumber (index) and the total number of images in the directory in a
|
|
|
353 separated frame. The first thing that has to be done is implementing a new frame
|
|
|
354 in diglib.jsp to provide space to write down the information.<br>
|
|
|
355 As we know the current index is stored in the parameter 'pn' in dlImage.jsp and
|
|
|
356 easily accessible in the scripts with 'att[1]', where as the total number of
|
|
|
357 pages is only known by the server. To get this information one has to make a
|
|
|
358 call to a server function. This is done in digilib.jsp (query += "&pt=" +
|
|
|
359 DB.getNumPages(request);) the resulting number that should not cheange during a
|
|
|
360 session is stored in a new parameter 'pt' that is sent in the parameter-list to
|
|
|
361 dlImage.jsp.<br>
|
|
|
362 In dlImage we have to load the module (configure 2.5.1). Next thing is to make
|
|
|
363 the 'pt' accessible through all the scripts (adding a new cell to the
|
|
|
364 'att'-array) by creating an init'function in the module. While the original
|
|
|
365 function is called 'init' the one in pagesTotal is called 'init_pagesTotal' and
|
|
|
366 acception the additional parameter 'pt'. In 'init_pagesTotal' there is a call to
|
|
|
367 the original 'init' with all parameters but 'pt' and so filling the first nine
|
|
|
368 cells of the att-array. Then it's time to add a new cell with 'pt' as its value.
|
|
|
369 Further on there is a call to function 'pagesTotal' that writes the data into
|
|
|
370 the new frame.<br>
|
|
|
371 As you can see there are some functions overriding the original ones.
|
|
|
372 'nextPage', 'page' and 'loadPicture' are rewritten in the module to make use of
|
|
|
373 the new functionality. In the first two functions we can make now some
|
|
|
374 additional checks that we cannot run past the last image. 'loadPicture' has to
|
|
|
375 be improved so that 'pt' will be in the URL sent when loading a new picture or
|
|
|
376 area.
|
|
|
377 </p>
|
|
|
378
|
|
|
379
|
|
|
380 <h3>3 Future</h3>
|
|
|
381
|
|
|
382 <p>
|
|
|
383 There are some future plans concerning the cilent software. While there is no
|
|
|
384 actual list of things that have to be done, but some vague ideas of
|
|
|
385 improvements:
|
|
|
386 </p>
|
|
|
387
|
|
|
388 <ul>
|
|
|
389 <li>Cleaning up the different stiles of holding the parameters.</li>
|
|
|
390 <li>Makeing some handy generic functions like mouseclicks or mousemoves so that
|
|
|
391 they can be used in modules.</li>
|
|
|
392 <li>Makeing the implementation of modules clearer, easier and safer than it is
|
|
|
393 now. In JavaScript there are some (rudimentary?) object-oriented ideas that
|
|
|
394 might help improving it - but I didn't got it until now.</li>
|
|
|
395 <li>Make it work on more platforms/browsers. Lots of trial and error has to be
|
|
|
396 done to make it work with 'Opera'.</li>
|
|
|
397 <li>You can always make the code clearer, smaller, better, faster, ... :-)</li>
|
|
|
398 </ul>
|
|
|
399
|
|
|
400
|
|
|
401 <h3>4 Information</h3>
|
|
|
402
|
|
|
403 <h4>4.1 Supported browsers and platforms</h4>
|
|
|
404
|
|
|
405 <p>
|
|
|
406 Here is a very incomplete list of browsers and platforms known to work with
|
|
|
407 digilib. We provide three different navigation-scripts to work with different
|
|
|
408 implementations of JavaScript in different browsers. These are Netscape 4,
|
|
|
409 Internet Explorer (working on versions 4 - 6) and the Mozilla5-engine. Due to
|
|
|
410 some bugs in the browsers and special behaviours of different platforms we
|
|
|
411 cannot garantee that digilib works on every platform supported by for example
|
|
|
412 the Mozilla5-engine. Anyone having success on a different platform than the ones
|
|
|
413 indicated below, please send a note.
|
|
|
414 </p>
|
|
|
415
|
|
|
416 <ul>
|
|
|
417 <li>Netscape 4.7x (Windows, MacOS 9.0/9.1, MacOS X, Linux, Solaris)</li>
|
|
|
418 <li>Mozilla 0.9.x (Windows, Linux, MacOS X)</li>
|
|
|
419 <li>Internet Explorer 4.01+ (Windows)</li>
|
|
|
420 <li>Internet Explorer 5 (MacOS 9.0/9.1, MacOS X)</li>
|
|
|
421 </ul>
|
|
|
422
|
|
|
423 <p>
|
|
|
424 It is known and already mentioned that 'Opera' is currently not supported by
|
|
|
425 digilib, but still this is some task that is planned for the future.
|
|
|
426 </p>
|
|
|
427
|
|
|
428 <hr>
|
|
|
429 <address>
|
|
|
430 University of Berne - Switzerland : History and Philosophy of Science<br>
|
|
|
431 18.02.2002 - Christian Luginbuehl
|
|
|
432 (<a href="mailto:luginbuehl@student.unibe.ch">luginbuehl@student.unibe.ch</a>)
|
|
|
433 </address>
|
