From 68126a82dcc8db74ea233c4184e30498330170a4 Mon Sep 17 00:00:00 2001 From: Jirka Date: Wed, 23 Mar 2022 10:22:13 +0100 Subject: [PATCH] Update docs on POST data to reflect more accurately the behaviour. Fix bug & implement propositions ~ issue #2094. --- src/imageloader.js | 8 +++++--- src/mousetracker.js | 9 ++++----- src/openseadragon.js | 22 ++++++++++++++-------- src/tile.js | 12 +++++++----- src/tilesource.js | 24 +++++++++++++++++++----- 5 files changed, 49 insertions(+), 26 deletions(-) diff --git a/src/imageloader.js b/src/imageloader.js index a120433a..198882b6 100644 --- a/src/imageloader.js +++ b/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. */ diff --git a/src/mousetracker.js b/src/mousetracker.js index 8c811326..cf796b6a 100644 --- a/src/mousetracker.js +++ b/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 - $.console.warn('updatePointerUp(): pointerup on untracked gPoint'); + // NOTE: 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, diff --git a/src/openseadragon.js b/src/openseadragon.js index ef002f37..731a06b4 100644 --- a/src/openseadragon.js +++ b/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 . - * The URL is split to 'http://some.url' and 'postdata=here'; post data is given to the - * {@link OpenSeadragon.TileSource} of the choice and can be further used within tile requests - * (see TileSource methods). {@link OpenSeadragon.TileSource.prototype.configure} return value - * should contain the post data so that it is given to its subclass in the constructor. - * NOTE: post data is expected to be ampersand-separated (just like GET parameters), and is not used - * to fetch tile image data if loadTilesWithAjax=false (but it is still used for the initial request). + * URL to be opened by a {@link OpenSeadragon.TileSource} can thus look like: http://some.url#postdata=here. + * The whole URL is used to fetch image info metadata and it is then split to 'http://some.url' and + * 'postdata=here'; post data is given to the {@link OpenSeadragon.TileSource} of the choice and can be further + * used within tile requests (see TileSource methods). + * NOTE: {@link OpenSeadragon.TileSource.prototype.configure} return value should contain the post data + * if you want to use it later - so that it is given to your constructor later. + * 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} diff --git a/src/tile.js b/src/tile.js index 8f2dfc1a..a6d40fd8 100644 --- a/src/tile.js +++ b/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 - * with HTML the entire tile is always used. + * drawing operation, in pixels. Note that this only works when drawing with canvas; when drawing + * 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; diff --git a/src/tilesource.js b/src/tilesource.js index c1956ac5..48cfe851 100644 --- a/src/tilesource.js +++ b/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: - * key=value&key2=value2... - * or null in case GET is used instead. + * If a value is returned, ajax issues POST request to the tile url. + * If null is returned, ajax issues GET request. + * 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;