digitallibrary/WEB-INF/lib (can also be found in the digilib-ext.zip package)
+ /docuserver) and for the web interface
+ (/docuserver/www)./docuserver/www). This will create
+ the digilib directory digitallibrary.digitallibrary/WEB-INF/lib. (Or just unpack the
+ digilib-ext.zip package there.)/docuserver This should
+ produce a directory /docuserver/jakarta-tomcat-5.0.29. Create a
+ link /docuserver/tomcat to the new directory./docuserver/tomcat/webapps (type ln -s
+ /docuserver/www/digitallibrary /docuserver/tomcat/webapps/) This installs
+ digilib in the default Tomcat instance running on port 8080 as
+ http://myserver:8080/digitallibrary/.catalina.sh (in the directory
+ /docuserver/tomcat/bin, see below for details)CATALINA_HOME = C:\jakarta-tomcat-4.1.24 (or similar)JAVA_HOME = C:\j2sdk (or similar)
+cmd.exe).%CATALINA_HOME%\bin\startup
+http://localhost:8080 or
+http://127.0.0.1:8080
+%CATALINA_HOME%\bin\shutdown.
+C:\docuserver.
+digitallibrary\WEB-INF\lib.
+(Or just unpack the digilib-ext.zip package there.)
+C:\jakarta-tomcat-4.1.24\conf\server.xmlC:\jakarta-tomcat-4.1.24\conf\tomcat-users.xmlC:\docuserver\digitallibrary\WEB-INF\digilib-config.xmlC:\docuserver\digitallibrary\WEB-INF\digilib-auth.xmlalcatraz-win-conf.zip package you can find
+prepared configuration files with the following default values:
+C:\bilder. digilib.digilib.9090.http://localhost:9090 or
+http://127.0.0.1:9090.
+The file catalina.sh (in /docuserver/tomcat/bin
+can be modified to provide the path to the JDK and runtime options
+for the Java VM. Somewhere at the beginning of the file you can put two lines
+like this:
+export JAVA_HOME=/usr/local/lib/IBMJava2-14 +export CATALINA_OPTS="-mx512m" ++ +
or, on Windows
+ +
+set CATALINA_HOME=C:\jakarta-tomcat-4.1.24 +set JAVA_HOME=C:\j2sdk ++ +
Adjust the JAVA_HOME path to point to your Java JDK
+installation directory. You can adjust the memory used by the Java VM
+with the -mx option.
All passwords and usernames have to be set up in the file
+tomcat-users.xml in /docuserver/tomcat/conf if you
+want to use authentication in digilib. The file looks like this:
+<tomcat-users> + <user name="tomcat" password="tomcat" roles="tomcat" /> + <user name="role1" password="tomcat" roles="role1" /> + <user name="both" password="tomcat" roles="tomcat,role1" /> +</tomcat-users> ++ +
A user is identified by a name and
+password. These two elements have to be entered in a
+authentication form presented by the browser when accessing a
+restricted resource. A user can have one or more
+roles. These roles will be used by digilib to decide if
+an authenticated user is allowed to access a document (see
+digilib-auth.xml below).
If you want to use the webinterface to configure Tomcat, you have to
+add administrational account with the roles admin and
+manager.
tomcat has to be restarted before changes to
+tomcat-users.xml have effect!
The main configuration for digilib is
+digilib-config.xml. It's normally in the
+WEB-INF directory in the webapp. (If you really need
+another location you can define it in the config-file
+init-parameter to the servlet)
In the configuration file you can set several paths and +options. The file looks like this:
+ ++<!-- Digilib servlet config file --> + +<digilib-config> + <!-- Image to be sent to indicate general failure. --> + <parameter name="error-image" value="/docuserver/images/icons/broken.gif" /> + + <!-- Image to be sent to indicate authorization failure. --> + <parameter name="denied-image" value="/docuserver/images/icons/alert.red.gif" /> + + <!-- List of directories where images are searched. + The authoritative directory with the high-resolution images + is first in list. --> + <parameter name="basedir-list" value="/docuserver/images:/docuserver/scaled/small" /> + + <!-- Java class to use for image operations --> + <parameter name="docuimage-class" value="digilib.image.JAIDocuImage" /> + + <!-- mimimum amount of scaling done with antialiasing --> + <parameter name="subsample-minimum" value="2"/> + + <!-- default interpolation quality (0=worst) --> + <parameter name="default-quality" value="1"/> + + <!-- is sending whole image files with mo=file allowed? --> + <parameter name="sendfile-allowed" value="true" /> + + <!-- the a maximum size of any sent image. (0 means no limit) --> + <parameter name="max-image-size" value="0" /> + + <!-- use safe but slow directory indexing --> + <parameter name="safe-dir-index" value="false" /> + + <!-- number of working threads --> + <parameter name="worker-threads" value="2" /> + + <!-- Restrict access to authorized users. + User authentication and roles are provided by the servlet container + (see tomcat-users.xml). + Authorization for resources (directories) is evaluated by the servlet + (see auth-file). --> + <parameter name="use-authorization" value="true"/> + + <!-- Location of XML file with authorization requirements. --> + <parameter name="auth-file" value="digilib-auth.xml"/> + + <!-- Part of URL to indicate authenticated access to Tomcat. --> + <parameter name="auth-url-path" value="authenticated/"/> + + <!-- use mapping of "virtual directories" to real directories on the server -- +> + <parameter name="use-mapping" value="false"/> + + <!-- location of XML mapping file --> + <parameter name="mapping-file" value="digilib-map.xml"/> + + <!-- location of logger config file --> + <parameter name="log-config-file" value="log4j-config.xml"/> +</digilib-config> ++ +
You have to adjust the basedir-list parameter to the
+directories where your images are installed. You need only one
+directory if you don't provide prescaled low resolution versions of your
+images. The directory with the high-resolution images must be the
+first entry in the list.
You can supply your own icons for the "error" and +"access denied" messages by the servlet. Standard images +will be used if these parameters are undefined.
+ +You can specify the Java toolkit implementation with the
+docuimage-class parameter. The
+ImageLoaderDocuImage might give best performance but
+works only with JDK 1.4 and up. JAIDocuImage works with
+JDK 1.3 and up.
The digilib access authorization is defined in the file defined by
+the auth-file parameter (usually
+digilib-auth.xml in WEB-INF).
The file has two parts diglib-paths and
+diglib-addresses. It looks like this:
+<auth-config> + + <digilib-paths> + <!-- + A user must supply one of the roles under "role" + to access the directory "name". + Roles under "role" must be separated by comma only (no spaces). + --> + <path name="histast/eastwood-collection" role="eastwood-coll" /> + <path name="ptolemaios_geo" role="ptolemaios-geo" /> + </digilib-paths> + + <digilib-addresses> + <!-- + A computer with an ip address that matches "ip" + is automatically granted all roles under "role". + The ip address is matched from the left (in full quads). + Roles under "role" must be separated by comma only (no spaces). + --> + <address ip="127" role="local" /> + <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" /> + <address ip="130.92.151" role="ALL" /> + </digilib-addresses> + +</auth-config> ++ +
diglib-paths defines restricted directories and
+the roles needed for access. The roles are defined with the users in
+tomcat-users.xml (see above). All subdirectories of the
+given directories have the same restrictions. All directories not
+listed here (and not subdirectories of listed directories) are freely
+accessible.
diglib-addresses defines hosts or networks of
+computers that are automatically authenticated without username and
+password. Hosts can be assigned roles. The special keyword ALL
+authorizes for everything. If the role assigned to the computer is not
+sufficient to access a resource the user will be asked for username
+and password.
A toolbar-friendly digilib page must define a Javascript variable
+toolbarEnabledURL whose value is a HTTP URL that
+produces a toolbar-enabled page. The toolbar should present a
+button to "take over" the page design by replacing
+the current page with the page from the given URL.
A toolbar-enabled page must offer the following Javascript functions:
+ +dlScriptVersion: a String variable that contains the version number of the Javascript code (e.g. "1.12b3")setMark(): lets the user click and sets a mark at the clicked locationzoomArea(): lets the user click to select an area and zooms to the selected areamoveCenter(): lets the user click and recenters the image around the clicked locationgetRef(): returns a String with a URL reference to the current documentremoveMark(): removes the last markzoomBy(float factor): magnifies the image by the given factor around the current centerzoomFullpage(): zooms out so that the whole image is visibledisplay(int prio): reloads the page with the current parametersnewParameter(String name, String defaultValue, int prio): declares a new parameter with name, default value (can be of any type) and prioritygetParameter(String name): returns the value of the parameter with the name namesetParameter(String name, String value): sets the value of the named parameter (value can be of any type)getAllParameters(int prio): returns a String of all parameters in HTTP request format (name=value) below the given priorityaddMark(Position pos): adds a mark with the given PositiondeleteMark(): removes the last mark form the listgetAllMarks(): returns a String with all current marks in digilib format (for parameter "mk")addFlag(String name): adds a digilib mode flag with the given namehasFlag(String name): returns if the given flag is currently setremoveFlag(String name): removes the given flagtoggleFlag(String name): toggles the given flaggetAllFlags(): returns a String with all current flags in digilib format (for parameter "mo")
+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), Opera 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. +
+ +