# HG changeset patch
# User hertzhaft
# Date 1382111012 -7200
# Node ID d9d004f706ef8748f6cad0f05db821340ba9e884
# Parent  458e6c33b972ab88b2e0a477e9ce2c2902419c22
added documentation/examples for client integration and plugins

diff -r 458e6c33b972 -r d9d004f706ef doc/src/site/markdown/client-integration.md
--- a/doc/src/site/markdown/client-integration.md	Thu Oct 17 16:04:30 2013 +0200
+++ b/doc/src/site/markdown/client-integration.md	Fri Oct 18 17:43:32 2013 +0200
@@ -6,11 +6,55 @@
 2. enable digilib interactive controls inside a fixed size image ("embedded mode")
 3. let the interactive image fill the browser window ("fullscreen mode")
 
-## Using the static image ##
+## Using a static digilib image ##
+
+Insert an image reference into your html code, referencing the "Scaler" servlet path in your digilib environment (servlet/Scaler, relative to your context). The image filename and path are specified in the `fn` parameter of the querystring. 
+
+    <img
+        src="http://your.imagerserver.org/digilib/servlet/Scaler?fn=/yourimage.jpg&dw=100&dh=100">
+    </img>
+
+Don't forget to specify at least one of the `dw` and `dh` parameters! They inform the servlet about the desired size (in pixel) of the scaled image. Otherwise you'll get an error image.
+
+Any other parameters can be added to the query string in order to specify further transformations of the image, for instance zoom-in coordinates, rotation, color changes etc. Look [here](scaler-api.html) for more information about query string parameters.
 
+An example file called _static.html_ is provided in your digilib context root directory.
 
+## Using digilib images in embedded mode ##
+
+To embed one or more scaled images with controls into your site, add one `div` element for each image to your HTML code. Set the image to load and its size in the scaler parameters `fn / pn` and `dw / dh`. These will be picked up by Digilib.
+
+        <div class="mydiv">
+            <img src="servlet/Scaler?dw=200&amp;dh=200&amp;fn=/p0005" />
+        </div>
+
+Apart from jQuery and jquery.digilib.js (the digilib plugin for jQuery) the digilib plugins `geometry` and `buttons` are needed. They must be loaded _after_ digilib. See [plugins](plugins.html) for the plugin documentation.
 
-## Using digilib embedded mode ##
+        <script type="text/javascript" src="jquery/jquery.js"></script>
+        <script type="text/javascript" src="jquery/jquery.digilib.js"></script>
+        <script type="text/javascript" src="jquery/jquery.digilib.geometry.js"></script>
+        <script type="text/javascript" src="jquery/jquery.digilib.buttons.js"></script>
+
+Add a jQuery `ready` event handler for the Javascript `document` object. In the handler the initialization function `digilib()` should be called. Set the `ìnteractionMode` option to "embedded" and the `digilibBaseUrl` option to the digilib context path.
 
