Mercurial > hg > digilib-old

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/client/doc/digilib_client.html	Tue Feb 26 18:43:36 2002 +0100
@@ -0,0 +1,433 @@
+<html>
+<head>
+<title>Documentation: digilib-client</title>
+</head>
+<body bgcolor="#FFFFFF">
+<h1>Dokumentation: digilib-client</h1>
+
+<h3>Table of contents</h3>
+
+<h4>1 Introduction</h4>
+
+<h4>2 Files</h4>
+
+<b>&nbsp;&nbsp;2.1 digilib.jsp<br>
+&nbsp;&nbsp;2.2 dlImage.jsp<br>
+&nbsp;&nbsp;2.3 navigation_XX.js<br>
+&nbsp;&nbsp;2.4 dlMenu.html<br>
+&nbsp;&nbsp;2.5 Modules<br></b>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.5.1 pdfMaker.js<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.5.2 pagesTotal.js
+
+<h4>3 Future</h4>
+
+<h4>4 Information</h4>
+
+<b>&nbsp;&nbsp;4.1 Supported browsers and platforms<br>&nbsp;</b>
+
+<hr>
+
+<h3>1 Introduction</h3>
+
+<p>
+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.<br>
+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.
+</p>
+<p>
+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.
+</p>
+<p>
+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.
+</p>
+
+<h3>2 Files</h3>
+
+<p>
+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.
+</p>
+
+<h4>2.1 digilib.jsp</h4>
+
+<p>
+This is the file you will request from the server and which will call the
+other files. The main purposes of this file are:
+</p>
+
+<ul>
+ <li>User authentication when wanting to access restriced documents. Check out
+     the serverside documentation for detailed explanation of how to set it
+     up.</li>
+ <li>Converting the query-string to the servlet style parameters (because of some
+     historical reasons the two parameter-sets are not equal and a project at the
+     Univerity of Berne based on digilib requires the first kind of parameters. So
+     for the moment we have to live with it...)</li>
+ <li>Building the frameset for the different frames like the one actually holding
+     the image, one for navigation, etc.. It's up to the developer of a certain
+     application to change it to its needs.</li>
+</ul>
+
+<p>
+The crutial point in this file is the way the query on the URL (get-method) is
+made. After <kbd>digilib.jsp?</kbd> 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.<br>
+Here is the list of the diffenent attributes in
+<kbd>digilib.jsp?[att0]+[att1]+[att2]+[att3]+[att4]+ ... +[att8]</kbd>:
+</p>
+
+<table border="0" align="center" width="95%">
+ <tr>
+  <td width="8%" valign="top">[att0]</td>
+  <td>Directory where the image can be found (check the documentation for
+      serverside).</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att1]</td>
+  <td>The page number (equals the index of the image in the sorted directory).</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att2]</td>
+  <td>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).</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att3]</td>
+  <td>Attribute to pass extra options to the servlet (for example 'fit' means
+      that normally not resized gif-images will be scaled).</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att4]</td>
+  <td>Here are the marks passed separated by ';', while the coordinates are
+      separated with '/'. The cooridnates are in a relative format (0.0 -
+      1.0).<br>
+      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.</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att5]</td>
+  <td>Relative (0.0 - 1.0) value giving the most left pixels visible in the
+      zoomed image.</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att6]</td>
+  <td>Dito with the topmost pixels.</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att7]</td>
+  <td>Gives the visible width of the image (also 0.0 - 1.0).</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">[att8]</td>
+  <td>Same with the height.</td>
+ </tr>
+</table>
+
+<p>
+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.
+</p>
+
+<h4>2.2 dlImage.jsp</h4>
+
+<p>
+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 <kbd>
+.../dlImage.jsp?fn=histbot/botany&pn=3& ... </kbd>. 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.
+</p>
+
+<table border="0" align="center" width="95%">
+ <tr>
+  <td width="8%" valign="top">fn</td>
+  <td>= att0</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">pn</td>
+  <td>= att1</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">ws</td>
+  <td>= att2</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">mo</td>
+  <td>= att3</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">mk</td>
+  <td>= att4</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">wx</td>
+  <td>= att5</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">wy</td>
+  <td>= att6</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">ww</td>
+  <td>= att7</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">wh</td>
+  <td>= att8</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">dx</td>
+  <td>Width of the frame containing the to be displayed image in pixels.</td>
+ </tr>
+ <tr>
+  <td width="8%" valign="top">dy</td>
+  <td>Dito with the height.</td>
+ </tr>
+</table>
+
+<p>
+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.
+</p>
+<p>
+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.<br>
+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.<br>
+Last but not least the parameters are passed to the navigation-script or the the
+module using them (<kbd>&lt;body bgcolor="#666666" onload='init_XXXXX("&lt;%= fn ...
+")'&gt;</kbd>).
+</p>
+
+<h4>2.3 navigation_XX.js</h4>
+
+<p>
+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:
+</p>
+
+<table border="0" align="center" width="95%">
+ <tr>
+  <td width="10%" valign="top">backPage</td>
+  <td>Loading the previous picture in the directory.</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">nextPage</td>
+  <td>Loading the next picture in the directory.</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">page</td>
+  <td>Loading a picture in the same directory by index.</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">digicat</td>
+  <td>Loading a new window containing thumbnails of images in the directoy (some
+      closely related project called 'digicat').</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">ref</td>
+  <td>Generating HTML- or LaTeX-style links for the special part of picture
+      including marks to build into other documents. The URL is made with
+      <kbd>digilib.jsp?...+... </kbd>.</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">mark</td>
+  <td>Sets a mark to the current picture.</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">zoomArea</td>
+  <td>Zooms an area of the current picture.</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">zoomPoint</td>
+  <td>Zooms in around the selected point on the picture.</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">moveTo</td>
+  <td>Moves the center of a image area to this point while maintaining the same
+      zooming grade (sometimes this is known as 'pan').</td>
+ </tr>
+ <tr>
+  <td width="10%" valign="top">scale</td>
+  <td>Scales an image relative to the dimensions of the image-frame (normally
+      the image fits right into it).</td>
+ </tr>
+</table>
+
+<p>
+The other functions are helpers that are should not be directly accessed from
+outside the frame.
+</p>
+
+<h4>2.4 dlMenu.html</h4>
+
+<p>
+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.<br>
+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.
+</p>
+
+<h4>2.5 Modules</h4>
+
+<p>
+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.
+</p>
+
+<h5>2.5.1 pdfMaker.js</h5>
+
+<p>
+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.<br>
+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.
+</p>
+
+<h5>2.5.2 pagesTotal.js</h5>
+
+<p>
+'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.<br>
+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.<br>
+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.<br>
+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.
+</p>
+
+
+<h3>3 Future</h3>
+
+<p>
+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:
+</p>
+
+<ul>
+ <li>Cleaning up the different stiles of holding the parameters.</li>
+ <li>Makeing some handy generic functions like mouseclicks or mousemoves so that
+     they can be used in modules.</li>
+ <li>Makeing the implementation of modules clearer, easier and safer than it is
+     now. In JavaScript there are some (rudimentary?) object-oriented ideas that
+     might help improving it - but I didn't got it until now.</li>
+ <li>Make it work on more platforms/browsers. Lots of trial and error has to be
+     done to make it work with 'Opera'.</li>
+ <li>You can always make the code clearer, smaller, better, faster, ... :-)</li>
+</ul>
+
+
+<h3>4 Information</h3>
+
+<h4>4.1 Supported browsers and platforms</h4>
+
+<p>
+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.
+</p>
+
+<ul>
+ <li>Netscape 4.7x (Windows, MacOS 9.0/9.1, MacOS X, Linux, Solaris)</li>
+ <li>Mozilla 0.9.x (Windows, Linux, MacOS X)</li>
+ <li>Internet Explorer 4.01+ (Windows)</li>
+ <li>Internet Explorer 5 (MacOS 9.0/9.1, MacOS X)</li>
+</ul>
+
+<p>
+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.
+</p>
+
+<hr>
+<address>
+University of Berne - Switzerland : History and Philosophy of Science<br>
+18.02.2002 - Christian Luginbuehl
+(<a href="mailto:luginbuehl@student.unibe.ch">luginbuehl@student.unibe.ch</a>)
+</address>