Update docs on POST data to reflect more accurately the behaviour.

Fix bug & implement propositions ~ issue #2094.

src/imageloader.js

@@ -43,7 +43,8 @@
  * @param {String} [options.loadWithAjax] - Whether to load this image with AJAX.
  * @param {String} [options.ajaxHeaders] - Headers to add to the image request if using AJAX.
  * @param {String} [options.crossOriginPolicy] - CORS policy to use for downloads
- * @param {String} [options.postData] - HTTP POST data in k=v&k2=v2... form or null
+ * @param {String} [options.postData] - HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
+ *      see TileSrouce::getPostData) or null
  * @param {Function} [options.callback] - Called once image has been downloaded.
  * @param {Function} [options.abort] - Called when this image job is aborted.
  * @param {Number} [options.timeout] - The max number of milliseconds that this image job may take to complete.
@@ -198,9 +199,10 @@ $.ImageLoader.prototype = {
      * @param {String} [options.loadWithAjax] - Whether to load this image with AJAX.
      * @param {String} [options.ajaxHeaders] - Headers to add to the image request if using AJAX.
      * @param {String|Boolean} [options.crossOriginPolicy] - CORS policy to use for downloads
-     * @param {String} [options.postData] - POST parameters in k=v&k2=v2... form or null
+     * @param {String} [options.postData] - POST parameters (usually but not necessarily in k=v&k2=v2... form,
+     *      see TileSrouce::getPostData) or null
      * @param {Boolean} [options.ajaxWithCredentials] - Whether to set withCredentials on AJAX
-     * requests.
+     *      requests.
      * @param {Function} [options.callback] - Called once image has been downloaded.
      * @param {Function} [options.abort] - Called when this image job is aborted.
      */

src/mousetracker.js

@@ -3286,13 +3286,12 @@
             gPoint = updateGPoint;
         } else {
             // Initialize for tracking and add to the tracking list (no pointerenter event occurred before this)
-            $.console.warn('pointerdown event on untracked pointer');
+            // NOTE: pointerdown event on untracked pointer
             gPoint.captured = false; // Handled by updatePointerCaptured()
             gPoint.insideElementPressed = true;
             gPoint.insideElement = true;
             gPoint.originalTarget = eventInfo.originalEvent.target;
             startTrackingPointer( pointsList, gPoint );
-            return;
         }
 
         pointsList.addContact();
