--- a/client/digitallibrary/jquery/jquery-digilib-plugins.txt	Sun Feb 20 11:55:51 2011 +0100
+++ b/client/digitallibrary/jquery/jquery-digilib-plugins.txt	Sun Feb 20 13:24:49 2011 +0100
@@ -40,3 +40,8 @@
   "update", updateDisplay(): after small updates in the display, e.g. when the scaler-img finished loading.
   "redisplay", redisplay(): after changes in the display, e.g. after changing zoom factor.
   "dragZoom(newZoomArea)": while dragging the zoom area (with parameter newZoomArea).
+
+* initial options for the plugin can be passed to digilib, together with digilib options, by passing an object to the 'digilib' function: $div.digilib(options);
+The passed options extend/override the default digilib options. The options are stored in the "data.settings" array.
+
+* A functional stub for new digilib plugins is available in the file "jquery.digilib.pluginstub.js"

--- a/client/digitallibrary/jquery/jquery-test-full.html	Sun Feb 20 11:55:51 2011 +0100
+++ b/client/digitallibrary/jquery/jquery-test-full.html	Sun Feb 20 13:24:49 2011 +0100
@@ -61,6 +61,7 @@
         <script type="text/javascript" src="jquery.digilib.geometry.js"></script>
         <script type="text/javascript" src="jquery.digilib.birdseye.js"></script>
         <script type="text/javascript" src="jquery.digilib.regions.js"></script>
+        <script type="text/javascript" src="jquery.digilib.pluginstub.js"></script>
         <link rel="stylesheet" type="text/css" href="jquery.digilib.css" />
 
 

