Mercurial > hg > digilib-doc
changeset 0:7b20d15a57e9
refactored into maven modules per servlet type.
can build servlet-api 2.3 and 3.0 via profile now!
| author | robcast |
|---|---|
| date | Tue, 26 Apr 2011 20:24:31 +0200 |
| parents | |
| children | 5baf44fed7b0 |
| files | digilib_install.html digilib_interop.html old/digilib_client.html |
| diffstat | 3 files changed, 856 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/digilib_install.html Tue Apr 26 20:24:31 2011 +0200 @@ -0,0 +1,365 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<html> +<head> +<title>Installation of digilib</title> +</head> + +<body> +<h1>What you need to install digilib</h1> + +<ul> + <li> + <a href="http://java.sun.com/downloads/index.html" >Java JDK</a> >1.2 (preferred 1.4 and up) + </li> + + <li> + <a href="http://jakarta.apache.org/tomcat/index.html" >Jakarta + Tomcat</a> version 4 or later (preferred 4.1 and up) from + <a href="http://jakarta.apache.org">http://jakarta.apache.org</a> + </li> + + <li>The digilib distribution package <a href="http://download.berlios.de/digilib/digilib-core.zip"><b>digilib-core.zip</b></a> (from + <a href="http://developer.berlios.de">http://developer.berlios.de</a>) + + </li> + + <li>Some auxiliary Java libraries to be put in <code>digitallibrary/WEB-INF/lib</code> (can also be found in the <a href="http://download.berlios.de/digilib/digilib-ext.zip">digilib-ext.zip</a> package) + <ul> + <li> + <b>concurrent.jar</b> from Doug Lea's <a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html">util.concurrent library</a> (see <a href="http://gee.cs.oswego.edu/dl/">http://gee.cs.oswego.edu/dl/</a>). + </li> + + <li> + <b>log4j.jar</b> from the <a href="http://logging.apache.org/log4j/docs/download.html">Log4J library</a> (see <a href="http://logging.apache.org">http://logging.apache.org</a>) + </li> + + <li> + <b>jai_imageio.jar</b> (and its native libraries) with JDK >= 1.4, from the <a href="http://java.sun.com/products/java-media/jai/current.html">Java Advanced Imaging Image-IO Tools</a> (see <a href="http://java.sun.com/products/java-media/jai/index.jsp">http://java.sun.com/products/java-media/jai/</a>) + </li> + + <li> + <b>jai_core.jar, jai_codec.jar</b> if you want to use the JAIDocuImage implementation, from the <a href="http://java.sun.com/products/java-media/jai/current.html">Java Advanced Imaging API</a> (see <a href="http://java.sun.com/products/java-media/jai/index.jsp">http://java.sun.com/products/java-media/jai/</a>) + </li> + + <li> + <b>batik-*.jar</b> if you want to use the Raster servlet, from the <a href="http://www.apache.org/dyn/closer.cgi/xml/batik">Apache Batik library</a> (see <a href="http://xml.apache.org/batik/">http://xml.apache.org/batik/</a>) + </li> + + <li> + <b>jena.jar</b> from the <a href="http://www.hpl.hp.com/semweb/jena1.htm">JENA RDF library version 1.6.1</a> (see <a href="http://jena.sourceforge.net/">http://jena.sourceforge.net/</a>) + </li> + </ul> +</ul> + +<h1>Installation</h1> + +<h2>On Linux/Unix</h2> + +<ol> + <li>Make shure the Java JDK is installed (a JRE won't do).</li> + + <li>Create a base directory for digilib (the default used here is + <code>/docuserver</code>) and for the web interface + (<code>/docuserver/www</code>).</li> + + <li>Unpack the <b>digilib-core.zip</b> package in the web + interface directory (<code>/docuserver/www</code>). This will create + the digilib directory <code>digitallibrary</code>.</li> + + <li>Install the auxiliary Java libraries in + <code>digitallibrary/WEB-INF/lib</code>. (Or just unpack the + <b>digilib-ext.zip</b> package there.)</li> + + <li>Unpack Jakarta Tomcat 5.0.29 in <code>/docuserver</code> This should + produce a directory <code>/docuserver/jakarta-tomcat-5.0.29</code>. Create a + link <code>/docuserver/tomcat</code> to the new directory.</li> + + <li>Create a link from the digilib directory into the Tomcat webapps + directory <code>/docuserver/tomcat/webapps</code> (type <code>ln -s + /docuserver/www/digitallibrary /docuserver/tomcat/webapps/</code>) This installs + digilib in the default Tomcat instance running on port 8080 as + <code>http://myserver:8080/digitallibrary/</code>.</li> + + <li>Adjust the path to the JDK and its options in + <code>catalina.sh</code> (in the directory + <code>/docuserver/tomcat/bin</code>, see below for details)</li> +</ol> + + +<h2>On Windows (quick install)</h2> + +<ol> +<li>Set the following Environment Variables:<br /> + <code>CATALINA_HOME = C:\jakarta-tomcat-4.1.24</code> (or similar)<br /> + <code>JAVA_HOME = C:\j2sdk</code> (or similar) +</li> + +<li> +Start Tomcat server: Open a console window (start <code>cmd.exe</code>).<br /> +Type: <code>%CATALINA_HOME%\bin\startup</code> +</li> + +<li> +Try the following URL in your browser: +<code>http://localhost:8080</code> or +<code>http://127.0.0.1:8080</code> +</li> + +<li> +You should now be able to see the Tomcat opening screen: <em>If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!</em> +</li> + +<li> +Shut it down again: In the console window type <code>%CATALINA_HOME%\bin\shutdown</code>. +</li> + +<li> +Extract the <b>diglib-core.zip</b> package, possibly to <code>C:\docuserver</code>. +</li> + +<li> +Install the auxiliary Java libraries in <code>digitallibrary\WEB-INF\lib</code>. +(Or just unpack the <b>digilib-ext.zip</b> package there.) +</li> + +<li> + Modify the following configuration files according to your paths (as in the "On Linux" section): +<br> +For tomcat +<ul> + <li><code>C:\jakarta-tomcat-4.1.24\conf\server.xml</code></li> + <li><code>C:\jakarta-tomcat-4.1.24\conf\tomcat-users.xml</code></li> +</ul> +For digilib +<ul> + <li><code>C:\docuserver\digitallibrary\WEB-INF\digilib-config.xml</code></li> + <li><code>C:\docuserver\digitallibrary\WEB-INF\digilib-auth.xml</code></li> +</ul> +In the <code>alcatraz-win-conf.zip</code> package you can find +prepared configuration files with the following default values: +<ul> + <li>The image file directory is <code>C:\bilder</code>. </li> + <li>The username for viewing image files is <code>digilib</code>.</li> + <li>The password for viewing image files is <code>digilib</code>.</li> + <li>The digilib server runs on Port <code>9090</code>.</li> +</ul> +</li> + +<li> +Now you can restart the Tomcat server: <code>http://localhost:9090</code> or +<code>http://127.0.0.1:9090</code>. +</li> + +<li> +Watch the images: +<a href="http://localhost:9090/docuserver/digitallibrary/digilib.jsp">http://localhost:9090/docuserver/digitallibrary/digilib.jsp</a> +</li> +</ol> + + +<h1>Configuration</h1> + +<h2>Tomcat</h2> + +<h3>catalina.sh / catalina.bat</h3> + +<p>The file <code>catalina.sh</code> (in <code>/docuserver/tomcat/bin</code> +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:</p> + +<pre> +export JAVA_HOME=/usr/local/lib/IBMJava2-14 +export CATALINA_OPTS="-mx512m" +</pre> + +<p>or, on Windows<p> + +<pre> +set CATALINA_HOME=C:\jakarta-tomcat-4.1.24 +set JAVA_HOME=C:\j2sdk +</pre> + +<p>Adjust the <code>JAVA_HOME</code> path to point to your Java JDK +installation directory. You can adjust the memory used by the Java VM +with the <code>-mx</code> option.</p> + + +<h3>tomcat-users.xml</h3> + +<p>All passwords and usernames have to be set up in the file +<code>tomcat-users.xml</code> in <code>/docuserver/tomcat/conf</code> if you +want to use authentication in digilib. The file looks like this:</p> + +<pre> +<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> +</pre> + +<p>A user is identified by a <code>name</code> and +<code>password</code>. 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 +<code>roles</code>. These roles will be used by digilib to decide if +an authenticated user is allowed to access a document (see +<code>digilib-auth.xml</code> below).</p> + +<p>If you want to use the webinterface to configure Tomcat, you have to +add administrational account with the roles <code>admin</code> and +<code>manager</code>.</p> + +<p>tomcat has to be restarted before changes to +<code>tomcat-users.xml</code> have effect!</p> + + +<h2>Digilib</h2> + +<h3>digilib-config.xml</h3> + +<p>The main configuration for digilib is +<code>digilib-config.xml</code>. It's normally in the +<code>WEB-INF</code> directory in the webapp. (If you really need +another location you can define it in the <code>config-file</code> +init-parameter to the servlet)</p> + +<p>In the configuration file you can set several paths and +options. The file looks like this:</p> + +<pre> +<!-- Digilib servlet config file --> + +<digilib-config> + <!-- Image to be sent to indicate general failure. --> + <parameter name="error-image" value=<b>"/docuserver/images/icons/broken.gif"</b> /> + + <!-- Image to be sent to indicate authorization failure. --> + <parameter name="denied-image" value=<b>"/docuserver/images/icons/alert.red.gif"</b> /> + + <!-- List of directories where images are searched. + The authoritative directory with the high-resolution images + is first in list. --> + <parameter name="basedir-list" value=<b>"/docuserver/images:/docuserver/scaled/small"</b> /> + + <!-- 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> +</pre> + +<p>You have to adjust the <code>basedir-list</code> 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.</p> + +<p>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.</p> + +<p>You can specify the Java toolkit implementation with the +<code>docuimage-class</code> parameter. The +<code>ImageLoaderDocuImage</code> might give best performance but +works only with JDK 1.4 and up. <code>JAIDocuImage</code> works with +JDK 1.3 and up.</p> + + +<h3>digilib-auth.xml</h3> + +<p>The digilib access authorization is defined in the file defined by +the <code>auth-file</code> parameter (usually +<code>digilib-auth.xml</code> in <code>WEB-INF</code>). </p> + +<p>The file has two parts <code>diglib-paths</code> and +<code>diglib-addresses</code>. It looks like this:</p> + +<pre> +<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> +</pre> + +<p><code>diglib-paths</code> defines restricted directories and +the roles needed for access. The roles are defined with the users in +<code>tomcat-users.xml</code> (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.</p> + +<p><code>diglib-addresses</code> defines hosts or networks of +computers that are automatically authenticated without username and +password. Hosts can be assigned roles. The special keyword <code>ALL</code> +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.</p> + + + +<hr> +<address>robcast@mail.berlios.de</address> +<!-- hhmts start -->Last modified: Tue Nov 2 13:14:57 CET 2004 <!-- hhmts end --> +</body> </html>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/digilib_interop.html Tue Apr 26 20:24:31 2011 +0200 @@ -0,0 +1,63 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> + <title>digilib toolbar interoperability</title> +</head> +<body> +<h1>Interoperability of digilib HTML pages with the Alcatraz toolbar</h1> + +<p>A toolbar-friendly digilib page must define a Javascript variable +<b><code>toolbarEnabledURL</code></b> whose value is a HTTP URL that +produces a <em>toolbar-enabled</em> 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.</p> + +<h2>Toolbar-enabled page</h2> + +<p>A <em>toolbar-enabled</em> page must offer the following Javascript functions:</p> + +<h3>Identification</h3> + +<ul> + <li><b><code>dlScriptVersion</code></b>: a String variable that contains the version number of the Javascript code (e.g. "1.12b3")<br> + The existence of this variable can be used to test for a <em>toolbar-enabled</em> page</li> +</ul> + +<h3>Interactive operations</h3> + +<ul> + <li><b><code>setMark()</code></b>: lets the user click and sets a mark at the clicked location</li> + <li><b><code>zoomArea()</code></b>: lets the user click to select an area and zooms to the selected area</li> + <li><b><code>moveCenter()</code></b>: lets the user click and recenters the image around the clicked location</li> +</ul> + +<h3>Page operations</h3> + +<ul> + <li><b><code>getRef()</code></b>: returns a String with a URL reference to the current document</li> + <li><b><code>removeMark()</code></b>: removes the last mark</li> + <li><b><code>zoomBy(float factor)</code></b>: magnifies the image by the given factor around the current center</li> + <li><b><code>zoomFullpage()</code></b>: zooms out so that the whole image is visible</li> + <li><b><code>display(int prio)</code></b>: reloads the page with the current parameters</li> +</ul> + +<h3>Parameter operations</h3> + +<ul> + <li><b><code>newParameter(String name, String defaultValue, int prio)</code></b>: declares a new parameter with name, default value (can be of any type) and priority</li> + <li><b><code>getParameter(String name)</code></b>: returns the value of the parameter with the name <code>name</code></li> + <li><b><code>setParameter(String name, String value)</code></b>: sets the value of the named parameter (value can be of any type)</li> + <li><b><code>getAllParameters(int prio)</code></b>: returns a String of all parameters in HTTP request format (name=value) below the given priority</li> + <li><b><code>addMark(Position pos)</code></b>: adds a mark with the given Position</li> + <li><b><code>deleteMark()</code></b>: removes the last mark form the list</li> + <li><b><code>getAllMarks()</code></b>: returns a String with all current marks in digilib format (for parameter "mk")</li> + <li><b><code>addFlag(String name)</code></b>: adds a digilib mode flag with the given name</li> + <li><b><code>hasFlag(String name)</code></b>: returns if the given flag is currently set</li> + <li><b><code>removeFlag(String name)</code></b>: removes the given flag</li> + <li><b><code>toggleFlag(String name)</code></b>: toggles the given flag</li> + <li><b><code>getAllFlags()</code></b>: returns a String with all current flags in digilib format (for parameter "mo")</li> +</ul> + +</body> +</html> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/old/digilib_client.html Tue Apr 26 20:24:31 2011 +0200 @@ -0,0 +1,428 @@ +<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> 2.1 digilib.jsp<br> + 2.2 dlImage.jsp<br> + 2.3 navigation_XX.js<br> + 2.4 dlMenu.html<br> + 2.5 Modules<br></b> + 2.5.1 pdfMaker.js<br> + 2.5.2 pagesTotal.js + +<h4>3 Future</h4> + +<h4>4 Information</h4> + +<b> 4.1 Supported browsers and platforms<br> </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><body bgcolor="#666666" onload='init_XXXXX("<%= fn ... +")'></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.</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), 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. +</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> + <li>Opera 6 (Windows, possibly other platforms)</li> +</ul> + +<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>