+Digilib is a client-server-software that transforms high-resolution images to
+formats that are acceptable for internet network connetions. the client software
+is based on HTML and JavaScript so that everybody can use it with a normal
+browser. To see in full detail which browsers and platforms are supported check
+chapter 4.1. This software provides lots of features like zooming areas of
+pictures, setting marks to the pictures, jumping to different pictures while
+always being able to generate URLs so that people can distibute these and
+everybody can see the same picture with ist marks.
+It has been put lots of attention providing files that are as intependant of
+each other as possible so that embedding it in other kind of pages will be as
+simple as it can be. Stuff like providing modules or a different menubar are
+just some of the stuff you can easily do without having to change the files
+provided.
+
+Some of the the client-files contain JSP code, to do some serverside +configuration. Because of the fact that the serverside software has to use a +java module for the web-server there is no need to install more stuff than what +is needed by the server-scripts. +
++This software is still work in progress and it is quite probable that lots of +stuff will change in the future, so check this file with every new version of +software you downloaded. +
+ ++There are quite some files the client software needs to run all the interactive +user-interface. To give you a detailed view of the files there is a subsection +provided in this document explaining what each file does and how it interacts +with the others. +
+ ++This is the file you will request from the server and which will call the +other files. The main purposes of this file are: +
+ +
+The crutial point in this file is the way the query on the URL (get-method) is
+made. After digilib.jsp? there is a comma-separated list of parameters. It is
+to say that principally all of them are optional, but the first of them
+describing the url of the image-directory should really be set.
+Here is the list of the diffenent attributes in
+digilib.jsp?[att0]+[att1]+[att2]+[att3]+[att4]+ ... +[att8]:
+
| [att0] | +Directory where the image can be found (check the documentation for + serverside). | +
| [att1] | +The page number (equals the index of the image in the sorted directory). | +
| [att2] | +The dimension relative to the visible height/width in the frame (1.0 means + that the image fits exactly into the frame, while 2.0 means twice that + size). | +
| [att3] | +Attribute to pass extra options to the servlet (for example 'fit' means + that normally not resized gif-images will be scaled). | +
| [att4] | +Here are the marks passed separated by ';', while the coordinates are
+ separated with '/'. The cooridnates are in a relative format (0.0 -
+ 1.0). + Example ... +0.33/0.5;0.25/0.25+ ... means that there are two marks one a + third from the left and half down the image and the second a quarter from + left and top of the image. |
+
| [att5] | +Relative (0.0 - 1.0) value giving the most left pixels visible in the + zoomed image. | +
| [att6] | +Dito with the topmost pixels. | +
| [att7] | +Gives the visible width of the image (also 0.0 - 1.0). | +
| [att8] | +Same with the height. | +
+It is important to understand that all cooridnates that are used by digilib are +passed as relative values where the width/height of an image is 1. This way it +is possible that the images are displayed the same way on all kind of different +screen-sizes and so making opening the possibility of sharing a url between +people that will see the same on their screens. +
+ ++The parameterlist in dlImage.jsp is quite the same as in digilib.jsp but is +represented in another format. As in chapter 2.1 we are discussing here the +parameterlist. The parameters are no longer separated with the plus-sign put +with an ampersand '&', which is the official way of passing different parameters +through the URL. The parameters have all a name followed by a value, like +.../dlImage.jsp?fn=histbot/botany&pn=3& ... . I will give you now a list of +parameters dlImage.jsp understands by default by indication the name and its +equivalent in digilib.jsp and if needed some special comments. It is possible +and the somehow the aim of dlImage to pass more parameters to this file for +additional functionality. Check out section 2.5.1 where is a good example of how +to modify dlImage.jsp for adding new functionality. +
+ +| fn | += att0 | +
| pn | += att1 | +
| ws | += att2 | +
| mo | += att3 | +
| mk | += att4 | +
| wx | += att5 | +
| wy | += att6 | +
| ww | += att7 | +
| wh | += att8 | +
| dx | +Width of the frame containing the to be displayed image in pixels. | +
| dy | +Dito with the height. | +
+DlImage.jsp can react in two completely different ways on a request. When +requesting the file it checks whether the width and height of the frame are +passed as parameters in the URL. This is not the case on every first view of a +session. If the dimensions are not set, then dlImage sends a dummy page to the +client, calculates the width and height of the frame (which is only possible +with a correct html-file) and resends the request to dlImage.jsp this time with +the indicated dimensions. +
+
+The other way dlImage.jsp reacts is its noraml reaction. This means that it
+parses the parameterslist and fills in some default values if they are missing
+(check out the source-code to see them). Then the file is going to include some
+script files that do offer the functionality. Part of these JavaScript-files are
+browser dependant, some are not. The most important files are named with
+navigation_XX.js where XX is a shortcut for the browser. The other files (the
+ones not browser-dependant) are some sample modules that are discussed in
+section 2.5.
+Then it is time to build the actual HTML for the frame. There is one layer
+holding the picture (the way the parameters should be passed is described in the
+serverside dokumentaion). The layers named 'dotX' are the layers holding the
+marks, the ones named 'eckX' are the corners when zooming a rectangle.
+Last but not least the parameters are passed to the navigation-script or the the
+module using them (<body bgcolor="#666666" onload='init_XXXXX("<%= fn ...
+")'>).
+
+Let's look at the crucail points about navigation_XX.js-files. Most important is +that the parameters passed to the init-function are stored in an array globally +accesible (the code in init shows this). The name of the array is 'att'. There +is also a function called 'loadPicture' that puts together a new URL +(dlImage.jsp?...) for loading a new picture or another part of the same. Then we +have lots of functions dealing with different parts of the digilib +functionality: +
+ +| backPage | +Loading the previous picture in the directory. | +
| nextPage | +Loading the next picture in the directory. | +
| page | +Loading a picture in the same directory by index. | +
| digicat | +Loading a new window containing thumbnails of images in the directoy (some + closely related project called 'digicat'). | +
| ref | +Generating HTML- or LaTeX-style links for the special part of picture + including marks to build into other documents. The URL is made with + digilib.jsp?...+... . | +
| mark | +Sets a mark to the current picture. | +
| zoomArea | +Zooms an area of the current picture. | +
| zoomPoint | +Zooms in around the selected point on the picture. | +
| moveTo | +Moves the center of a image area to this point while maintaining the same + zooming grade (sometimes this is known as 'pan'). | +
| scale | +Scales an image relative to the dimensions of the image-frame (normally + the image fits right into it). | +
+The other functions are helpers that are should not be directly accessed from +outside the frame. +
+ +
+This file generates the navigation-frame with buttons and menus. From this point
+the calls are made to navigation_XX.js. Please consider this frame as a sample
+the we at the University of Berne are currently using. If you are good in
+graphics design feel free to create your own buttons.
+The files related to dlMenu.html are in a subdirectory called 'buttons' where
+the gif-images are stored and also the menu.js-scripts handling the menus.
+
+The modules form a very important part of the whole project. This software aims +to be easy to upgrade with new functionality. Because of the fact that +JavaScript is not a full featured programming language modularisation in so +that intuitive and simple. Still we have found a way of providing enough freedom +to build new modules and adding features to digilib. The example of two sample +modules (that are nevertheless useful), we would like to show how we think one +should implement another module to add new functionality. +
+ +
+In the subdirectory 'modules' is a very simple module called pdfMaker.js. This
+very basic module only has one function (makePDF) that does nothing more than
+giving a prompt where one can enter a number of image-indices and call a
+serverside script that creates a PDF-file with the different picures. To make
+this module work it has first to be loaded by dlImage.jsp. Because it is
+browser-independant there is only one version of it. Aften being loaded it has
+access to the whole 'att'-array which is quite stupidely shown in makePDF by
+giving the index of the currently displayed image as default value.
+One other thing that has to be done is to enter a new button to navigation.html
+so that the new function can be called... quite logic i know.
+
+'pagesTotal.js' is a lot more complicated than the first module and shows some
+more things to think of when making a module. It aims to show the current
+pagenumber (index) and the total number of images in the directory in a
+separated frame. The first thing that has to be done is implementing a new frame
+in diglib.jsp to provide space to write down the information.
+As we know the current index is stored in the parameter 'pn' in dlImage.jsp and
+easily accessible in the scripts with 'att[1]', where as the total number of
+pages is only known by the server. To get this information one has to make a
+call to a server function. This is done in digilib.jsp (query += "&pt=" +
+DB.getNumPages(request);) the resulting number that should not cheange during a
+session is stored in a new parameter 'pt' that is sent in the parameter-list to
+dlImage.jsp.
+In dlImage we have to load the module (configure 2.5.1). Next thing is to make
+the 'pt' accessible through all the scripts (adding a new cell to the
+'att'-array) by creating an init'function in the module. While the original
+function is called 'init' the one in pagesTotal is called 'init_pagesTotal' and
+acception the additional parameter 'pt'. In 'init_pagesTotal' there is a call to
+the original 'init' with all parameters but 'pt' and so filling the first nine
+cells of the att-array. Then it's time to add a new cell with 'pt' as its value.
+Further on there is a call to function 'pagesTotal' that writes the data into
+the new frame.
+As you can see there are some functions overriding the original ones.
+'nextPage', 'page' and 'loadPicture' are rewritten in the module to make use of
+the new functionality. In the first two functions we can make now some
+additional checks that we cannot run past the last image. 'loadPicture' has to
+be improved so that 'pt' will be in the URL sent when loading a new picture or
+area.
+
+There are some future plans concerning the cilent software. While there is no +actual list of things that have to be done, but some vague ideas of +improvements: +
+ ++Here is a very incomplete list of browsers and platforms known to work with +digilib. We provide three different navigation-scripts to work with different +implementations of JavaScript in different browsers. These are Netscape 4, +Internet Explorer (working on versions 4 - 6) and the Mozilla5-engine. Due to +some bugs in the browsers and special behaviours of different platforms we +cannot garantee that digilib works on every platform supported by for example +the Mozilla5-engine. Anyone having success on a different platform than the ones +indicated below, please send a note. +
+ ++It is known and already mentioned that 'Opera' is currently not supported by +digilib, but still this is some task that is planned for the future. +
+ +