From e983bd81081b526619a47a2bf83f0eb3dc3037e3 Mon Sep 17 00:00:00 2001 From: Uwe Schmidt Date: Fri, 12 May 2023 23:48:31 +0200 Subject: [PATCH] Add docs for updating ajax headers --- src/tiledimage.js | 36 +++++++++++++++++++++++++++++------- src/tilesource.js | 4 ++++ src/viewer.js | 17 +++++++++++++++-- 3 files changed, 48 insertions(+), 9 deletions(-) diff --git a/src/tiledimage.js b/src/tiledimage.js index 60e61827..974c51a6 100644 --- a/src/tiledimage.js +++ b/src/tiledimage.js @@ -1010,7 +1010,18 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag }, /** - * TODO + * Update headers to include when making AJAX requests. + * + * Unless `propagate` is set to false (which is likely only useful in rare circumstances), + * the updated headers are propagated to all tiles and queued image loader jobs. + * + * Note that the rules for merging headers still apply, i.e. headers returned by + * {@link OpenSeadragon.TileSource#getTileAjaxHeaders} take precedence over + * the headers here in the tiled image (`TiledImage.ajaxHeaders`). + * + * @function + * @param {Object} ajaxHeaders Updated AJAX headers, which will be merged over any headers specified in {@link OpenSeadragon.Options}. + * @param {Boolean} [propagate=true] Whether to propagate updated headers to existing tiles and queued image loader jobs. */ setAjaxHeaders: function(ajaxHeaders, propagate) { if (ajaxHeaders === null) { @@ -1022,11 +1033,24 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag } this._ownAjaxHeaders = ajaxHeaders; - this._updateAjaxHeaders(propagate); + this.updateAjaxHeaders(propagate); }, - // private - _updateAjaxHeaders: function(propagate) { + /** + * Update headers to include when making AJAX requests. + * + * This function has the same effect as calling {@link OpenSeadragon.TiledImage#setAjaxHeaders}, + * expect that the headers for this tiled image do not change. This is especially useful + * for propagating updated headers from {@link OpenSeadragon.TileSource#getTileAjaxHeaders} + * to existing tiles. + * + * Note that `TiledImage.ajaxHeaders` might still change if {@link OpenSeadragon.Viewer#setAjaxHeaders} + * was previously called without propagating the updated headers (not recommended). + * + * @function + * @param {Boolean} [propagate=true] Whether to propagate updated headers to existing tiles and queued image loader jobs. + */ + updateAjaxHeaders: function(propagate) { if (propagate === undefined) { propagate = true; } @@ -1038,7 +1062,7 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag this.ajaxHeaders = this._ownAjaxHeaders; } - // propagate header updates to all tiles and queued imageloader jobs + // propagate header updates to all tiles and queued image loader jobs if (propagate) { var numTiles, xMod, yMod, tile; @@ -1063,8 +1087,6 @@ $.extend($.TiledImage.prototype, $.EventSource.prototype, /** @lends OpenSeadrag } } - // TODO: good enough? running jobs are not stored anywhere - // maybe look through this._imageLoader.failedTiles and restart jobs? but which ones? for (var i = 0; i < this._imageLoader.jobQueue.length; i++) { var job = this._imageLoader.jobQueue[i]; job.loadWithAjax = job.tile.loadWithAjax; diff --git a/src/tilesource.js b/src/tilesource.js index b7782dbe..9d553a98 100644 --- a/src/tilesource.js +++ b/src/tilesource.js @@ -663,6 +663,10 @@ $.TileSource.prototype = { * The headers returned here will override headers specified at the Viewer or TiledImage level. * Specifying a falsy value for a header will clear its existing value set at the Viewer or * TiledImage level (if any). + * + * Note that the headers of existing tiles don't automatically change when this function + * returns updated headers. To do that, you need to call {@link OpenSeadragon.TiledImage#updateAjaxHeaders}. + * * @function * @param {Number} level * @param {Number} x diff --git a/src/viewer.js b/src/viewer.js index 9afa1585..5b9ec344 100644 --- a/src/viewer.js +++ b/src/viewer.js @@ -979,7 +979,20 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, }, /** - * TODO + * Update headers to include when making AJAX requests. + * + * Unless `propagate` is set to false (which is likely only useful in rare circumstances), + * the updated headers are propagated to all tiled images, each of which will subsequently + * propagate the changed headers to all their tiles. + * If applicable, the headers of the viewer's navigator and reference strip will also be updated. + * + * Note that the rules for merging headers still apply, i.e. headers returned by + * {@link OpenSeadragon.TileSource#getTileAjaxHeaders} take precedence over + * `TiledImage.ajaxHeaders`, which take precedence over the headers here in the viewer. + * + * @function + * @param {Object} ajaxHeaders Updated AJAX headers. + * @param {Boolean} [propagate=true] Whether to propagate updated headers to tiled images, etc. */ setAjaxHeaders: function(ajaxHeaders, propagate) { if (ajaxHeaders === null) { @@ -1435,7 +1448,7 @@ $.extend( $.Viewer.prototype, $.EventSource.prototype, $.ControlDock.prototype, * @param {Object} [options.ajaxHeaders] * A set of headers to include when making tile AJAX requests. * Note that these headers will be merged over any headers specified in {@link OpenSeadragon.Options}. - * requests. + * Specifying a falsy value for a header will clear its existing value set at the Viewer level (if any). * @param {Function} [options.success] A function that gets called when the image is * successfully added. It's passed the event object which contains a single property: * "item", which is the resulting instance of TiledImage.