Mercurial > hg > digilib-old
comparison client/doc/old/digilib_client.html @ 325:ed94b0e7dd00
moved old doc
author | robcast |
---|---|
date | Tue, 02 Nov 2004 13:31:11 +0100 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
324:d28bbd150b8b | 325:ed94b0e7dd00 |
---|---|
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.</li> | |
396 <li>You can always make the code clearer, smaller, better, faster, ... :-)</li> | |
397 </ul> | |
398 | |
399 | |
400 <h3>4 Information</h3> | |
401 | |
402 <h4>4.1 Supported browsers and platforms</h4> | |
403 | |
404 <p> | |
405 Here is a very incomplete list of browsers and platforms known to work with | |
406 digilib. We provide three different navigation-scripts to work with different | |
407 implementations of JavaScript in different browsers. These are Netscape 4, | |
408 Internet Explorer (working on versions 4 - 6), Opera 6 and the Mozilla5-engine. Due to | |
409 some bugs in the browsers and special behaviours of different platforms we | |
410 cannot garantee that digilib works on every platform supported by for example | |
411 the Mozilla5-engine. Anyone having success on a different platform than the ones | |
412 indicated below, please send a note. | |
413 </p> | |
414 | |
415 <ul> | |
416 <li>Netscape 4.7x (Windows, MacOS 9.0/9.1, MacOS X, Linux, Solaris)</li> | |
417 <li>Mozilla 0.9.x (Windows, Linux, MacOS X)</li> | |
418 <li>Internet Explorer 4.01+ (Windows)</li> | |
419 <li>Internet Explorer 5 (MacOS 9.0/9.1, MacOS X)</li> | |
420 <li>Opera 6 (Windows, possibly other platforms)</li> | |
421 </ul> | |
422 | |
423 <hr> | |
424 <address> | |
425 University of Berne - Switzerland : History and Philosophy of Science<br> | |
426 18.02.2002 - Christian Luginbuehl | |
427 (<a href="mailto:luginbuehl@student.unibe.ch">luginbuehl@student.unibe.ch</a>) | |
428 </address> |