@@ -3436,8 +3435,8 @@
             releasePoint = updateGPoint.currentPos;
             releaseTime = updateGPoint.currentTime;
         } else {
-            // should never get here...we'll start to track pointer anyway
+            // NOTE: updatePointerUp(): pointerup on untracked gPoint
-            $.console.warn('updatePointerUp(): pointerup on untracked gPoint');
+            // ...we'll start to track pointer again
             gPoint.captured = false; // Handled by updatePointerCaptured()
             gPoint.insideElementPressed = false;
             gPoint.insideElement = true;
@@ -3460,7 +3459,7 @@
                 if ( pointsList.contacts === 0 ) {
 
                     // Release (pressed in our element)
-                    if ( tracker.releaseHandler ) {
+                    if ( tracker.releaseHandler && releasePoint ) {
                         tracker.releaseHandler(
                             {
                                 eventSource:           tracker,

src/openseadragon.js

@@ -665,13 +665,18 @@
   *
   * @property {Boolean} [splitHashDataForPost=false]
   *     Allows to treat _first_ hash ('#') symbol as a separator for POST data:
-  *     URL to be opened by a {@link OpenSeadragon.TileSource} can thus look like: http://some.url#postdata=here .
+  *     URL to be opened by a {@link OpenSeadragon.TileSource} can thus look like: http://some.url#postdata=here.
-  *     The URL is split to 'http://some.url' and 'postdata=here'; post data is given to the
+  *     The whole URL is used to fetch image info metadata and it is then split to 'http://some.url' and
-  *     {@link OpenSeadragon.TileSource} of the choice and can be further used within tile requests
+  *     'postdata=here'; post data is given to the {@link OpenSeadragon.TileSource} of the choice and can be further
-  *     (see TileSource methods). {@link OpenSeadragon.TileSource.prototype.configure} return value
+  *     used within tile requests (see TileSource methods).
-  *     should contain the post data so that it is given to its subclass in the constructor.
+  *     NOTE: {@link OpenSeadragon.TileSource.prototype.configure} return value should contain the post data
-  *     NOTE: post data is expected to be ampersand-separated (just like GET parameters), and is not used
+  *     if you want to use it later - so that it is given to your constructor later.
-  *     to fetch tile image data if loadTilesWithAjax=false (but it is still used for the initial request).
+  *     NOTE: usually, post data is expected to be ampersand-separated (just like GET parameters), and is NOT USED
+  *     to fetch tile image data unless explicitly programmed, or if loadTilesWithAjax=false 4
+  *     (but it is still used for the initial image info request).
+  *     NOTE: passing POST data from URL by this feature only supports string values, however,
+  *     TileSource can send any data using POST as long as the header is correct
+  *     (@see OpenSeadragon.TileSource.prototype.getTilePostData)
   */
 
  /**
@@ -2315,7 +2320,8 @@ function OpenSeadragon( options ){
          * @param {Function} options.error - a function to call on when an error occurs
          * @param {Object} options.headers - headers to add to the AJAX request
          * @param {String} options.responseType - the response type of the the AJAX request
-         * @param {String} options.postData - HTTP POST data in k=v&k2=v2... form, GET method used if null
+         * @param {String} options.postData - HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
+         *      see TileSrouce::getPostData), GET method used if null
          * @param {Boolean} [options.withCredentials=false] - whether to set the XHR's withCredentials
          * @throws {Error}
          * @returns {XMLHttpRequest}

src/tile.js

@@ -46,13 +46,14 @@
  *      this tile failed to load? )
  * @param {String} url The URL of this tile's image.
  * @param {CanvasRenderingContext2D} context2D The context2D of this tile if it
- * is provided directly by the tile source.
+ *      is provided directly by the tile source.
  * @param {Boolean} loadWithAjax Whether this tile image should be loaded with an AJAX request .
  * @param {Object} ajaxHeaders The headers to send with this tile's AJAX request (if applicable).
  * @param {OpenSeadragon.Rect} sourceBounds The portion of the tile to use as the source of the
- * @param {String} postData HTTP POST data in k=v&k2=v2... form or null
+ *      drawing operation, in pixels. Note that this only works when drawing with canvas; when drawing
- * drawing operation, in pixels. Note that this only works when drawing with canvas; when drawing
+ *      with HTML the entire tile is always used.
- * with HTML the entire tile is always used.
+ * @param {String} postData HTTP POST data  (usually but not necessarily in k=v&k2=v2... form,
+ *      see TileSrouce::getPostData) or null
  */
 $.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, ajaxHeaders, sourceBounds, postData) {
     /**
@@ -101,7 +102,8 @@ $.Tile = function(level, x, y, bounds, exists, url, context2D, loadWithAjax, aja
     /**
      * Post parameters for this tile. Either it is an URL-encoded string
      * in k1=v1&k2=v2... format or null
-     * @member {String} postData HTTP POST data in k=v&k2=v2... form or null
+     * @member {String} postData HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
+     *      see TileSrouce::getPostData) or null
      * @memberof OpenSeadragon.Tile#
      */
     this.postData  = postData;

src/tilesource.js

@@ -550,7 +550,8 @@ $.TileSource.prototype = {
                      * @property {OpenSeadragon.TileSource} eventSource - A reference to the TileSource which raised the event.
                      * @property {String} message
                      * @property {String} source
-                     * @property {String} postData - HTTP POST data in k=v&k2=v2... form or null
+                     * @property {String} postData - HTTP POST data (usually but not necessarily in k=v&k2=v2... form,
+                     *      see TileSrouce::getPostData) or null
                      * @property {?Object} userData - Arbitrary subscriber-defined object.
                      */
                     _this.raiseEvent( 'open-failed', {
@@ -623,13 +624,26 @@ $.TileSource.prototype = {
 
     /**
      * Must use AJAX in order to work, i.e. loadTilesWithAjax = true is set.
-     * It should return url-encoded string with the following structure:
+     * If a value is returned, ajax issues POST request to the tile url.
-     *   key=value&key2=value2...
+     * If null is returned, ajax issues GET request.
-     * or null in case GET is used instead.
+     * The return value must comply to the header 'content type'.
+     *
+     * Examples (USED HEADER --> getTilePostData CODE):
+     * 'Content-type': 'application/x-www-form-urlencoded' -->
+     *   return "key1=value=1&key2=value2";
+     *
+     * 'Content-type': 'application/x-www-form-urlencoded' -->
+     *   return JSON.stringify({key: "value", number: 5});
+     *
+     * 'Content-type': 'multipart/form-data' -->
+     *   let result = new FormData();
+     *   result.append("data", myData);
+     *   return result;
+
      * @param level
      * @param x
      * @param y
-     * @return {string || null} post data to send with tile configuration request
+     * @return {* || null} post data to send with tile configuration request
      */
     getTilePostData: function( level, x, y ) {
         return null;