--- a/client/digitallibrary/jquery/jquery.digilib.birdseye.js	Sun Feb 20 11:55:51 2011 +0100
+++ b/client/digitallibrary/jquery/jquery.digilib.birdseye.js	Sun Feb 20 13:24:49 2011 +0100
@@ -45,6 +45,7 @@
 
     // plugin installation called by digilib on plugin object.
     var install = function(digilib) {
+        console.debug('installing birdseye plugin. digilib:', digilib);
         // import geometry classes
         geom = digilib.fn.geometry;
         FULL_AREA = geom.rectangle(0,0,1,1);
@@ -61,6 +62,7 @@
 
     // plugin initialization
     var init = function (data) {
+        console.debug('initialising birdseye plugin. data:', data);
         var $data = $(data);
         // install event handler
         $data.bind('setup', handleSetup);
@@ -305,7 +307,7 @@
 
     // plugin object with name and init
     // shared objects filled by digilib on registration
-    var digilib = {
+    var plugin = {
             name : 'birdseye',
             install : install,
             init : init,
@@ -318,6 +320,6 @@
     if ($.fn.digilib == null) {
         $.error("jquery.digilib.birdview must be loaded after jquery.digilib!");
     } else {
-        $.fn.digilib('plugin', digilib);
+        $.fn.digilib('plugin', plugin);
     }
 })(jQuery);

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/client/digitallibrary/jquery/jquery.digilib.pluginstub.js	Sun Feb 20 13:24:49 2011 +0100
@@ -0,0 +1,95 @@
+/**
+digilib plugin stub
+ */
+
+(function($) {
+
+    var geom;
+
+    var FULL_AREA;
+
+    var buttons = {
+            stub : {
+                onclick : ["doStub", 1],
+                tooltip : "what does this button do?",
+                icon : "stub.png"
+                }
+    };
+
+    var defaults = {
+            // is stub active?
+            'isStubActive' : true
+    };
+
+    var actions = {
+            // action code goes here 
+            doStub : function (data, param) {
+                var settings = data.settings;
+                console.log('isStubActive', settings.isStubActive);
+                // do some useful stuff ...
+            }
+    };
+
+    // plugin installation called by digilib on plugin object.
+    var install = function(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
+        $.extend(digilib.defaults, defaults);
+        // add actions
+        $.extend(digilib.actions, actions);
+        // add buttons
+        $.extend(digilib.buttons, buttons);
+    };
+
+    // plugin initialization
+    var init = function (data) {
+        console.debug('initialising stub plugin. data:', data);
+        var $data = $(data);
+        // install event handler
+        $data.bind('setup', handleSetup);
+        $data.bind('update', handleUpdate);
+        $data.bind('redisplay', handleRedisplay);
+        $data.bind('dragZoom', handleDragZoom);
+    };
+
+
+    var handleSetup = function (evt) {
+        console.debug("stub: handleSetup");
+        var data = this;
+    };
+
+    var handleUpdate = function (evt) {
+        console.debug("stub: handleUpdate");
+        var data = this;
+    };
+
+    var handleRedisplay = function (evt) {
+        console.debug("stub: handleRedisplay");
+        var data = this;
+    };
+
+    var handleDragZoom = function (evt, zoomArea) {
+        var data = this;
+    };
+
+    // plugin object with name and init
+    // shared objects filled by digilib on registration
+    var plugin = {
+            name : 'pluginstub',
+            install : install,
+            init : init,
+            buttons : {},
+            actions : {},
+            fn : {},
+            plugins : {}
+    };
+
+    if ($.fn.digilib == null) {
+        $.error("jquery.digilib.pluginstub must be loaded after jquery.digilib!");
+    } else {
+        $.fn.digilib('plugin', plugin);
+    }
+})(jQuery);

--- a/client/digitallibrary/jquery/jquery.digilib.regions.js	Sun Feb 20 11:55:51 2011 +0100
+++ b/client/digitallibrary/jquery/jquery.digilib.regions.js	Sun Feb 20 13:24:49 2011 +0100
@@ -53,61 +53,66 @@
     };
 
     var actions = { 
+
         // define a region interactively with two clicked points
         "setRegion" : function(data) {
             var $elem = data.$elem;
+            var $body = $('body');
+            var bodyRect = geom.rectangle($body);
             var $scaler = data.$scaler;
-            var picRect = geom.rectangle($scaler);
+            var scalerRect = geom.rectangle($scaler);
             var pt1, pt2;
-            // TODO: temporary rectangle only, pass values to "addRegion" factory
-            var $tempDiv = $('<div class="region" style="display:none"/>');
-            $elem.append($tempDiv);
+            // overlay prevents other elements from reacting to mouse events 
+            var $overlay = $('<div class="digilib-overlay"/>');
+            $body.append($overlay);
+            bodyRect.adjustDiv($overlay);
+            // the region to be defined
+            var $regionDiv = $('<div class="region" style="display:none"/>');
+            $elem.append($regionDiv);
 
+            // mousedown handler: start sizing
             var regionStart = function (evt) {
                 pt1 = geom.position(evt);
                 // setup and show zoom div
-                pt1.adjustDiv($tempDiv);
-                $tempDiv.width(0).height(0);
-                $tempDiv.show();
-                // register events
-                $elem.bind("mousemove.dlRegion", regionMove);
-                $elem.bind("mouseup.dlRegion", regionEnd);
+                pt1.adjustDiv($regionDiv);
+                $regionDiv.width(0).height(0);
+                $regionDiv.show();
+                // register mouse events
+                $overlay.bind("mousemove.dlRegion", regionMove);
+                $overlay.bind("mouseup.dlRegion", regionEnd);
                 return false;
             };
 
-            // mouse move handler
+            // mousemove handler: size region
             var regionMove = function (evt) {
                 pt2 = geom.position(evt);
                 var rect = geom.rectangle(pt1, pt2);
-                rect.clipTo(picRect);
-                // update zoom div
-                rect.adjustDiv($tempDiv);
+                rect.clipTo(scalerRect);
+                // update region
+                rect.adjustDiv($regionDiv);
                 return false;
             };
 
-            // mouseup handler: end moving
+            // mouseup handler: end sizing
             var regionEnd = function (evt) {
                 pt2 = geom.position(evt);
                 // assume a click and continue if the area is too small
                 var clickRect = geom.rectangle(pt1, pt2);
                 if (clickRect.getArea() <= 5) return false;
-                // unregister events
-                $elem.unbind("mousemove.dlRegion", regionMove);
-                $elem.unbind("mouseup.dlRegion", regionEnd);
-                // clip and transform
-                clickRect.clipTo(picRect);
-                clickRect.adjustDiv($tempDiv);
-                $tempDiv.remove();
-                data.settings.regions.push(clickRect);
+                // unregister mouse events and get rid of overlay
+                $overlay.unbind("mousemove.dlRegion", regionMove);
+                $overlay.unbind("mouseup.dlRegion", regionEnd);
+                $overlay.remove();
+                // clip region
+                clickRect.clipTo(scalerRect);
+                clickRect.adjustDiv($regionDiv);
+                data.settings.regions.push(clickRect); // TODO: trafo, params
                 // fn.redisplay(data);
                 return false;
             };
 
-            // clear old handler (also ZoomDrag)
-            $scaler.unbind('.dlRegion');
-            $elem.unbind('.dlRegion');
             // bind start zoom handler
-            $scaler.one('mousedown.dlRegion', regionStart);
+            $overlay.one('mousedown.dlRegion', regionStart);
         },
 
         // remove the last added region
@@ -218,14 +223,13 @@
 
     // plugin installation called by digilib on plugin object.
     var install = function(digilib) {
+        console.debug('installing regions plugin. digilib:', digilib);
         // import geometry classes
         geom = digilib.fn.geometry;
         FULL_AREA = geom.rectangle(0,0,1,1);
-        // add defaults
+        // add defaults, actions, buttons
         $.extend(digilib.defaults, defaults);
-        // add actions
         $.extend(digilib.actions, actions);
-        // add buttons
         $.extend(digilib.buttons, buttons);
     };
 
@@ -248,7 +252,7 @@
         $data.bind('dragZoom', handleDragZoom);
     };
 
-    // plugin object with name and init
+    // plugin object with name and install/init methods
     // shared objects filled by digilib on registration
     var pluginProperties = {
             name : 'region',
@@ -261,7 +265,7 @@
     };
 
     if ($.fn.digilib == null) {
-        $.error("jquery.digilib.birdview must be loaded after jquery.digilib!");
+        $.error("jquery.digilib.regions must be loaded after jquery.digilib!");
     } else {
         $.fn.digilib('plugin', pluginProperties);
     }