+        <script type="text/javascript">
+            $(document).ready(function(){
+                var options = {
+                    interactionMode : 'embedded',
+                    digilibBaseUrl : '/digilib'
+                    };
+                $('.mydiv').digilib(options);
+        </script>
 
-## Using digilib fullscreen mode ##
\ No newline at end of file
+For the standard controls (contained in the buttons plugin) to be displayed next to the image, the <div> should have a `position: relative` CSS property and a fixed width.
+
+        div.mydiv {
+            position: relative;
+            width: 250px;
+        }
+
+An example file called _embedded.html_ is provided in your digilib context root directory.
+
+## Using digilib fullscreen mode ##
+
+An example file called _digilib.html_ is provided in your digilib context root directory.
diff -r 458e6c33b972 -r d9d004f706ef doc/src/site/markdown/features.md
--- a/doc/src/site/markdown/features.md	Thu Oct 17 16:04:30 2013 +0200
+++ b/doc/src/site/markdown/features.md	Fri Oct 18 17:43:32 2013 +0200
@@ -3,4 +3,8 @@
 * **client-server architecture**: all the "heavy lifting" is done on the 
   server, the client only displays the image.
   
-* **low bandwidth**: you can work 
\ No newline at end of file
+* **low bandwidth**: you can work 
+
+* **plugins**: there are several Digilib plugins written in Javascript to add functionality to the client side, making use of jQuery features. See the [plugins](plugins.html) documentation.
+
+* **digilib API**: modifiy the settings, write Javascript functions or provide your own Digilib plugins and event handlers.
\ No newline at end of file
diff -r 458e6c33b972 -r d9d004f706ef doc/src/site/markdown/plugins.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/site/markdown/plugins.md	Fri Oct 18 17:43:32 2013 +0200
@@ -0,0 +1,54 @@
+# Digilib Plugins #
+
+The basic client-side Javascript functions to control the Scaler image are provided by a jQuery plugin in the file 'jquery.digilib.js' (in the "jquery" subdirectory of the webapp). The Digilib jQuery plugin comes with a number of its own (sub-)plugins which provide additional functionality, making extensive use of the jQuery javascript library.
+
+All Digilib plugin code must be executed after jQuery and the main Digilib module (jquery.digilib.js).
+
+## Cookie plugin ##
+
+Stores the settings of your current Digilib preferences and view settings in a cookie.
+
+## Geometry plugin ##
+
+Required if you use the client side digilib functions in jquery.digilib.js. The plugin provides basic geometric functions which help calculating screen positions.
+
+## Arrows plugin ##
+
+Adds divs containing navigation arrows around the scaled image.
+
+## Auth plugin ##
+
+Handles authentication.
+
+## Bird's eye plugin ##
+
+Shows a small bird's eye view window with the highlighted current zoom area, useful when looking at zoomed images.
+
+## Dialogs plugin ##
+
+Provides dialogs to set the image calibration (for rendering the object on the image in its original size) and the scaling mode (screen size, predefined image size, or pixel of the original file).
+
+## Range plugin ##
+
+Provides HTML5 range controls for setting brightness, contrast and color values of the scaled image.
+
+## Marks plugin ##
+
+Allows the user to set visual marks on top of the scaled image, defining and referencing points of interest. The marks are numbered and always point to the defined location even when the image is zoomed, rotated or mirrored. The positions of the marks are part of the address. The marks are reproduced when the URL is opened in another browser or computer.
+
+## Regions plugin ##
+
+Allows the user to draw visual regions over the scaled image, defining and referencing areas of interest. The regions are numbered and always point to the defined location even when the image is zoomed, rotated or mirrored. The positions of the regions are part of the address. User-defined regions are reproduced when the URL is opened in another browser or computer.
+
+Regions can also be stored in the HTML code of the page. The code for each region may contain a link to an external resource. When the user clicks on a region, he is transferred to the external resource.
+
+The regions plugin provides an additional set of buttons for defining and deleting regions. Regions can be queried and highlighted by entering coordinates or text.
+
+## Annotator plugin ##
+
+Allows the user to add visual annotations on top of the scaled image, defining and referencing areas or points of interest. The annotations are loaded from an annotation server; new annotations can be inserted and edited. Annotations always point to the defined location even when the image is zoomed, rotated or mirrored.
+
+## How to write your own plugin ##
+
+Start with the stub file `jquery.digilib.pluginstub.js` in the "jquery" subdirectory of your digilib webapp directory.
+
diff -r 458e6c33b972 -r d9d004f706ef doc/src/site/site.xml
--- a/doc/src/site/site.xml	Thu Oct 17 16:04:30 2013 +0200
+++ b/doc/src/site/site.xml	Fri Oct 18 17:43:32 2013 +0200
@@ -34,6 +34,7 @@
     <menu name="Development">
       <item name="The digilib Scaler API" href="scaler-api.html"/>
       <item name="Integrating digilib into your page" href="client-integration.html"/>
+      <item name="Digilib plugins" href="plugins.html"/>
       <!-- <item name="Integrating digilib into your server" href=""/> -->
     </menu>
     <menu ref="reports"/>
diff -r 458e6c33b972 -r d9d004f706ef webapp/src/main/webapp/embedded.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/webapp/src/main/webapp/embedded.html	Fri Oct 18 17:43:32 2013 +0200
@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Digilib example: embedded image</title>
+
+        <style type="text/css">
+            body {
+                 background: silver;
+            }
+            div.mydiv {
+                position: relative;
+                width: 250px;
+            }
+        </style>
+
+        <script type="text/javascript" src="jquery/jquery.js"></script>
+        <script type="text/javascript" src="jquery/jquery.digilib.js"></script>
+        <script type="text/javascript" src="jquery/jquery.cookie.js"></script>
+        <script type="text/javascript" src="jquery/jquery.digilib.geometry.js"></script>
+        <script type="text/javascript" src="jquery/jquery.digilib.buttons.js"></script>
+
+        <script type="text/javascript">
+            $(document).ready(function(){
+                var $divs = $('.mydiv');
+                var opts = {
+                    interactionMode : 'embedded',
+                    digilibBaseUrl : '/digilib'
+                    };
+                $divs.digilib(opts);
+
+                // $('div.digilib').each(function(){
+                //    console.log($(this).data('digilib').settings);
+                //    });
+            });
+
+        </script>
+
+        <link rel="stylesheet" type="text/css" href="jquery/jquery.digilib.css" />
+
+    </head>
+
+    <body>
+        <div class="mydiv">
+            <img title="Embedded image 1" src="servlet/Scaler?dw=200&amp;dh=200&amp;fn=/p0005" />
+            Embedded Image 1
+        </div>
+
+        <div class="mydiv">
+            <img title="Embedded image 2" src="servlet/Scaler?dw=200&amp;dh=200&amp;fn=/ruler" />
+            Embedded Image 2
+        </div>
+    </body>
+</html>
+
diff -r 458e6c33b972 -r d9d004f706ef webapp/src/main/webapp/jquery/jquery.digilib.pluginstub.js
--- a/webapp/src/main/webapp/jquery/jquery.digilib.pluginstub.js	Thu Oct 17 16:04:30 2013 +0200
+++ b/webapp/src/main/webapp/jquery/jquery.digilib.pluginstub.js	Fri Oct 18 17:43:32 2013 +0200
@@ -34,35 +34,36 @@
     var FULL_AREA;
 
     var buttons = {
-            stub : {
-                onclick : ["doStub", 1],
+            STUB : {
+                onclick : ["doSTUB", 1],
                 tooltip : "what does this button do?",
-                icon : "stub.png"
+                icon : "STUB.png"
                 }
     };
 
     var defaults = {
-            // is stub active?
-            'isStubActive' : true
+            // set default values for options here
+            // is STUB active?
+            'isSTUBActive' : true
     };
 
     var actions = {
             // action code goes here 
-            doStub : function (data, param) {
+            doSTUB : function (data, param) {
                 var settings = data.settings;
-                console.log('isStubActive', settings.isStubActive);
+                console.log('isSTUBActive', settings.isSTUBActive);
                 // do some useful stuff ...
             }
     };
 
-    // plugin installation called by digilib on plugin object.
+    // plugin installation routine, called by digilib on each plugin object.
     var install = function(plugin) {
         digilib = plugin;
-        console.debug('installing stub plugin. digilib:', digilib);
+        console.debug('installing STUB plugin. digilib:', digilib);
         // import geometry classes
         geom = digilib.fn.geometry;
         FULL_AREA = geom.rectangle(0,0,1,1);
-        // add defaults, actins, buttons
+        // add defaults, actions, buttons to the main digilib object
         $.extend(digilib.defaults, defaults);
         $.extend(digilib.actions, actions);
         $.extend(digilib.buttons, buttons);
@@ -70,9 +71,9 @@
 
     // plugin initialization
     var init = function (data) {
-        console.debug('initialising stub plugin. data:', data);
+        console.debug('initialising STUB plugin. data:', data);
         var $data = $(data);
-        // install event handler
+        // install event handlers
         $data.bind('setup', handleSetup);
         $data.bind('update', handleUpdate);
         $data.bind('redisplay', handleRedisplay);
@@ -81,17 +82,17 @@
 
 
     var handleSetup = function (evt) {
-        console.debug("stub: handleSetup");
+        console.debug("STUB: handleSetup");
         var data = this;
     };
 
     var handleUpdate = function (evt) {
-        console.debug("stub: handleUpdate");
+        console.debug("STUB: handleUpdate");
         var data = this;
     };
 
     var handleRedisplay = function (evt) {
-        console.debug("stub: handleRedisplay");
+        console.debug("STUB: handleRedisplay");
         var data = this;
     };
 
@@ -99,10 +100,10 @@
         var data = this;
     };
 
-    // plugin object with name and init
-    // shared objects filled by digilib on registration
+    // plugin object, containing name, install and init routines 
+    // all shared objects are filled by digilib on registration
     var plugin = {
-            name : 'pluginstub',
+            name : 'STUB',
             install : install,
             init : init,
             buttons : {},
@@ -112,7 +113,7 @@
     };
 
     if ($.fn.digilib == null) {
-        $.error("jquery.digilib.pluginstub must be loaded after jquery.digilib!");
+        $.error("jquery.digilib.pluginstub.js must be loaded after jquery.digilib!");
     } else {
         $.fn.digilib('plugin', plugin);
     }
diff -r 458e6c33b972 -r d9d004f706ef webapp/src/main/webapp/static.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/webapp/src/main/webapp/static.html	Fri Oct 18 17:43:32 2013 +0200
@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Digilib example: static image</title>
+
+        <style type="text/css">
+            body {
+                 background: silver;
+            }
+        </style>
+
+    </head>
+
+    <body>
+        <div>
+            <img title="Static Image" src="servlet/Scaler?dw=200&amp;dh=200&amp;fn=/p0005.jpg" />
+        </div>
+        <div>A static example image served from the following address (relative to your digilib context):
+        <pre>servlet/Scaler?dw=200&amp;dh=200&amp;fn=/p0005.jpg</pre>
+        Notice the parameters: <i>fn</i> denotes the image path and filename (set in WEB-INF/digilib-config.xml),
+        <i>dw</i> and <i>dh</i> the width and height (in pixels) of the reduced image to be transferred from the digilib servlet. 
+        </div>
+    </body>
+</html>
+